scip-query 0.19.6 → 0.19.10

package/docs/WATCH_REFRESH_REQUESTS.md

@@ -21,10 +21,15 @@ A claim is an exclusive processing marker for that admitted request. A
 completion is a durable receipt proving that the attempt associated with the
 claim finished successfully, or that the request expired before execution.
 
-These records provide at-least-once execution for an accepted, unexpired
-request. At-least-once execution means a crash after reindex success but before
-the completion receipt may repeat the safe reindex operation; it never means an
-unacknowledged request can disappear.
+On hosts that support directory synchronization, these records provide
+at-least-once execution across process, operating-system, and machine failure
+for an accepted, unexpired request. At-least-once execution means a crash after
+reindex success but before the completion receipt may repeat the safe reindex
+operation; it never means an acknowledged request can disappear. On Windows
+hosts where Node cannot synchronize directory handles, admission reports
+`achievedDurability: "file-flushed"` and `directorySync: "unsupported"`:
+process-crash recovery remains intact, but the stronger machine-crash
+namespace guarantee is not claimed.
 
 ## Layout
 
@@ -52,18 +57,22 @@ deadline remain authoritative.
 
 ## Lifecycle
 
-1. The requester durably writes a complete staging record.
-2. It exclusively links that record into `requests/`. A collision is a
+1. The requester durably establishes the protocol root, `staging/`, and the
+   target record directory from the nearest existing ancestor.
+2. It writes and flushes a complete staging record.
+3. It exclusively links that record into `requests/`. A collision is a
    duplicate, not an overwrite.
-3. The watch server, while holding the project watch lock, claims pending,
+4. It flushes `requests/` before returning accepted and reports the achieved
+   platform guarantee.
+5. The watch server, while holding the project watch lock, claims pending,
    unexpired requests through exclusive claim records.
-4. It deliberately coalesces one claimed batch into one `watch-demand`
+6. It deliberately coalesces one claimed batch into one `watch-demand`
    refresh. Requests arriving while the watcher is busy remain pending.
-5. A successful corresponding reindex writes every completion receipt before
+7. A successful corresponding reindex writes every completion receipt before
    removing any claim.
-6. A failed reindex removes its claims without writing completion, making the
+8. A failed reindex removes its claims without writing completion, making the
    requests pending after a bounded retry delay.
-7. A successor watch server removes predecessor claims only after acquiring
+9. A successor watch server removes predecessor claims only after acquiring
    the same exclusive watch lock. Completed requests remain completed; all
    other claimed requests become pending.
 
@@ -76,17 +85,21 @@ retention window.
 
 ## Crash and Concurrency Outcomes
 
-| Boundary | Observable outcome |
-| --- | --- |
-| Crash before exclusive admission | No request was accepted; only staging may remain |
+| Boundary                                         | Observable outcome                                                                      |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| Crash before exclusive admission                 | No request was accepted; only staging may remain                                        |
 | Crash after admission before caller sees success | Request remains pending; retrying the same idempotency key returns the admitted request |
-| Two callers use one idempotency key | Exactly one immutable request wins |
-| Two callers use distinct keys | Both requests remain independently visible and may be coalesced deliberately |
-| Crash after claim before reindex | Successor clears the stale claim and retries the request |
-| Reindex failure | Claim is released; request remains pending |
-| Crash after reindex before completion | Request may execute again; it is never lost |
-| Crash after completion before claim removal | Completion prevents replay; successor removes the obsolete claim |
-| Activity writer races any row above | Activity changes only `watch-activity.json` and cannot modify request state |
+| Two callers use one idempotency key              | Exactly one immutable request wins                                                      |
+| Two callers use distinct keys                    | Both requests remain independently visible and may be coalesced deliberately            |
+| Crash after claim before reindex                 | Successor clears the stale claim and retries the request                                |
+| Reindex failure                                  | Claim is released; request remains pending                                              |
+| Crash after reindex before completion            | Request may execute again; it is never lost                                             |
+| Crash after completion before claim removal      | Completion prevents replay; successor removes the obsolete claim                        |
+| Activity writer races any row above              | Activity changes only `watch-activity.json` and cannot modify request state             |
+
+The first two rows are machine-crash claims only when admission returned
+`directory-durable`. A `file-flushed` result is explicit evidence that the
+host could not commit the complete namespace frontier.
 
 ## Compatibility and Diagnostics
 

