Files

T

claude bd0c557f16 docs(ledger, glossary): tap-subscribers cycle tidy — C8/C27/C28 lifts, tap subscription vocabulary

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

2026-07-21 23:56:14 +02:00

5.8 KiB

Raw Blame History

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 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); the mechanism ships now, verified sound.

5.8 KiB Raw Blame History

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

Current state

See also

5.8 KiB

Raw Blame History