Skip to content

docs: accuracy and consistency pass across spec, SDK READMEs, and companion docs - #55

Merged
chuks merged 5 commits into
mainfrom
docs/accuracy-pass-alpha16
Aug 1, 2026
Merged

docs: accuracy and consistency pass across spec, SDK READMEs, and companion docs#55
chuks merged 5 commits into
mainfrom
docs/accuracy-pass-alpha16

Conversation

@chuks

@chuks chuks commented Jul 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

A deep accuracy and consistency review of all protocol documentation, so every doc points to the same canonical facts, plus the narrative-demo and test-gate maintenance that the review surfaced.

Scope: documentation, narrative-demo maintenance, and test-gate coverage; no protocol, SDK, or wire-format behavior changes. Gates green (release-sync, readme-sync, section/link validation, full SDK test suite including the narrative-demo build gate).

Why

The docs are the front door for anyone integrating the protocol. This pass reconciles cross-references, enumerations, and examples that had drifted, and makes the SDK quickstarts copy-paste correct.

SPEC

  • Align the section 4 failure-type list with the closed status set in section 5.9: drop the reserved-only unauthorized and add scope_denied, invalid_scope, delegation_not_authorized.
  • Fix stale cross-references: the VerifyOptions fast-path now points to 5.17, the constraint_unknown fail-closed status to 5.9, and a dangling section 3 principle reference.

README and SDK READMEs

  • Describe the constraints module by its real types (geo, time, speed, amount, rate, resource-path); remove a nonexistent "version" constraint.
  • Fix three compile-breaking C examples, each verified against the public header: the length argument on ratify_challenge_generate and ratify_proof_bundle_create, and the expires_at argument on ratify_delegation_issue.
  • Document the resource-path verification entry point and the advanced and bounds C test suites.
  • Remove unused imports in the TypeScript, Python, and Rust snippets; make the Python receive example self-contained.

Companion docs

  • Move resource-bound authority and deeper chains into the shipped section of the roadmap (they had been left in a future table).
  • Scope the benchmark latency claim to the depths actually measured; keep the deeper-depth figures labeled projections.
  • Reconcile the test-plan fixture enumeration to 79 and align the single-component tamper section with the fixtures that now ship.
  • Refresh the release ladder, SDK status list, resource-profile status, and attribution wording.

Verification

  • check-release-sync.sh: ok (79 fixtures, 54 scopes)
  • gen-sdk-readmes.py --check: readme-sync ok
  • make test-all: ok across Go, TypeScript, Python, Rust, C

Additional accuracy rounds (commits 2 through 5)

Beyond the round-1 items above, later commits on this branch:

  • Replaced the fictional N-by-N interop claim with the real hub-and-spoke mechanism (SDKS, RELEASES); corrected CONTRIBUTING counts and the TypeScript post-quantum dependency; corrected the Python package name and Rust/C crypto libraries.
  • Corrected the resource-path chain algebra everywhere (a child may carry a broader prefix and still verify; effective authority never widens), the C depth-failure status (invalid / chain_too_deep, not delegation_not_authorized), and the multi-party TransactionReceipt description.
  • Fixed the four-versus-five narrative-demo claims; downgraded unverified C RTOS target support.
  • Resolved dangling cross-references: repointed four SPEC references to their named ROADMAP sections and made an ambiguous CHANGELOG reference explicit; preserved correct external (FIPS 204, RFC 8032) and historical references. Every section reference, Markdown anchor, and relative link now resolves.
  • Narrative-demo maintenance: all four demos (Go, TypeScript, Python, Rust) now use RevocationProvider instead of the deprecated closure; fixed an ignored issuance Result; added a Rust-demo build gate (with -D warnings) to make test-all.

Nothing is merged; the alpha.16 tag remains held. Version pins stay at alpha.15 (the release process owns the bump).

chuks added 5 commits July 31, 2026 10:00
@chuks
docs: accuracy and consistency pass across spec, SDK READMEs, and com…
a4c26ad 
…panion docs

Reconcile all protocol documentation to the same canonical facts and fix
drift found in a deep review. No code or protocol behavior changes.

