Config reference drift guardrail: committed JSON Schema per product

[jeremi]

Part of the 1.0 release-readiness push.

Context

PR #355 added typed project-authoring schemas, and PR #364 added typed Notary PostgreSQL authoring. The remaining drift risk is the complete runtime configuration accepted by Registry Relay and Registry Notary. Hand-maintained references can diverge from strict deserializers and create avoidable implementer failures.

Scope

• Generate a product-owned JSON Schema for the complete Relay configuration and a separate product-owned JSON Schema for the complete Notary configuration.
• Include shared platform types only through the product schema that embeds them. Do not create one shared Relay/Notary configuration model.
• Commit schemas/registry-relay.config.schema.json and schemas/registry-notary.config.schema.json as reproducible artifacts with bit-for-bit CI checks.
• Check schema key paths against the product configuration reference documentation in both directions.
• Make registryctl schema output consume the same product artifacts or prove it cannot drift from them.
• Keep secrets represented as references or redacted examples, never concrete values.

Acceptance criteria

• CI fails when a Relay or Notary runtime config type changes without regenerating its product schema.
• CI fails when a product schema and its configuration reference disagree on supported key paths.
• A documented command reproduces each committed artifact.
• An implementer can validate generated or hand-authored product configuration locally and receives a product-specific path and error.
• Project-authoring schemas remain separate and are not duplicated as a second runtime config model.

Related work

• Converge Relay and Notary on Registry Stack project authoring #355 and feat(notary): move correctness state to PostgreSQL #364 establish the current product boundaries.
• registryctl: source project-authoring limits from product-owned constants #370 is post-1.0 constant-source cleanup and does not replace this runtime contract guardrail.

Security note

Schema generation must preserve strict parsing and secret redaction. Suspected vulnerabilities belong in SECURITY.md, not this issue.

[jeremi]

The 2026-07-07 YAML config audit found that this issue's premise ("with deny_unknown_fields everywhere...") currently holds only for the Relay runtime Config and notary-core. Three surfaces break it and now have their own tickets: #249 (registry-manifest-core, zero occurrences across ~75 structs), #250 (sidecar legacy structs), #251 (registryctl Project). Worth landing those before or with the schema generation here, since a schemars-derived schema of a struct that silently ignores unknown keys would inherit the permissiveness (additionalProperties would need forcing).

Also confirming the "hand-written one-level-deep JSON" note: lightweight_schema() behind registry-relay schema (crates/registry-relay/src/main.rs:1524-1546) validates top-level key names only, everything nested is typed as bare object/array. And when scoping this, consider including the split metadata manifest structs (registry-manifest-core::MetadataManifest), not just the two product configs; that file is an adopter-authored surface with the weakest validation of the three.

[jeremi]

Narrowed after PRs #355 and #364. Project-authoring schemas already exist. The remaining 1.0 acceptance is product-owned full Relay and Notary configuration schemas plus reproducible generation and documentation drift checks. Keep separate product schemas and owners; do not create a shared configuration model. #370 is later constant-source cleanup and does not replace this contract guardrail.

[jeremi]

Relay-first implementation packet ready

The first independently reviewable slice of #227 is now executable from the current release/1.0 integration head.

Scope

• Generate the complete Draft 2020-12 schema from the real deserialization-oriented Relay Config graph.
• Replace the current top-level-only registry-relay schema --format json output.
• Commit a byte-stable schemas/registry-relay.config.schema.json artifact with a stable $id.
• Add strict structural tests for nested unknown fields, tagged variants, human-readable durations, constrained references/identifiers, credential-fingerprint alternatives, and secret absence.
• Validate every maintained Relay runtime fixture.
• Add an exact bidirectional schema-key-path index in the canonical Relay configuration reference.
• Keep registry-relay doctor authoritative for environment, filesystem, source, activation, and cross-field validation.

Ownership boundary

Relay config models, schema generator/CLI, Relay tests/justfile/docs/changelog, root Cargo dependency/lockfile, and the new root schema artifact only. This slice must not edit Notary, Registryctl, project-authoring schemas, generated docs-site product pages, or the root CI workflow.

Registryctl already generates Relay YAML through the same production Config type and runs production validation, so its existing deterministic product-output test is the non-drift proof. No second schema copy belongs in Registryctl.

Required verification

• byte-for-byte regeneration check and Draft 2020-12 compilation
• maintained fixture validation plus strict negative/security cases
• locked Relay all-target checks and tests
• locked Registryctl deterministic product-output test
• locked workspace all-target check and broader tests
• strict clippy, formatting, Relay preflight
• current documentation test and build

The Notary schema remains a later dependent slice after the final credential configuration settles. This packet avoids direct overlap with active #383 and the pending #380 runtime-base work.