Skip to content

feat(registry): the schema-parity ledger, with its cadence and an honest drift contract #11221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JSONbored merged 1 commit into from
Aug 14, 2026
Merged

feat(registry): the schema-parity ledger, with its cadence and an honest drift contract #11221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions generated/graphql/schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4440,6 +4440,40 @@ type GapsArtifactGaps {
gaps: Gaps!
gap_severity: String
gap_priority: Int
schema_parity: GapsArtifactGapsSchemaParity
}

type GapsArtifactGapsSchemaParity {
"""
The capture lane's declared cadence in hours. Compare it against the backing entries' \`snapshot.observed_at\` (GET /api/v1/schemas) to judge whether this measurement rests on a current capture. No age is baked: this document is served for hours after it is built, so a build-stamped age would be wrong on arrival.
"""
capture_cadence_hours: Float!

"""Captured machine-readable specs backing this measurement."""
captured_schema_count: Int!

"""
Paths the subnet's captured spec(s) declare, summed across captured specs.
"""
captured_path_count: Int!

"""
Declared POST/PUT/PATCH/DELETE operations. NULL when the captured entries predate the capture-time stamp -- unmeasured, not zero.
"""
declared_non_get_count: Int

"""
Registered concrete route surfaces (subnet-api/sse/data-artifact; the openapi spec surface itself is not a route).
"""
registered_route_surface_count: Int!

"""Registered surfaces declaring a non-GET method (#11146 phase 3)."""
registered_non_get_count: Int!

"""
True when the subnet declares more paths than the catalogue registers as routes -- a caller reading only the registry cannot tell which routes are missing. Judge its currency from the entry's \`observed_at\` against the schema index's \`capture_cadence_hours\`.
"""
flagged: Boolean!
}

