claude
1baee774bb
Decide #310's data-authorability fork as (b), split by run-mode authority: selecting a Named fold subscription is data-reachable on the one-shot run path; adding a fold stays a Rust entry (role 2, C25). `aura run` gains a repeatable --tap TAP=FOLD selector feeding the existing TapPlan seam: no flag keeps the record-all default; any flag replaces the plan entirely (unlisted taps stay unbound — C27 inert, non-error). Validation stays in bind_tap_plan (roster-enumerating label refusal, typed UndeclaredTap, both before store I/O); parse-level refusals (malformed pair, duplicate tap) exit 2 via the verb's usage convention. Rejected alternatives (minuted on #310 with the skeptic-pass rationale): an op-script/blueprint carrier (C27 forbids recording policy in the serialized fragment); ratifying Rust-only (softens a designed-in promise with effort as the only rationale). The campaign/document carrier and the persist_taps/declared-tap namespace reconciliation are deferred to the Measurement-reachable milestone (#312/#327, minuted on #312). Ledger: C27 Current state records the boundary; the superseded sentence moved verbatim to the new c27-declared-taps.history.md sidecar; the glossary tap-plan paragraph updated, fixing the pre-existing inaccuracy that named `aura measure` a record-all-passing verb (it is the post-hoc IC analysis and constructs no tap plan). Verification: 5 new unit tests (parse branches), 5 new binary-level selector tests incl. a byte-identity pin of an explicit all-record plan vs the record-all default (C1), 1 measurement-arm test; full workspace suite green; clippy -D warnings clean. Independent opus diff review: approved, no Important/Minor findings (nits: inert-arm generic refusal, a=b=c falling to the roster refusal — accepted as-is). closes #310
6.6 KiB
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).
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 run, 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 — 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; 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.
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)