docs(ledger, glossary, guide): construction args across the surfaces

C24 gains the add-op args clause and the data-driven format-version
paragraph (tier-2 discipline with id-stability); C15's current state
records Session as args-authorable; the glossary defines construction
arg and arg kind (and de-stales the session-node entry to aura-market);
the authoring guide fixes the moved roster path, extends the
Session-anchoring section with the args path, and teaches the add-op
args row; the README op-list sentence notes args on arg-bearing types.

refs #271
This commit is contained in:
2026-07-24 21:43:13 +02:00
parent a8b1ba45c5
commit bc8fb46110
5 changed files with 70 additions and 15 deletions
+33 -7
View File
@@ -49,8 +49,9 @@ the same shape every node in `aura-std` already follows.
`src/lib.rs`, registered under the project's own `<namespace>::` prefix)
and appends its path to the project's `Aura.toml [nodes]` section.
- **A block promoted to universal** — reused across projects and folded into
the engine itself — lives in `crates/aura-std/src/`, unprefixed, and is
rostered in `crates/aura-std/src/vocabulary.rs` instead of a node crate's
the engine itself — lives in `crates/aura-std/` (or its sibling domain
crates: `aura-market`, `aura-strategy`), unprefixed, and is rostered in
`crates/aura-vocabulary/src/lib.rs` instead of a node crate's
`vocabulary()` function. The pattern below is identical either way; only
the rostering call site differs (see "Rostering the type" below).
@@ -89,11 +90,16 @@ Every node type — std or project-local — is three things:
`aura_core::aura_project!` macro wires up (every `aura new` scaffold
emits a starter pair — see the worked example below). Add one match arm
to `vocabulary()` and one entry to `type_ids()`'s slice.
- **Std-side** (only when promoting a node into `aura-std` itself): one
line in the `std_vocabulary_roster!` macro invocation in
[`crates/aura-std/src/vocabulary.rs`](../crates/aura-std/src/vocabulary.rs)
- **Std-side** (only when promoting a node into the shipped std
vocabulary): one line in the `std_vocabulary_roster!` macro invocation in
[`crates/aura-vocabulary/src/lib.rs`](../crates/aura-vocabulary/src/lib.rs)
`"TypeId" => Type,` — which expands into both the resolver `match` and
the enumerable type-id list, so the two surfaces cannot drift apart.
the enumerable type-id list, so the two surfaces cannot drift apart. A
zero-arg `Type::builder()` rosters directly; an **arg-bearing** type
(structural, non-scalar construction — see "Session anchoring" below and
`docs/glossary.md`'s `construction arg` entry, #271) rosters the exact
same way — its `builder()` is itself zero-arg, returning a *pending*
recipe the `add` op's `args` configures before any `bind`.
An unrostered type fails safe either way: the loader refuses with a clean
`LoadError::UnknownNodeType` naming the missing id, and the type is simply
absent from `aura graph introspect --vocabulary` — never a silent partial
@@ -228,7 +234,7 @@ are dotted `<identifier>.<port>` on both sides of a wire.
| `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). |
| `add` | `{"op":"add","type":<TypeId>,"name":<str>?,"bind":{<param>:<Scalar>}?}` | instantiate a node of a type in the closed vocabulary (`aura graph introspect --vocabulary`) — see §0 below for how a type gets into that vocabulary in the first place. `name` becomes the node's identifier for later ops (default: the type's own lowercase label — two unnamed nodes of the same type then collide). `bind` sets zero or more of its params. |
| `add` | `{"op":"add","type":<TypeId>,"name":<str>?,"args":{<arg>:<str>}?,"bind":{<param>:<Scalar>}?}` | instantiate a node of a type in the closed vocabulary (`aura graph introspect --vocabulary`) — see §0 below for how a type gets into that vocabulary in the first place. `name` becomes the node's identifier for later ops (default: the type's own lowercase label — two unnamed nodes of the same type then collide). `args` (#271) configures an **arg-bearing** type's structural, non-scalar construction (`Session`'s timezone/open, `LinComb`/`CostSum`'s arity) — a closed table of string values, applied BEFORE `bind`; `aura graph introspect --node <T>` lists a type's declared `arg` rows. `bind` sets zero or more of the (now real) params. |
| `use` | `{"op":"use","ref":{"content_id":<id-or-prefix>}\|{"name":<label>},"name":<str>?,"bind":{<path>:<Scalar>}?}` | splice a **registered blueprint** into the graph as a nested composite under an instance identifier (`name`; default: the stored composite's own name). The ref resolves by content id (full or unique prefix) or by a register-time label; `graph build` echoes every resolution (`aura: note: use "…": … -> <id>`) so the exact id can be pinned. The instance's open input roles wire as `<instance>.<role>`, its outputs as `<instance>.<field>`; its open params surface path-qualified (`<instance>.<node>.<param>`), sweepable (ganging an instance's params is not yet supported — the `gang` op refuses a composite instance's member path). A doc-less stored source refuses at the op (C29). The emitted blueprint contains the subgraph *inline* — no reference survives into the artifact. |
| `feed` | `{"op":"feed","role":<str>,"into":[<port>, …]}` | fan a previously-declared role into one or more interior input slots, all-or-nothing (a failing target leaves none of the batch wired). |
| `connect` | `{"op":"connect","from":<port>,"to":<port>}` | wire one interior output field to one interior input slot. A `connect` that would close a dataflow cycle is rejected immediately — the only legal feedback path is an explicit delay/state node (domain invariant 5). |
@@ -342,6 +348,26 @@ Wire it like any node —
`{"op":"add","type":"SessionFrankfurt","bind":{"period_minutes":{"I64":15}}}`,
feed its `trigger` from a once-per-bar stream, and read `bars_since_open`.
**Any other timezone/open: `Session` + `args` (#271).** `SessionFrankfurt`
stays baked sugar for the one Frankfurt open; the canonical path for ANY IANA
timezone and local open time is the base `Session` type through the typed
construction-args channel — `args` configures it BEFORE `bind`:
```json
{"op":"add","type":"Session","name":"ny",
"args":{"tz":"America/New_York","open":"09:30"},
"bind":{"period_minutes":{"I64":15}}}
```
`tz` is `chrono_tz`'s own exact, case-sensitive IANA name (`"berlin"` refuses;
`"Europe/Berlin"` accepts); `open` is strict zero-padded local `HH:MM`
(`"9:30"` refuses; `"09:30"` accepts) — the accepted string IS the canonical
form, no normalization. Giving `Session` no `args` at all refuses the `add`
op (`node <name> is missing required arg "tz"`) — an arg-bearing type never
silently enters the graph half-configured. `aura graph introspect --node
Session` lists both declared `arg` rows with their kind and hint text before
you write the JSON.
### Commands
```