type EvidenceList {
Expand Down
33 changes: 33 additions & 0 deletions generated/graphql/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2745,9 +2745,28 @@ export type GapsArtifactGaps = {
gaps: Gaps;
name: Scalars['String']['output'];
netuid: Scalars['Int']['output'];
schema_parity?: Maybe<GapsArtifactGapsSchemaParity>;
slug: Scalars['String']['output'];
};

export type GapsArtifactGapsSchemaParity = {
__typename?: 'GapsArtifactGapsSchemaParity';
/** The capture lane's declared cadence in hours. Compare it against the backing entries' `snapshot.observed_at` (GET /api/v1/schemas) to judge whether this measurement rests on a current capture. No age is baked: this document is served for hours after it is built, so a build-stamped age would be wrong on arrival. */
capture_cadence_hours: Scalars['Float']['output'];
/** Paths the subnet's captured spec(s) declare, summed across captured specs. */
captured_path_count: Scalars['Int']['output'];
/** Captured machine-readable specs backing this measurement. */
captured_schema_count: Scalars['Int']['output'];
/** Declared POST/PUT/PATCH/DELETE operations. NULL when the captured entries predate the capture-time stamp -- unmeasured, not zero. */
declared_non_get_count?: Maybe<Scalars['Int']['output']>;
/** True when the subnet declares more paths than the catalogue registers as routes -- a caller reading only the registry cannot tell which routes are missing. Judge its currency from the entry's `observed_at` against the schema index's `capture_cadence_hours`. */
flagged: Scalars['Boolean']['output'];
/** Registered surfaces declaring a non-GET method (#11146 phase 3). */
registered_non_get_count: Scalars['Int']['output'];
/** Registered concrete route surfaces (subnet-api/sse/data-artifact; the openapi spec surface itself is not a route). */
registered_route_surface_count: Scalars['Int']['output'];
};

/** Registry-wide interface gap report page. Mirrors GET /api/v1/gaps (and MCP list_gaps). */
export type GapsList = {
__typename?: 'GapsList';
Expand Down Expand Up @@ -8592,6 +8611,7 @@ export type ResolversTypes = ResolversObject<{
Float: ResolverTypeWrapper<Scalars['Float']['output']>;
Gaps: ResolverTypeWrapper<Gaps>;
GapsArtifactGaps: ResolverTypeWrapper<GapsArtifactGaps>;
GapsArtifactGapsSchemaParity: ResolverTypeWrapper<GapsArtifactGapsSchemaParity>;
GapsList: ResolverTypeWrapper<GapsList>;
GlobalHealth: ResolverTypeWrapper<GlobalHealth>;
GlobalIncidentSurface: ResolverTypeWrapper<GlobalIncidentSurface>;
Expand Down Expand Up @@ -9061,6 +9081,7 @@ export type ResolversParentTypes = ResolversObject<{
Float: Scalars['Float']['output'];
Gaps: Gaps;
GapsArtifactGaps: GapsArtifactGaps;
GapsArtifactGapsSchemaParity: GapsArtifactGapsSchemaParity;
GapsList: GapsList;
GlobalHealth: GlobalHealth;
GlobalIncidentSurface: GlobalIncidentSurface;
Expand Down Expand Up @@ -11475,9 +11496,20 @@ export type GapsArtifactGapsResolvers<ContextType = GqlContext, ParentType exten
gaps?: Resolver<ResolversTypes['Gaps'], ParentType, ContextType>;
name?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
netuid?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
schema_parity?: Resolver<Maybe<ResolversTypes['GapsArtifactGapsSchemaParity']>, ParentType, ContextType>;
slug?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
}>;

export type GapsArtifactGapsSchemaParityResolvers<ContextType = GqlContext, ParentType extends ResolversParentTypes['GapsArtifactGapsSchemaParity'] = ResolversParentTypes['GapsArtifactGapsSchemaParity']> = ResolversObject<{
capture_cadence_hours?: Resolver<ResolversTypes['Float'], ParentType, ContextType>;
captured_path_count?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
captured_schema_count?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
declared_non_get_count?: Resolver<Maybe<ResolversTypes['Int']>, ParentType, ContextType>;
flagged?: Resolver<ResolversTypes['Boolean'], ParentType, ContextType>;
registered_non_get_count?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
registered_route_surface_count?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
}>;

export type GapsListResolvers<ContextType = GqlContext, ParentType extends ResolversParentTypes['GapsList'] = ResolversParentTypes['GapsList']> = ResolversObject<{
cursor?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
gaps?: Resolver<Array<ResolversTypes['GapsArtifactGaps']>, ParentType, ContextType>;
Expand Down Expand Up @@ -14748,6 +14780,7 @@ export type Resolvers<ContextType = GqlContext> = ResolversObject<{
FailureReasonsDay?: FailureReasonsDayResolvers<ContextType>;
Gaps?: GapsResolvers<ContextType>;
GapsArtifactGaps?: GapsArtifactGapsResolvers<ContextType>;
GapsArtifactGapsSchemaParity?: GapsArtifactGapsSchemaParityResolvers<ContextType>;
GapsList?: GapsListResolvers<ContextType>;
GlobalHealth?: GlobalHealthResolvers<ContextType>;
GlobalIncidentSurface?: GlobalIncidentSurfaceResolvers<ContextType>;
Expand Down
22 changes: 21 additions & 1 deletion packages/contract/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8636,6 +8636,22 @@ export interface components {
gaps: components["schemas"]["Gaps"];
name: string;
netuid: number;
schema_parity?: {
/** @description The capture lane's declared cadence in hours. Compare it against the backing entries' `snapshot.observed_at` (GET /api/v1/schemas) to judge whether this measurement rests on a current capture. No age is baked: this document is served for hours after it is built, so a build-stamped age would be wrong on arrival. */
capture_cadence_hours: number;
/** @description Paths the subnet's captured spec(s) declare, summed across captured specs. */
captured_path_count: number;
/** @description Captured machine-readable specs backing this measurement. */
captured_schema_count: number;
/** @description Declared POST/PUT/PATCH/DELETE operations. NULL when the captured entries predate the capture-time stamp -- unmeasured, not zero. */
declared_non_get_count: number | null;
/** @description True when the subnet declares more paths than the catalogue registers as routes -- a caller reading only the registry cannot tell which routes are missing. Judge its currency from the entry's `observed_at` against the schema index's `capture_cadence_hours`. */
flagged: boolean;
/** @description Registered surfaces declaring a non-GET method (#11146 phase 3). */
registered_non_get_count: number;
/** @description Registered concrete route surfaces (subnet-api/sse/data-artifact; the openapi spec surface itself is not a route). */
registered_route_surface_count: number;
};
slug: string;
}[];
generated_at: string;
Expand Down Expand Up @@ -10347,7 +10363,10 @@ export interface components {
schema_version: 1;
schemas: {
content_type?: string | null;
/** @enum {string} */
/**
* @description How this capture compares to the PREVIOUS capture of the same surface by this registry -- NOT to the subnet's live spec. `unchanged` means 'our snapshot is what it was', never 'the upstream API has not changed'. Judge currency by comparing this entry's `snapshot.observed_at` against `capture_cadence_hours` on the subnet's /api/v1/gaps `schema_parity` block.
* @enum {string}
*/
drift_status: "new" | "changed" | "unchanged" | "not-captured" | "missing-after-previous-capture";
error?: string | null;
hash?: string | null;
Expand All @@ -10370,6 +10389,7 @@ export interface components {
generated_at?: string | null;
hash?: string | null;
netuid?: number | null;
non_get_operation_count?: number;
observed_at?: string | null;
openapi_version?: string | null;
path_count?: number;
Expand Down
67 changes: 67 additions & 0 deletions public/metagraph/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34250,6 +34250,67 @@
"minimum": 0,
"type": "integer"
},
"schema_parity": {
"additionalProperties": false,
"properties": {
"capture_cadence_hours": {
"description": "The capture lane's declared cadence in hours. Compare it against the backing entries' `snapshot.observed_at` (GET /api/v1/schemas) to judge whether this measurement rests on a current capture. No age is baked: this document is served for hours after it is built, so a build-stamped age would be wrong on arrival.",
"minimum": 0,
"type": "number"
},
"captured_path_count": {
"description": "Paths the subnet's captured spec(s) declare, summed across captured specs.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"captured_schema_count": {
"description": "Captured machine-readable specs backing this measurement.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"declared_non_get_count": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Declared POST/PUT/PATCH/DELETE operations. NULL when the captured entries predate the capture-time stamp -- unmeasured, not zero."
},
"flagged": {
"description": "True when the subnet declares more paths than the catalogue registers as routes -- a caller reading only the registry cannot tell which routes are missing. Judge its currency from the entry's `observed_at` against the schema index's `capture_cadence_hours`.",
"type": "boolean"
},
"registered_non_get_count": {
"description": "Registered surfaces declaring a non-GET method (#11146 phase 3).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"registered_route_surface_count": {
"description": "Registered concrete route surfaces (subnet-api/sse/data-artifact; the openapi spec surface itself is not a route).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"capture_cadence_hours",
"captured_schema_count",
"captured_path_count",
"declared_non_get_count",
"registered_route_surface_count",
"registered_non_get_count",
"flagged"
],
"type": "object"
},
"slug": {
"type": "string"
}
Expand Down Expand Up @@ -43447,6 +43508,7 @@
]
},
"drift_status": {
"description": "How this capture compares to the PREVIOUS capture of the same surface by this registry -- NOT to the subnet's live spec. `unchanged` means 'our snapshot is what it was', never 'the upstream API has not changed'. Judge currency by comparing this entry's `snapshot.observed_at` against `capture_cadence_hours` on the subnet's /api/v1/gaps `schema_parity` block.",
"enum": [
"new",
"changed",
Expand Down Expand Up @@ -43634,6 +43696,11 @@
}
]
},
"non_get_operation_count": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"observed_at": {
"anyOf": [
{
Expand Down
22 changes: 21 additions & 1 deletion public/metagraph/types.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8636,6 +8636,22 @@ export interface components {
gaps: components["schemas"]["Gaps"];
name: string;
netuid: number;
schema_parity?: {
/** @description The capture lane's declared cadence in hours. Compare it against the backing entries' `snapshot.observed_at` (GET /api/v1/schemas) to judge whether this measurement rests on a current capture. No age is baked: this document is served for hours after it is built, so a build-stamped age would be wrong on arrival. */
capture_cadence_hours: number;
/** @description Paths the subnet's captured spec(s) declare, summed across captured specs. */
captured_path_count: number;
/** @description Captured machine-readable specs backing this measurement. */
captured_schema_count: number;
/** @description Declared POST/PUT/PATCH/DELETE operations. NULL when the captured entries predate the capture-time stamp -- unmeasured, not zero. */
declared_non_get_count: number | null;
/** @description True when the subnet declares more paths than the catalogue registers as routes -- a caller reading only the registry cannot tell which routes are missing. Judge its currency from the entry's `observed_at` against the schema index's `capture_cadence_hours`. */
flagged: boolean;
/** @description Registered surfaces declaring a non-GET method (#11146 phase 3). */
registered_non_get_count: number;
/** @description Registered concrete route surfaces (subnet-api/sse/data-artifact; the openapi spec surface itself is not a route). */
registered_route_surface_count: number;
};
slug: string;
}[];
generated_at: string;
Expand Down Expand Up @@ -10347,7 +10363,10 @@ export interface components {
schema_version: 1;
schemas: {
content_type?: string | null;
/** @enum {string} */
/**
* @description How this capture compares to the PREVIOUS capture of the same surface by this registry -- NOT to the subnet's live spec. `unchanged` means 'our snapshot is what it was', never 'the upstream API has not changed'. Judge currency by comparing this entry's `snapshot.observed_at` against `capture_cadence_hours` on the subnet's /api/v1/gaps `schema_parity` block.
* @enum {string}
*/
drift_status: "new" | "changed" | "unchanged" | "not-captured" | "missing-after-previous-capture";
error?: string | null;
hash?: string | null;
Expand All @@ -10370,6 +10389,7 @@ export interface components {
generated_at?: string | null;
hash?: string | null;
netuid?: number | null;
non_get_operation_count?: number;
observed_at?: string | null;
openapi_version?: string | null;
path_count?: number;
Expand Down
1 change: 1 addition & 0 deletions schemas-src/graphql/published-names.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -633,6 +633,7 @@ export const PUBLISHED_TYPE_NAMES: Readonly<Record<string, string>> = {
EvidenceLedgerArtifactSummary: "EvidenceLedgerArtifactSummary",
Gaps: "Gaps",
GapsArtifactGaps: "GapsArtifactGaps",
GapsArtifactGapsSchemaParity: "GapsArtifactGapsSchemaParity",
GlobalIncidentsArtifactSummary: "GlobalIncidentsArtifactSummary",
HealthHistoryArtifactSurfaces: "HealthHistoryArtifactSurfaces",
HealthIncidentsArtifactSurfaces: "HealthIncidentsArtifactSurfaces",
Expand Down
Loading
Loading