package/docs/WINDOWS_SIDECAR_RELEASE.md

@@ -234,10 +234,15 @@ both coordinates and repairs only the absent intended package.
 The path is stable for one pair of package coordinates. Repacking different
 bytes, using a different source revision, or selecting a different registry
 under those same versions therefore collides with the existing record and
-stops before registry work. The record is atomically replaced with directory
-durability while the release lock is owned. It is intentionally ignored by Git
-and omitted from the npm package: it is local recovery state, not portable
-release authority. The normative shape is
+stops before registry work. The record is atomically replaced while the
+release lock is owned. The coordinator reports `directory-durable` when the
+host synchronizes the containing directory and
+`file-flushed; directory sync unsupported` when Windows exposes only the
+bounded file guarantee; a real synchronization failure aborts the run. It is
+intentionally ignored by Git and omitted from the npm package: it is local
+recovery state, not portable release authority. Fresh registry observation,
+immutable npm versions, and exact package identity remain the external safety
+authority regardless of the local result. The normative shape is
 `docs/schemas/npm-release-state.schema.json`.
 
 Current-schema additive fields are tolerated. Malformed JSON, a wrong

package/docs/analyzer-inventory.md

@@ -52,7 +52,7 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 | `wrapper-candidates`             | Small production callables with one real external caller, caller fan-in, and boundary-token evidence                                                                                                                                |                             Hygiene | Contextual signal, sometimes direct                                                                          | Single-caller wrappers can be needless indirection, but may also be names, domain/lifecycle boundaries, test seams, or API shaping. Boundary evidence discounts those without hiding them.                                                                                                                               |
 | `passthrough-candidates`         | Small production callables with exactly one callee, literal pass-through body, runtime-boundary evidence, public-facade evidence, action tier, recommendation, and score count                                                      | Hygiene, with `scoreCount` discount | Direct when no boundary or public-facade evidence is present; contextual signal when either exists           | Body-shape gate is real. Boundary evidence distinguishes adapter, provider, public, capability, transport, lifecycle, access-policy, and facade-shaped forwarders; public-facade evidence separately identifies package-public or rooted exported passthroughs.                                                          |
 | `stale-abstractions`             | Type-like definitions, real consumers, barrel consumers, transitive reachability, definer usage, confidence, staleness kind, action tier, and recommendation                                                                        |                             Hygiene | Direct for unused abstractions; contextual signal for one-consumer ownership rows                            | `0 consumers` is direct repair. `1 consumer` is contextual, including high-confidence misplaced types, because the repair may be move, inline, keep, or document as public contract.                                                                                                                                     |
-| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, project-owned architecture report, sibling patterns, action tier, policy basis, recommendation                                                                      |                             Hygiene | Split by kind                                                                                                | `unused-import` and grouped `architecture-violation` rows are direct repair. `pattern-deviation` rows are contextual signals and remain excluded from health scoring. Undeclared boundary edges, reciprocity, and connected groups appear only in architecture context.                                                   |
+| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, project-owned architecture report, sibling patterns, action tier, policy basis, recommendation                                                                      |                             Hygiene | Split by kind                                                                                                | `unused-import` and grouped `architecture-violation` rows are direct repair. `pattern-deviation` rows are contextual signals and remain excluded from health scoring. Undeclared boundary edges, reciprocity, and connected groups appear only in architecture context.                                                  |
 | `complexity-hotspots`            | Production callable LOC, fan-in, fan-out, callee count                                                                                                                                                                              |                                Risk | Direct repair pressure                                                                                       | Complexity pressure usually means refactor, but the current score is structural, not cyclomatic. It should be separate from branch-count complexity.                                                                                                                                                                     |
 | `co-change` / hidden coupling    | Git co-change pairs, dependency edges, declared couplings, file noise filters, partner-class labels, declared-coupling suggestions, commit scope, recency context, commit-subject context, and score-weighted count                 |  Risk, weighted by history strength | Contextual signal                                                                                            | Strong evidence that coordination may be missing, but not proof that extraction or unification is correct. Partner classes, history context, subject context, and score weighting now separate contract-like focused current pairs from broad, stale, or unlabeled history before suggesting declared coupling.          |
 | Suppression inventory            | `scip-query: ignore-*` comments in source, plus structured `.scipquery.json` suppressions                                                                                                                                           |               Evidence quality axis | Meta signal                                                                                                  | Useful precision feedback. High suppressions should reduce trust or weight for that detector family. Structured file-scoped suppressions now validate path freshness.                                                                                                                                                    |
