docs(guide, ledger, glossary): the eleventh op — naming a blueprint from the script
The authoring guide's ops table grows the name row (ten -> eleven) plus a paragraph on what the graph default costs a multi-strategy project (indistinguishable store entries, one shared trace directory, colliding use-splice instance defaults). C24's op-script grammar records the eleventh verb and the two-seam shape gate with its C29 read-back exemption; the glossary's blueprint-label entry now separates the render name (op-settable, keys trace runs and instance defaults) from the registry label (register --name, explicit, orthogonal). refs #331
This commit is contained in:
+10
-1
@@ -227,10 +227,11 @@ $ aura graph build < smacross.json > blueprint.json
|
||||
Nodes are referenced by an **identifier** (given by `add`, see below); ports
|
||||
are dotted `<identifier>.<port>` on both sides of a wire.
|
||||
|
||||
### The ten ops
|
||||
### The eleven ops
|
||||
|
||||
| op | JSON shape | does |
|
||||
|---|---|---|
|
||||
| `name` | `{"op":"name","name":<str>}` | set the composite's **render name**, script-level and at-most-once (a second `name` op refuses: `a script names its blueprint at most once`). The name must be a single path segment (non-empty, no `/`, `\`, `.` or `..`) since it keys a trace directory (`traces/<name>/`) at run time. Omitting the op keeps the CLI's own default, `"graph"`. |
|
||||
| `doc` | `{"op":"doc","text":<str>}` | declare the composite's one-line meaning (C29) — the op-script twin of the Rust builder's `.doc(...)`. Required before `aura graph register` accepts the product (the store refuses a doc-less composite); at most one per script (a second refuses: `a doc op may appear at most once`). The text is gated: empty or merely restating the composite's name refuses at register. |
|
||||
| `source` | `{"op":"source","role":<str>,"kind":<ScalarKind>}` | reserve a bound root **source** role of `kind` — a real input the harness feeds (e.g. `"price"`). |
|
||||
| `input` | `{"op":"input","role":<str>}` | reserve an open root **input** role (kind inferred from the slots it feeds) — the formal parameter of an **open pattern**, a fragment meant to be wired by an *enclosing* graph. An open pattern builds and registers like any blueprint. Running it standalone is governed by the ordinary run gates: the harness binds input roles to archive columns **by name** (C26), so a pattern whose roles match the data runs as-is; what refuses, by name, is a role the harness cannot bind — or the run surface's other gates (a signal without a bias output or tap; free knobs). |
|
||||
@@ -242,6 +243,14 @@ are dotted `<identifier>.<port>` on both sides of a wire.
|
||||
| `tap` | `{"op":"tap","from":<port>,"as":<str>}` | declare a **measurement tap** on an interior output field under the name `as` — the output-side twin of `expose` (a recorded observation point, not a boundary output; a `Composite.taps` entry, C27). A single `aura run` constructs a recorder at each declared tap and persists its per-cycle series as a `ColumnarTrace`; a sweep leaves it inert. Tap names are their own namespace and must be unique (a second `tap` under one name refuses: `duplicate tap name`). |
|
||||
| `gang` | `{"op":"gang","as":"channel_length","into":["channel_hi.length","channel_lo.length"]}` | Fuse two or more sibling params into ONE public knob: the member addresses leave the sweepable param space and `as` replaces them; the bound or swept value fans out to every member at bootstrap. Members must share one scalar kind and stay open (un-bound). |
|
||||
|
||||
Omitting `name` is fine for a single strategy, but it has three live
|
||||
consequences once a project has more than one: every unnamed store document
|
||||
is indistinguishable by name (`"graph"` again), every unnamed strategy's
|
||||
default tap recording lands in the same shared `traces/graph/` directory
|
||||
(later runs overwrite earlier ones), and two `use`-splices of unnamed
|
||||
blueprints collide on the same default instance identifier (`graph`) inside
|
||||
the same composing script. A one-line `name` op dissolves all three at once.
|
||||
|
||||
Value forms are the typed-tag representations used everywhere in this
|
||||
family of artifacts:
|
||||
|
||||
|
||||
@@ -196,8 +196,15 @@ rejected at construction.
|
||||
|
||||
The op-script is a JSON **array of ops**, each object internally tagged by `"op"`,
|
||||
replayed in order; nodes are referenced **by identifier**, ports as dotted
|
||||
`<identifier>.<port>`. The ten verbs:
|
||||
`<identifier>.<port>`. The eleven verbs:
|
||||
|
||||
- `name` — `{"op":"name","name":<str>}` — set the composite's render name
|
||||
(#331), script-level and at-most-once (a second refuses); omitted, the
|
||||
built composite keeps the CLI's own seed default (`"graph"`). Gated by a
|
||||
shared shape check (non-empty, single path segment, no `/`, `\`, `.` or
|
||||
`..`) applied at both data-borne birth routes — this op intake and the
|
||||
blueprint-envelope root name — since store read-back (reproduce, `use`
|
||||
resolution) stays ungated per C29.
|
||||
- `source` — `{"op":"source","role":<str>,"kind":<ScalarKind>}` — declare a root
|
||||
source role producing a base column of `kind`.
|
||||
- `input` — `{"op":"input","role":<str>}` — declare a root input role (kind inferred
|
||||
|
||||
+1
-1
@@ -37,7 +37,7 @@ The param-generic, input-role-generic graph-as-data produced by running a Rust b
|
||||
|
||||
### blueprint label
|
||||
**Avoid:** —
|
||||
A registry-level name pointing at a registered blueprint's content id (`graph register --name <label>`, #317) — a mutable, latest-wins pointer over the immutable content-addressed store, not a second identity: re-registering under an existing label *repoints* it (the earlier content id stays reachable by its own id, never invalidated). `graph introspect --registered` lists every label with its content-id prefix and root `doc` line — the discovery surface a `use (op)` reference by name resolves against.
|
||||
A registry-level name pointing at a registered blueprint's content id (`graph register --name <label>`, #317) — a mutable, latest-wins pointer over the immutable content-addressed store, not a second identity: re-registering under an existing label *repoints* it (the earlier content id stays reachable by its own id, never invalidated). `graph introspect --registered` lists every label with its content-id prefix and root `doc` line — the discovery surface a `use (op)` reference by name resolves against. Orthogonal to the composite's own **render name** (the `name` field carried in the blueprint bytes, op-settable via `{"op":"name",...}`, #331; defaults to `"graph"` if omitted): the render name keys the run's trace directory (`traces/<name>/`) and a `use`-splice's default instance identifier, while the label is an explicit, separately-set store pointer.
|
||||
|
||||
### bootstrap
|
||||
**Avoid:** —
|
||||
|
||||
Reference in New Issue
Block a user