docs(readme, guides, glossary, ledger), bench: the surviving surface everywhere
Slice 8, closing the #319 retirement's prose and bench debt. Bench argv rides exec (fixed_cost single-run probe, campaign surfaces, and the seed helper that still called the retired sweep at runtime — caught by the bench run itself); all five fingerprints unchanged against the committed baselines, confirming record-line parity through the retirement. Live docs (README, authoring guide, project layout, glossary) describe only exec + campaign documents + graph introspect --params; three glossary entries explicitly mark their verb retired. Ledger amendments per the C29 discipline — C25's executor-verb-set re-settled (exec + the --override residue), C14's dual grammar reduced to the one dispatch, C24's document-built runs/families + gated-intake route list (lockstep with the code comment), C12's override clause and identity anchor repointed to the runner-layer hash computation, C18/C22/C27/C01 mention rewrites — superseded sentences moved verbatim to the history sidecars (c25's created). Stale dual-grammar doc comment on is_blueprint_file rewritten. refs #319
This commit is contained in:
@@ -31,47 +31,46 @@ Invoke it as `aura <command> …` (examples below use the plain name).
|
||||
|
||||
- **Blueprint** — a serialized signal graph as data: a param-generic
|
||||
`price → bias` node graph. A blueprint file (`blueprint.json`) is the unit a
|
||||
downstream consumer loads and drives verbs over.
|
||||
downstream consumer loads and executes or varies.
|
||||
- **Open vs. closed** — a blueprint with unbound (free) numeric knobs is *open*;
|
||||
one with every knob bound is *closed*. Different verbs want different states
|
||||
(see each verb below).
|
||||
- **Family** — the set of runs one verb produces over a blueprint (a sweep grid,
|
||||
a Monte-Carlo seed set, a walk-forward window sequence). Families are persisted
|
||||
in a content-addressed store and can be listed, ranked, and reproduced.
|
||||
one with every knob bound is *closed*. A plain `exec` wants closed; naming a
|
||||
knob as a campaign axis (or an `exec --override`) is what reopens it.
|
||||
- **Family** — the set of runs a campaign document's process pipeline produces
|
||||
over a blueprint (a sweep grid, a Monte-Carlo seed set, a walk-forward window
|
||||
sequence). Families are persisted in a content-addressed store and can be
|
||||
listed, ranked, and reproduced.
|
||||
- **Axis** — one named, sweepable knob of a blueprint (e.g. `fast.length`),
|
||||
bound with a comma-separated value list. A **gang** fuses several sibling
|
||||
knobs into one axis (one value drives all members).
|
||||
|
||||
## Running & orchestrating a loaded blueprint
|
||||
## Executing a document
|
||||
|
||||
These verbs all take the **blueprint file as their first positional argument**.
|
||||
Most drive a family of runs over it; `graph` renders its structure so a mis-wire
|
||||
is visible before a run. `walkforward`, `mc`, and `generalize` share
|
||||
`sweep`'s generic grammar — the blueprint positional plus `--real` and a
|
||||
repeatable `--axis <name>=<csv>` (`generalize` takes `--real <SYM1,SYM2,…>`, at
|
||||
least two instruments, with a single value per axis) — see `--help`.
|
||||
`aura exec <target>` (#319) is the one executor verb: `<target>` is either a
|
||||
loaded **blueprint** file (a single synthetic run) or a **campaign document**
|
||||
(a `.json` file or its registered 64-hex content id — instruments × windows ×
|
||||
strategy × param axes × process, see `docs/authoring-guide.md` §3). `graph`
|
||||
renders a blueprint's structure so a mis-wire is visible before a run.
|
||||
|
||||
| Command | Purpose |
|
||||
|---|---|
|
||||
| `aura run <bp.json>` | Run one backtest of a **closed** blueprint and print its report. An open (free-knob) blueprint is refused with a clean error — bind it, or use `sweep`. |
|
||||
| `aura exec <bp.json>` | Run one backtest of a **closed** blueprint and print its report. An open (free-knob) blueprint is refused with a clean error — bind it, or vary it as a campaign axis. |
|
||||
| `aura exec <bp.json> --override <node.param>=<value>` | Reopen one **bound** param for this single execution only (the value is recorded raw in the manifest); repeatable. |
|
||||
| `aura exec <bp.json> --tap <name>=<fold>` | Subscribe a declared tap to a fold (`record`/`count`/`sum`/`mean`/`min`/`max`/`first`/`last`) for this run; repeatable. |
|
||||
| `aura graph <bp.json>` | **Render** the blueprint's structure as an interactive HTML DAG so a mis-wire is visible before a run. Omit the file to render the built-in sample; a named-but-unreadable file is a usage error. |
|
||||
| `aura sweep <bp.json> --list-axes` | **Discover** the blueprint's open, sweepable knobs. Prints each as `<name>:<kind>`. Run this first to learn the axis names. |
|
||||
| `aura sweep <bp.json> --axis <name>=<csv> [--axis …]` | Run a **grid family** over the named axes and persist it. |
|
||||
| `aura mc <bp.json> --seeds <n>` | Run a **synthetic Monte-Carlo family** of `n` seeded realizations. Wants a **closed** blueprint (the inverse of sweep). |
|
||||
| `aura mc <bp.json> --real <sym> --axis <name>=<csv> [--axis …]` | Run a **Monte-Carlo R-bootstrap campaign** over recorded data — driven through the same generated-campaign pipeline as `sweep`; `--block-len`/`--resamples`/`--seed` tune the bootstrap. |
|
||||
| `aura walkforward <bp.json> --axis <name>=<csv> [--axis …]` | Run an **in-sample-refit walk-forward family** — rolling optimize + out-of-sample test across windows, stitched into one verdict + parameter stability. `--select` chooses the per-window objective. |
|
||||
| `aura graph introspect --params <bp.json\|id>` | **Discover** a blueprint's open, sweepable knobs. Prints each as `<name>:<kind>`, bound params trailing `default=<value>`. Run this first to learn the axis names for a campaign document. |
|
||||
| `aura exec <campaign.json\|id> [--parallel-instruments <n>]` | Execute a **campaign document** — a grid family, gates, walk-forward, Monte-Carlo, and cross-instrument generalization per its process document, one cell per (strategy, instrument, window). |
|
||||
| `aura runs families` | List every persisted family (id, kind, member count). |
|
||||
| `aura runs family <id> [rank <metric>]` | List one family's members, optionally ranked best-first by an R metric (e.g. `sqn_normalized`, `expectancy_r`). |
|
||||
| `aura reproduce <family-id>` | Re-derive every member of a persisted family from the content-addressed store and check it is bit-identical (the C18/C1 determinism guarantee). |
|
||||
|
||||
**Important contract — every open knob is mandatory.** On `sweep` and
|
||||
`walkforward`, the knobs enumerated by `--list-axes` are *all* required: you must
|
||||
supply an `--axis` for each open knob. There is no default value — pin a knob you
|
||||
don't want to vary with a single-value axis (`--axis name=4`). Omitting one is a
|
||||
clean error naming the missing knob, not a silent default.
|
||||
**Important contract — every open knob is mandatory on a campaign axis.** A
|
||||
campaign document's `strategies[].axes` must name every open knob
|
||||
`graph introspect --params` lists: there is no default value — pin a knob you
|
||||
don't want to vary with a single-value axis (`{"kind":"I64","values":[4]}`).
|
||||
Omitting one is a clean error naming the missing knob, not a silent default.
|
||||
|
||||
Use `aura <cmd> --help` for the full data-window (`--real`/`--from`/`--to`),
|
||||
naming (`--name`), and selection (`--select`) flags.
|
||||
Use `aura exec --help` for the exact flag grammar, `docs/authoring-guide.md`
|
||||
for the campaign document shape (data window, naming, presentation/emit).
|
||||
|
||||
## Authoring & introspecting topology
|
||||
|
||||
@@ -111,11 +110,11 @@ Each element is one op, tagged by `"op"`. Node params are bound with the **typed
|
||||
```
|
||||
|
||||
Piping this document into `aura graph build` emits a `blueprint.json` you can
|
||||
then feed to `run` / `sweep` / `mc` / `walkforward` above:
|
||||
then feed to `exec` above:
|
||||
|
||||
```sh
|
||||
aura graph build < crossover.ops.json > crossover.bp.json
|
||||
aura sweep crossover.bp.json --list-axes
|
||||
aura graph introspect --params crossover.bp.json
|
||||
```
|
||||
|
||||
The op kinds are `source`, `input`, `add`, `feed`, `connect`, `expose`, `tap`,
|
||||
|
||||
Reference in New Issue
Block a user