86b9cf0 · Oversight

Add registry v1 stability note

Document the v1.0 candidate route surface, registry error envelope, conformance gate, and remaining burn-in gates for operators. Update the README, roadmap, deployment guide, spec draft, and changelog to point at the candidate profile.

Co-authored-by: Codex (GPT-5.4) <noreply@openai.com>

86b9cf0 Zion Boggan committed on Jun 1, 2026 (3 weeks ago)

CHANGELOG.md +5 -0

		@@ -48,6 +48,11 @@
		now checks `/tlog/range` response shape plus representative
		`signature_invalid`, `sidecar_mismatch`, `missing_field`, and `not_found`
		error envelopes, raising the live/in-process harness to 38 checks.
	+	- Registry v1 candidate stability note. Added
	+	`docs/REGISTRY_V1_STABILITY.md`, which names the candidate-frozen route
	+	surface, JSON field families, error envelope, conformance gate, breaking
	+	change rules, and remaining v1.0 burn-in gates for independent registry
	+	operators.
		- GitHub Actions runtime hygiene. Main CI workflows opt into the GitHub
		Actions Node 24 runtime before the hosted runner default changes.
		- Rust policy test parity. Fixed the `oversight-policy` crate's manifest

README.md +5 -2

		@@ -110,10 +110,13 @@ silently skipped.
		The Python reference registry now has matching tlog recovery and range
		validation, including exact `leaf_data_hex` persistence for newly appended
		leaves.
	+	`docs/REGISTRY_V1_STABILITY.md` now records the registry v1.0 candidate
	+	wire-format freeze: the endpoint set, error envelope, canonicalization rules,
	+	sidecar authority rule, and conformance gate are the operator burn-in target.

		The next Rust-registry gate is operational burn-in: longer-running deployment
	-	tests against real operator databases and a final wire-format stability
	-	declaration before v1.0.
	+	tests against real operator databases and a final v1.0 release tag against the
	+	candidate profile.

		## Quick start

docs/REGISTRY_DEPLOYMENT.md +4 -1

		@@ -151,6 +151,8 @@ for startup recovery and `/tlog/range`; newly appended records include
		Both reference registries return the registry v1 error envelope
		`{"error":{"code":"...","message":"..."}}` for registry failures, and the
		live conformance harness checks representative envelope codes.
	+	`docs/REGISTRY_V1_STABILITY.md` defines the candidate-frozen v1.0 route,
	+	field, and error-envelope surface that operators should burn in against.

		## Rust Registry Burn-In Checklist

		@@ -169,5 +171,6 @@ reference registry to the Rust Axum registry:
		7. Fetch `/.well-known/oversight-registry`, `/tlog/head`, `/tlog/range`,
		and at least one `/evidence/{file_id}` bundle, then verify the evidence
		bundle with an independent client.
	-	8. Keep the Python database and tlog as rollback artifacts until the Rust
	+	8. Compare the deployed surface with `docs/REGISTRY_V1_STABILITY.md`.
	+	9. Keep the Python database and tlog as rollback artifacts until the Rust
		service has completed the operator's burn-in window.

