diff --git a/docs/authoring-guide.md b/docs/authoring-guide.md index 3b4b27b..f0d06fb 100644 --- a/docs/authoring-guide.md +++ b/docs/authoring-guide.md @@ -55,8 +55,8 @@ family of artifacts: ```json [ {"op": "source", "role": "price", "kind": "F64"}, - {"op": "add", "type": "SMA", "name": "fast", "bind": {"length": {"I64": 2}}}, - {"op": "add", "type": "SMA", "name": "slow", "bind": {"length": {"I64": 4}}}, + {"op": "add", "type": "SMA", "name": "fast"}, + {"op": "add", "type": "SMA", "name": "slow"}, {"op": "feed", "role": "price", "into": ["fast.series", "slow.series"]}, {"op": "add", "type": "Sub", "name": "sub"}, {"op": "connect", "from": "fast.value", "to": "sub.lhs"}, @@ -67,9 +67,16 @@ family of artifacts: ] ``` -(`bias.scale` is left unbound here on purpose — an open campaign axis, see -§3. This is the milestone fieldtest corpus's own example, verified below; -also on disk at `fieldtests/milestone-research-artifacts/mra_1_strategy_smacross.json`.) +(`fast.length`, `slow.length`, and `bias.scale` are all left unbound here on +purpose — three open campaign axes, see §3. This is the milestone fieldtest +corpus's own example, verified below; byte-identical to the on-disk +`fieldtests/milestone-research-artifacts/mra_1_strategy_smacross.json`.) + +A `bind` in an `add` op pins that param to a fixed value and **removes it +from the sweepable param space**: a bound param is closed — it never shows +up in `--params`/`--list-axes`, and no campaign axis and no `aura sweep +--axis` can reopen it. `bind` is for a constant the strategy never varies; +leave a param unbound, as all three are here, to keep it open for sweeping. ### Commands @@ -101,6 +108,20 @@ slow.length:I64 bias.scale:F64 ``` +These printed names are the **raw param-space namespace**: op-script params +and a campaign document's `strategies[].axes` keys (§3) share this one raw +form. There is a third, *wrapped* surface: the dissolved `aura sweep + --axis` CLI (glossary `sweep`) accepts only the names `aura +sweep --list-axes` prints — the raw name prefixed with the +root-composite instance name, `graph.` — never the raw form; the +campaign document the sweep sugar generates still stores the raw form +(#210): + +``` +raw (--params, campaign axes): fast.length +wrapped (--list-axes, --axis): graph.fast.length +``` + `--content-id`, `--identity-id`, `--params`, and `graph register` all accept **either** shape: the raw op-script array or an already-built `#155` blueprint envelope (object) — shape-discriminated automatically, so you diff --git a/docs/glossary.md b/docs/glossary.md index 83a8462..790431f 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -285,7 +285,7 @@ The harness's structural parameterization — which strategy, instrument(s), bro ### sweep **Avoid:** param-sweep, parameter sweep -An orchestration axis varying tuning params (grid or random) within a fixed structure. The inner, param-tuning loop, distinct from the structural experiment matrix. On a loaded blueprint every open knob (`--list-axes`) is **required** — a subset is refused with the missing knob named; pin an unwanted knob with a single-value axis (`--axis name=`), there is no default. +An orchestration axis varying tuning params (grid or random) within a fixed structure. The inner, param-tuning loop, distinct from the structural experiment matrix. On a loaded blueprint every open knob (`--list-axes`) is **required** — a subset is refused with the missing knob named; pin an unwanted knob with a single-value axis (`--axis name=`), there is no default. `aura sweep --axis` takes the `--list-axes`-printed, root-composite-wrapped name (e.g. `graph.fast.length`) — not the raw `param_space` name (`fast.length`) that `graph introspect --params` and a campaign document's axes use; the CLI strips exactly one leading wrapper segment (#210). ### tap **Avoid:** —