automated-qa 0.11.0

package/schemas/inventory.schema.json

@@ -0,0 +1,2167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frontend-verify.dev/schemas/inventory.schema.json",
+  "title": "inventory.json",
+  "description": "bin/inventory.mjs \u2014 static route/data inventory and the mutation -> entity -> route sync graph.",
+  "type": "object",
+  "required": [
+    "root",
+    "generated",
+    "counts",
+    "routes",
+    "matrix",
+    "resourceMatrix",
+    "syncRisks",
+    "syncRisksWaived",
+    "duplicateSources",
+    "cache"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "root": {
+      "type": "string"
+    },
+    "routing": {
+      "type": "object",
+      "description": "How the application maps a route path to a browser URL. `path` (the default) means <base><path>; `hash` means <base>/#<path>, detected from the router's own API (createHashRouter, HashRouter, useHashLocation, createWebHashHistory, createHashHistory) and never from a `#/` string. Route paths in `routes` stay logical in both modes.",
+      "required": [
+        "mode",
+        "evidence"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "path",
+            "hash"
+          ]
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "file",
+              "line",
+              "match"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "match": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "cache": {
+      "$ref": "#/$defs/cache"
+    },
+    "atlasVersion": {
+      "type": "integer",
+      "enum": [
+        1,
+        2
+      ]
+    },
+    "generated": {
+      "type": "string"
+    },
+    "counts": {
+      "type": "object",
+      "required": [
+        "files",
+        "routes",
+        "entities",
+        "queries",
+        "queryUsages",
+        "mutations",
+        "syncRisks",
+        "syncRisksWaived",
+        "duplicateSources"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "routes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "entities": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "queries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "queryUsages": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "mutations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "syncRisks": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "syncRisksWaived": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "duplicateSources": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "routes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/route"
+      }
+    },
+    "matrix": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "resourceMatrix": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "syncRisks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/syncRisk"
+      }
+    },
+    "syncRisksWaived": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/syncRisk"
+      }
+    },
+    "duplicateSources": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/duplicateSource"
+      }
+    },
+    "coherence": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "schemaVersion",
+            "coverage",
+            "resourceFamilies",
+            "cacheKeys",
+            "cacheOperations",
+            "reads",
+            "mutations",
+            "invalidations",
+            "operationReadPairs",
+            "surfaces",
+            "ownershipEdges",
+            "candidates",
+            "graph"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "schemaVersion": {
+              "const": 4
+            },
+            "coverage": {
+              "type": "object",
+              "required": [
+                "status",
+                "reason",
+                "counts",
+                "unresolved"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "status": {
+                  "enum": [
+                    "measured",
+                    "partial",
+                    "unmeasured"
+                  ]
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "counts": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "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": {
+                    "$ref": "#/$defs/coherenceUnresolvedV3"
+                  }
+                }
+              }
+            },
+            "resourceFamilies": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceFamily"
+              }
+            },
+            "cacheKeys": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceCacheKey"
+              }
+            },
+            "cacheOperations": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceCacheOperationStrict"
+              }
+            },
+            "reads": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceReadV3"
+              }
+            },
+            "mutations": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceMutationV3"
+              }
+            },
+            "invalidations": {
+              "type": "array",
+              "maxItems": 0
+            },
+            "operationReadPairs": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceOperationReadPair"
+              }
+            },
+            "surfaces": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceSurface"
+              }
+            },
+            "ownershipEdges": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceOwnershipEdge"
+              }
+            },
+            "candidates": {
+              "type": "array"
+            },
+            "units": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceUnit"
+              }
+            },
+            "graph": {
+              "type": "object",
+              "description": "The semantic-graph v2 root; graph.schema.json is its full contract.",
+              "required": [
+                "artifact",
+                "schemaVersion",
+                "coverage",
+                "nodes",
+                "edges"
+              ],
+              "properties": {
+                "artifact": {
+                  "const": "frontend-verify.semantic-graph"
+                },
+                "schemaVersion": {
+                  "const": 2
+                }
+              }
+            }
+          },
+          "description": "CURRENT (v4). One semantic graph v2 is REQUIRED; every compatibility array is a checked projection of it. Schema validity is necessary and not sufficient -- the graph must also pass graph.schema.json and validateSemanticGraph, which qa dev validate runs at this boundary."
+        },
+        {
+          "type": "object",
+          "required": [
+            "schemaVersion",
+            "coverage",
+            "resourceFamilies",
+            "reads",
+            "mutations",
+            "invalidations",
+            "surfaces",
+            "candidates"
+          ],
+          "additionalProperties": true,
+          "properties": {
+            "schemaVersion": {
+              "const": 1
+            }
+          },
+          "description": "LEGACY (v1), non-proof. Readable for migration and query only: it carries no semantic graph, so nothing in it satisfies a current join, obligation, or measured denominator. validateCoherenceIrIdentities returns {current:false} for it."
+        },
+        {
+          "type": "object",
+          "required": [
+            "schemaVersion",
+            "coverage",
+            "resourceFamilies",
+            "reads",
+            "mutations",
+            "invalidations",
+            "surfaces",
+            "ownershipEdges",
+            "candidates"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "schemaVersion": {
+              "const": 2
+            },
+            "coverage": {
+              "type": "object",
+              "required": [
+                "status",
+                "reason",
+                "counts",
+                "unresolved"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "measured",
+                    "partial",
+                    "unmeasured"
+                  ]
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "counts": {
+                  "type": "object",
+                  "required": [
+                    "ownershipEdgesDiscovered",
+                    "ownershipEdgesResolved",
+                    "ownershipEdgesUnresolved",
+                    "ambiguousMutationOccurrences"
+                  ],
+                  "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
+                    }
+                  }
+                },
+                "unresolved": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/$defs/coherenceUnresolved"
+                  }
+                }
+              }
+            },
+            "resourceFamilies": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceFamily"
+              }
+            },
+            "reads": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceRead"
+              }
+            },
+            "mutations": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceMutation"
+              }
+            },
+            "invalidations": {
+              "type": "array"
+            },
+            "surfaces": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceSurface"
+              }
+            },
+            "ownershipEdges": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceOwnershipEdge"
+              }
+            },
+            "candidates": {
+              "type": "array"
+            },
+            "units": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceUnit"
+              }
+            }
+          },
+          "description": "LEGACY (v2), non-proof. Readable for migration and query only: it carries no semantic graph, so nothing in it satisfies a current join, obligation, or measured denominator. validateCoherenceIrIdentities returns {current:false} for it."
+        },
+        {
+          "type": "object",
+          "required": [
+            "schemaVersion",
+            "coverage",
+            "resourceFamilies",
+            "cacheKeys",
+            "cacheOperations",
+            "reads",
+            "mutations",
+            "invalidations",
+            "operationReadPairs",
+            "surfaces",
+            "ownershipEdges",
+            "candidates"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "schemaVersion": {
+              "const": 3
+            },
+            "coverage": {
+              "type": "object",
+              "required": [
+                "status",
+                "reason",
+                "counts",
+                "unresolved"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "status": {
+                  "enum": [
+                    "measured",
+                    "partial",
+                    "unmeasured"
+                  ]
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "counts": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "integer",
+                    "minimum": 0
+                  }
+                },
+                "unresolved": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/$defs/coherenceUnresolvedV3"
+                  }
+                }
+              }
+            },
+            "resourceFamilies": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceFamily"
+              }
+            },
+            "cacheKeys": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceCacheKey"
+              }
+            },
+            "cacheOperations": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceCacheOperationStrict"
+              }
+            },
+            "reads": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceReadV3"
+              }
+            },
+            "mutations": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceMutationV3"
+              }
+            },
+            "invalidations": {
+              "type": "array",
+              "maxItems": 0
+            },
+            "operationReadPairs": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceOperationReadPair"
+              }
+            },
+            "surfaces": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceSurface"
+              }
+            },
+            "ownershipEdges": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceOwnershipEdge"
+              }
+            },
+            "candidates": {
+              "type": "array"
+            },
+            "units": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceUnit"
+              }
+            }
+          },
+          "description": "LEGACY (v3), non-proof. Readable for migration and query only: it carries no semantic graph, so nothing in it satisfies a current join, obligation, or measured denominator. validateCoherenceIrIdentities returns {current:false} for it."
+        }
+      ],
+      "description": "Embedded coherence IR. Exactly one branch matches: the current v4 root, or one of the explicitly legacy v1/v2/v3 roots, which are never current proof."
+    }
+  },
+  "$defs": {
+    "coherenceId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "coherenceMutation": {
+      "type": "object",
+      "required": [
+        "id",
+        "material"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "material": {
+          "type": "object",
+          "required": [
+            "namespace",
+            "version",
+            "sourceRef",
+            "endpoint"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "namespace": {
+              "const": "coherence/mutation"
+            },
+            "version": {
+              "const": 1
+            },
+            "sourceRef": {
+              "type": "object",
+              "required": [
+                "file",
+                "line"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "file": {
+                  "type": "string"
+                },
+                "line": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "endpoint": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "hook": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "family": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "writes": {
+          "type": "array"
+        },
+        "invalidations": {
+          "type": "array"
+        },
+        "confidence": {
+          "type": "string"
+        }
+      }
+    },
+    "coherenceJcsValue": {
+      "anyOf": [
+        {
+          "type": [
+            "string",
+            "boolean",
+            "null"
+          ]
+        },
+        {
+          "type": "number",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/coherenceJcsValue"
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/coherenceJcsValue"
+          }
+        }
+      ]
+    },
+    "coherenceKeyOrigin": {
+      "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
+        }
+      }
+    },
+    "coherenceLiteralTerm": {
+      "type": "object",
+      "required": [
+        "kind",
+        "value"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "const": "literal"
+        },
+        "value": {
+          "$ref": "#/$defs/coherenceJcsValue"
+        },
+        "origin": {
+          "$ref": "#/$defs/coherenceKeyOrigin"
+        }
+      }
+    },
+    "coherenceSymbolicTerm": {
+      "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/coherenceKeyOrigin"
+        },
+        "resolutionPath": {
+          "type": "array",
+          "maxItems": 26,
+          "items": {
+            "type": "string"
+          }
+        },
+        "resolution": {
+          "const": "unresolved"
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "coherenceKeyTerm": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/coherenceLiteralTerm"
+        },
+        {
+          "$ref": "#/$defs/coherenceSymbolicTerm"
+        }
+      ]
+    },
+    "coherenceCacheKey": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "provenance"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "material": {
+          "type": "object",
+          "required": [
+            "namespace",
+            "version",
+            "segments"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "namespace": {
+              "const": "coherence/cache-key"
+            },
+            "version": {
+              "const": 1
+            },
+            "segments": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceKeyTerm"
+              }
+            }
+          }
+        },
+        "provenance": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "coherenceCacheOperationStrict": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "provenance"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "material": {
+          "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": {
+              "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"
+                  ]
+                }
+              }
+            },
+            "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/coherenceKeyTerm"
+                }
+              ]
+            },
+            "filters": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": {},
+                "stale": {},
+                "fetchStatus": {},
+                "refetchType": {}
+              }
+            },
+            "effects": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "kind",
+                  "scope"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "kind": {
+                    "enum": [
+                      "invalidate",
+                      "refetch",
+                      "reset",
+                      "remove",
+                      "update",
+                      "clear-query-cache",
+                      "clear-mutation-cache"
+                    ]
+                  },
+                  "scope": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "provenance": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "coherenceMutationV3": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "file",
+        "line",
+        "endpoint",
+        "family",
+        "writes",
+        "operationIds",
+        "confidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "material": {
+          "type": "object",
+          "required": [
+            "namespace",
+            "version",
+            "sourceRef",
+            "endpoint"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "namespace": {
+              "const": "coherence/mutation"
+            },
+            "version": {
+              "const": 1
+            },
+            "sourceRef": {
+              "type": "object",
+              "required": [
+                "file",
+                "line"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "file": {
+                  "type": "string"
+                },
+                "line": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "endpoint": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
+        "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"
+        },
+        "operationIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/coherenceId"
+          }
+        },
+        "confidence": {
+          "enum": [
+            "exact",
+            "resolved",
+            "coarse",
+            "unresolved"
+          ]
+        }
+      }
+    },
+    "coherenceReadV3": {
+      "type": "object",
+      "required": [
+        "id",
+        "keyId",
+        "file",
+        "line",
+        "pattern",
+        "endpoint",
+        "family",
+        "confidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceEvidenceId"
+        },
+        "keyId": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "span": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/coherenceSourceSpan"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "pattern": {
+          "type": "object",
+          "required": [
+            "segments"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "segments": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/coherenceKeyTerm"
+              }
+            }
+          }
+        },
+        "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"
+          ]
+        }
+      }
+    },
+    "coherenceOperationReadPair": {
+      "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/coherenceId"
+        },
+        "readId": {
+          "$ref": "#/$defs/coherenceEvidenceId"
+        },
+        "keyCoverage": {
+          "enum": [
+            "covered",
+            "not-covered",
+            "unresolved"
+          ]
+        },
+        "effectCoverage": {
+          "enum": [
+            "covered",
+            "not-covered",
+            "unresolved"
+          ]
+        },
+        "mandatory": {
+          "type": "boolean"
+        }
+      }
+    },
+    "coherenceSurface": {
+      "type": "object",
+      "required": [
+        "id",
+        "material",
+        "route",
+        "file",
+        "component",
+        "readIds",
+        "families",
+        "confidence",
+        "kind"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "material": {
+          "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": {
+              "type": "object",
+              "required": [
+                "file",
+                "line"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "file": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "line": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            }
+          }
+        },
+        "route": {
+          "type": "string"
+        },
+        "file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "component": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "readIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/coherenceEvidenceId"
+          }
+        },
+        "families": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "confidence": {
+          "enum": [
+            "exact",
+            "resolved",
+            "coarse",
+            "unresolved"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "route",
+            "component",
+            "modal",
+            "drawer",
+            "tab",
+            "wizard-step",
+            "embedded-widget"
+          ]
+        }
+      }
+    },
+    "coherenceFamily": {
+      "type": "object",
+      "required": [
+        "id",
+        "material"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "material": {
+          "type": "object",
+          "required": [
+            "namespace",
+            "version",
+            "endpointFamily"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "namespace": {
+              "const": "coherence/family"
+            },
+            "version": {
+              "const": 1
+            },
+            "endpointFamily": {
+              "type": "string"
+            }
+          }
+        },
+        "family": {
+          "type": "string"
+        },
+        "mutationIds": {
+          "type": "array"
+        },
+        "readIds": {
+          "type": "array"
+        },
+        "surfaceIds": {
+          "type": "array"
+        },
+        "keyTerms": {
+          "type": "array"
+        },
+        "invalidations": {
+          "type": "integer"
+        },
+        "invalidationsUnresolved": {
+          "type": "integer"
+        },
+        "readsUnresolvedKey": {
+          "type": "integer"
+        }
+      }
+    },
+    "coherenceEvidenceId": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "coherenceSourceSpan": {
+      "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
+        }
+      }
+    },
+    "coherenceRead": {
+      "type": "object",
+      "required": [
+        "id",
+        "file",
+        "line",
+        "span",
+        "pattern",
+        "endpoint",
+        "family",
+        "confidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/coherenceEvidenceId"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "span": {
+          "$ref": "#/$defs/coherenceSourceSpan"
+        },
+        "pattern": {
+          "type": "object"
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "family": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "confidence": {
+          "enum": [
+            "exact",
+            "resolved",
+            "coarse",
+            "unresolved"
+          ]
+        }
+      }
+    },
+    "coherenceUnresolved": {
+      "type": "object",
+      "required": [
+        "id",
+        "file",
+        "line",
+        "kind",
+        "reason"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "kind": {
+          "enum": [
+            "read",
+            "write",
+            "ownership"
+          ]
+        },
+        "reason": {
+          "type": "string"
+        },
+        "span": {
+          "$ref": "#/$defs/coherenceSourceSpan"
+        }
+      }
+    },
+    "coherenceUnresolvedV3": {
+      "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/coherenceSourceSpan"
+        }
+      }
+    },
+    "coherenceOwnershipEdge": {
+      "type": "object",
+      "required": [
+        "surfaceId",
+        "readId",
+        "confidence",
+        "resolution",
+        "reason",
+        "source",
+        "provenance",
+        "path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "surfaceId": {
+          "$ref": "#/$defs/coherenceId"
+        },
+        "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/coherenceSourceSpan"
+        },
+        "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/coherenceEvidenceId"
+            },
+            "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"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "coherenceModuleRef": {
+      "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/coherenceSourceSpan"
+        }
+      }
+    },
+    "coherenceUnit": {
+      "type": "object",
+      "required": [
+        "file",
+        "imports",
+        "moduleRefs"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "imports": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "moduleRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/coherenceModuleRef"
+          }
+        }
+      }
+    },
+    "cache": {
+      "type": "object",
+      "description": "the content-identity cache lib/qa/source-snapshot.mjs computes -- see CLAUDE.md 'Outputs are byte-stable'.",
+      "required": [
+        "hit",
+        "identity",
+        "schemaVersion",
+        "sourceDigest",
+        "computedAt"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "hit": {
+          "type": "boolean"
+        },
+        "identity": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "schemaVersion": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "sourceDigest": {
+          "type": "string"
+        },
+        "computedAt": {
+          "type": "string"
+        },
+        "reusedAt": {
+          "type": "string"
+        }
+      }
+    },
+    "route": {
+      "type": "object",
+      "required": [
+        "path",
+        "file",
+        "kind",
+        "modules",
+        "entities",
+        "queries",
+        "mutations"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "file": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "next-app",
+            "next-pages",
+            "react-router",
+            "route-config",
+            "file-router",
+            "remix",
+            "sveltekit",
+            "astro",
+            "vue-pages",
+            "expo-router",
+            "declared"
+          ]
+        },
+        "component": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "modules": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "entities": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "queries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/query"
+          }
+        },
+        "mutations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/mutation"
+          }
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "repo-relative files reachable from the route entry (capped at 400)"
+        }
+      }
+    },
+    "query": {
+      "type": "object",
+      "required": [
+        "key",
+        "file",
+        "line"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "entity": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "key": {
+          "type": "string"
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "hook": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "via": {
+          "type": "string"
+        },
+        "verb": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "mutation": {
+      "type": "object",
+      "required": [
+        "invalidates",
+        "clearsCache",
+        "clearsIndirectly",
+        "nonWrite",
+        "file",
+        "line"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "writes": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "verb": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "fnName": {
+          "type": "string"
+        },
+        "hook": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "invalidates": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "via": {
+          "type": "string",
+          "description": "How the mutation was found. `raw-write` marks the raw client-write fallback, used when the repo has no mutation-hook layer at all: its endpoint and verb are measured, its cache semantics are NOT read, so clearsCache/invalidates carry no evidence and it is never judged for staleness, and syncRiskCoverage stays `unmeasured` while these are the only mutations found. Otherwise `via` is the repo-declared wrapper hook the mutation was found through (collectWrappers in bin/inventory.mjs captures the identifier, so the value cannot be enumerated ahead of time -- it is whatever the target repo named its data layer).",
+          "pattern": "^(raw-write|use[A-Z][A-Za-z0-9_]*)$"
+        },
+        "clearsCache": {
+          "type": "boolean"
+        },
+        "clearsIndirectly": {
+          "type": "boolean"
+        },
+        "nonWrite": {
+          "type": "boolean"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "route": {
+          "type": "string"
+        }
+      }
+    },
+    "syncRisk": {
+      "type": "object",
+      "required": [
+        "severity",
+        "kind",
+        "route",
+        "mutation",
+        "invalidates",
+        "detail"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "severity": {
+          "type": "string",
+          "enum": [
+            "P0",
+            "P1",
+            "P2",
+            "P3"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "no-invalidation",
+            "partial-invalidation"
+          ]
+        },
+        "unresolved": {
+          "type": "boolean"
+        },
+        "route": {
+          "type": "string"
+        },
+        "entity": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "hook": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "mutation": {
+          "type": "string"
+        },
+        "verb": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "endpoint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "invalidates": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "staleRoutes": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "detail": {
+          "type": "string"
+        }
+      }
+    },
+    "duplicateSource": {
+      "type": "object",
+      "required": [
+        "entity",
+        "endpoint",
+        "keys",
+        "detail"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "entity": {
+          "type": "string"
+        },
+        "endpoint": {
+          "type": "string"
+        },
+        "keys": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "detail": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}