Edge recorder

[juan-malbeclabs]

A recorder for the edge feed family: it keeps the bytes, and records its own losses inside the archive.

Both halves are what make one question answerable after the fact — did the publisher send what the spec says it must, and did it arrive? Without the bytes there is nothing left to ask. Without the recorder's own losses, every gap it caused is charged to the publisher.

Design: docs/superpowers/specs/2026-08-28-edge-recorder-crates-design.md · Plan: docs/superpowers/plans/2026-08-30-edge-recorder-record-path.md

Phase 1 — the record path

• dz-recorder-core: types, traits, configuration
• dz-recorder-archive: pcapng writer, rotation, manifest, staging watermark
• dz-recorder-replay: the archive as a Source
• dz-recorder-capture: socket mode and AF_PACKET mode
• Injected faults end to end, and their counters
• Cross-language golden vector — still deferred until the Go reader moves to pcapng (the spec's step 2). codec: dz-edge-mbp, and the chain judged by the specification's own rules #67 gets closer without closing it: a Go tool reads bytes that came out of replay, but through a classic pcap this repository writes, not by reading the segment

Phase 2 — health and rollout

• DatagramHeader::peek in dz-edge-core
• dz-recorder-health: the header-only observer and the dz_recorder_* metrics
• The object key: the manifest states where an object lands
• dz-recorder: the binary that wires the three together
• Manifest index table and the shipper contract
• Replay exposes the provenance and the drop scope the archive already records — ArchiveSource hands back capture_drop_scope(), identity(), link_headers() and section_recv_ts_kind(). Landed with the record path and never ticked
• Roll out one host at a time

Phase 3 — the analysis tier

• Sequence-loss detection over any Source
• dz-edge-mbp — the five depth-grain messages, with golden vectors both languages read (codec: dz-edge-mbp, and the chain judged by the specification's own rules #67)
• Subscriber state machine, book, fingerprint
• Replay into the conformance rule set — the mechanism landed in codec: dz-edge-mbp, and the chain judged by the specification's own rules #67 (replay → pcap → dz-conformance, gated in CI against a pinned spec revision, with a negative control). What is missing is running it over real archives rather than traffic a test generated
• Row loaders, idempotent on (object key, sha256)
• Cross-site join

Also landed

• End-to-end tests from a publisher's encoder to replay, over a real socket, gated in CI

• An agreement test: one stream through the live tier and an offline pass, counts compared

• Rows design for a loss and conformance dashboard, DDL executed against a real ClickHouse

• The ClickHouse migration that creates those tables, in the repository that owns the column store

• Bounds on every key the wire controls, in both tiers: instances, eras, delivered ranges, and the sequence values that open them

• The binary's shutdown proved at binary altitude — a real process, a real SIGTERM on a quiet feed, an object and its manifest on the disk

What landed, as merged

PR
#60	the record path
#61	the health tier
#62	end to end, and CI gates it
#63	sequence loss
#65	the binary
#67	dz-edge-mbp, the depth feed across all three ports, and the chain judged by the specification's own 88 rules

487 tests on main, debug and release, clippy and fmt clean, with afpacket and
e2e gating every pull request. Five rounds of review across the stack found
twenty-seven defects; every one of them carries a test checked by reverting the
behaviour it asserts.

The Reset Count wrap is settled (#67, Numbering the eras in the rows
design): the loader records where each era opened — one row per reset, every
column observable inside the object being loaded, so the loader stays a pure
function of it — and era_index is a dense rank over that table rather than a
number anybody stored. An object whose first era might be a continuation of one
in a missing object is written anchor_certain = false and its gaps report
unverifiable, because merging two sequence spaces hides every gap between them
and inventing a boundary puts a reset that never happened in front of an
operator.

What a deployment still supplies: the configuration, DZ_RECORDER_BUILD_COMMIT,
the shipper behind completed_dir, the disk, and a scrape of a metrics endpoint
that should not be bound to a public interface. What an administrator still
supplies: test, afpacket and e2e in the branch ruleset's required checks —
the workflow is unfiltered now so they can be listed, but this repository's files
cannot list them.