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](c26-input-binding.md)). 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](c20-strategy-harness.md)/[C21](c21-world.md)). 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](c18-registry.md)); 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](c26-input-binding.md)):
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).

**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). 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](c25-role-model.md) — 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](c23-graph-compilation.md));
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](c26-input-binding.md) — the input-side twin (`input_roles`); `check_root_roles_bound`, the mandatory-input counterpart
- [C23](c23-graph-compilation.md) — compilation/lowering and the deferred DCE cycle the tap design anticipates
- [C18](c18-registry.md) — the trace store and registry the tap series feed; order statistics live sink-side
- [C20](c20-strategy-harness.md), [C21](c21-world.md) — the tier ontology behind run-mode recording authority
- [C8](c08-node-contract.md) — the node/sink contract (a no-out-edge producer as a valid runnable sink)