Aura/docs/design/contracts/c27-declared-taps.md

C27 — Declared taps: named measurement points bind sinks run-mode-aware

Guarantee. A blueprint may declare taps — named, pure output-side declarations { name, from: {node, field} }, the output-side twin of input_roles (C26). A tap names an interior producer's output field without naming a sink, exactly as a Role names an abstract input without naming a source. At compile the tap resolves — and, for an interior composite, hoists to the root — through the same lowering remap edges and OutField re-exports use (resolve_tap_wire, a flat_taps accumulator threaded through the lowering recursion), landing in FlatGraph.taps as a FlatTap { name, node, field } whose name survives compile and is load-bearing for by-name binding (like SourceSpec.role, #275).

Binding is run-mode-aware: the run-mode-owning layer constructs a consumer at a bound tap via FlatGraph::bind_tap, which takes a caller-built Box<dyn Node> sink (so the engine keeps its aura-core-only production dependency — it never constructs a domain sink type) and appends it plus an edge before bootstrap. What consumes a tap is declared per run by a tap plan (#283): a Named { label, params } subscription resolves against a layered fold registry (core vocabulary record | count | sum | mean | min | max | first | last; growth is a new Rust entry, C25, injectable by higher layers without a core edit), and Live(closure) is the single deliberately non-data variant. Both declared-tap entry points — the single-run path (run_signal_r) and the bare measurement path (run_measurement) — bind through one shared wiring pair, so they cannot drift: record persists the full series at constant memory through the trace store's streamed write path (env.trace_store()), folds keep an O(1) accumulator and land one summary row at finalize, so the tap columns surface through the same tooling the campaign path feeds; a sweep/reduce run leaves taps unbound.

Forbids. A tap carrying a channel endpoint or effect in the serialized artefact — recording policy is run-mode authority, not fragment-embedded (a fragment must not drag its measurement decisions into every harness that embeds it; the tier ontology, C20/C21). The engine constructing a domain sink type (the aura-core-only wall — the sink is caller-built). Order statistics (median, etc.) inside the graph — they stay sink/analysis-side (C18); multi-instrument study inputs stay harness/World tier.

Non-error. An unbound tap is inert, not a fault — unlike an unbound root input role, which check_root_roles_bound rejects (C26): observation is optional, a fed input is mandatory. A declared-but-unbound tap compiles and runs, its producer evaluating and its output discarded (a no-out-edge producer is a valid runnable sink — the Kahn sort emits it, check_ports_connected gates only inputs). The CLI surfaces this to the human as a note (aura: note: declared tap "…" unbound this run) printed from the unbound names the entry points return beside their report — never emitted by the library itself (#297).

Why. Observability must be expressible in a hand-authored blueprint — the measurement-shaped study computes in the graph and surfaces via taps, no throwaway Rust harness — while recording stays a run-mode decision, not a fragment-embedded effect. Taps are designed DCE-compatible (a bound tap is a natural DCE root, an unbound tap a dead declaration) but this contract does not depend on DCE: an unbound tap's sink is simply never constructed (build-time elision, which the engine already tolerates). (#282, 2026-07-18.)

Current state

The tap types are realized in aura-engine: the authoring-level Tap (crates/aura-engine/src/blueprint.rs, the output-side twin of Role), the compiled FlatTap { name, node, field } and the FlatGraph.taps field (crates/aura-engine/src/harness.rs), and FlatGraph::bind_tap, which appends a caller-built Box<dyn Node> sink plus an edge and raises a typed UndeclaredTap on a tap the graph does not declare (duplicate detection across binds is the caller's — the method keeps no cross-call state). Lowering resolves and hoists taps via resolve_tap_wire and the flat_taps accumulator (blueprint.rs). The subscription seam is aura-runner::tap_plan (#283): TapPlan/TapSubscription, the layered FoldRegistry (each entry carries a doc line — the help surface and the roster-enumerating refusal — plus a scalar-typed param schema; all core entries are param-less today, the seam ships in every entry's build signature), and the shared bind_tap_plan/BoundTaps pair called by both declared-tap entry points, run_signal_r (aura-runner::member) and run_measurement (aura-runner::measure) — both arms of the single CLI verb aura exec (#319), whose repeatable --tap TAP=FOLD selector (#310) makes the Named selection data-reachable: no flag keeps the record-all default, any flag replaces the plan entirely (unlisted taps stay unbound/inert). BoundTaps carries the unbound tap names out (skipped: Vec<String>), riding beside the returned report rather than inside it, so the CLI — not the library — prints the unbound-tap note (#297). Since #309 both entry points return that pair as a named RunOutcome { report, skipped, trace_name }, the third field being the trace-store handle the run recorded under — since #311 the run's own identity, <render-name>-<id8>, minted from the manifest the entry point now assembles before the bind and reuses for the record (Some under exactly the condition that opens the write path, None otherwise) — the same beside-the-report discipline, widened rather than re-cut: the record keeps its shape and the shell renders the handle. The boundary is thereby fixed in place: selecting a subscription is run-mode authority, exercised by the run-mode owner — on the one-shot path the CLI invocation itself, a projection exercising this contract's authority, not a second home for intent under C25 — while adding a fold stays a Rust entry (role 2). The campaign/document carrier, and the reconciliation of the presentation-tap namespace (persist_taps) with declared taps it requires, is deferred to the Measurement-reachable milestone (#312/#327, minuted on #312). The record consumer (aura-runner::tap_recorder::TapRecorder) holds the trace store's streaming writer in-graph — initialize opens (deferred acquisition), eval appends (Timestamp, Cell) (zero per-cycle heap, #77), finalize reports exactly one terminal outcome; fold consumers (aura-std::TapFold) land one summary row, emitted at finalize and stamped with the instant of the last contributing (warm) value — first alone pins the first contributing instant; min/max deliberately do not carry the extremum's timestamp (a whole-window row privileges no interior instant) — ratified as-is, #335; live closures run inline (aura-std::TapLive). The sweep/reduce path never calls bind_tap.

The chain-pruning benefit — a sweep paying zero for the study wires behind an unbound tap — is deferred to the future DCE cycle (C23); the mechanism ships now, verified sound.

#337 (2026-07-26 harvest) ships the positive discovery view: Composite::declared_taps() (crates/aura-engine/src/blueprint.rs) walks the blueprint depth-first collecting (tap name, source wire, column kind), bare at every depth, bounds-total over an invalid wire; graph introspect --taps <FILE|ID> renders one row per declared tap (a tap-less blueprint is a stderr-noted listing, exit 0). This closes the recovery-only discovery gap: before #337, the only way to learn a blueprint's declared tap names was provoking bind_tap_plan's UnknownTap refusal roster (#333) — a real name surfaced only as the side effect of naming a wrong one first. The refusal roster itself is unchanged and remains the recovery half (what to do once a tap name is already wrong); --taps is the discovery half (learning the right names up front).

See also

• C26 — the input-side twin (input_roles); check_root_roles_bound, the mandatory-input counterpart
• C23 — compilation/lowering and the deferred DCE cycle the tap design anticipates
• C18 — the trace store and registry the tap series feed; order statistics live sink-side
• C20, C21 — the tier ontology behind run-mode recording authority
• C8 — the node/sink contract (a no-out-edge producer as a valid runnable sink)