claude
bd0c557f16
Cycle-close audit for the #283/#77 tap-subscribers cycle (09994b8..6e3f394). Architect review: code contract-clean; what holds — C1/C7/C8 (empty-output caller-built consumers, (Timestamp, Cell) zero-heap payload, lifecycle hooks inside the sequential loop, byte-identical twin-run and streamed-vs-legacy byte-equality pins), C28 (assembly-crate placement of the writer-holding consumer, c28_layering guard green), C25 (registry growth = new Rust entry, data-expressible Named form, roster-enumerating refusals). All drift items were doc lifts, resolved in this commit: - C8: the lifecycle is now a symmetric pair — initialize() as finalize's start-of-stream mirror (infallible by signature; acquire-in-initialize, degrade-to-inert, surface-once-at-finalize); history sidecar records the refinement and the #77 resolution the old Deferred paragraph still carried as open. - C27: Guarantee and Current state now describe the shipped model — tap plan (Named{label, params} | Live) over the layered fold registry, BOTH entry points (run_signal_r AND run_measurement) on the one shared wiring pair, record streaming at constant memory. - C28: aura-runner now defines one graph node of its own (the in-graph record consumer — exactly the graph-meets-persistence assembly position); the #297 refusal-site count grows ~20 → ~24 (the four tap-plan refusals, already typed before the exit). - glossary §tap: the subscription/fold-registry sense added; Avoid line steers probe/monitor/scope away from the observation slot. Bench (report-only, loadavg 5.8 > 2 on the box — read with care), all fingerprints OK, no regression: engine_throughput bars_per_s 14005262 wall_s 0.714s Δ bars_per_s +3.0% wall_s -3.0% ingest_throughput bars_per_s 12970670 wall_s 0.387s Δ bars_per_s +0.5% wall_s -0.5% campaign_sweep cpu_percent 2202.0 peak_rss_mb 92.2 wall_s 1.396s Δ cpu_percent +1.5% peak_rss_mb -6.1% wall_s -1.5% campaign_heavy cpu_percent 2155.0 peak_rss_mb 94.8 wall_s 5.585s Δ cpu_percent +1.8% peak_rss_mb -3.5% wall_s -0.4% cli_fixed_cost help_ms 1.5ms run_ms 3.6ms Δ help_ms -1.8% run_ms -2.6% No baseline update (report-only surface; no ratify due). Correction on 6e3f394's body: "no Probe symbol is introduced anywhere" — introduced is the operative word; the pre-existing aura-core test fixture `struct Probe` stays, as the cycle's design record specified. Follow-ups on the tracker: #308 (legacy Recorder surface migration), #307 (binary trace format). Cycle spec/plan working files discarded. refs #283 refs #77
89 lines
5.8 KiB
Markdown
89 lines
5.8 KiB
Markdown
# 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 CLI verbs pass a record-all plan. 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](c23-graph-compilation.md));
|
|
the mechanism ships now, verified sound.
|
|
|
|
## 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)
|