SPEC:
- Align the section 4 failure-type list with the section 5.9 status set
  (drop the reserved-only unauthorized; add scope_denied, invalid_scope,
  delegation_not_authorized).
- Correct cross-references: VerifyOptions fast-path to 5.17, the
  constraint_unknown fail-closed status to 5.9, and a dangling section 3
  principle reference.

README / SDK READMEs:
- Describe the constraints file by its real types (geo, time, speed,
  amount, rate, resource-path); remove a nonexistent version constraint.
- Fix compile-breaking C examples: challenge length argument on
  ratify_challenge_generate and ratify_proof_bundle_create, and the
  expires_at argument on ratify_delegation_issue; verified against the
  public header.
- Document the resource-path verification entry point and the advanced
  and bounds C test suites.
- Remove unused imports in the TypeScript, Python, and Rust snippets and
  make the Python receive example self-contained.

Companion docs:
- Move resource-bound authority and deeper chains into the shipped
  section of the roadmap; scope the benchmark latency claim to measured
  depths; reconcile the test-plan fixture enumeration to 79 and align
  the single-component tamper section with the shipped fixtures; refresh
  release ladder, SDK status, resource-profile status, and attribution
  wording.

Signed-off-by: chuks <891251+chuks@users.noreply.github.com>
@chuks
docs: second accuracy pass across SDK READMEs, contributing guide, an…
fb7fe79 
…d companion docs

Continues the documentation reconciliation. Documentation only; no code,
wire format, or protocol behavior changes. Gates green (readme-sync,
release-sync, link and section-reference validation, full SDK test suite).

Interop and CI accuracy:
- Replace the overstated N-by-N interop matrix claim in SDKS and RELEASES
  with the actual hub-and-spoke mechanism (the Go reference generates the
  byte-equivalence corpus; TypeScript, Python, and Rust assert against it;
  C is validated through the shared conformance fixtures).
- Correct the CI descriptions to the real per-SDK jobs.

Counts, names, and dependencies:
- CONTRIBUTING: fixture count 59 to 79 across all five SDKs, and name the
  TypeScript post-quantum dependency.
- SDKS: correct the Python package name, the Rust and C crypto libraries,
  and the current minimum API surface; qualify C target support (std and
  heap targets, and RTOS only with a std shim; bare-metal points to Rust).
- demos: four narrative demo languages (no C narrative demo); fixture count.

Receipts and cross-references:
- AGENT_TO_AGENT: one hybrid verification per additional cert; receipt
  envelope, fixtures, and SDK APIs shipped; TransactionReceipt is a native
  multi-party envelope, not pairwise-only.
- TRANSACTION_RECEIPTS: normative version corrected to alpha.6.
- SECURITY: repoint the out-of-scope reference to the section that exists.
- TypeScript README: correct a canonical-serialization section reference.

ROADMAP and SDK READMEs:
- Move the released alpha.11 and alpha.12 work out of the planned section.
- C README: reconcile the status table, the entropy and RTOS and
  bare-metal guidance, and the key-generation wording.
- Add a consistent alpha.16 API section to every SDK README (available on
  main, ships in the next release) via the body sources.

Signed-off-by: chuks <891251+chuks@users.noreply.github.com>
@chuks
docs: third accuracy pass covering resource-path algebra, C status, a…
62779c7 
…nd demo build

Addresses defects found in adversarial re-review. Documentation and one test
gate only; no protocol or SDK code changes.

Confirmed defects:
- Rust quickstart and narrative demo destructured generate_agent as a tuple,
  but it returns a Result; both now use .expect(). The Rust demo is a
  standalone cargo project outside the SDK workspace, so it was not built by
  any gate; add its build to test-all so this cannot recur. Verified the demo
  compiles and runs (valid case accepts, all four attack cases reject).
- Resource-path chain algebra was overclaimed as "can only narrow" in the
  root README, EXPLAINED, ROADMAP, and the unreleased CHANGELOG entry. A child
  may carry a broader prefix on the same resource and still verify; effective
  authority can stay the same or narrow but never widen because every upstream
  constraint still applies. Corrected all four to match SPEC 5.7.3 and the
  child_broader_accept fixture.
- C README mapped excessive chain depth to delegation_not_authorized; actual
  behavior is identity_status invalid with error_reason beginning
  chain_too_deep. delegation_not_authorized is for a non-root issuer lacking
  identity:delegate. Fixed both passages and the status table; added time to
  the constraint_denied list.
- Demo and testing docs claimed five narrative demos; there are four
  (Go, TypeScript, Python, Rust). C is exercised through the conformance
  fixtures, not a narrative demo. Corrected the claims and added the C
  conformance command to the rigorous-validation list.

Smaller accuracy fixes:
- Fixture descriptions in SDKS and TEST_PLAN no longer say all 79 assert
  verifier output; each fixture runs through the API for its kind (62 of 79
  exercise bundle verification).
- C RTOS targets (FreeRTOS, Zephyr, thumbv7em-none-eabihf) marked conditional
  and unverified: they need a custom std-providing toolchain and are not gated.

Nits: C alpha.16 section cites both 5.7.3 and 5.16; C abbreviated snippets
labelled; Go pin guidance recommends a commit SHA; TEST_PLAN depth telemetry
uses a 4-through-8 bucket.

Signed-off-by: chuks <891251+chuks@users.noreply.github.com>
@chuks
docs: resolve dangling cross-references in spec and changelog
daafaf3 
Completes the cross-reference sweep for the accuracy pass. Documentation only.

The SPEC referenced ROADMAP by section numbers that ROADMAP does not use (it
has named sections, not numbered ones), so four v1.1 type descriptions pointed
at nonexistent ROADMAP sections. Repointed each to the ROADMAP section by name:

- RevocationPush and SessionToken to "Continuous real-time interactions".
- WitnessEntry and TransactionReceipt to "Tamper-evident transaction streams".

CHANGELOG: an ambiguous "(5.3.1)" now names its target explicitly
(docs/RELEASES.md 5.3.1).

Deliberately preserved, because they are correct:
- FIPS 204 3.4 and RFC 8032 5.1.5 are external-standard citations.
- The CHANGELOG note that a "stale SPEC 4.3 reference" was "corrected to
  5.1/5.7" is accurate historical narrative, not a live link.
- The CHANGELOG reference to docs/RELEASES.md 4.2 resolves to a real heading.

Swept every Markdown file: all section references now resolve to a real
current heading (SPEC, or an explicitly named companion document), all
Markdown anchors resolve to real heading slugs, and all relative links
resolve to real files.

Signed-off-by: chuks <891251+chuks@users.noreply.github.com>
@chuks
demos: use RevocationProvider, fix ignored issuance Result, and harde…
56cb00d 
…n the gate

Narrative-demo maintenance and test-gate coverage; no protocol, SDK, or
wire-format behavior changes.

- The Go, TypeScript, and Python demos used the deprecated legacy revocation
  closure (is_revoked / IsRevoked), scheduled for removal in v1.0.0-beta.1; the
  Python demo printed a DeprecationWarning during the advertised run. All three
  now use a minimal demo-local RevocationProvider (SPEC 17.1), matching what the
  Rust demo already does. The revoked output is unchanged.
- The Rust demo and the Rust README quickstart ignored the must-use Result from
  issue_delegation; both now handle it with .expect(). The Rust demo gate in
  test-all now builds with RUSTFLAGS="-D warnings" so an ignored Result fails
  the gate rather than warning.
- demos/README no longer claims the narrative demos prove byte-for-byte
  canonical-serialization equivalence (they use independently generated keys and
  do not compare signable bytes). It now says each demo signs and verifies using
  its SDK's canonical serialization; byte equivalence is established by the
  fixture and cross-SDK corpus, as the following paragraph already states.

Verified: all four narrative demos (Go, TypeScript, Python, Rust) build and run
with matching accept/reject outcomes; the Python demo no longer emits a
DeprecationWarning; the Rust demo builds clean under -D warnings.

Signed-off-by: chuks <891251+chuks@users.noreply.github.com>
@chuks
chuks merged commit 9fac5e0 into main Aug 1, 2026
14 checks passed
@chuks
chuks deleted the docs/accuracy-pass-alpha16 branch August 1, 2026 16:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@chuks