Aura/docs/specs/0088-construction-op-script.md

# Introspectable, fail-fast construction service — Design Spec

**Date:** 2026-06-29
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude
**Issue:** #157 (depends on #155, landed `d5602ec`)

## Goal

Deliver an **introspectable, fail-fast construction service** that lets a
data-level author (Claude Code, or a small LLM) build a runnable blueprint
through validated ops — without hand-writing the raw-index serialized format
(#155) and without authoring a many-invariant artifact blind. The service emits
a blueprint (the #155 value), reusing the engine's *existing* construction gates
rather than introducing a second validator (C24).

The surface, settled in #157's discussion, is a **declarative, replayable,
by-identifier op-script**: a document of construction ops, replayed op-by-op
from scratch, stopping at the first op that does not resolve and naming it. The
document *is* the artifact (a Strudel-style document-re-eval model — the script
replayed from scratch is deterministic (C1) and a World-owned topology value
(C24)), with no held process state that can drift from the history that produced
it. MCP is out of scope (deferred, consumer-strength-dependent).

The work has a **surface-agnostic core** (the value of #157) and a thin CLI
shell over it:

- **Core (engine):** split the construction gates into *eager* per-op checks
  and *holistic* end-of-document checks, both calling the same extracted
  predicates; a per-op-fallible construction surface that drives them; and a
  build-free introspection API over the closed `aura-std` vocabulary and over a
  partial script.
- **Shell (CLI):** a JSON op-list encoding and the `aura graph build` /
  `aura graph introspect` subcommands.

This retires, in concert with #159, the hard-wired `aura-cli` harness
(`sample_blueprint`, `crates/aura-cli/src/main.rs:3313`) — topology as Rust
source is exactly what C24 forbids; this issue supplies the data-authoring
surface that replaces it.

## Feature-acceptance criterion (applied, aura CLAUDE.md)

aura's deliverable is the **engine**, and its north star (C24) is *topology as
data for every author*. The criterion for this feature:

1. **A data-level author naturally reaches for it.** The author writes a
   document of ops (shown below) instead of Rust builder source or raw-index
   JSON — and is never authoring blind, because introspection answers "what
   nodes exist, what are this node's ports/kinds, what is still unwired" without
   a build.
2. **It measurably improves correctness / removes redundancy.** A constructed
   graph runs **identically** to its Rust-built twin (C1); the hard-wired CLI
   harness it replaces is removed source. No second validator is introduced —
   the per-op and holistic checks are the *same* engine predicates at two
   cadences.
3. **It reintroduces no class of failure the core constraint exists to
   eliminate.** The failure mode that sank the RustAst DSL was *unaided
   authoring of a many-invariant artifact*. The op-script does not reintroduce
   it: every op is checked fail-fast against the engine's own gates, and
   introspection means the author never authors blind. The document carries no
   logic — only constructive ops with literal params — so it is data, not an
   applied/Turing-complete DSL (C24, invariant 10).

The worked author program under **Concrete code shapes** is this criterion's
empirical evidence.

## Architecture

Three layers, named §A/§B/§C; §A+§B are the surface-agnostic engine core
(iteration 1), §C the CLI shell (iteration 2).

### §A — Eager / holistic gate split (the shared predicates)

Today, *all* structural validation runs at finalize, in two stages:

- `GraphBuilder::build()` (`crates/aura-engine/src/builder.rs:131`) resolves
  port/field **names** to indices, yielding `BuildError` for unknown/ambiguous
  ports and bad handles. It does **not** check edge kinds — the module doc
  (`builder.rs:50-52`) states a name-resolved edge with mismatched kinds
  surfaces only downstream.
- `Composite::compile_with_params` →`compile_with_cells`
  (`blueprint.rs:262`, `:207`) runs the three structural gates:
  `check_param_namespace_injective` (`:566`), `validate_wiring` (`:628`, which
  includes the edge **kind-match**, raised as `Bootstrap(KindMismatch)` at
  `:644`), and `check_ports_connected` (`:688`).

The op-script needs some of these checks to fire **per op** (acceptance 2:
"rejected at the op"), while others are only decidable once the document ends.
The split is forced by *what is decidable when*:

| Check | Today (finalize) | Op-script cadence | Why |
|---|---|---|---|
| Name resolution (port/field → index) | `build()` | **eager** (per op) | the referenced node is already added |
| Edge kind-match (producer field kind == consumer slot kind) | `validate_wiring` `:638-649` | **eager** (per op) | both schemas known at the `connect` op |
| Slot covered **>1** (`DoubleWiredPort`) | `check_ports_connected` `:708` | **eager** (per op) | a second cover is visible the moment it happens |
| Param bind name/kind | `bind` panics (`node.rs`) | **eager** (per op) | the node's schema is known at `add` |
| Slot covered **0** (`UnconnectedPort`) | `check_ports_connected` `:707` | **holistic** (finalize) | a mid-document graph is *legitimately* incomplete |
| Param-namespace injective (`DuplicateParamPath`) | `check_param_namespace_injective` | **holistic** (finalize) | only decidable once all nodes + names exist |
| Role-kind consistency, root-role boundness, output range | `compile_with_*` | **holistic** (finalize) | whole-graph properties |

The principle is sharpest at `check_ports_connected`, whose match has exactly
two failure arms: the **>1** arm (`DoubleWiredPort`) is eagerly decidable; the
**0** arm (`UnconnectedPort`) is not. The op-script front-runs the >1 arm and
defers the 0 arm.

**No second validator.** The eager path does not re-implement these checks: the
edge-kind check is **extracted** from `validate_wiring`'s inline loop into a
shared predicate called by *both* the eager op and the unchanged holistic
`validate_wiring`; the eager coverage tracker shares the "exactly-once"
invariant with the unchanged `check_ports_connected` (which remains the holistic
backstop, still catching both arms). The name-resolution helpers
(`builder.rs:160-198`, `resolve_slot`/`resolve_field`) become shared
(`pub(crate)`) and are called eagerly per op.

### §B — Per-op-fallible construction surface + introspection (engine)

A new engine surface (planner names the type; provisionally `GraphSession`)
drives the eager checks. It is **not** an extension of `GraphBuilder`:
`GraphBuilder`'s documented contract is *infallible accumulate, one fallible
`build()`* (`builder.rs:1-9`, `:67-68`); the op-script's stop-at-first-failing-op
is a different, per-op-fallible discipline. The new surface reuses
`GraphBuilder`'s resolution helpers and the §A predicates over shared internals,
rather than overloading one type with two contracts.

It owns: the in-progress nodes/schemas/edges/roles/outputs (as `GraphBuilder`
does), an **incremental coverage map** `(node, slot) → count` (the eager
double-wire tracker), and a **name→handle map** for the document's `as NAME`
identifiers. Each op is applied fallibly; a terminal `finish` runs the holistic
gates and returns the `Composite` (→ `blueprint_to_json` for the emitted
blueprint; → `compile_with_params` for the runnable `FlatGraph`).

**Introspection** is read-only and build-free, in two modes:

- **Static (type-level):** enumerate the vocabulary; for a type, its ports +
  kinds (`NodeSchema.inputs`/`.output`, `PortSpec`/`FieldSpec` carry `name` +
  `kind`) and its param paths (`PrimitiveBuilder::params`). All declared
  pre-build (C8). This requires an **enumerable** companion to the closed
  `std_vocabulary` match (see §Components) — a `fn(&str)->Option<…>` resolver
  alone cannot be listed.
- **Partial-script (instance-level):** the still-**unwired** slots of an
  in-progress session = every added node's declared input slots minus the
  covered ones, read straight off the coverage map.

### §C — JSON op-list encoding + CLI shell

The document's canonical encoding is a **JSON op-list** (serde-native, mirroring
#155's blueprint JSON), so the core carries no hand-written parser/lexer (the
smallest "no new language" surface). A line-oriented human text front-end is a
**deferred** ergonomic sugar (not this cycle).

`aura graph build < doc.json` deserializes the op-list, replays it through a
`GraphSession`, and on success emits the blueprint JSON (and/or compiles to a
`FlatGraph`); on the first failing op it prints the op index + cause and exits
non-zero. `aura graph introspect` answers the static + partial-script queries.
Both extend the existing flat argv `match` (`main.rs:3292`); the bare
`["graph"]` HTML-render arm is unaffected for now (its `sample_blueprint`
removal is #159's concern, with which this pairs).

## Concrete code shapes

### Worked author program (the acceptance evidence)

The author builds the `sma_cross` **signal blueprint** — `price → fast/slow SMA
→ Sub → Bias`, exposed as `bias`. Every node is in the zero-arg vocabulary
(`SMA`, `Sub`, `Bias`), so it round-trips today. (A *full* harness adds
`SimBroker`/`Recorder`, whose construction-arg / `mpsc::Sender` builders are
deliberately outside the #155 vocabulary — #156; so the op-script's near-term
reach is signal blueprints, not full harnesses, exactly as #157's sequencing
note states.)

Canonical document (`sma_cross.json`):

```json
[
  {"op": "source",  "role": "price", "kind": "f64"},
  {"op": "add",     "type": "SMA",   "as": "fast", "bind": {"length": 2}},
  {"op": "add",     "type": "SMA",   "as": "slow", "bind": {"length": 4}},
  {"op": "add",     "type": "Sub"},
  {"op": "add",     "type": "Bias"},
  {"op": "feed",    "role": "price", "into": ["fast.series", "slow.series"]},
  {"op": "connect", "from": "fast.value", "to": "sub.lhs"},
  {"op": "connect", "from": "slow.value", "to": "sub.rhs"},
  {"op": "connect", "from": "sub.value",  "to": "bias.signal"},
  {"op": "expose",  "from": "bias.bias",  "as": "bias"}
]
```

```console
$ aura graph build < sma_cross.json
# stdout: the #155 blueprint JSON (format_version + blueprint{nodes,edges,…})
```

Deferred text-sugar equivalent (illustrative only, **not** in this cycle):

```
source price: f64
add SMA(length=2) as fast
add SMA(length=4) as slow
add Sub
add Bias
feed price -> fast.series, slow.series
connect fast.value -> sub.lhs
connect slow.value -> sub.rhs
connect sub.value  -> bias.signal
expose bias.bias as bias
```

Fail-fast rejection (acceptance 2) — each names the offending op + cause, and
nothing after it runs:

```console
$ echo '[{"op":"add","type":"Nope"}]' | aura graph build
error: op 0 (add): unknown node type "Nope"        # not in std_vocabulary

# kind mismatch — a bool field into an f64 slot, rejected at the connect op
$ aura graph build < kindbad.json
error: op 4 (connect gt.value -> bias.signal): kind mismatch (producer bool, consumer f64)

# double-wire — a second producer into an already-wired slot
$ aura graph build < doublewire.json
error: op 5 (connect slow.value -> sub.lhs): slot sub.lhs already wired
```

Introspection (acceptance 3) — build-free:

```console
$ aura graph introspect --vocabulary
Add And Bias CarryCost ConstantCost Delay EMA EqConst FixedStop Gt Latch
LongOnly Mul PositionManagement Resample RollingMax RollingMin Sizer SMA
Sqrt Sub VolSlippageCost

$ aura graph introspect --node SMA
SMA  inputs: series:f64   output: value:f64   params: length:i64

# the still-unwired slots of a partial document
$ aura graph introspect --unwired < partial.json
sub.rhs:f64  bias.signal:f64
```

### Engine shapes (secondary, before → after)

**(1) Extract the edge-kind predicate** — shared by the eager op and the
unchanged holistic `validate_wiring`.

```rust
// NEW shared predicate (pub(crate)); the body is lifted verbatim from
// validate_wiring's edge loop (blueprint.rs:638-649), so the variant is
// unchanged (Bootstrap(KindMismatch)) and existing compiled-graph tests stay green.
pub(crate) fn edge_kind_check(
    from: &NodeSchema, from_field: usize,
    to: &NodeSchema, slot: usize,
) -> Result<(), CompileError> {
    let f = from.output.get(from_field).ok_or(CompileError::BadInteriorIndex)?;
    let s = to.inputs.get(slot).ok_or(CompileError::BadInteriorIndex)?;
    if f.kind != s.kind {
        return Err(CompileError::Bootstrap(BootstrapError::KindMismatch {
            producer: f.kind, consumer: s.kind,
        }));
    }
    Ok(())
}
// validate_wiring's edge loop now calls edge_kind_check (after its index lookups);
// the eager connect op calls the same predicate. ONE check, two cadences.
```

**(2) `check_ports_connected` is unchanged** (`blueprint.rs:688`) — it stays the
holistic backstop catching the **0** arm (`UnconnectedPort`) and, defensively,
the **>1** arm. The eager surface front-runs the **>1** arm via its incremental
coverage map:

```rust
// inside the per-op connect/feed handler (eager half of the exactly-once invariant)
let n = *self.coverage.entry((to_node, slot)).or_insert(0);
if n >= 1 { return Err(OpError::SlotAlreadyWired { node: to_node, slot }); } // DoubleWiredPort, raised early
self.coverage.insert((to_node, slot), n + 1);
```

**(3) A non-panicking bind** — today `PrimitiveBuilder::bind` *panics* on an
unknown/ambiguous/kind-wrong param (`node.rs`, the `debug_assert`/`expect`
path). The `add … bind{…}` op needs a fallible variant so a bad param is
rejected *at the op*, not a panic:

```rust
// NEW: the fallible twin of bind() (same exactly-one-match + kind rule, Result not panic)
pub fn try_bind(self, slot: &str, value: Scalar) -> Result<Self, BindOpError> { … }
```

**(4) The per-op surface (engine) — op enum + drive/finish:**

```rust
pub enum Op {                       // serde-deserialized from the JSON op-list (§C)
    Source  { role: String, kind: ScalarKind },
    Input   { role: String },
    Add     { type_id: String, as_name: Option<String>, bind: Vec<(String, Scalar)> },
    Feed    { role: String, into: Vec<String> },   // "node.slot" identifiers
    Connect { from: String, to: String },          // "node.field" -> "node.slot"
    Expose  { from: String, as_name: String },
}

pub struct GraphSession { /* nodes, schemas, edges, roles, out, coverage, name->handle */ }

impl GraphSession {
    pub fn new(name: &str, vocab: &dyn Fn(&str) -> Option<PrimitiveBuilder>) -> Self;
    pub fn apply(&mut self, op: Op) -> Result<(), OpError>;     // eager checks (§A)
    pub fn finish(self) -> Result<Composite, OpError>;          // holistic gates → Composite
    // build-free introspection over the partial session:
    pub fn unwired(&self) -> Vec<(String /*node.slot*/, ScalarKind)>;
}

// replay driver: stop at first failing op, naming it (acceptance 2)
pub fn replay(name: &str, ops: Vec<Op>, vocab: …) -> Result<Composite, (usize, OpError)>;
```

`OpError` carries by-identifier causes (`UnknownNodeType(String)`,
`UnknownPort{node,name}`, `KindMismatch{…}`, `SlotAlreadyWired{…}`,
`DuplicateIdentifier(String)`, `BadParam(BindOpError)`, and a holistic
`Incomplete(CompileError)` wrapping the finalize gate). The eager variants reuse
§A's predicates and `builder.rs`'s resolution; `Incomplete` wraps the unchanged
`compile_with_params`/finalize path.

### §C — enumerable vocabulary companion

```rust
// aura-std/src/vocabulary.rs — companion to the existing std_vocabulary match (:30)
pub fn std_vocabulary_types() -> &'static [&'static str] {
    &["Add","And","Bias","CarryCost","ConstantCost","Delay","EMA","EqConst",
      "FixedStop","Gt","Latch","LongOnly","Mul","PositionManagement","Resample",
      "RollingMax","RollingMin","Sizer","SMA","Sqrt","Sub","VolSlippageCost"]
}
// introspection maps each type → std_vocabulary(type).schema() for ports/kinds/params.
// (The same iterable surface would let #160's guard test iterate; #160 stays separate.)
```

## Components

- **`aura-engine` (§A):** extract `edge_kind_check` (and the index-range lookups
  it needs) from `validate_wiring`; make `resolve_slot`/`resolve_field` shared
  (`pub(crate)`); add `PrimitiveBuilder::try_bind` (fallible twin of `bind`).
  `check_ports_connected` and `compile_with_params` are **unchanged**.
- **`aura-engine` (§B):** the `GraphSession` per-op surface + `Op`/`OpError`
  enums + the `replay` driver + `unwired` introspection. New module
  (e.g. `construction.rs`).
- **`aura-std` (§C):** `std_vocabulary_types()` — the enumerable companion.
- **`aura-cli` (§C):** serde `Deserialize` for `Op` (the JSON op-list); the
  `["graph","build", …]` and `["graph","introspect", …]` argv arms over
  `main.rs:3292`; rendering of `OpError` / introspection results to
  stdout/stderr with the op index.

## Data flow

```
document (JSON op-list)                          [§C]
  └─ serde → Vec<Op>
       └─ replay(name, ops, std_vocabulary) ──── [§B]
            ├─ per op: apply(op) → eager checks   [§A predicates]   ──┐ stop at first Err,
            │                                                          │ naming op index + cause
            └─ finish() → holistic gates → Composite                  ┘
                 ├─ blueprint_to_json(&composite)  → emitted blueprint (#155)   [title: "emits blueprints"]
                 └─ composite.compile_with_params(params) → FlatGraph
                       └─ identical to the Rust-built twin's FlatGraph  [acceptance 1, C1]

introspection (no build):
  --vocabulary  → std_vocabulary_types()
  --node T      → std_vocabulary(T).schema()  (ports/kinds) + .params()
  --unwired     → replay partial → GraphSession::unwired()
```

## Error handling

- **Eager (per op):** `apply` returns `OpError` with a by-identifier cause; the
  `replay` driver returns `(op_index, OpError)`; the CLI prints `op N (kind):
  cause` and exits non-zero. Stop-at-first — no op after the failing one runs.
- **Holistic (finish):** `Incomplete(CompileError)` wraps the unchanged finalize
  gates (`UnconnectedPort`, `DuplicateParamPath`, `UnboundRootRole`, …). An
  `UnconnectedPort` is reported against the document as a whole, not an op.
- **No second validator:** every eager rejection traces to a §A predicate that
  the holistic gate also uses; the holistic gates remain the backstop. A bug in
  a predicate fails both cadences identically (a single fix site).

## Testing strategy

Iteration 1 (engine, §A+§B) — driven directly through `GraphSession`/`replay`,
no CLI:

- **Acceptance 1 (identical run):** author `sma_cross` (the worked example) via
  `replay`; author the same via `GraphBuilder`; compile both with the same
  params; assert `flat.edges` and `flat.sources` equal — modeled on the green
  `builder_harness_compiles_identically_to_hand_wired` (`builder.rs:234`).
- **Acceptance 2 (per-op rejection):** one test per cause — unknown node
  (`add Nope` → op 0), edge kind-mismatch (bool→f64 → at the connect op),
  double-wire (second connect into a slot → at that op), bad bind param. Each
  asserts the failing op index + the `OpError` variant.
- **Eager/holistic boundary:** a document missing a connection passes every
  per-op `apply` but `finish` returns `Incomplete(UnconnectedPort{…})` — proving
  totality is *not* front-run (the legitimately-incomplete mid-document state).
- **No-second-validator:** a kind-mismatch caught eagerly and the same wiring
  caught by `validate_wiring` both resolve to `edge_kind_check` (the eager
  `OpError::KindMismatch` and the holistic `Bootstrap(KindMismatch)` agree).
- **Introspection:** `std_vocabulary_types()` lists exactly the resolvable
  keys (cross-check against `std_vocabulary` — a key present in one but not the
  other fails); `--node SMA` shape; `unwired()` on a partial session.

Iteration 2 (CLI, §C) — E2E: `aura graph build < doc.json` emits the blueprint;
an invalid op prints `op N` + cause and exits non-zero; `aura graph introspect`
answers each query. `cargo test --workspace` green; `clippy --all-targets -D
warnings` clean.

## Acceptance criteria

- [ ] **(1)** A `sma_cross` signal blueprint built purely through the ops
  compiles to a `FlatGraph` identical (edges + sources) to its `GraphBuilder`-built
  twin (C1).
- [ ] **(2)** An invalid op — unknown node, edge kind-mismatch, double-wire, bad
  bind param — is rejected **at that op**, naming the op index + cause; no later
  op runs.
- [ ] **(3)** Introspection answers the node vocabulary, a node's ports/kinds +
  param paths, and a partial document's unwired slots — all without a build.
- [ ] No second validator: the eager and holistic checks call the same extracted
  predicates (`edge_kind_check`, the exactly-once coverage invariant); the
  finalize gates (`compile_with_params`) are unchanged.
- [ ] `aura graph build` emits the #155 blueprint JSON for a valid document.
- [ ] `cargo test --workspace` green; `cargo clippy --workspace --all-targets -D
  warnings` clean.

## Iteration scope (for the planner)

- **Iteration 1 — engine core (§A + §B):** the gate split + shared predicates,
  `GraphSession`/`Op`/`replay`, `try_bind`, the introspection API + enumerable
  vocabulary companion. Fully testable through the engine API; no CLI.
- **Iteration 2 — CLI shell (§C):** the JSON op-list serde encoding and the
  `aura graph build` / `aura graph introspect` subcommands; E2E tests.