@@ -85,19 +85,19 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 
 ## Graph, Risk, and Planning Analyzers
 
-| Analyzer             | Evidence examined                                                                                                                  | Recommended role          | Evaluation                                                                                                                                                          |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `affected`           | Transitive symbol impact from a changed symbol                                                                                     | Support analysis          | Blast-radius map, not smell.                                                                                                                                        |
-| `change-surface`     | Definitions in a file plus external consumer counts                                                                                | Support/risk analysis     | Pre-change risk briefing. Useful for planning and score context, not a repair.                                                                                      |
-| `plan-context`       | Trace, references, call graph, dataflow, deps/rdeps, surface, affected, change-surface, complexity, history                        | Support analysis          | Composite planning bundle. It should not contribute smell score directly.                                                                                           |
-| `bottlenecks`        | Callable fan-in times fan-out, risk kind, action tier, evidence reasons, recommendation                                            | Contextual signal         | Good risk hotspot, not automatic refactor. Output now states `signal` and frames central code as coordination risk rather than repair proof.                        |
-| `hotspots`           | Most referenced symbols                                                                                                            | Support/contextual signal | Identifies choke points. Not a smell alone.                                                                                                                         |
-| `fan-in` / `fan-out` | Reference counts into symbols or out of files                                                                                      | Support analysis          | Raw graph metrics.                                                                                                                                                  |
-| `coupling`           | Shared symbols between two files or top coupled pairs, coupling kind, action tier, evidence reasons, recommendation                | Contextual signal         | May reveal boundary problems, but shared symbols can be intended. Output now makes the coordination-pressure interpretation explicit.                               |
-| `architecture`       | Project-owned boundary paths and dependency rules applied to resolved import and re-export edges, with mapping coverage, policy-row coverage, edge breadth, reciprocity, and SCCs | Split by evidence         | Forbidden edges, required-but-missing policy rows, cycles under `requireAcyclic`, and boundaries hiding an internal sub-directory cycle under `requireResolvedBoundaries` are direct policy findings. Unmapped files, reciprocity, and advisory cycles remain report-only signals.                       |
-| `deep-chains`        | Longest dependency chains after SCC condensation, suffix de-duplication, chain kind, action tier, evidence reasons, recommendation | Contextual signal         | Long chains imply propagation risk, but action depends on layers and ownership. Strict suffix duplicates are now removed from top results.                          |
-| `complexity`         | Branch count, cyclomatic estimate, callee count, fan-in, fan-out for one symbol                                                    | Direct repair pressure    | This is closer to the user-specified "cyclomatic complexity" analyzer than `complexity-hotspots`. Should score strongly when branches/cyclomatic exceed thresholds. |
-| `self-audit`         | Cheap evidence paths checked against TypeScript compiler oracle                                                                    | Meta analysis             | Measures analyzer accuracy. Should guide trust/weight, not code health directly.                                                                                    |
+| Analyzer             | Evidence examined                                                                                                                                                                 | Recommended role          | Evaluation                                                                                                                                                                                                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `affected`           | Transitive symbol impact from a changed symbol                                                                                                                                    | Support analysis          | Blast-radius map, not smell.                                                                                                                                                                                                                                                       |
+| `change-surface`     | Definitions in a file plus external consumer counts                                                                                                                               | Support/risk analysis     | Pre-change risk briefing. Useful for planning and score context, not a repair.                                                                                                                                                                                                     |
+| `plan-context`       | Trace, references, call graph, dataflow, deps/rdeps, surface, affected, change-surface, complexity, history                                                                       | Support analysis          | Composite planning bundle. It should not contribute smell score directly.                                                                                                                                                                                                          |
+| `bottlenecks`        | Callable fan-in times fan-out, risk kind, action tier, evidence reasons, recommendation                                                                                           | Contextual signal         | Good risk hotspot, not automatic refactor. Output now states `signal` and frames central code as coordination risk rather than repair proof.                                                                                                                                       |
+| `hotspots`           | Most referenced symbols                                                                                                                                                           | Support/contextual signal | Identifies choke points. Not a smell alone.                                                                                                                                                                                                                                        |
+| `fan-in` / `fan-out` | Reference counts into symbols or out of files                                                                                                                                     | Support analysis          | Raw graph metrics.                                                                                                                                                                                                                                                                 |
+| `coupling`           | Shared symbols between two files or top coupled pairs, coupling kind, action tier, evidence reasons, recommendation                                                               | Contextual signal         | May reveal boundary problems, but shared symbols can be intended. Output now makes the coordination-pressure interpretation explicit.                                                                                                                                              |
+| `architecture`       | Project-owned boundary paths and dependency rules applied to resolved import and re-export edges, with mapping coverage, policy-row coverage, edge breadth, reciprocity, and SCCs | Split by evidence         | Forbidden edges, required-but-missing policy rows, cycles under `requireAcyclic`, and boundaries hiding an internal sub-directory cycle under `requireResolvedBoundaries` are direct policy findings. Unmapped files, reciprocity, and advisory cycles remain report-only signals. |
+| `deep-chains`        | Longest dependency chains after SCC condensation, suffix de-duplication, chain kind, action tier, evidence reasons, recommendation                                                | Contextual signal         | Long chains imply propagation risk, but action depends on layers and ownership. Strict suffix duplicates are now removed from top results.                                                                                                                                         |
+| `complexity`         | Branch count, cyclomatic estimate, callee count, fan-in, fan-out for one symbol                                                                                                   | Direct repair pressure    | This is closer to the user-specified "cyclomatic complexity" analyzer than `complexity-hotspots`. Should score strongly when branches/cyclomatic exceed thresholds.                                                                                                                |
+| `self-audit`         | Cheap evidence paths checked against TypeScript compiler oracle                                                                                                                   | Meta analysis             | Measures analyzer accuracy. Should guide trust/weight, not code health directly.                                                                                                                                                                                                   |
 
 ## Navigation and Evidence Providers
 
