docs: SessionFrankfurt output semantics + declared-tap authoring (#285)
Surfaced by the measurement-milestone fieldtest: a downstream author reaching for session anchoring or declared taps had no public statement of either — the semantics lived only in node source / the design ledger. SessionFrankfurt / Session output semantics: - glossary `session node`: corrected — it claimed three streams (`bars_since_open`, `in_session`, `session_open_ts`), but the shipped node emits ONE `i64` field `bars_since_open`. Now states the real contract: the count of completed bar-periods since the local (tz-aware, DST-correct) session open, close-instant indexed (09:15->1, 09:45->3; pre-open <=0), with the Frankfurt 09:00 Europe/Berlin open + `period_minutes` knob + the value-ignored `trigger`. - authoring-guide: a "Session anchoring: the SessionFrankfurt preset" subsection — schema (trigger / period_minutes / bars_since_open), the close-instant multiples, the EqConst gating pattern, DST handling, and the add-snippet. Verified against `aura graph introspect --node SessionFrankfurt`. Declared-tap authoring (C27 / the #284 tap op): - authoring-guide: the `tap` op-table row (seven ops -> eight) + a worked "declaring a measurement tap" example. The example is verified: piping it through `aura graph build` emits `taps:[{"name":"spread","from":{"node":2,"field":0}}]`. - design ledger op-list (INDEX.md): a `tap` bullet (seven verbs -> eight); also corrected the `expose` "only verb that keeps `as`" claim — `tap` keeps it too. - README op-kind enumeration: adds `tap`. Docs only; no code change. Both worked examples were run through the built `aura` binary; the SessionFrankfurt schema was checked against introspect. closes #285
This commit is contained in:
+10
-3
@@ -2373,7 +2373,7 @@ fixture from the scaffolder.
|
||||
**Op-script grammar (`aura graph build`, the #157 wire surface).** The construction
|
||||
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 seven verbs:
|
||||
`<identifier>.<port>`. The eight verbs:
|
||||
- `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
|
||||
@@ -2388,8 +2388,15 @@ replayed in order; nodes are referenced **by identifier**, ports as dotted
|
||||
field to an input slot; a `connect` closing a cycle is rejected eagerly
|
||||
(invariant 5).
|
||||
- `expose` — `{"op":"expose","from":<port>,"as":<str>}` — promote an interior output
|
||||
field to a boundary output, aliased by `as` — **the only verb that keeps `as`**
|
||||
(a real alias, not a naming; contrast `add`'s `name`).
|
||||
field to a boundary output, aliased by `as` (a real alias, not a naming; contrast
|
||||
`add`'s `name`) — one of the two verbs that keep `as` (with `tap`).
|
||||
- `tap` — `{"op":"tap","from":<port>,"as":<str>}` — declare a measurement **tap** on
|
||||
an interior output field under `as` (#284) — the output-side twin of `expose`: a
|
||||
recorded observation point (a `Composite.taps` entry, C27), not a boundary output.
|
||||
Name-addressed like every other op (no raw index); tap names are their own
|
||||
namespace (a duplicate refuses). The `finish` gate threads op-declared taps into
|
||||
the built `Composite` (`.with_taps`); a single `aura run` records each, a sweep
|
||||
leaves them inert.
|
||||
- `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
|
||||
|
||||
Reference in New Issue
Block a user