# C8 — The node contract

**Guarantee.** A node is the universal composable dataflow unit — a **producer, a
consumer, or both**. It has a **signature**, its `NodeSchema`: each input port
(scalar kind + firing group), its output record, and its own **tunable
parameters** — each a **typed knob** (`name` + scalar kind). The node declares a
knob's *existence and type*, never its search interval: which subset/grid a sweep
covers is the run's concern (an experiment axis, C20), not the node's. The knobs
aggregate into the blueprint's flat, path-qualified param-space the optimizer
sweeps (C12/C19/C20). The whole signature is **declared once, pre-build, on the
value-empty recipe** (C19), so the entire interface is legible without building;
the built node carries no `schema()`. The one param-dependent quantity — an
input's buffer **lookback** depth (e.g. an `Sma`'s window = its `length`) — is not
in the signature but answered by `lookbacks()`, read once at bootstrap to size the
windows. The built node implements `eval(ctx) -> Option<&[Cell]>`: the engine
provides read-only, zero-copy windows into each input's SoA ring buffer
(`ctx.f64_in(i)[k]`, sized at wiring), and `eval` returns a borrowed row — one
`Cell` per declared output column — into a node-owned buffer, so the forward path
allocates nothing per cycle (C7). A node may *additionally* keep its own mutable
series for derived/intermediate state. Binding is **field-wise**: one edge selects
one producer column, so consuming a whole record is N edges — there is no
"bind whole record" mechanism. The K columns of one record are **co-fresh by
construction** (one `eval`, one timestamp), so C6 is untouched.

A **producer/transformer** exposes **one output port**, whose payload is a
**record of 1..K base-scalar columns** (a scalar is the degenerate K=1 record); a
**pure consumer (sink)** — chart, equity, logger — declares **no output** and
records via an out-of-graph side effect. **Recording is a node role, not a type:**
a node declaring `output: vec![]` *is* a sink (the empty record is the whole
declaration — no `Sink` type, trait, or engine flag), its `eval` returns `None` or
a zero-width `Some(&[])`, and it pushes its record to a destination it holds as a
field (a channel, a chart handle). A node may record **and** return a forwarded
output in the same `eval` (the "both" case). `None` = filter / not-yet-warmed-up /
pure sink. Sources are pure producers; sinks are pure consumers. Beside `eval`,
the contract has a symmetric lifecycle pair — default-no-op hooks the engine calls
once per node, in topological order: `initialize()` before the first source value,
letting a consumer acquire its run resources (e.g. the file a recording sink
streams into) at stream start, and `finalize()` after the source loop drains,
letting a sink fold online and flush one compact summary at stream end instead of
streaming a row every fired cycle. A node also exposes `label()`, a single-line,
non-load-bearing render symbol (C23).

**Forbids.** A node sizing/growing its input lookback at runtime; more than one
output **port** per node; a fifth scalar type or a heterogeneous output payload (a
record is a bundle of base columns, C7); copy-on-read of input history; a `Sink`
type/trait/engine flag or a "bind whole record" mechanism (both are structurally
absent by design).