@@ -123,14 +123,14 @@ The codebase already avoids some duplicate analysis by sharing kernels:
 
 The remaining conceptual overlap is mostly healthy, but needs product labels:
 
-| Overlap family             | Members                                                                                                                              | Same analysis or distinct?                                                                                      | Recommendation                                                                                                                                          |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Deletability               | `dead`, `isolated`, `cleanup-plan`, `redundant-reexports`, `new-dead`                                                                | Distinct evidence scopes over the same core question: can this be removed or must it be wired?                  | Model as one "deletability" action family with subtypes and confidence.                                                                                 |
-| Similarity and reuse       | `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, React/Vue duplicates, `recent-duplicates`, `echo` | Distinct evidence bases. The risk is UX confusion, not implementation duplication.                              | Keep separate, but expose basis, action tier, and root-cause groups where pairwise rows repeat.                                                         |
-| Extraction pressure        | `extract-candidates`, React/Vue behavior candidates, large component/view pressure, `incomplete-migration`                           | Different stages: discover seam, detect duplicated behavior, detect excessive size, catch unfinished migration. | Score unfinished migrations higher than discovery leads.                                                                                                |
-| Indirection                | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`                                                                 | Related but not the same: single caller, literal forwarding, low-consumer types.                                | Passthrough and wrapper rows now split by boundary evidence; stale should split by confidence.                                                          |
-| Architecture/history drift | `architecture`, `drift`, `doc-drift`, `co-change`, `co-change-partner`, `doc-reference`                                              | Same broad problem of things moving out of sync, but sources differ.                                            | Explicit architecture rules are direct; co-change remains signal; doc-reference strength depends on citation kind.                                     |
-| Graph risk                 | `architecture`, `fan-in`, `fan-out`, `hotspots`, `bottlenecks`, `coupling`, `deep-chains`, `change-surface`, `affected`              | Mostly layered views of graph pressure.                                                                         | Treat inferred graph shape as support/context; declared forbidden edges and acyclicity violations are direct policy disagreements.                     |
+| Overlap family             | Members                                                                                                                              | Same analysis or distinct?                                                                                      | Recommendation                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Deletability               | `dead`, `isolated`, `cleanup-plan`, `redundant-reexports`, `new-dead`                                                                | Distinct evidence scopes over the same core question: can this be removed or must it be wired?                  | Model as one "deletability" action family with subtypes and confidence.                                                            |
+| Similarity and reuse       | `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, React/Vue duplicates, `recent-duplicates`, `echo` | Distinct evidence bases. The risk is UX confusion, not implementation duplication.                              | Keep separate, but expose basis, action tier, and root-cause groups where pairwise rows repeat.                                    |
+| Extraction pressure        | `extract-candidates`, React/Vue behavior candidates, large component/view pressure, `incomplete-migration`                           | Different stages: discover seam, detect duplicated behavior, detect excessive size, catch unfinished migration. | Score unfinished migrations higher than discovery leads.                                                                           |
+| Indirection                | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`                                                                 | Related but not the same: single caller, literal forwarding, low-consumer types.                                | Passthrough and wrapper rows now split by boundary evidence; stale should split by confidence.                                     |
+| Architecture/history drift | `architecture`, `drift`, `doc-drift`, `co-change`, `co-change-partner`, `doc-reference`                                              | Same broad problem of things moving out of sync, but sources differ.                                            | Explicit architecture rules are direct; co-change remains signal; doc-reference strength depends on citation kind.                 |
+| Graph risk                 | `architecture`, `fan-in`, `fan-out`, `hotspots`, `bottlenecks`, `coupling`, `deep-chains`, `change-surface`, `affected`              | Mostly layered views of graph pressure.                                                                         | Treat inferred graph shape as support/context; declared forbidden edges and acyclicity violations are direct policy disagreements. |
 
 ## Score Model Implications
 
