docs(0088): document op-script grammar; refresh stale cycle-0088 example corpus

#163 — the construction op-script (`aura graph build`) had no durable public
schema doc, and the only worked-example corpus had drifted out of sync with the
current binary, so a consumer copying the visible example was misled.

Grammar reference (durable): a compact op-script grammar — the six verbs
(source/input/add/feed/connect/expose), their keys, the typed-Scalar bind form
({"I64":2}) and the capitalized ScalarKind, the by-identifier / dotted-port
model, and the add-`name` vs expose-`as` distinction — added to the C24 ledger
entry, with a correct worked-example pointer. Surfacing the same grammar in
`aura graph build --help` is left to ride with the CLI-discoverability work
(#159), keeping this change decoupled from the deferred World/project-as-crate
layer.

Corpus refresh: the cycle-0088 fixture corpus replayed against the current
binary failed on two accumulated drifts. (1) `add`'s naming key was renamed
`as` -> `name` (3c4b667; `expose` keeps `as` as a real alias) — the inputs now
use `name` for `add` ops only. (2) The dataflow-cycle bug the 0088 fieldtest
found was fixed (1652042, closes #161), so `c0088_3m_two_cycle` is now a
rejection fixture: the gap-era cyclic-blueprint golden is removed and
`c0088_3m.err` carries the eager cycle-rejection message. FINDINGS.md gets a
dated refresh stamp; its findings are preserved as written at fieldtest time.

Verified: the four golden-bearing success fixtures (_1, _2_completed,
_2_partial via --unwired) reproduce byte-identically; all 15 error fixtures
produce the intended by-identifier `op N (kind): cause` (or finalize) message.
Doc + fixtures only, no engine/CLI code touched.

closes #163
This commit is contained in:
2026-06-30 15:45:23 +02:00
parent 3f75d59598
commit 8bb21b1c16
22 changed files with 72 additions and 35 deletions
+29
View File
@@ -1841,6 +1841,35 @@ sequencing-coupled to the **project-as-crate authoring layer** (`aura new` /
`Aura.toml` / `cdylib` loading, C16/C17) and the **composable-orchestration** thread
(#109): topology-as-data is the substrate both stand on.
**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 six 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
from the slots it feeds).
- `add``{"op":"add","type":<TypeId>,"name":<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.
- `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
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`).
Value forms are the #155 representations: a `Scalar` bind value is the typed tag form
`{"I64":2}` / `{"F64":0.5}` / `{"Bool":true}` / `{"Timestamp":<i64>}`, and `kind` is
the capitalized `ScalarKind` (`"F64"`). Worked example:
`fieldtests/cycle-0088-construction-op-script/c0088_1_sma_crossover.json`
(an SMA-crossover bias). The surface is introspectable build-free:
`aura graph introspect --vocabulary | --node <T> | --unwired`. (Surfacing this same
grammar in `aura graph build --help` rides with the CLI-discoverability work, #159.)
---
## Open architectural threads not yet resolved