docs: retire Relay V1 and registryctl from the published docs - #709
Merged
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 397764ca2c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
jeremi
force-pushed
the
agent/docs-relay-v2-cutover
branch
from
August 11, 2026 05:34
397764c to
189bac5
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 189bac5a1c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
v0.19.0 replaced the configuration-driven Relay 1.0 runtime with the contract-compiled Relay V2 runtime (`relay`) and retired `registryctl` in favour of `relayctl`. The published documentation still described the retired runtime as the product a reader adopts, so it taught capabilities no shipped binary has. Retired pages are deleted rather than archived, and every removed route carries a redirect to its nearest live successor. The spec layer is rewritten against the V2 surface instead of being withdrawn, and `rs-pr-registryctl` becomes `rs-pr-relayctl`. Correct the standards register against the post-cutover product ids. The id `registry-relay` now denotes V2, so every claim V2 does not implement was a false public claim: DCAT, BRegDCAT-AP, OGC API Records, ODRL, OGC API Features, OGC API EDR, FHIR R4, and SP-DCI are re-scoped, and OpenAPI, SHACL, JSON Schema, JSON-LD, SDMX, and GovStack are repointed at `crates/registry-relay-v2` evidence anchored at v0.19.0. Drop the retired tooling from the docs build and CI: the deleted generators and checks leave the `generate` and `check` chains, the five registryctl tutorial jobs leave `ci.yml`, and the guardrails that pointed at deleted material are either retargeted at their V2 equivalent or removed with the thing they guarded. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Sweep the two defect classes review found remaining after the first pass: Relay audits data requests rather than every request, and a contract binds one or more read-only SQLite sources rather than exactly one. Correct the relayctl release-asset list to the three platforms the release workflow publishes. Add the four Relay V2 sources ops-posture-spec.test.mjs reads to the docs classifier in ci_changes.py, so a runtime change that invalidates a published operational claim runs the test that catches it. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…bar by product The governed-SQLite tutorial built its project by copying an acceptance fixture and writing the database through a Python heredoc, and it never started the service, so a reader finished without seeing an answer or a refusal. Rewrite it as a run transcribed end to end: the reader installs the released binaries, writes the SQL and the contract, watches `check --production` refuse five governance gaps, records the review, seals the package, serves it, and reads both the answer and the audit line behind it. Reorganize the sidebar on one rule, now pinned by the IA test: a page that names one product lives under that product, and the cross-product sections keep only what applies to every deployment. Relay gains its operate pages, Evidence keeps its security model, and both promote their first tutorial beside the overview. Also correct the installer story, which described a runtime-only Linux-amd64 installer and a source checkout neither path now needs, and replace two instructions to start from a repository fixture with links to the tracked worked example. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
The docs build no longer compiles a registryctl authoring-reference generator, so the rust-cache step that warmed it in the docs jobs of `ci.yml` and `docs-pages.yml` restores and saves nothing. Remove it with the tooling it served. The `project-authoring-determinism` job keeps its own registryctl build: that one exercises the crate, which this branch does not retire. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Three `referenceExclusions` globs named generated configuration-reference data and the registryctl authoring-reference generator. This branch deletes those files, and the closure check requires every exclusion to match at least one tracked file, so `generate.py --check-references` fails until they go. The catalog fingerprints `products/relay-v2/CONCEPT.md`, which this branch edits, so its recorded source digest moves with it. Regenerated with `products/identifiers/scripts/generate.py`, not by hand. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
jeremi
force-pushed
the
agent/docs-relay-v2-cutover
branch
from
August 11, 2026 09:06
189bac5 to
b080f90
Compare
`test_docs_deploy_rechecks_latest_published_release` pinned the rust-cache step that warmed the registryctl authoring-reference generator in both the `docs-pages.yml` build job and the `ci.yml` docs job. This branch deletes that generator and the steps that cached it, so the assertions fail on a guard for tooling that no longer exists. There is no V2 equivalent to retarget them at: the docs build compiles no Rust reference generator now. Remove them with the thing they guarded and leave the test to the deploy-recheck ordering its name describes. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dc043f95e7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The relayctl reference claimed seven flat commands. The command line also carries `tooling`, whose `editor` and `language-server` subcommands are the only way to install project schema mappings or host the LSP, so document both and state the nesting. Correct two claims about runtime defaults. `CursorRuntime` and `ShutdownRuntime` make every field required, so the 300 second and 30 second defaults apply only when the whole section is absent, and a partial section is refused rather than filled in. Record that a contract binding any list or search operation must configure `cursor`. Cursors bind search operations exactly as they bind list operations: the compiler gives both a pagination block and the runtime treats the two kinds identically at the source boundary. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
The install instructions claimed one installer publishes both relay and relayctl for three platforms. install.sh accepts Linux amd64 only, downloads only the relay asset, and installs only relay, so the tutorial's relayctl --version call right after the installer could not succeed. Document the two binaries separately and give relayctl its own release-asset download. The audit walkthrough read a phase "attempt" record as proof the caller "was answered". RelayAudit::attempt writes that record before source access and carries no outcome; the terminal record carries it. Describe what the attempt line actually proves. The threat model forbade describing Relay as an Evidence Gateway source hop. AGENTS.md, products/relay-v2/CONCEPT.md, explanation/architecture, and explanation/integration-patterns all document that composition as supported. Narrow the boundary to the inherited-authorization rule it was written for, and correct the same over-reach in the quickstart. Repoint the two release/READINESS.md evidence links this branch broke by deleting their target pages, pinning them to v0.19.0, the last release that carried them. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ff87d0c883
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+86
to
+89
| status: referenced | ||
| claim_level: compares_against | ||
| adoption_mode: not adopted | ||
| used_by: [] |
There was a problem hiding this comment.
After this cutover marks OGC API Features and EDR as unimplemented by maintained products, release/notes/standards-claims-inventory.md:23-25 still describes them as current Relay emissions and links the now-deleted reference/apis/registry-relay.mdx; similarly, release/notes/behavioral-guarantee-claims.md:23-29,69 links other deleted V1 pages without identifying them as historical. A release-readiness review therefore sees claims that contradict the new standards register and cannot follow their evidence. Fresh evidence beyond the corrected READINESS.md links is that these two durable inventories retain unpinned deleted targets; update them for V2 or preserve the V1 rows with stable tag-pinned links.
AGENTS.md reference: AGENTS.md:L280-L282
Useful? React with 👍 / 👎.
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.
Why
v0.19.0 replaced the configuration-driven Relay 1.0 runtime with the contract-compiled Relay V2 runtime (
relay) and retired theregistryctlCLI in favour ofrelayctl. The published documentation was never cut over. It still described the retired runtime as the product a reader adopts, so the site taught spreadsheet ingestion, HTTP sources, OAuth client credentials, Rhai script adapters, PostgreSQL materialization, and baseline approval: capabilities no shipped binary has. The beta-29 manifest states the legacy runtime and theregistryctlbinary are absent from the release.What this does
Deletes retired pages, with redirects. 25 content pages removed.
src/lib/relay-v2-retirement-redirects.mjscarries 114 entries (38 route sources, their.mdtwins, and 39 retired API operation slugs) resolving to 10 live targets. No redirect source collides with a live page, and every target resolves.Rewrites the spec layer rather than withdrawing it.
rs-pr-registryctlbecomesrs-pr-relayctl;rs-pr-relay,rs-arc-g,rs-op-posture,rs-sec-g,rs-dm-manifest, andrs-termsare rewritten against the V2 surface.rs-termsretires the cross-product term "Registry Stack project" in favour of the per-deployment authoring project, which is the name the tooling itself uses (crates/registry-relayctl/src/lib.rs).Corrects the standards register. This is the part worth reading closely.
src/data/projects.yamldefines six product ids and there is noregistry-relay-v2id: after the cutover the idregistry-relaydenotes V2. So everyused_by: registry-relayentry for a standard V2 does not implement had become a false public interoperability claim.Re-scoped (product id dropped, V1 evidence relabelled as a retired record):
used_bynarrowed toregistry-manifest; the catalog routes belonged to V1used_bynarrowed toregistry-manifest; Manifest still publishes static Records item collections, only Relay's live adapter went with V1compares_against,not adopted, no userregistry-manifest;registry-platform-pdp's only consumer was V1compares_against, no user: both were reachable only through the V1 remote-HTTP source modelRepointed at
crates/registry-relay-v2evidence anchored atv0.19.0: OpenAPI (3.1.0, generated per deployment atGET /openapi.json, so there is no product-level document to pin), SHACL, JSON Schema, JSON-LD, SDMX, GovStack. A bogusregistry-relay-v2line insdmx.used_byis deleted.Drops retired tooling from the build and CI. Deleted generators and checks leave the
generateandcheckchains; the fiveRegistryctl tutorial *jobs leaveci.yml; guardrails that pointed at deleted material are either retargeted at their V2 equivalent or removed with the thing they guarded.crates/registryctlRust jobs are kept, since the crate stays in-tree for historical release validation.Fact-checks the surviving prose against
crates/registry-relay-v2. Four review passes read every claim the cutover left standing back to source. The corrections worth calling out:operate/relay.mdxpublished aruntime.yamlexample withsecret:file/secrets/audit-integrity-key.valid_secret_referencepermits no/; the nested form is an explicit rejection test case. A reader copying that example got a startup failure. Everysecret:file/reference in the docs now names a single flat lowercase filename, and the grammar is stated where it is introduced.trusted-context-constraints.mdxanddpi-safeguards-alignment.mdxnamed aprocessingcontext key. The struct field isprocessingDescriptionsunderdeny_unknown_fields, with no serde alias, so the documented document was unparseable.rs-sec-gandrs-op-posture: resource metadata and generated artifacts also answer anonymously when the contract marks that metadata public.glossary.mdxnow matches whatrs-termsalready said.GET /v2/artifacts/{artifactIdentifier}under the contract's metadata visibility, and the route is in the public OpenAPI projection unconditionally.interoperabilityandreviewabilitydefinitions still promised a DCAT catalog and ODRL policy documents from a Relay deployment. Both now attribute each shape to the product that actually emits it.relayctl inspecttakes a database path, not a project;--fixturetakes an identifier, not a path; packaging does open each bound source read-only, so "never opens the institution's database" was wrong.Verification
All green on the settled tree:
docs/site:npm test304/304,npm run checkexit 0 (15348 links, 155 llms, SEO, markdownlint, build),npm run check:cutoverclean,check-evidence-links.mjs65 links verified against local Git objects.github/scripts/test_ci_changes.py45/45release/scripts:test_registry_release80,test_check_gates_inventory70,test_first_country_release_form54,test_check_stable_surface_compatibility16Review round
Rebased onto
mainat #708. Automated review left five findings; four are fixed in the second commit.dpi-safeguards-alignment.mdxstill said one audit record per served request, and six pages still said Relay serves one SQLite source. A contract may declare more than one, and each resource binds to exactly one of them. Swept properly this time.relayctlrelease assets.quickstart.mdxandoperate/index.mdximplied a single platform. The release workflow publishes linux-amd64, linux-arm64, and macos-arm64.ops-posture-spec.test.mjsto readcrates/registry-relay-v2/src/{server,main,contract,startup}.rs, where onmainit readcrates/registry-platform-ops/src/lib.rs. The classifier routed the old dependency to the docs job but not the new one, so a probe route or runtime bound could change and leave RS-OP-POSTURE stale with nothing to catch it. Those four paths are now docs inputs, andtest_ci_changes.pypins both directions: the four route to docs, and a Relay V2 source no docs test reads does not.The fifth finding is real but predates this PR, and I did not act on it.
release/scripts/first-country-release-form.pywas reported as broken by the two deletedcheck-registryctl-*.shscripts it invokes at lines 3374 and 3428. It is broken, but earlier and for a different reason:verify_asset_setruns at line 3266 and requiresregistryctl-{tag}-install.shandregistryctl-{tag}-image-lock.json.release/notes/v0.19.0.mdstates those assets are not included. The form therefore already fails on any v0.19.0 or later tag, roughly a hundred lines before it reaches anything this PR deleted. Its 54 tests pass because the fixtures synthesize the registryctl assets, which is why nothing flagged it at the v0.19.0 cut.Restoring two shell scripts that drive a retired binary would not fix that. The form needs either a
relayctlrebuild or a deliberate retirement, which is release governance rather than a docs cutover. Flagging it for you instead of guessing.Scope note
Root
AGENTS.mdsays to keep a change scoped to one owning area, and this one crosses into.github/,release/,products/, and rootREADME.md. Those edits are forced rather than opportunistic: the deleted docs generators were CI-wired, andrelease/scripts/check-stable-surface-compatibility.pyread files this cutover deletes. Splitting them out would leave the tree red between PRs. Flagging it rather than hiding it.The two
products/files are there because they are published.products/relay-v2/CONCEPT.mdbecomes the public Registry Relay overview in this PR, and it said in the present tense thatregistryctl"is not renamed, migrated, deprecated, or otherwise changed" (plus two "Relay V1" labels where the subject is V2). Publishing that verbatim would have shipped a denial of the retirement this PR documents, so those four sentences are corrected in place.products/evidence/README.mddescribedevidencectlas being "likeregistryctlfor the rest of the stack"; it now saysrelayctl.One structural question for you.
CONCEPT.mdis an approved scoping document, written before the work, in "this work / non-goals / deferred" register, 873 lines long. Manifest and Evidence each publish a purpose-written overview (products/manifest/docs/overview.md,products/evidence/README.md). Relay is now the only product whose public overview is an internal concept doc, and it sits atnav_order: 0. I corrected what was false rather than authoring a replacement, because that is your call, not mine.release/contracts/selected-metrics.jsonis emptied because Relay V2 exposes no metrics endpoint and the V1 binary does not ship. Each retired family is recorded inRETIRED_SELECTED_METRICSwith a stated reason, so the compatibility gate still tells a deliberate retirement apart from a regression.