@@ -272,3 +272,12 @@ boundary paths and dependency rows to import-only file edges, retaining edge
 breadth and representative files. It is report-only in this slice: inferred
 reciprocity and strongly connected groups do not affect health or diff-gate,
 and an unconfigured repository receives no implicit source-layer policy.
+
+## 2026-07-26 Diff-Gate Progress Follow-Up
+
+The `src/queries/impact/diff-gate.ts` citation remains accurate after bounded
+progress reporting was added. `DIFF_GATE_CHECKS` is still the canonical public
+check list and `diffGate()` still owns check execution; the check-name type and
+process-local observer contract now live in `queries/internal`, while the
+impact query emits start and completion notifications around each executed
+check.

package/docs/analyzer-validation-ledger.md

@@ -506,3 +506,11 @@ still overriding it with the content-aware version. And the report described a
 single-import edge as "incidental rather than load-bearing" — the graph
 establishes edge breadth, not importance, so it now reports the measurement and
 says explicitly that breadth alone settles nothing.
+
+## 2026-07-26 Diff-Gate Progress Follow-Up
+
+The change-time gate and check-list citations remain accurate. Progress
+instrumentation does not add, remove, or reorder any `DIFF_GATE_CHECKS` entry:
+`diffGate()` emits process-local start and completion notifications around
+each check, while isolated CLI execution turns those notifications into
+diagnostic progress and active-detector timeout evidence.

