Cut spec release v0.1.0: discovery + sync chapters, vectors, capture rig#1
Merged
Conversation
Complete the wire-protocol specification to a releasable state. - spec/01-discovery.md: full multicast discovery transport, _asdp_v framing, Alive/Response/ByeBye types, peer-state payload entries and byte layouts, ttl timeout/pruning model. - spec/02-sync.md: _link_v ping/pong measurement, ghost-time transform and median offset filter, tmln timeline model with beat-origin priority, session election/merge, stst start/stop propagation, quantum/phase model. Algorithm rationale cited to Goltz, LAC 2018. - tools/capture-vectors.sh + .github/workflows/capture-vectors.yml: build the pinned reference and record loopback scenarios to vectors/*.pcap. Reference source is cloned outside the repo, never vendored. - vectors/: discovery-join-leave, sync-tempo-change, sync-start-stop, audio-channel-lifecycle captures (CC0) with README. - Resolve open questions in 00-overview and 03-audio against the captures and reference runtime behavior; verdicts recorded in CHANGELOG. One IPv6 question deferred (no v6 interface available). - Bump chapters and README status to v0.1.0. https://claude.ai/code/session_01PY9eo7cNgFHPfKjChRA1qK
First piece of the evidence-first rebuild: decodes all three protocol families field-by-field from captures and generates manifests of observed facts (topology, gateways per peer, message-type counts, payload-entry shapes, audio-buffer parameters). Vector docs and spec claims will quote this output instead of hand-narrated descriptions, so they cannot drift from what a capture actually contains. https://claude.ai/code/session_01PY9eo7cNgFHPfKjChRA1qK
Full re-derivation of all four chapters and the vector pipeline so that no published claim can drift from what was actually observed: - Evidence classes (Chapter 0 §1.1): every claim tagged wire-observed [W], behavioral [B], or normative [N]; changelog verdicts carry the class their resolution rests on. - Vectors recaptured in isolated network namespaces (single-gateway baseline, deliberate multi-gateway scenario) with observed-fact manifests generated from the pcap bytes (tools/analyze_pcap.py) and per-scenario structural assertions (tools/check_vectors.py) that fail hollow captures. Audio scenario now evidences request keepalive repetition and a mid-stream tempo change. - Corrections found by the audit: multicast loopback is enabled only on loopback-address gateways (Ch.1 §2 previously claimed the opposite); removed a citation to a vector that does not exist; the IPv6 size row is now labeled as arithmetic, not observation. - Chapter 2: exact inverse phase-encoding equations; join-rule behavior under measurement noise stated honestly; phase alignment operations given neutral spec-defined names (also applied in Chapter 3). - Chapter 3 additions from re-verification: buffer flush rules, first chunk sequence number, multi-chunk datagrams vs the 576-byte aspiration, request dispatch by channel id. - upstream-watch workflow implemented (README previously referenced a file that did not exist); capture workflow now runs the manifest + assertion pipeline. https://claude.ai/code/session_01PY9eo7cNgFHPfKjChRA1qK
Task: reference-vs-candidate conformance testing for the clean-side implementation. Homed in this repository rather than authored into link-wire-rs: the harness is dirty-side-authored tooling, so it belongs behind the spec repo's provenance-reviewed release gate, and the clean team integrates it themselves from a release tag (a thin CI workflow with zero protocol knowledge; example provided). - conformance/run.py: scenario runner emitting plain-text pass/fail observations (discovery join/leave, tempo follow, start/stop, beat phase alignment, audio announce/subscribe/stream/bye). No protocol logic: every assertion is on observable endpoint behavior. - conformance/hut_adapter.py: drives the reference hut binaries through their own keyboard/stdout interface, translating to the documented candidate contract; doubles as the self-test stand-in candidate. - conformance/CANDIDATE-CONTRACT.md: the stdin/stdout line protocol a candidate exposes (application-observable state only). - conformance/run-isolated.sh: netns + reference build + dummy JACK wrapper; tools/build-reference.sh extracted and shared with the capture rig. - conformance/example-candidate-ci.yml: copy-paste workflow for candidate repositories (spec fetched at a pinned release tag into CI caches, never vendored). - .github/workflows/conformance-selftest.yml: CI runs the harness reference-vs-reference; all 14 observations pass locally. - PROVENANCE.md: firewall item 2 now covers executing the released harness; artifacts table includes it. https://claude.ai/code/session_01PY9eo7cNgFHPfKjChRA1qK
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Complete the wire-protocol specification to a releasable state.
https://claude.ai/code/session_01PY9eo7cNgFHPfKjChRA1qK