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:
2026-07-18 16:31:17 +02:00
parent 43a1cc44d3
commit a5e02ff541
4 changed files with 79 additions and 8 deletions
+10 -3
View File
@@ -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