automated-qa 0.11.0

package/schemas/coherence-ir.schema.json

@@ -0,0 +1,1585 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frontend-verify.dev/schemas/coherence-ir.schema.json",
+  "title": "coherence IR",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/current"
+    },
+    {
+      "$ref": "#/$defs/legacyV3"
+    }
+  ],
+  "$defs": {
+    "current": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "coverage",
+        "resourceFamilies",
+        "cacheKeys",
+        "cacheOperations",
+        "reads",
+        "mutations",
+        "invalidations",
+        "operationReadPairs",
+        "surfaces",
+        "ownershipEdges",
+        "candidates",
+        "graph"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": {
+          "const": 4
+        },
+        "coverage": {
+          "$ref": "#/$defs/coverage"
+        },
+        "resourceFamilies": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/family"
+          }
+        },
+        "cacheKeys": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cacheKey"
+          }
+        },
+        "cacheOperations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cacheOperation"
+          }
+        },
+        "reads": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/read"
+          }
+        },
+        "mutations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/mutation"
+          }
+        },
+        "invalidations": {
+          "type": "array",
+          "maxItems": 0
+        },
+        "operationReadPairs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/operationReadPair"
+          }
+        },
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/surface"
+          }
+        },
+        "ownershipEdges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ownershipEdge"
+          }
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/candidate"
+          }
+        },
+        "units": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/unit"
+          }
+        },
+        "graph": {
+          "type": "object",
+          "description": "The semantic-graph v2 root. Fully specified by graph.schema.json; this branch only binds its identity, because the local validator resolves same-document refs only.",
+          "required": [
+            "artifact",
+            "schemaVersion",
+            "coverage",
+            "nodes",
+            "edges"
+          ],
+          "properties": {
+            "artifact": {
+              "const": "frontend-verify.semantic-graph"
+            },
+            "schemaVersion": {
+              "const": 2
+            }
+          }
+        }
+      },
+      "title": "coherence IR v4 (current)",
+      "description": "CURRENT. One semantic graph v2 is REQUIRED and every compatibility array is a checked projection of it. Schema validity is necessary and not sufficient: the graph root must also validate against graph.schema.json and pass validateSemanticGraph, and the views must recompute from it."
+    },
+    "legacyV3": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "coverage",
+        "resourceFamilies",
+        "cacheKeys",
+        "cacheOperations",
+        "reads",
+        "mutations",
+        "invalidations",
+        "operationReadPairs",
+        "surfaces",
+        "ownershipEdges",
+        "candidates"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": {
+          "const": 3
+        },
+        "coverage": {
+          "$ref": "#/$defs/coverage"
+        },
+        "resourceFamilies": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/family"
+          }
+        },
+        "cacheKeys": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cacheKey"
+          }
+        },
+        "cacheOperations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cacheOperation"
+          }
+        },
+        "reads": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/read"
+          }
+        },
+        "mutations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/mutation"
+          }
+        },
+        "invalidations": {
+          "type": "array",
+          "maxItems": 0
+        },
+        "operationReadPairs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/operationReadPair"
+          }
+        },
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/surface"
+          }
+        },
+        "ownershipEdges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ownershipEdge"
+          }
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/candidate"
+          }
+        },
+        "units": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/unit"
+          }
+        }
+      },
+      "title": "coherence IR v3 (legacy, non-proof)",
+      "description": "LEGACY. Readable only as non-proof input: a v3 document carries no semantic graph, so nothing in it can satisfy a current join, obligation or measured denominator. validateCoherenceIrIdentities returns {current:false} for it."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "evidenceId": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "sourceRef": {
+      "type": "object",
+      "required": [
+        "file",
+        "line"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "sourceSpan": {
+      "type": "object",
+      "required": [
+        "file",
+        "start",
+        "end",
+        "line",
+        "column"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "start": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "jcsValue": {
+      "anyOf": [
+        {
+          "type": [
+            "string",
+            "boolean",
+            "null"
+          ]
+        },
+        {
+          "type": "number",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/jcsValue"
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/jcsValue"
+          }
+        }
+      ]
+    },
+    "keyOrigin": {
+      "type": "object",
+      "required": [
+        "file",
+        "start",
+        "end",
+        "line",
+        "column"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "start": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "literalTerm": {
+      "type": "object",
+      "required": [
+        "kind",
+        "value"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "const": "literal"
+        },
+        "value": {
+          "$ref": "#/$defs/jcsValue"
+        },
+        "origin": {
+          "$ref": "#/$defs/keyOrigin"
+        }
+      }
+    },
+    "symbolicTerm": {
+      "type": "object",
+      "required": [
+        "kind",
+        "expression",
+        "ownerSymbol",
+        "targetSymbol",
+        "origin",
+        "resolutionPath",
+        "resolution",
+        "reason"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "parameter",
+            "wildcard",
+            "call",
+            "unknown"
+          ]
+        },
+        "expression": {
+          "type": "string"
+        },
+        "ownerSymbol": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "targetSymbol": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "origin": {
+          "$ref": "#/$defs/keyOrigin"
+        },
+        "resolutionPath": {
+          "type": "array",
+          "maxItems": 26,
+          "items": {
+            "type": "string"
+          }
+        },
+        "resolution": {
+          "const": "unresolved"
+        },
+        "reason": {
+          "enum": [
+            "dynamic-key",
+            "unknown-helper",
+            "unsupported-client",
+            "unsupported-expression",
+            "unsafe-number",
+            "non-json-value",
+            "contract-conflict",
+            "dynamic-import",
+            "namespace-spread",
+            "export-star",
+            "computed-member",
+            "ambiguous-alias",
+            "unresolved-module",
+            "unsupported-syntax"
+          ]
+        }
+      }
+    },
+    "term": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/literalTerm"
+        },
+        {
+          "$ref": "#/$defs/symbolicTerm"
+        }
+      ]
+    },
+    "pattern": {
+      "type": "object",
+      "required": [
+        "segments"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "segments": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/term"
+          }
+        }
+      }
+    },
+    "cacheKeyMaterial": {
+      "type": "object",
+      "required": [
+        "namespace",
+        "version",
+        "segments"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "namespace": {
+          "const": "coherence/cache-key"
+        },
+        "version": {
+          "const": 1
+        },
+        "segments": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/term"
+          }
+        }
+      }
+    },
+    "cacheKey": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "provenance"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "material": {
+          "$ref": "#/$defs/cacheKeyMaterial"
+        },
+        "provenance": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "operationSpan": {
+      "type": "object",
+      "required": [
+        "file",
+        "start",
+        "end"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "start": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "end": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "receiver": {
+      "type": "object",
+      "required": [
+        "expression",
+        "ownerSymbol",
+        "targetSymbol",
+        "kind",
+        "resolution",
+        "reason"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "expression": {
+          "type": "string"
+        },
+        "ownerSymbol": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "targetSymbol": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "query-client",
+            "query-cache",
+            "unknown"
+          ]
+        },
+        "resolution": {
+          "enum": [
+            "resolved",
+            "unresolved"
+          ]
+        },
+        "reason": {
+          "enum": [
+            null,
+            "unsupported-client"
+          ]
+        }
+      }
+    },
+    "effect": {
+      "type": "object",
+      "required": [
+        "kind",
+        "scope"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "invalidate",
+            "refetch",
+            "reset",
+            "remove",
+            "update",
+            "clear-query-cache",
+            "clear-mutation-cache"
+          ]
+        },
+        "scope": {
+          "type": "string"
+        }
+      }
+    },
+    "cacheOperationMaterial": {
+      "type": "object",
+      "required": [
+        "namespace",
+        "version",
+        "sourceRef",
+        "receiver",
+        "operation",
+        "keyId",
+        "keyMatch",
+        "exact",
+        "predicate",
+        "filters",
+        "effects"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "namespace": {
+          "const": "coherence/cache-operation"
+        },
+        "version": {
+          "const": 1
+        },
+        "sourceRef": {
+          "$ref": "#/$defs/operationSpan"
+        },
+        "receiver": {
+          "$ref": "#/$defs/receiver"
+        },
+        "operation": {
+          "enum": [
+            "invalidateQueries",
+            "refetchQueries",
+            "resetQueries",
+            "removeQueries",
+            "setQueryData",
+            "setQueriesData",
+            "clear"
+          ]
+        },
+        "keyId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "keyMatch": {
+          "enum": [
+            "all",
+            "prefix",
+            "exact",
+            "unknown"
+          ]
+        },
+        "exact": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "predicate": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/term"
+            }
+          ]
+        },
+        "filters": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": {},
+            "stale": {},
+            "fetchStatus": {},
+            "refetchType": {}
+          }
+        },
+        "effects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/effect"
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "operation": {
+                "const": "clear"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "effects": {
+                "items": {
+                  "properties": {
+                    "kind": {
+                      "enum": [
+                        "clear-query-cache",
+                        "clear-mutation-cache"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "effects": {
+                "items": {
+                  "properties": {
+                    "kind": {
+                      "enum": [
+                        "invalidate",
+                        "refetch",
+                        "reset",
+                        "remove",
+                        "update"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "cacheOperation": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "provenance"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "material": {
+          "$ref": "#/$defs/cacheOperationMaterial"
+        },
+        "provenance": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "operationReadPair": {
+      "type": "object",
+      "required": [
+        "id",
+        "operationId",
+        "readId",
+        "keyCoverage",
+        "effectCoverage",
+        "mandatory"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}:sha256:[a-f0-9]{64}$"
+        },
+        "operationId": {
+          "$ref": "#/$defs/id"
+        },
+        "readId": {
+          "$ref": "#/$defs/evidenceId"
+        },
+        "keyCoverage": {
+          "enum": [
+            "covered",
+            "not-covered",
+            "unresolved"
+          ]
+        },
+        "effectCoverage": {
+          "enum": [
+            "covered",
+            "not-covered",
+            "unresolved"
+          ]
+        },
+        "mandatory": {
+          "type": "boolean"
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "required": [
+        "status",
+        "reason",
+        "counts",
+        "unresolved"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "enum": [
+            "measured",
+            "partial",
+            "unmeasured"
+          ]
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "counts": {
+          "type": "object",
+          "required": [
+            "ownershipEdgesDiscovered",
+            "ownershipEdgesResolved",
+            "ownershipEdgesUnresolved",
+            "ambiguousMutationOccurrences",
+            "keysDiscovered",
+            "keysResolved",
+            "keysUnresolved",
+            "operationsDiscovered",
+            "operationsResolved",
+            "operationsUnresolved",
+            "operationReadPairsDiscovered",
+            "operationReadPairsCovered",
+            "operationReadPairsNotCovered",
+            "operationReadPairsUnresolved"
+          ],
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "properties": {
+            "ownershipEdgesDiscovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "ownershipEdgesResolved": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "ownershipEdgesUnresolved": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "ambiguousMutationOccurrences": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "keysDiscovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "keysResolved": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "keysUnresolved": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationsDiscovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationsResolved": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationsUnresolved": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationReadPairsDiscovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationReadPairsCovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationReadPairsNotCovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operationReadPairsUnresolved": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "unjoinedWriterFamilies": {
+          "description": "The endpoint families of every `family-join` row, deduplicated and sorted. Present on every current (v4) document; absent from legacy v3, which predates the join. A non-empty list is why `status` is `partial` rather than `measured`.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "unresolved": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "file",
+              "line",
+              "kind",
+              "reason"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "kind": {
+                "description": "`family-join` is a RESOLVED write whose family no surface reads. It is deliberately not `write`: identity.mjs ledgers `write` as exactly the writes that could not be resolved, so a resolved write listed there would both trip that ledger and overstate the unknown write surface. What is unresolved is the join to a reader surface, so the row names that relation.",
+                "enum": [
+                  "read",
+                  "write",
+                  "family-join",
+                  "ownership",
+                  "cache-key",
+                  "cache-operation"
+                ]
+              },
+              "family": {
+                "description": "The endpoint family of a `family-join` row. Only that kind carries one.",
+                "type": "string",
+                "minLength": 1
+              },
+              "reason": {
+                "type": "string"
+              },
+              "span": {
+                "$ref": "#/$defs/sourceSpan"
+              }
+            }
+          }
+        }
+      }
+    },
+    "familyMaterial": {
+      "type": "object",
+      "required": [
+        "namespace",
+        "version",
+        "endpointFamily"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "namespace": {
+          "const": "coherence/family"
+        },
+        "version": {
+          "const": 1
+        },
+        "endpointFamily": {
+          "type": "string"
+        }
+      }
+    },
+    "family": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "family",
+        "mutationIds",
+        "readIds",
+        "surfaceIds",
+        "keyTerms",
+        "invalidations",
+        "invalidationsUnresolved",
+        "readsUnresolvedKey"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "material": {
+          "$ref": "#/$defs/familyMaterial"
+        },
+        "family": {
+          "type": "string"
+        },
+        "mutationIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "readIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidenceId"
+          }
+        },
+        "surfaceIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "keyTerms": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "invalidations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "invalidationsUnresolved": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "readsUnresolvedKey": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "read": {
+      "type": "object",
+      "required": [
+        "id",
+        "keyId",
+        "file",
+        "line",
+        "pattern",
+        "endpoint",
+        "family",
+        "confidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/evidenceId"
+        },
+        "keyId": {
+          "$ref": "#/$defs/id"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "span": {
+          "description": "null when no source call site could be anchored (e.g. an inventory-derived query with no matching literal call) -- identity then falls back to {file,line}, see identity.mjs stableEvidenceId callers.",
+          "anyOf": [
+            { "$ref": "#/$defs/sourceSpan" },
+            { "type": "null" }
+          ]
+        },
+        "pattern": {
+          "$ref": "#/$defs/pattern"
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "family": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "familySource": {
+          "description": "WHICH join produced `family`: `declaration` is a repo-declared entity alias (a claim, not measured evidence -- analyze.mjs downgrades any candidate resting on one to `uncertain`), `endpoint` is derived from the endpoint itself, `unresolved` means no family could be attributed. Present on every current row; absent from legacy v3, which predates entity aliases.",
+          "enum": [
+            "declaration",
+            "endpoint",
+            "unresolved"
+          ]
+        },
+        "confidence": {
+          "enum": [
+            "exact",
+            "resolved",
+            "coarse",
+            "unresolved"
+          ]
+        }
+      }
+    },
+    "mutationMaterial": {
+      "type": "object",
+      "required": [
+        "namespace",
+        "version",
+        "sourceRef",
+        "endpoint"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "namespace": {
+          "const": "coherence/mutation"
+        },
+        "version": {
+          "const": 1
+        },
+        "sourceRef": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "mutation": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "file",
+        "line",
+        "endpoint",
+        "family",
+        "writes",
+        "operationIds",
+        "confidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "material": {
+          "$ref": "#/$defs/mutationMaterial"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "hook": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "family": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "familySource": {
+          "description": "WHICH join produced `family`: `declaration` is a repo-declared entity alias (a claim, not measured evidence -- analyze.mjs downgrades any candidate resting on one to `uncertain`), `endpoint` is derived from the endpoint itself, `unresolved` means no family could be attributed. Present on every current row; absent from legacy v3, which predates entity aliases.",
+          "enum": [
+            "declaration",
+            "endpoint",
+            "unresolved"
+          ]
+        },
+        "writes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "pattern"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "pattern": {
+                "$ref": "#/$defs/pattern"
+              }
+            }
+          }
+        },
+        "operationIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "confidence": {
+          "enum": [
+            "exact",
+            "resolved",
+            "coarse",
+            "unresolved"
+          ]
+        }
+      }
+    },
+    "surfaceMaterial": {
+      "type": "object",
+      "required": [
+        "namespace",
+        "version",
+        "route",
+        "component",
+        "sourceRef"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "namespace": {
+          "const": "coherence/surface"
+        },
+        "version": {
+          "const": 1
+        },
+        "route": {
+          "type": "string"
+        },
+        "component": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "sourceRef": {
+          "$ref": "#/$defs/sourceRef"
+        }
+      }
+    },
+    "surface": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "route",
+        "file",
+        "component",
+        "readIds",
+        "families",
+        "confidence",
+        "kind"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "material": {
+          "$ref": "#/$defs/surfaceMaterial"
+        },
+        "route": {
+          "type": "string"
+        },
+        "file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "component": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "readIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidenceId"
+          }
+        },
+        "families": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "confidence": {
+          "enum": [
+            "exact",
+            "resolved",
+            "coarse",
+            "unresolved"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "route",
+            "component",
+            "modal",
+            "drawer",
+            "tab",
+            "wizard-step",
+            "embedded-widget"
+          ]
+        }
+      }
+    },
+    "ownershipEdge": {
+      "type": "object",
+      "required": [
+        "surfaceId",
+        "readId",
+        "confidence",
+        "resolution",
+        "reason",
+        "source",
+        "provenance",
+        "path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "surfaceId": {
+          "$ref": "#/$defs/id"
+        },
+        "readId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "confidence": {
+          "enum": [
+            "resolved",
+            "unresolved"
+          ]
+        },
+        "resolution": {
+          "enum": [
+            "resolved",
+            "unresolved"
+          ]
+        },
+        "reason": {
+          "enum": [
+            null,
+            "dynamic-import",
+            "namespace-spread",
+            "export-star",
+            "computed-member",
+            "ambiguous-alias",
+            "unresolved-module",
+            "unsupported-syntax"
+          ]
+        },
+        "source": {
+          "$ref": "#/$defs/sourceSpan"
+        },
+        "provenance": {
+          "type": "object",
+          "required": [
+            "adapter",
+            "method"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "adapter": {
+              "const": "structural-js"
+            },
+            "method": {
+              "const": "symbol-traversal"
+            }
+          }
+        },
+        "path": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 26,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "resolution": {
+              "const": "resolved"
+            },
+            "confidence": {
+              "const": "resolved"
+            },
+            "readId": {
+              "$ref": "#/$defs/evidenceId"
+            },
+            "reason": {
+              "const": null
+            }
+          }
+        },
+        {
+          "properties": {
+            "resolution": {
+              "const": "unresolved"
+            },
+            "confidence": {
+              "const": "unresolved"
+            },
+            "readId": {
+              "const": null
+            },
+            "reason": {
+              "enum": [
+                "dynamic-import",
+                "namespace-spread",
+                "export-star",
+                "computed-member",
+                "ambiguous-alias",
+                "unresolved-module",
+                "unsupported-syntax"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "candidate": {
+      "type": "object",
+      "required": [
+        "kind",
+        "severity",
+        "confirmed",
+        "mutationId",
+        "source",
+        "family",
+        "readIds",
+        "unresolvedReadIds",
+        "surfaceIds",
+        "routes",
+        "components",
+        "coverage",
+        "rootCauseId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "coherence.no-invalidation-candidate",
+            "coherence.partial-invalidation-candidate"
+          ]
+        },
+        "severity": {
+          "const": "P3"
+        },
+        "confirmed": {
+          "const": false
+        },
+        "mutationId": {
+          "$ref": "#/$defs/id"
+        },
+        "source": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "family": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "readIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidenceId"
+          }
+        },
+        "unresolvedReadIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidenceId"
+          }
+        },
+        "surfaceIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "routes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "coverage": {
+          "enum": [
+            "measured",
+            "partial",
+            "unmeasured"
+          ]
+        },
+        "rootCauseId": {
+          "type": "string",
+          "pattern": "^crc:[a-f0-9]{64}$"
+        },
+        "waived": {
+          "type": "boolean"
+        }
+      }
+    },
+    "moduleRef": {
+      "type": "object",
+      "required": [
+        "specifier",
+        "kind",
+        "resolvedFile",
+        "span"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "specifier": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "static-import",
+            "dynamic-import",
+            "named-reexport",
+            "export-star"
+          ]
+        },
+        "resolvedFile": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "span": {
+          "$ref": "#/$defs/sourceSpan"
+        }
+      }
+    },
+    "unit": {
+      "type": "object",
+      "required": [
+        "file",
+        "imports",
+        "moduleRefs"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "imports": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "moduleRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/moduleRef"
+          }
+        }
+      }
+    }
+  }
+}