package/docs/schemas/cli-output-page.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ainsleyclark/scip-query/blob/main/docs/schemas/cli-output-page.schema.json",
+  "title": "scip-query CLI output page v1",
+  "description": "A bounded, resumable page of rendered scip-query output.",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "producer", "command", "contentType", "page", "content"],
+  "properties": {
+    "kind": {
+      "const": "scip-query-output-page"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "producer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "const": "scip-query"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "command": {
+      "type": "string",
+      "minLength": 1
+    },
+    "contentType": {
+      "enum": ["text/plain", "application/json"]
+    },
+    "agentInstruction": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A direct evidence-completeness obligation for an AI agent consuming this page."
+    },
+    "page": {
+      "type": "object",
+      "required": [
+        "offset",
+        "returnedCharacters",
+        "totalCharacters",
+        "omittedCharacters",
+        "remainingCharacters",
+        "complete",
+        "outputHash"
+      ],
+      "properties": {
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "returnedCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "totalCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "omittedCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "remainingCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "complete": {
+          "type": "boolean"
+        },
+        "outputHash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "continuation": {
+          "type": "object",
+          "required": ["cursor", "command"],
+          "properties": {
+            "cursor": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096
+            },
+            "command": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "content": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/docs/schemas/outcome-event-record.schema.json

@@ -27,12 +27,68 @@
     },
     "comparisonBaseCommit": { "type": "string" },
     "verifiedAgainstCommit": { "type": "string" },
-    "symbol": { "type": "string" }
+    "symbol": { "type": "string" },
+    "gateRunId": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "observer": {
+      "type": "object",
+      "required": ["kind", "authority"],
+      "properties": {
+        "kind": { "enum": ["local-agent", "local-human", "protected-ci"] },
+        "authority": { "enum": ["repository-writable", "protected-external"] },
+        "source": { "type": "string", "minLength": 1, "maxLength": 256 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "authority": { "const": "protected-external" } }, "required": ["authority"] },
+          "then": { "properties": { "kind": { "const": "protected-ci" } } }
+        }
+      ],
+      "additionalProperties": true
+    },
+    "observation": {
+      "type": "object",
+      "required": ["schemaVersion", "authorityKind", "observedAt", "projectIdentity"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "authorityKind": {
+          "enum": ["index-worktree", "index-only", "worktree-only", "process-local"]
+        },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "projectIdentity": { "type": "string", "minLength": 1 },
+        "index": {
+          "type": "object",
+          "required": ["generationIdentity", "source", "alignment"],
+          "properties": {
+            "generationIdentity": { "type": "string", "minLength": 1 },
+            "source": { "enum": ["immutable", "legacy"] },
+            "alignment": { "enum": ["not-certified", "leased"] }
+          },
+          "additionalProperties": true
+        },
+        "worktree": {
+          "type": "object",
+          "required": ["identity", "clean"],
+          "properties": {
+            "identity": { "type": "string", "minLength": 1 },
+            "clean": { "type": "boolean" },
+            "headCommit": { "type": "string", "minLength": 1 },
+            "treeOid": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "suppressionPolicyVersion": { "type": "integer", "minimum": 1 }
   },
   "allOf": [
     {
       "if": { "required": ["verifiedAgainstCommit"] },
       "then": { "properties": { "event": { "const": "resolved" } } }
+    },
+    {
+      "if": { "required": ["suppressionPolicyVersion"] },
+      "then": { "properties": { "event": { "const": "suppressed" } } }
     }
   ],
   "additionalProperties": true

package/docs/schemas/project-config.schema.json

@@ -143,7 +143,88 @@
         "file": { "type": "string", "minLength": 1 },
         "reason": { "type": "string", "minLength": 1 },
         "expiresAt": { "type": "string", "format": "date-time" },
-        "createdAt": { "type": "string", "format": "date-time" }
+        "createdAt": { "type": "string", "format": "date-time" },
+        "decision": {
+          "type": "object",
+          "required": ["kind", "reasonCode", "decidedBy", "policyVersion", "evidence", "invalidateOn"],
+          "additionalProperties": true,
+          "properties": {
+            "kind": { "const": "automated-adjudication" },
+            "reasonCode": {
+              "enum": [
+                "entry-surface",
+                "generated-code",
+                "compatibility-shim",
+                "reflection-or-registration",
+                "test-fixture",
+                "intentional-twin",
+                "historical-coupling-ended",
+                "detector-counterexample"
+              ]
+            },
+            "decidedBy": { "enum": ["agent", "human"] },
+            "policyVersion": { "const": 1 },
+            "observation": {
+              "type": "object",
+              "required": ["schemaVersion", "authorityKind", "observedAt", "projectIdentity"],
+              "properties": {
+                "schemaVersion": { "const": 1 },
+                "authorityKind": {
+                  "enum": ["index-worktree", "index-only", "worktree-only", "process-local"]
+                },
+                "observedAt": { "type": "string", "format": "date-time" },
+                "projectIdentity": { "type": "string", "minLength": 1 },
+                "index": {
+                  "type": "object",
+                  "required": ["generationIdentity", "source", "alignment"],
+                  "properties": {
+                    "generationIdentity": { "type": "string", "minLength": 1 },
+                    "source": { "enum": ["immutable", "legacy"] },
+                    "alignment": { "enum": ["not-certified", "leased"] }
+                  },
+                  "additionalProperties": true
+                },
+                "worktree": {
+                  "type": "object",
+                  "required": ["identity", "clean"],
+                  "properties": {
+                    "identity": { "type": "string", "minLength": 1 },
+                    "clean": { "type": "boolean" },
+                    "headCommit": { "type": "string", "minLength": 1 },
+                    "treeOid": { "type": "string", "minLength": 1 }
+                  },
+                  "additionalProperties": true
+                }
+              },
+              "additionalProperties": true
+            },
+            "evidence": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "required": ["kind", "referent", "claim"],
+                "additionalProperties": true,
+                "properties": {
+                  "kind": { "enum": ["source", "config", "test", "graph"] },
+                  "referent": { "type": "string", "minLength": 1 },
+                  "claim": { "type": "string", "minLength": 1 },
+                  "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+                  "generation": { "type": "string", "minLength": 1 }
+                }
+              }
+            },
+            "invalidateOn": {
+              "type": "object",
+              "required": ["targetContentChange", "detectorMajorChange"],
+              "additionalProperties": true,
+              "properties": {
+                "targetContentChange": { "type": "boolean" },
+                "detectorMajorChange": { "type": "boolean" }
+              }
+            }
+          }
+        }
       },
       "anyOf": [{ "required": ["id"] }, { "required": ["check"] }]
     },

