Skip to content

Bring the contract and docs up to 0.4.0; add performance, configuration and a changelog - #16

Merged
JBailes merged 1 commit into
mainfrom
docs/ring-v0.4-docs
Oct 31, 2026
Merged

JBailes merged 1 commit into
mainfrom
docs/ring-v0.4-docs

Conversation

@JBailes

@JBailes JBailes commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

What

The contract and the docs caught up to 0.4.0, and three documents that were missing now exist.

The largest gap was in the contract itself. spec/wire-and-segment.md described none of D13 to D16, so someone implementing the ring from the spec, which is what the spec is for, would not have found the doorbell protocol, liveness or the telemetry region. They existed only as decision records and explanatory pages.

The spec

  • New sections:

    • Doorbells: the sleeper and signaller protocol, with its fences.
    • Liveness: process exit, announced detach, stale heartbeat, and the client's watch on the host.
    • Telemetry: the record, ring, loss, wake-up, pacing and grant.

    These sections state the rules and leave rationale to decisions.md and offsets to the vectors.

  • The attach handshake gains the capabilities word and a table of its three bits. Descriptors are now 3, 5 or 7, not "three".

  • Region diagram: host_waiting, the lease view, client_waiting and the telemetry region.

  • Security: the doorbell and telemetry threat notes.

  • Corrected: the decision range (D1 to D16, was D1 to D12) and the wire vector counts (14 positive and 16 negative, was 10 and 13). The open question on arena routing is moved to answered: D12 routes arena payloads by reference, and they are no longer "dropped with a count". The em dashes in the diagram labels are colons.

  • spec/README.md: what the ring owns now includes doorbells, liveness and the telemetry hand-off.

The docs

  • Architecture: the memory map and region table gain the waiting flags and the telemetry region, and the descriptor sentence matches the spec.
  • Attach and admission:
    • The reply and the listener diagram reach 7 descriptors.
    • A pidfd slot is released when its process exits, not at the next attach.
    • Detach is announced.
  • Implementations and conformance:
    • The CI list names all four C builds, including Release with assertions kept.
    • The pitfalls add the doorbell fences and telemetry pacing.
    • Heartbeats are skipped when process liveness is granted.
  • Versions and releases: a C ABI change takes a minor bump within 0.x, and the 0.4.0 pacing fields come from reserved space.

New

  • docs/performance.md: what the benchmark measures, and how to pin it. It explains why a number compares only on its own machine: the record has 83 ns and 127 ns from different machines and code, and 144 against 157 ns from CCX placement alone. It also covers what the three budget checks catch, and what they cannot.
  • docs/configuration.md: every environment variable, flag and build option the implementations read, taken from the source. The libraries read two variables, both for telemetry pacing. It also lists the API-only settings an operator asks about.
  • CHANGELOG.md: 0.1.0 to 0.4.0. Each entry comes from the merged pull requests and the tag ranges, and says what a consumer gets and what stays compatible.

Checked

  • Every relative link and #anchor in the 19 Markdown files resolves under GitHub's slug rules. The checker was tested against a file with a known bad anchor and a missing file first, and it caught both.
  • vectors/check_vectors_current.py and scripts/check_single_host.sh pass.
  • Each new claim was checked against the source. Checking caught several errors in my drafts, all corrected:
    • a pidfd fallback that does not exist;
    • a Rust test said to skip that is actually #[ignore]d;
    • stale_after_ns 0, which turns reaping off;
    • two benchmark numbers attributed to the same build.
  • Prose follows voice-guide: no authorial em dashes, no intensifiers, and bulleted items that lead with a bold noun phrase.

Not checked: the Mermaid diagrams were not rendered. Rendering needed the mermaid-cli container image, and pulling it was not permitted here. Two diagrams changed, both with plain syntax: the architecture memory map (one node and one subgraph added) and two message labels in attach and admission. GitHub renders them in this PR's file view.

…guration and a changelog

The wire spec described none of D13 to D16. It now states the doorbell
protocol, liveness and detach, the telemetry region, record, hand-off and
pacing, and the attach capabilities with their 3, 5 or 7 descriptors. It
also corrects the decision range, the wire vector counts, and the open
question on arena routing, which D12 settled.

The docs pages had the same drift: three descriptors, no waiting flags
or telemetry region in the memory map, release at the next attach rather
than at process exit, unannounced detach, and a CI list without the
Release build.

New pages: performance (what the bench measures, why a number belongs to
its machine, what the budget enforces), configuration (every variable,
flag and build option the implementations read), and CHANGELOG.md for
0.1.0 to 0.4.0, sourced from the merged pull requests.
@JBailes
JBailes merged commit b962ef0 into main Oct 31, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant