docs(site): publish cross-language conformance as a citeable page#955
Merged
Conversation
Add a permanent /conformance page to the agentreceipts.ai Starlight site that leads with the interop claim — three independent SDKs (Go, Python, TypeScript) verify one another's receipts against a shared Ed25519 keypair, over a positive corpus and a MUST-reject corpus, across four pinned spec versions. Include a results matrix whose vector counts are generated from the frozen vector files by scripts/conformance_matrix/count.py (not hand-typed), an honest seed-level coverage statement, commit-pinned permalinks to every frozen vector set, and a run-it-yourself pointer. Cross-language signature verification is CI-enforced (sdk-go/sdk-py/sdk-ts and cross-sdk-tests workflows run it on every relevant push and PR), so the page asserts CI enforcement and links the workflows. Surface the credential from where it was buried: rewrite cross-sdk-tests/README to lead with the interop story (contributor note moved lower), and add a prominent Conformance link plus section to the top-level README.
Code-review follow-ups on the conformance count emitter: - Fix the module docstring, which pointed at a non-existent site/src/content/docs/specification/conformance.mdx; the page lives at site/src/content/docs/conformance.mdx. - Count version-pinned vectors by JSON object type rather than a metadata denylist, so a future scalar metadata field cannot silently inflate a citeable count. Add a regression test for that case. Counts are unchanged (total 69).
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a citeable “Conformance” page to the Starlight documentation site, documenting and linking the repository’s cross-language receipt interoperability (Go/Python/TypeScript) and the frozen vector corpus used to enforce it. It also introduces a small, dependency-free script to generate the conformance matrix vector counts from committed JSON, and updates README entry points to surface the conformance claim.
Changes:
- Add
sitedocumentation page at/conformance/describing cross-SDK interop, a pinned results matrix, CI enforcement, and reproducible commands. - Add
scripts/conformance_matrix/count.py(+ unit tests) to count vectors directly from committed corpora and emit table/MD/JSON outputs. - Update repository readmes to lead with the interop story and link prominently to the conformance page.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| site/src/content/docs/conformance.mdx | New conformance page describing cross-language verification, results matrix, CI links, and reproduction steps. |
| site/astro.config.mjs | Adds “Conformance” to the site navigation/sidebar. |
| scripts/conformance_matrix/count.py | New vector-count emitter used to keep the published matrix counts reproducible and non-hand-authored. |
| scripts/conformance_matrix/test_count.py | Unit tests validating counting logic and output shape over real committed vectors. |
| scripts/conformance_matrix/AGENTS.md | Local run instructions and explanation of counting rules for the script directory. |
| README.md | Adds a top-level “Conformance” link and section explaining the interop suite. |
| cross-sdk-tests/README.md | Rewrites to lead with the interop claim and adds instructions for reproducing published vector counts. |
- conformance.mdx "Run it yourself": wrap each per-suite command in a subshell so `cd sdk/go` no longer leaks into the next line; the snippet is now runnable top-to-bottom from the repo root. - cross-sdk-tests/README: the surrounding commands run from cross-sdk-tests/, so point the count.py invocation at ../scripts/... and note the script resolves the repo root itself. - count.py: read vector JSON with explicit encoding="utf-8" for reproducible, locale-independent counts, and catch UnicodeDecodeError in main() so a non-UTF-8 file exits 1 (documented) instead of tracing back. Counts unchanged (total 69).
ojongerius
force-pushed
the
claude/conformance-credential-page-gu24y5
branch
from
July 2, 2026 20:16
545d4eb to
02799d8
Compare
Move Conformance from a flat top-level sidebar item into the Ecosystem group, above Landscape. Link it from the homepage: a callout after the architecture diagram and an entry in the "Explore the spec" list.
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.
Add a permanent /conformance page to the agentreceipts.ai Starlight site that
leads with the interop claim — three independent SDKs (Go, Python, TypeScript)
verify one another's receipts against a shared Ed25519 keypair, over a positive
corpus and a MUST-reject corpus, across four pinned spec versions. Include a
results matrix whose vector counts are generated from the frozen vector files by
scripts/conformance_matrix/count.py (not hand-typed), an honest seed-level
coverage statement, commit-pinned permalinks to every frozen vector set, and a
run-it-yourself pointer.
Cross-language signature verification is CI-enforced (sdk-go/sdk-py/sdk-ts and
cross-sdk-tests workflows run it on every relevant push and PR), so the page
asserts CI enforcement and links the workflows.
Surface the credential from where it was buried: rewrite cross-sdk-tests/README
to lead with the interop story (contributor note moved lower), and add a
prominent Conformance link plus section to the top-level README.