**Why.** Engine-provided windows mean LLM-authored code cannot mis-manage lookback
bookkeeping, and history passes through zero-copy. Fixed, pre-sized buffers suit
deterministic, pre-dimensioned sims (no realloc in the hot loop). Declaring the
signature once, pre-build on the recipe, keeps the whole interface legible without
building and dissolves the drift of declaring params twice (recipe vs built node).
The empty-output sink keeps in-graph routing engine-owned data (the edge table)
and pushes every escape *out* of the graph onto the node's own side effect — that
boundary is the determinism / graph-as-data boundary (C1/C7). `finalize` gives a
folding sink O(trades)/O(1) owned accumulator state and one summary row, instead of
an unbounded channel that buffers O(cycles) rows until the run ends; it runs once
*after* the deterministic event loop, adding no within-sim concurrency (C1), and
holds only owned state, no interior mutability (C7). `initialize` mirrors it at
stream start (#283): resource acquisition happens inside the same deterministic
sequence, and the hook is infallible by signature — a consumer that fails to
acquire stores the error, degrades to inert, and surfaces the failure once,
terminally, at `finalize` (the run completes; refusal-worthy faults are caught
pre-run, at construction/bind time).

## Current state

The signature types and the `Node` trait live in `aura-core/src/node.rs`.
`NodeSchema { inputs: Vec<PortSpec>, output: Vec<FieldSpec>, params: Vec<ParamSpec> }`;
`PortSpec { kind, firing, name }`, `FieldSpec { name, kind }`, and
`ParamSpec { name, kind }` each carry a `name` that is a **non-load-bearing** debug
symbol (C23) — wiring is positional by slot; bootstrap and the run loop never read
it. Permitted param kinds are `i64`/`f64`/`bool` (a `timestamp` knob is a
structural axis, C20, never a numeric sweep param).

`trait Node` declares `lookbacks() -> Vec<usize>`, `eval(&mut self, ctx) ->
Option<&[Cell]>`, `label() -> String` (default a placeholder every shipped node
overrides; overrides carry identifying params so `SMA(2)` vs `SMA(4)` disambiguate
in a graph render, #13), and the lifecycle pair `initialize(&mut self)` /
`finalize(&mut self)` (both default no-op). There is **no**
`Node::schema()` — the signature is pre-build data, not a built-node method. The
signature is declared once on the value-empty recipe `PrimitiveBuilder`
(`aura-core/src/node.rs`), whose `schema()` / `params()` are read pre-build by the
param-space aggregation, the structural validation, and the render; `named(...)`
sets a node instance's authoring name and `bind(slot, value)` fixes a knob to a
structural constant, removing it from the param surface.

Field-wise binding is `Edge::from_field` (`aura-engine/src/blueprint.rs`), resolved
against the producer's `output` at bootstrap. A sink's empty `output` therefore
makes it structurally unwireable as an in-graph producer — no edge can bind a field
of a zero-output node. The run loop (`aura-engine/src/harness.rs`) debug-asserts
`row.len()` equals the declared output width, and that `lookbacks()` arity equals
`signature().inputs.len()`. The lifecycle pair is realized in `Harness::run`
(`aura-engine/src/harness.rs`): an `initialize()` prologue once per node in
topological order before the source loop, and the `finalize()` epilogue after it
drains — each pinned by its own once-per-run mirror test; `GatedRecorder` and
`SeriesReducer` (`aura-std`) are the folding siblings of the per-cycle `Recorder`
(`aura-std/src/recorder.rs`), which survives for the live / `--trace` / test-tap
path.

`BlueprintNode::signature()` (`aura-engine/src/blueprint.rs`) answers uniformly for
both arms: a primitive returns its recipe's schema, a composite *derives* it via
`derive_signature` (input-port kinds from interior target slots, output-field kinds
from re-exported `OutField`s, aggregated params). `Composite::param_space()`
(same file) aggregates every node's declared params into one flat, path-qualified
list mirroring the inline order (C19/C23) — a read-only projection of the
graph-as-data (C9). Identity in the flat graph is positional; the `param_space()`
**name projection** (the by-name authoring/sweep address space) must be
**injective** for a blueprint to compile, enforced by
`check_param_namespace_injective` → `CompileError::DuplicateParamPath`, so
same-type siblings in one composite must be `.named(...)` apart (also what
disambiguates a same-type fan-in, C9). A vector knob (`LinComb.weights`) expands to
`N` flat `weights[i]` entries, `N` topology-fixed (C19).

Wiring is **total and single-valued** over interior input slots:
`check_ports_connected`, run inside `validate_wiring` at every nesting level,
requires every interior node's every declared input slot to be covered by
**exactly one** wiring act (one interior `Edge { to, slot }` or one role
`Target { node, slot }`, counted uniformly). Zero coverage is
`CompileError::UnconnectedPort`, more than one is `CompileError::DoubleWiredPort`.
A composite's **own** input roles (`source: None`) are coverage *providers* (the
wired-by-enclosing boundary, the root case guarded by `UnboundRootRole`), never
consumers. There is no optional-input concept — every declared input port is
required. The check is index-based and name-free, so C23 is untouched.

A `Composite` carries an optional authored rationale `doc: Option<String>`
(`aura-engine/src/builder.rs`: `GraphBuilder::doc` / `Composite::with_doc`) — the
prose twin of its `name`, the same C23 non-load-bearing category. It is persisted
as an additive-optional `CompositeData` field (`aura-engine/src/blueprint_serde.rs`;
absent-field documents keep their exact bytes, so existing content ids are
untouched), blanked in the identity projection by `strip_debug_symbols`, dissolved
at inline like the name, and surfaced read-only in the graph model and viewer
(C22).

Deferred: Naming input ports
(`PortSpec.name`) makes swap-prone same-kind slots self-documenting but does not add
a name-consuming wiring validation; a swapped same-kind wiring is still only
kind-checked (#21). The construction op-script vocabulary has no doc-carrying
surface yet (scope cut on #125).

## See also
- [C1](c01-determinism.md) — the deterministic, non-concurrent event loop; `finalize` runs once after it; the determinism / graph-as-data boundary.
- [C6](c06-firing-policy.md) — the co-freshness of a record's K columns.
- [C7](c07-scalar-soa.md) — the four base scalar types, the tag-free `Cell` carrier, records as bundles of base columns, zero per-cycle allocation.
- [C9](c09-fractal-composition.md) — graph-as-data; `param_space` as a read-only projection; same-type fan-in disambiguation by name.
- [C12](c12-atomic-sim-unit.md) — the aggregated param-space the optimizer sweeps.
- [C18](c18-registry.md) — `FieldSpec.name` as metadata for sinks and the playground.
- [C19](c19-bootstrap.md) — the value-empty recipe, the pre-build signature, and inline order.
- [C20](c20-strategy-harness.md) — the sweep axis; the search-range is the run's; a `timestamp` axis is structural.
- [C22](c22-playground-traces.md) — read-only surfacing of the composite `doc` and the blueprint view.
- [C23](c23-graph-compilation.md) — names as non-load-bearing debug symbols; positional (by-index) identity.

> History: [c08-node-contract.history.md](c08-node-contract.history.md)