docs/REGISTRY_V1_STABILITY.md +92 -0

		@@ -0,0 +1,92 @@
	+	# Registry v1 Stability Note
	+
	+	Status: v1.0 candidate profile, dated 2026-05-31. The registry v1 surface is
	+	still formally draft until the first v1.0 release tag, but the wire contract
	+	described here is the compatibility target for operator burn-in.
	+
	+	This note exists so independent registry operators can tell which parts of the
	+	current spec are expected to remain stable, which parts may still change before
	+	v1.0, and what kind of change would require a new compatibility profile.
	+
	+	## Candidate-Frozen Surface
	+
	+	The following route shapes and response families are candidate-frozen for the
	+	v1.0 line:
	+
	+	- `GET /health`
	+	- `GET /.well-known/oversight-registry`
	+	- `POST /register`
	+	- `POST /attribute`
	+	- `POST /dns_event`
	+	- `GET /evidence/{file_id}`
	+	- `GET /tlog/head`
	+	- `GET /tlog/proof/{index}`
	+	- `GET /tlog/range`
	+	- `GET /p/{token_id}.png`
	+	- `GET /r/{token_id}` and `GET /ocsp/r/{token_id}`
	+	- `GET /v/{token_id}` and `GET /lic/v/{token_id}`
	+	- `GET /candidates/semantic`
	+
	+	The canonical JSON manifest-signature rules, sidecar equality rule, identifier
	+	length ceiling, DNS bridge authentication rule, operator-token header contract,
	+	evidence-bundle core fields, local tlog leaf record fields, and standard error
	+	envelope are also candidate-frozen.
	+
	+	## Compatibility Rules
	+
	+	A compatible implementation MAY add optional fields to JSON objects when older
	+	clients can ignore them safely. A compatible implementation MUST NOT remove
	+	fields, rename fields, change endpoint paths, change canonicalization, weaken
	+	authentication requirements, or return framework-native error shapes instead of
	+	the registry v1 error envelope.
	+
	+	The standard error envelope is:
	+
	+	```json
	+	{"error":{"code":"not_found","message":"unknown file_id"}}
	+	```
	+
	+	The current code vocabulary is `missing_field`, `signature_invalid`,
	+	`sidecar_mismatch`, `issuer_mismatch`, `auth_required`, `rate_limited`,
	+	`not_found`, and `server_error`.
	+
	+	## Conformance Gate
	+
	+	`tests/test_registry_conformance.py` is the executable compatibility gate. As
	+	of this note it runs 38 checks against either the in-process Python reference
	+	registry or a live operator URL:
	+
	+	```bash
	+	OVERSIGHT_REGISTRY_URL=https://registry.example.org \
	+	python3 tests/test_registry_conformance.py
	+	```
	+
	+	Passing the harness is required for an operator to claim registry v1 candidate
	+	compatibility. The harness currently checks identity, liveness, registration,
	+	manifest-signature rejection, sidecar rejection, attribution, evidence bundles,
	+	tlog head/range shape, browser CORS, beacon routes, DNS-event fail-closed
	+	behavior, and representative error-envelope codes.
	+
	+	## Changes That Require a New Profile
	+
	+	The following changes are breaking and require a new profile name or a v2 draft:
	+
	+	- Changing manifest canonicalization or signature-verification bytes.
	+	- Accepting unsigned beacon or watermark sidecars as registry authority.
	+	- Removing or renaming required evidence-bundle fields.
	+	- Changing tlog leaf hashing or inclusion-proof shape.
	+	- Allowing unauthenticated non-loopback DNS events.
	+	- Changing route paths or making a required route optional.
	+	- Returning non-envelope errors for registry failures.
	+
	+	## Remaining v1.0 Gates
	+
	+	Before the first v1.0 release tag, the project still needs:
	+
	+	1. Longer-running burn-in against a migrated operator database.
	+	2. A final live conformance run against the public deployment target.
	+	3. A release note naming the exact `tests/test_registry_conformance.py` count.
	+	4. A v1.0 tag that freezes this profile for downstream implementers.
	+
	+	Until those gates close, this document is a candidate freeze, not a final
	+	standards claim.

docs/ROADMAP.md +4 -2

		@@ -261,8 +261,10 @@ range behavior, with `leaf_data_hex` on newly appended local tlog records.
		Both registry implementations now return the registry v1 `{error: {code,
		message}}` envelope for representative client and server errors, and the
		conformance harness checks those envelopes.
	-	Remaining work: longer-running deployment tests and a wire-format stability
	-	declaration before declaring v1.0 ready.
	+	As of 2026-05-31, `docs/REGISTRY_V1_STABILITY.md` records the registry v1.0
	+	candidate wire-format freeze for operator burn-in. Remaining work:
	+	longer-running deployment tests and a final v1.0 release tag against that
	+	candidate profile.

		---

docs/spec/registry-v1.md +5 -4

		@@ -1,9 +1,10 @@
		# Oversight Registry v1 Interop Draft

	-	Status: draft; the wire format is not stable until Oversight v1.0. This
	-	document tracks the surface a second operator needs to implement to run
	-	a registry that the Python and Rust reference clients can treat as
	-	interchangeable with the origin deployment.
	+	Status: v1.0 candidate draft. The wire format is not final until the first
	+	Oversight v1.0 release tag, but the candidate-frozen compatibility surface is
	+	tracked in `docs/REGISTRY_V1_STABILITY.md`. This document tracks the surface a
	+	second operator needs to implement to run a registry that the Python and Rust
	+	reference clients can treat as interchangeable with the origin deployment.

		## Goals