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
@@ -17,10 +17,14 @@ stream; reference data feeds source/session nodes from beside the hot path.
**Session context — `bars_since_open` is the shipped contract (#154).** The
session-context node `Session` (`crates/aura-market/src/session.rs`) emits
**one** scalar stream, `bars_since_open: i64` (tz-aware, DST-correct, over a
baked Frankfurt open), and takes no scalar params; the zero-arg
`SessionFrankfurt` roster preset (#261) exposes it with a single
`period_minutes` knob. This is a deliberate narrowing pinned in the node's own
**one** scalar stream, `bars_since_open: i64` (tz-aware, DST-correct), over a
timezone/open time that is now data-authorable via the typed construction-args
channel (`Session` roster-reaches `std_vocabulary` as an arg-bearing type,
#271: `args: {"tz": <IANA name>, "open": "HH:MM"}`, applied before its one
scalar param, `period_minutes`). The zero-arg `SessionFrankfurt` roster preset
(#261) stays as baked sugar over the 09:00 `Europe/Berlin` open — the
canonical path for any OTHER open/timezone is `Session` + `args`, not a new
preset per market. This is a deliberate narrowing pinned in the node's own
contract: `bars_since_open` alone is the gate — a downstream `EqConst(== N)`
subsumes an `in_session: bool` stream (pre-open instants read `<= 0`, which
never match), and nothing consumes a `session_open_ts: timestamp`. The two
+17 -2
View File
@@ -197,10 +197,17 @@ replayed in order; nodes are referenced **by identifier**, ports as dotted
from the slots it feeds) — a reusable **pattern**'s formal parameter, left open
until an enclosing graph wires it (#317's open patterns): `finish()` accepts an
op-script that never binds it, only `compile`/bootstrap require it bound.
- `add` — `{"op":"add","type":<TypeId>,"name":<str>?,"bind":{<param>:<Scalar>}?}` —
- `add` — `{"op":"add","type":<TypeId>,"name":<str>?,"args":{<arg>:<str>}?,"bind":{<param>:<Scalar>}?}` —
add a node of compiled-in type identity `type`; **`name` is its identifier**
(mirrors the builder's `.named(...)`; defaults to the lowercased type label, so
two unnamed nodes of one type collide); `bind` sets params.
two unnamed nodes of one type collide); `args` (#271) configures an **arg-bearing**
type's structural, non-scalar construction (`Session`'s IANA timezone/open,
`LinComb`/`CostSum`'s arity) through the closed, load-time-validated `ArgKind`
table (`Tz`/`TimeOfDay`/`Count`) — applied BEFORE `bind`, so a bound param
`args` unlocks (e.g. `LinComb`'s `weights[i]`) is only bindable once `arity` is
consumed; an arg-bearing type given no `args` refuses (`BadArg(MissingArg)`), a
`Plain` type given `args` it does not declare also refuses
(`BadArg(NotArgBearing)`); `bind` sets the (now real) params.
- `feed` — `{"op":"feed","role":<str>,"into":[<port>,…]}` — fan a root role into
interior input slots.
- `connect` — `{"op":"connect","from":<port>,"to":<port>}` — wire an interior output
@@ -269,6 +276,14 @@ additive-optional fields of v1; the first ship consciously freezes v1, gangs inc
and activates the bump discipline. The per-section required-flag scheme is deferred (no
current Tier-2 section to validate it; recorded on #156).
**First data-driven bump (#271):** construction args are the first Tier-2 case whose
version is decided PER DOCUMENT, not a single global bump. The writer emits
`format_version: 1` for an args-free document (byte-identical to every pre-#271
document — content ids stable) and `2` the moment any primitive, at any composite
nesting depth, carries `args` — the must-understand signal an old (pre-#271) reader
needs, since it cannot construct a pending arg-bearing type at all. The loader accepts
the closed range `1..=2`.
### Enforcement shift — invariant 9 on the data plane
Lifting topology onto the data plane relocates *where* the engine/project boundary