Canonical Specs And Docs-First Process

Canonical Specs And Docs-First Process

Use this page for docs-first update order and process policy.
If you only need direct contract-source links, use Canonical Specs.

Canonical Contract Sources

• product and startup/runtime contract: docs/specs/prd.md
• exact JSON-RPC tuples and errors: docs/specs/json-rpc-contract.md
• docs-first update process: docs/specs/docs-first-process.md

If wording differs, docs/specs/json-rpc-contract.md is authoritative for API-level details.

Required Update Order

For contract-affecting behavior changes:

1. Update docs/specs/prd.md and docs/specs/json-rpc-contract.md first.
2. Update internal support docs under docs/specs/internal/.
3. Update public Mintlify pages under docs/.

Deferred-Surface Promotion And Phase-1 Boundary And Graduation Criteria

This section is the canonical public-doc criteria for:

• promoting a deferred/out-of-contract surface into the ZEVM public contract
• changing phase-1 public boundary statements
• declaring phase-1 boundary graduation in this docs set

Criteria:

• deferred/out-of-contract status changes only through docs-first updates to canonical spec sources: docs/specs/prd.md and docs/specs/json-rpc-contract.md
• update order is mandatory: canonical spec sources first, then internal support docs, then public Mintlify docs
• public pages that inventory deferred surfaces (for example Unsupported And Deferred) are summaries and do not independently promote contract status
• phase-1 boundary or graduation claims are canonical only after matching updates land in the same docs-first path above
• when wording differs across public pages, canonical spec sources remain authoritative for runtime/RPC scope

Release Metadata Records

Phase-1 release metadata is published per release identifier in ZEVM release metadata. Each canonical record requires both files for one selected identifier:

• release-tuple.json
• light-default-checkpoints.json

Publication-time validation gate for canonical claims:

• canonical claims are allowed only after publication validation passes for the selected releaseIdentifier
• publication validation requires exactly one published release asset named release-tuple.json and exactly one named light-default-checkpoints.json
• missing or duplicate required filenames fails the gate and marks that identifier metadata-invalid for canonical claims

For canonical publication claims, both files must validate schema/version and .releaseIdentifier equality for the same selected identifier. For end-to-end procedure (fetch, validation, pinned checkouts, manifest provenance, runtime baked-default audit), use Release Metadata Runbook.

Metadata-Invalid releaseIdentifier Handling

Treat a published identifier as metadata-invalid when publication validation fails (missing or duplicate required asset filenames) or when required release artifacts are unreadable, malformed, schema-mismatched, releaseIdentifier-mismatched, or value-mismatched against the contract.

• metadata-invalid identifiers are outside canonical reproducibility claims
• metadata-invalid identifiers remain historical audit records only
• phase 1 does not require runtime JSON-RPC/CLI discovery, repair, or reporting of metadata-invalid artifacts; this remains operator provenance workflow

Append-Only Correction Policy

Release metadata is append-only by releaseIdentifier:

• do not mutate or replace artifact files in place for an existing identifier
• publish corrections under a new releaseIdentifier with a complete replacement artifact pair (release-tuple.json + light-default-checkpoints.json)
• keep superseded release assets unchanged for auditability

Every correction release must include exactly one release-notes block with this exact template:

## ZEVM Supersession Note
schemaVersion: zevm-supersession-note.v1
supersedesReleaseIdentifier: v0.6.1
correctedArtifacts: release-tuple.json
reason: Fixed release-tuple.json zevmGitRevision value mismatch.

Field constraints:

• schemaVersion must be the literal zevm-supersession-note.v1
• supersedesReleaseIdentifier must name one valid previously published releaseIdentifier
• correctedArtifacts must be exactly one of release-tuple.json, light-default-checkpoints.json, or both
• reason must be non-empty single-line UTF-8 text describing the corrected defect

Phase-1 Release Qualification Checklist

Coverage intent for phase-1 qualification is explicit startup/configuration/runtime/transport/method coverage from docs, not ad hoc spot checks. Before shipping, confirm all PRD criteria:

• clean-checkout source build verification passes: zig build --fetch, zig build, and zig build test succeed on pinned package dependencies/toolchain without local patching
• CI runs the root release gates documented in CI And Release Gates, including package dependency preflight, strict qualification coverage, generated-metadata smoke validation, dirty-worktree preflight, and scheduled/manual external verification
• default zig build test graph covers all shipped executable startup/configuration/runtime/transport/method/semantic behaviors from PRD sections 3.1 and 4 through 12
• qualification evidence maps each shipped phase-1 surface in PRD sections 3.1, 3.3, 3.4, and 4 through 12 to at least one qualification assertion
• for candidates claiming a published releaseIdentifier, qualification validates both required release artifacts and all PRD section 3.4 field/schema/value invariants
• qualification enforces the publication-time validation gate for canonical claims (exactly one required release asset filename per artifact; duplicates fail qualification)
• automated listener/socket smoke coverage validates startup/request flow for trusted mode and light-mode startup plus restart/resume from persisted checkpoint input
• transport/parsing verification asserts notification-only request and notification-only batch behavior returns HTTP 204 with empty body and uses one canonical ZEVM-owned transport/parser stack

Related Pages

• Installation
• CI And Release Gates
• Release Metadata Runbook
• ZEVM