feat(registry): the schema-parity ledger, with its cadence and an honest drift contract - #11221
Merged
Conversation
…est drift contract (#11146) Three mechanisms broke "every subnet's API, exactly like using it directly", each silently. Phase 3 (the surface method dimension) landed in #11210 and the first declared mutation in #11212; this closes the rest. THE PARITY LEDGER. Each gaps row gains schema_parity: captured paths and declared mutations against registered route surfaces and registered mutations, flagged when the catalogue registers fewer routes than the subnet declares. Derived from schema INDEX entries only -- captured documents exist solely in credentialed builds -- with the capture lane now stamping non_get_operation_count so both sides are measured. Unmeasured counts report null, never zero. First build: 53 subnets measured, 27 flagged. FRESHNESS IS MEASURABLE, AND JUDGED BY THE READER. The lane's declared cadence (SCHEMA_CAPTURE_CADENCE_HOURS = 48) rides the parity block. No age is baked: the document is served for hours after it is built, so a build-stamped age is wrong on arrival -- and buildTimestamp() is the 1970 placeholder in every local build, which would have published a twelve-day-old capture as FRESH. Entries already carry observed_at; the subtraction belongs to whoever has a real clock. DRIFT SAYS WHAT IT MEASURES, IN THE CONTRACT. drift_status compares our snapshot to OUR previous snapshot, never upstream -- which is why 23 of 24 measurably-drifted subnets reported "unchanged". Stated at the point of consumption, in the published schema, because the schema index artifact is a deploy-owned capture cache whose committed copy a PR cannot regenerate: annotating it breaks the preservation gate protecting 58 captured schemas. Closes #11146
|
Superagent didn't find any vulnerabilities or security issues in this PR. |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
metagraphed-registry-sync-api | 88e35c3 | Aug 14 2026, 01:30 PM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
metagraphed-wss-lb | 88e35c3 | Aug 14 2026, 01:30 PM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
metagraphed-data-api | 88e35c3 | Aug 14 2026, 01:30 PM |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #11221 +/- ##
=======================================
Coverage 95.51% 95.51%
=======================================
Files 742 742
Lines 45308 45310 +2
Branches 16648 16648
=======================================
+ Hits 43277 43279 +2
Misses 526 526
Partials 1505 1505
🚀 New features to boost your workflow:
|
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.
Closes #11146.
Phase 3 (the surface
methoddimension) landed in #11210 and the first declared mutation in #11212; this closes the rest of the epic in one change.The parity ledger
Each gaps row gains
schema_parity: captured paths and declared mutations against registered route surfaces and registered mutations,flaggedwhen the catalogue registers fewer routes than the subnet declares — the check the SN105 report asked for.Derived from schema index entries only (captured documents exist solely in credentialed builds, so a rollup reading them would not be reproducible), with the capture lane now stamping
non_get_operation_countso both sides of the mutation ledger are measured. Counts absent on pre-stamp entries report null, never zero.First measurement: 53 subnets measured, 27 flagged — sn-3 registers 8 routes against 208 declared paths; sn-105 registers 29 (including the
POSTsurface from #11212, counted as its 1 registered mutation) against 53.Freshness is measurable, and judged by the reader
capture_cadence_hours(48) rides the parity block. No age is baked: the document is served for hours after it is built, so a build-stamped age is wrong on arrival — andbuildTimestamp()returns the 1970 epoch placeholder in every local build, so an earlier revision of this branch published a twelve-day-old capture as fresh. That was caught in a built artifact and is why the design changed. Entries already carryobserved_at; the subtraction belongs to whoever has a real clock.Drift says what it measures — in the contract
drift_statuscompares our snapshot to our previous snapshot, never upstream, which is why 23 of 24 measurably-drifted subnets reportedunchanged. Its published description now states exactly that, at the point of consumption.Why a description rather than a field: the schema-index artifact is a deploy-owned capture cache, and
artifacts-build-schema-indexasserts a rebuild reproduces its committed copy exactly. Any added field breaks the gate that protects 58 captured schemas — so this PR leaves that artifact completely untouched (it is not in the diff) and puts the honesty where every consumer reads it.Validation
typecheck,lint,format:checkvalidate(129 subnets / 3,330 surfaces),validate:api(215 routes),validate:openapi,validate:contract-drift,validate:published-names,validate:unreferenced-exports(731 — at the ceiling, not raised),validate:schema-vocabularies,validate:mcp(240 tools),validate:schemasartifacts.test.ts,artifacts-build-schema-index, andartifacts-build-determinism— each re-run against a pristine committed baseline