Repository navigation
Bring the contract and docs up to 0.4.0; add performance, configuration and a changelog - #16
Merged
Merged
Conversation
…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.
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
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.
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.mddescribed 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:
These sections state the rules and leave rationale to
decisions.mdand 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_waitingand 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
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
#anchorin 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.pyandscripts/check_single_host.shpass.#[ignore]d;stale_after_ns0, which turns reaping off;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-clicontainer 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.