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:
+33
-7
@@ -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
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user