package/docs/schemas/suppression-record.schema.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://unpkg.com/scip-query/docs/schemas/suppression-record.schema.json",
-  "title": "scip-query suppression record v1",
+  "title": "scip-query suppression record v2",
   "description": "A repository-owned policy decision stored as one file under .scipquery/suppressions/.",
   "type": "object",
-  "required": ["kind", "schemaVersion", "suppressionIdentity", "writer", "reason", "createdAt"],
+  "required": ["kind", "schemaVersion", "suppressionIdentity", "writer", "reason", "createdAt", "decision"],
   "properties": {
     "kind": { "const": "scip-query-suppression" },
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "suppressionIdentity": { "type": "string", "minLength": 1 },
     "writer": {
       "type": "object",
@@ -22,6 +22,87 @@
     "check": { "type": "string", "minLength": 1 },
     "file": { "type": "string", "minLength": 1 },
     "reason": { "type": "string", "minLength": 1 },
+    "decision": {
+      "type": "object",
+      "required": ["kind", "reasonCode", "decidedBy", "policyVersion", "evidence", "invalidateOn"],
+      "properties": {
+        "kind": { "const": "automated-adjudication" },
+        "reasonCode": {
+          "enum": [
+            "entry-surface",
+            "generated-code",
+            "compatibility-shim",
+            "reflection-or-registration",
+            "test-fixture",
+            "intentional-twin",
+            "historical-coupling-ended",
+            "detector-counterexample"
+          ]
+        },
+        "decidedBy": { "enum": ["agent", "human"] },
+        "policyVersion": { "const": 1 },
+        "observation": {
+          "type": "object",
+          "required": ["schemaVersion", "authorityKind", "observedAt", "projectIdentity"],
+          "properties": {
+            "schemaVersion": { "const": 1 },
+            "authorityKind": {
+              "enum": ["index-worktree", "index-only", "worktree-only", "process-local"]
+            },
+            "observedAt": { "type": "string", "format": "date-time" },
+            "projectIdentity": { "type": "string", "minLength": 1 },
+            "index": {
+              "type": "object",
+              "required": ["generationIdentity", "source", "alignment"],
+              "properties": {
+                "generationIdentity": { "type": "string", "minLength": 1 },
+                "source": { "enum": ["immutable", "legacy"] },
+                "alignment": { "enum": ["not-certified", "leased"] }
+              },
+              "additionalProperties": true
+            },
+            "worktree": {
+              "type": "object",
+              "required": ["identity", "clean"],
+              "properties": {
+                "identity": { "type": "string", "minLength": 1 },
+                "clean": { "type": "boolean" },
+                "headCommit": { "type": "string", "minLength": 1 },
+                "treeOid": { "type": "string", "minLength": 1 }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["kind", "referent", "claim"],
+            "properties": {
+              "kind": { "enum": ["source", "config", "test", "graph"] },
+              "referent": { "type": "string", "minLength": 1 },
+              "claim": { "type": "string", "minLength": 1 },
+              "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+              "generation": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": true
+          }
+        },
+        "invalidateOn": {
+          "type": "object",
+          "required": ["targetContentChange", "detectorMajorChange"],
+          "properties": {
+            "targetContentChange": { "type": "boolean" },
+            "detectorMajorChange": { "type": "boolean" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
     "expiresAt": { "type": "string", "format": "date-time" },
     "createdAt": { "type": "string", "format": "date-time" },
     "updatedAt": { "type": "string", "format": "date-time" }