scip-query 0.19.4 → 0.19.6

package/docs/WINDOWS_SIDECAR_RELEASE.md

@@ -0,0 +1,298 @@
+# Windows Sidecar Provenance and Release
+
+The Windows sidecar is the npm package `scip-query-scip-windows` and the two
+Windows PE executables it carries. It is a platform-specific optional package
+whose distinguishing role is to make the `scip` index converter available on
+Windows without placing roughly 40 MB of Windows-only bytes in every
+`scip-query` installation.
+
+A sidecar provenance record is the versioned `provenance.json` file committed
+under `packages/scip-windows`. It is a build attestation distinguished by
+binding one sidecar package version to the exact upstream repository, tag,
+immutable source commit, Go toolchain, build flags, Windows target, PE machine,
+file size, and SHA-256 of both executable files. The JSON Schema is
+`docs/schemas/windows-sidecar-provenance.schema.json`.
+
+## Authority and guarantees
+
+The committed provenance record is the release authority for local sidecar
+bytes. The executable files are intentionally ignored by Git because of their
+size; file presence alone therefore proves nothing. A release is locally
+eligible only when all of these facts agree:
+
+1. The main package pins the exact sidecar package version.
+2. `provenance.json` names that package and version.
+3. Its repository, tag, Go version, command, flags, and build environment match
+   the checked-in build contract.
+4. It names exactly the x64 and ARM64 targets.
+5. Each file is a PE32+ executable with the target's machine code.
+6. Each observed byte size and SHA-256 equals the manifest.
+
+This evidence proves which reviewed build claim belongs to the exact local
+bytes. It is not a cryptographic signature by a remote builder. Trust in the
+source and toolchain claim comes from producing the record in a clean trusted
+environment, reviewing the generated manifest, and committing it with the
+release change. Registry-byte identity and partial multi-package publication
+are separate contracts implemented by REL-02 and REL-03.
+
+## Rebuild procedure
+
+The build contract currently pins:
+
+- SCIP repository: `https://github.com/scip-code/scip.git`
+- SCIP tag: `v0.8.1`
+- Go toolchain: `go1.26.4`
+- command: `go build -trimpath -ldflags="-s -w" ./cmd/scip`
+- environment: `CGO_ENABLED=0`, `GOOS=windows`
+- targets: `GOARCH=amd64` and `GOARCH=arm64`
+
+From a clean trusted checkout:
+
+1. Install the pinned Go toolchain.
+2. Run `npm run build:scip-windows`.
+3. Run `npm run verify:scip-windows`.
+4. Review the generated `packages/scip-windows/provenance.json`, README, and
+   license change. Confirm the immutable source commit is the intended tag.
+5. Run `npm pack --dry-run` inside `packages/scip-windows`. Its `prepack`
+   lifecycle verifies provenance before npm computes the tarball.
+6. Commit the provenance and release metadata. Do not commit the ignored
+   executables.
+
+`SCIP_REPO_URL`, `SCIP_VERSION`, and `SCIP_GO_VERSION` are intentional-update
+inputs, not ways to bypass the contract. A changed value makes verification
+fail until a rebuild produces reviewed evidence for the new input.
+
+The first provenance-bearing package is `0.13.1`. Published `0.13.0` has the
+same executables but lacks `provenance.json`; npm versions are immutable, so
+the registry identity gate correctly requires the patch bump instead of
+trying to overwrite it.
+
+## Registry identity gate
+
+A packed sidecar identity is the npm package coordinate, exact tarball
+SHA-1/SHA-512/size, and decoded provenance bytes observed from one locally
+created `.tgz`. What distinguishes it from a version-existence check is that
+it identifies the bytes intended for installation, not merely the name under
+which some bytes were published.
+
+Before any registry mutation, the release flow:
+
+1. verifies the checked-in binaries and provenance;
+2. packs the local sidecar once into a private temporary directory;
+3. recomputes the tarball hashes and size instead of trusting npm's JSON
+   report;
+4. extracts `provenance.json` from the tar archive under a 64 MiB decompression
+   ceiling; and
+5. requires the packed manifest bytes to equal the reviewed local file.
+
+For an existing version, the flow reads npm's `dist` identity, downloads the
+published tarball with lifecycle scripts disabled, recomputes its hashes, and
+requires all of the following to agree:
+
+- registry metadata and downloaded tarball SHA-1/SHA-512;
+- local and registry package names and versions;
+- local and registry tarball SHA-1/SHA-512; and
+- local and registry provenance bytes.
+
+An explicit npm `E404` is the only evidence that authorizes the
+not-yet-published branch. Authentication failures, timeouts, output-limit
+failures, malformed metadata, generic proxy errors, and server failures are
+ambiguous registry states and stop the release. Pack and registry commands
+have finite 120-second and 30-second deadlines respectively, a 4 MiB captured
+output ceiling, and typed timeout/output/exit failure classification.
+
+Run `npm run verify:scip-windows-registry` for a read-only reconciliation. It
+packs and verifies local bytes, then either proves that the existing registry
+tarball is identical or reports that the version is absent and ready for its
+first publish. The wrapper passes an explicit verification-only capability;
+no inherited environment variable can suppress an authorized release publish.
+
+The complete release coordinator publishes an already verified local `.tgz`,
+not a directory that npm could repack differently. If a publish command fails
+because another process won the race, the coordinator rereads and downloads
+the winning registry version. It may continue only when the winner has the
+same complete identity; a different winner requires a new package version.
+
+The historical `npm run publish:scip-windows` alias is now local verification
+only. `npm_lifecycle_event`, npm's dry-run environment, and other inherited
+environment variables cannot grant it registry mutation authority. The
+sidecar-only registry reader has an explicit verification capability, while
+the complete coordinator is the only publishing CLI.
+
+## Two-package release coordinator
+
+A two-package release is one ordered publication of an exact main-package
+tarball and the exact Windows-sidecar tarball pinned by that main package.
+Unlike a database transaction, it cannot roll back an npm publication. Its
+essential safety property is therefore not atomicity: it is that every
+partial registry state identifies the intended bytes, is observed before the
+next irreversible step, and can be reconciled by rerunning one command.
+
+The release coordinator is the repository command that owns this entire
+ordering. It differs from a lifecycle hook by packing and validating both
+artifacts before either registry mutation, recording local recovery evidence,
+and verifying registry truth after each publication:
+
+1. acquire the token-owned release lock;
+2. require a clean Git checkout and record the exact `HEAD` object ID;
+3. resolve one canonical credential-free HTTPS npm registry and retain it for
+   the complete run;
+4. run typecheck, the complete test suite, and lint; lint includes formatting,
+   production build, API compatibility, downstream compilation, and skill
+   link checks;
+5. verify provenance and pack the sidecar;
+6. pack the main package with lifecycle scripts disabled;
+7. extract both packed `package.json` files, require their coordinates, and
+   require the packed main tarball to pin the exact packed sidecar version;
+8. require Git `HEAD` and complete tracked/untracked working-tree cleanliness
+   to be unchanged;
+9. durably record the registry and both local tarball identities before
+   reading the registry;
+10. observe and fully verify both registry coordinates, always passing the
+    retained registry URL explicitly, before the first
+    publish;
+11. publish and verify the sidecar if absent, then durably record that fact;
+12. publish and verify the main package if absent, then durably record that
+    fact; and
+13. remove private packs and release the owned lock.
+
+Every Git, npm pack, registry, publish, test, and lint process has a finite
+deadline and captured-output limit. A cleanup or lock-release failure produces
+a nonzero outcome without erasing an earlier build, registry, or publication
+failure from the diagnostic.
+
+### Operator runbook
+
+Prepare and commit the complete release change first. The checkout must be
+clean because the recorded source revision is the wider evidence from which
+the two packed artifacts were tested and produced.
+
+1. Bump the main package version. If sidecar bytes or provenance changed, also
+   bump the immutable sidecar version and update its exact optional-dependency
+   pin.
+2. Rebuild and review sidecar provenance when required, following the rebuild
+   procedure above.
+3. Review and commit the version, lockfile, changelog, provenance, schemas,
+   release code, and tests.
+4. Run:
+
+   ```bash
+   npm run release:npm:dry-run
+   ```
+
+   This runs the complete local preflight, packs both artifacts, writes the
+   local recovery record, and reads/downloads any existing registry versions.
+   It never invokes `npm publish`.
+
+5. Review the reported coordinates, integrities, registry states, and the JSON
+   record under `.scipquery/releases/`.
+6. Run:
+
+   ```bash
+   npm run release:npm
+   ```
+
+7. Require the final output to say that both exact registry identities are
+   verified. A later retry of the same command is safe: it repeats local
+   preflight and registry verification, but it does not republish an already
+   identical coordinate.
+
+Do not run `npm publish` directly. The root `prepublishOnly` guard refuses that
+path because npm's lifecycle owns only one package publication and cannot
+record or recover the pair. An operator can deliberately bypass lifecycle
+scripts with npm's `--ignore-scripts` option; that is an administrative
+capability outside the repository's enforcement boundary, not an alternate
+supported release path. The coordinator itself uses `--ignore-scripts` only
+when publishing the two tarballs it has already packed, hashed, inspected,
+and recorded.
+
+### Durable local release state
+
+A local release-state record is a schema-versioned JSON recovery fact stored
+outside both npm tarballs under `.scipquery/releases/`. It is distinguished
+from registry authority by recording what this checkout intended and what an
+earlier run verified, while never permitting a later run to skip fresh
+registry observation.
+
+Schema version 1 records:
+
+- a content-derived `releaseId`;
+- the clean Git revision used for preflight and packing;
+- the canonical HTTPS npm registry on which the coordinates are interpreted;
+- each package's name, version, byte size, SHA-1, and SHA-512 integrity;
+- `createdAt` and nondecreasing `updatedAt` timestamps;
+- the writer identity; and
+- a canonical set of completed facts:
+  `local-preflight-complete`, `sidecar-registry-verified`, and
+  `main-registry-verified`.
+
+The registry facts are independent observations, not a fictional transaction
+log. For example, an old or manually created state may have the main identity
+verified while the sidecar is absent. The next coordinator run still verifies
+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
+`docs/schemas/npm-release-state.schema.json`.
+
+Current-schema additive fields are tolerated. Malformed JSON, a wrong
+discriminator, an invalid identity, a noncanonical stage list, or a future
+schema fails closed. Do not hand-edit a damaged record. Preserve it for
+diagnosis, move it out of the coordinate-stable path, and rerun from the exact
+recorded source revision; the new run will recompute local bytes and reverify
+both registry coordinates before acquiring publication authority.
+
+## Failure and recovery
+
+| Observed state or failure                                           | Safe outcome and recovery                                                                                                  |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Missing executable or provenance                                    | Stop before registry reads; rebuild, review, and commit the intended sidecar                                               |
+| Stale hash, wrong PE machine, or changed build input                | Stop before registry reads; do not authorize bytes from file presence                                                      |
+| One target build fails or promotion is interrupted                  | No complete new build is authorized; rebuild both and rerun verification                                                   |
+| Dirty checkout before preflight                                     | Stop before tests and registry reads; commit, remove, or intentionally ignore/restore every tracked or untracked path      |
+| Missing, insecure, credential-bearing, or malformed registry URL    | Stop before tests and registry reads; configure one canonical credential-free HTTPS npm registry                           |
+| Git revision or any tracked/untracked path changes during preflight | Stop before the state record and registry reads; remove the concurrent editor and rerun from one completely clean revision |
+| Test, lint, build, API, sidecar pack, or main pack fails            | No registry mutation has occurred; fix the local failure and rerun                                                         |
+| Initial state publication fails                                     | No registry read or mutation has occurred; repair local filesystem durability/permissions and rerun                        |
+| State contains only `local-preflight-complete`                      | Registry is freshly reconciled; absent packages publish in sidecar-then-main order                                         |
+| Sidecar is exact, main is absent                                    | Record sidecar verification if needed, then publish and verify the main package                                            |
+| Main is exact, sidecar is absent                                    | Verify the main tarball pins the intended sidecar, then publish and verify only the sidecar                                |
+| Both packages are exact, state is stale or absent                   | Record both observed facts and finish without publication                                                                  |
+| Sidecar publishes but its state write fails                         | Stop before main; retry observes the exact sidecar and continues                                                           |
+| Main publishes but its state write fails                            | Retry observes both exact registry identities and records completion                                                       |
+| Publish reports failure but an identical winner is visible          | Accept the registry fact after downloading and hashing it; continue                                                        |
+| Publish and its immediate registry reconciliation both fail         | Report both causal failures; rerun the coordinator to establish registry truth before another publication decision         |
+| Publish returns success but identity is not yet visible             | Stop after bounded visibility retries; rerun the coordinator rather than publishing blindly                                |
+| Registry query times out, is unauthorized, or is malformed          | Stop; ambiguity is not converted to absence                                                                                |
+| Published tarball disagrees with `dist` metadata                    | Stop; treat the download or registry metadata as corrupt                                                                   |
+| Existing coordinate lacks provenance or has different bytes         | Stop; npm versions are immutable, so bump the changed package version                                                      |
+| State records different source or bytes under the same versions     | Stop before registry reads; resume the recorded revision, or bump the changed package version                              |
+| Configured registry differs from the recorded release registry      | Stop before registry reads; restore the intended registry or begin new package versions for the other registry             |
+| Malformed or future local state                                     | Preserve and move the artifact for diagnosis; rerun from the recorded revision so local and registry facts are rebuilt     |
+| Release lock is held by a live owner                                | Wait; a dead attributable owner is reclaimed conservatively, while unverifiable ownership fails closed                     |
+| Cleanup and an earlier operation both fail                          | Both failures are reported; inspect registry/state first, then rerun to reconcile                                          |
+| Lock ownership changes before release                               | Command exits nonzero; do not infer failure or success from the local message—rerun and require exact registry identity    |
+
+Build outputs are produced in a private temporary directory. Only after both
+targets and the manifest exist are individual files atomically replaced in the
+sidecar directory. A process crash between replacements can leave an old/new
+mixture visible, but the next verifier detects the mismatch and fails closed.
+
+## Compatibility
+
+Schema version 1 is the first executable provenance format. Readers accept
+unknown additive fields within version 1 but require every identity and binary
+field used by the release decision. Missing, malformed, older, or future
+versions are not treated as legacy success. Changing a required field or its
+meaning requires a new schema version and an explicit overlap policy before a
+writer ships it.
+
+The local release-state schema is independently versioned at 1. Because it has
+not shipped before `0.19.6`, it has no legacy reader. Additive current fields
+are compatible; removing or reinterpreting a required identity, source, stage,
+or timestamp field requires a new schema and an explicit recovery policy.

package/docs/analyzer-validation-ledger.md

@@ -12,12 +12,12 @@ The companion documents are:
 
 The ledger is anchored to the current tool surface, not memory.
 
-| Surface                   | Source                                                                                                                                                                                                                                                                                                        | Why it anchors the ledger                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:218`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()` through the health budget that carries full-vs-bounded semantic enrichment.                                                                                | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
-| Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:228`, where `diffGate()` runs the default diff-scoped checks: `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, and `new-dead`. The baseline ratchet is explicit because it is repo-wide.    | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
-| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:11`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:104`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                  |
-| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:64`, where the canonical diff-gate check list is exported.                                                                                                                                                               | The ledger must cover every change-time check that can block a diff.                          |
+| Surface                   | Source                                                                                                                                                                                                                                                                                                                                                             | Why it anchors the ledger                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:218`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()` through the health budget that carries full-vs-bounded semantic enrichment.                                                                                                                                     | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
+| Change-time gate analysis | `scip-query trace diffGate --json` resolves `diffGate()` in `src/queries/impact/diff-gate.ts`, where it runs the default diff-scoped checks: `echo`, `incomplete-migration`, `co-change-partner`, `twin-partner`, `coverage-contract`, `architecture`, `doc-reference`, `unused-params`, and `new-dead`. The baseline ratchet is explicit because it is repo-wide. | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
+| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:11`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:104`, where command descriptors are resolved by id.                                                      | The ledger must not silently miss a public analyzer command.                                  |
+| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` resolves the canonical exported check list in `src/queries/impact/diff-gate.ts`.                                                                                                                                                                                                                                        | The ledger must cover every change-time check that can block a diff.                          |
 
 ## Core Concepts
 
@@ -337,13 +337,14 @@ budget choice.
 
 ## 2026-07-02 Doc-Reference Hub-Cascade Follow-Up
 
-The `diffGate()` and `DIFF_GATE_CHECKS` citations were refreshed (line anchors
-`diff-gate.ts:205` -> `:228` and `:62` -> `:64`) after followup #8 added
-hub-file cascade damping to the doc-reference check: when more than 3 docs
-cite the same changed hub file in one gate run, their findings collapse into
-one clustered finding carrying `citationCount`, up to 3 `citationExemplars`,
-and an explicit `suppressedCount`. Default diff-gate still runs the same
-check family through the same entry point; per-doc findings under the
+The `diffGate()` and `DIFF_GATE_CHECKS` citations were refreshed after
+followup #8 added hub-file cascade damping to the doc-reference check: when
+more than 3 docs cite the same changed hub file in one gate run, their
+findings collapse into one clustered finding carrying `citationCount`, up to
+3 `citationExemplars`, and an explicit `suppressedCount`. Slice 23 removed the
+historical line numbers from these source anchors because the exported symbol
+identities are stable while repeated additive checks made the numbers stale.
+The current table names every default check; per-doc findings under the
 threshold are unchanged.
 
 ## 2026-07-10 TypeScript Dead-Code Certification Follow-Up
@@ -403,7 +404,7 @@ covered, so the result is not an artifact of a permanently-firing check.
 **Precision decision.** Module-hierarchy suppression is content-aware, not
 path-based. `classifyFile` decides "barrel" from the filename, which labels
 every `index.ts` bookkeeping — including `src/language-parsers/index.ts`, a
-130-line cache module that was the *target* of the narrowest real back edge in
+130-line cache module that was the _target_ of the narrowest real back edge in
 the repository. A path-based rule therefore produced a false negative on the
 single most important finding. A barrel is now excluded only when the index
 records no definitions of its own inside it.
@@ -415,7 +416,7 @@ files depending on one of its own sub-directories is the most common real
 intra-boundary cycle, not module bookkeeping.
 
 **Known limits, not yet calibrated.** Sub-units are one directory level, so a
-layer inversion *inside* a single directory is invisible; the `src/source`
+layer inversion _inside_ a single directory is invisible; the `src/source`
 primitives/facts/products tangle had to be derived by hand and was fixed by
 splitting the directory. Test files are not SCIP-indexed and are therefore
 outside boundary enforcement entirely. `requireCompletePolicy` checks that a
@@ -428,17 +429,17 @@ Five rules were added to `architecture` after auditing what boundary
 enforcement still could not see. Each is opt-in and defaults to off, so
 upgrading tightens no existing project's gate.
 
-| Rule | Closes | Finding identity |
-| --- | --- | --- |
-| `requireMinimalPolicy` | A declared allowance outliving the edge that justified it. `requireCompletePolicy` checks a row *exists*, never that it is *minimal*, so policy widens silently. | `architecture:stale-allowance:<from>:<to>` |
-| `maxBoundaryFanOut` / global `maxBoundaryFiles` / per-boundary `maxFiles` | A boundary growing until it is coupled to most of the system. A local file ceiling overrides the global default only for its reviewed boundary. Coarseness was previously caught only when it *hid a cycle*, never when it merely got large. | `architecture:boundary-limit:<kind>:<boundary>` |
-| `testPaths` | Test files are excluded from the compiler project and therefore from the index, leaving them outside every boundary rule. | `architecture:test-boundary:<test>:<boundary>` |
-| `subUnits: 'file'` | A layer inversion *inside* one directory, invisible when sub-units are directories. | (reuses `coarse-boundary`) |
-| `fragileEdges` (report-only) | No signal distinguishing a load-bearing dependency from one resting on a single import. 60 of 251 edges here are single-import. | none — advisory |
+| Rule                                                                      | Closes                                                                                                                                                                                                                                       | Finding identity                                |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `requireMinimalPolicy`                                                    | A declared allowance outliving the edge that justified it. `requireCompletePolicy` checks a row _exists_, never that it is _minimal_, so policy widens silently.                                                                             | `architecture:stale-allowance:<from>:<to>`      |
+| `maxBoundaryFanOut` / global `maxBoundaryFiles` / per-boundary `maxFiles` | A boundary growing until it is coupled to most of the system. A local file ceiling overrides the global default only for its reviewed boundary. Coarseness was previously caught only when it _hid a cycle_, never when it merely got large. | `architecture:boundary-limit:<kind>:<boundary>` |
+| `testPaths`                                                               | Test files are excluded from the compiler project and therefore from the index, leaving them outside every boundary rule.                                                                                                                    | `architecture:test-boundary:<test>:<boundary>`  |
+| `subUnits: 'file'`                                                        | A layer inversion _inside_ one directory, invisible when sub-units are directories.                                                                                                                                                          | (reuses `coarse-boundary`)                      |
+| `fragileEdges` (report-only)                                              | No signal distinguishing a load-bearing dependency from one resting on a single import. 60 of 251 edges here are single-import.                                                                                                              | none — advisory                                 |
 
 **Test-boundary calibration.** The first rule shape — "a test may import only what
 its subject's boundary may import" — produced 91 findings, nearly all
-legitimate: a test for `analysis/git-history` drives it *through*
+legitimate: a test for `analysis/git-history` drives it _through_
 `queries/cleanup/co-change`, which is composition, not coupling. The shipped
 rule allows the subject's **transitive** reach plus any boundary that reaches
 the subject (a consumer is the natural driver). That yields 0 findings here,

package/docs/schemas/cli-json-envelope.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ainsleyclark/scip-query/blob/main/docs/schemas/cli-json-envelope.schema.json",
+  "title": "scip-query CLI JSON envelope v1",
+  "description": "The public transport record emitted by scip-query commands that accept --json.",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "producer", "command", "resultSchemaVersion", "args", "options", "result"],
+  "properties": {
+    "kind": {
+      "const": "scip-query-result"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "producer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "const": "scip-query"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "command": {
+      "type": "string",
+      "minLength": 1
+    },
+    "resultSchemaVersion": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "evidence": {
+      "enum": ["graph-fact", "heuristic", "mixed"]
+    },
+    "analysisBudget": {},
+    "args": {
+      "type": "array"
+    },
+    "options": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "result": {},
+    "coverage": {},
+    "agentResult": {}
+  },
+  "additionalProperties": true
+}

package/docs/schemas/npm-release-state.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/PlunderStruck/scip-query/blob/main/docs/schemas/npm-release-state.schema.json",
+  "title": "scip-query npm release state",
+  "description": "Durable local progress for one exact main-package and Windows-sidecar npm release.",
+  "type": "object",
+  "required": [
+    "kind",
+    "schemaVersion",
+    "releaseId",
+    "source",
+    "packages",
+    "completedStages",
+    "createdAt",
+    "updatedAt",
+    "writer"
+  ],
+  "properties": {
+    "kind": {
+      "const": "scip-query-npm-release-state"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "releaseId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "source": {
+      "type": "object",
+      "required": ["gitRevision", "registry"],
+      "properties": {
+        "gitRevision": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40,64}$"
+        },
+        "registry": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://",
+          "allOf": [
+            {
+              "not": {
+                "pattern": "^https://[^/]*@"
+              }
+            },
+            {
+              "not": {
+                "pattern": "[?#]"
+              }
+            }
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "packages": {
+      "type": "object",
+      "required": ["main", "sidecar"],
+      "properties": {
+        "main": {
+          "$ref": "#/$defs/packageIdentity"
+        },
+        "sidecar": {
+          "$ref": "#/$defs/packageIdentity"
+        }
+      },
+      "additionalProperties": true
+    },
+    "completedStages": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["local-preflight-complete", "sidecar-registry-verified", "main-registry-verified"]
+      },
+      "oneOf": [
+        {
+          "const": ["local-preflight-complete"]
+        },
+        {
+          "const": ["local-preflight-complete", "sidecar-registry-verified"]
+        },
+        {
+          "const": ["local-preflight-complete", "main-registry-verified"]
+        },
+        {
+          "const": ["local-preflight-complete", "sidecar-registry-verified", "main-registry-verified"]
+        }
+      ]
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "writer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "const": "scip-query"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The main-package version that produced this state; the executable reader requires it to equal packages.main.version."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "packageIdentity": {
+      "type": "object",
+      "required": ["name", "version", "size", "shasum", "integrity"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "shasum": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40}$"
+        },
+        "integrity": {
+          "type": "string",
+          "pattern": "^sha512-[A-Za-z0-9+/]+={0,2}$"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/scip-query/docs/schemas/outcome-event-record.schema.json",
+  "title": "scip-query outcome event record v1",
+  "description": "One immutable repository-owned finding transition stored under .scipquery/events/.",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "eventIdentity", "writer", "ts", "check", "findingId", "event", "commit"],
+  "properties": {
+    "kind": { "const": "scip-query-outcome-event" },
+    "schemaVersion": { "const": 1 },
+    "eventIdentity": { "type": "string", "minLength": 1 },
+    "writer": {
+      "type": "object",
+      "required": ["tool", "version"],
+      "properties": {
+        "tool": { "const": "scip-query" },
+        "version": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "ts": { "type": "number" },
+    "check": { "type": "string", "minLength": 1 },
+    "findingId": { "type": "string", "minLength": 1 },
+    "event": { "enum": ["caught", "resolved", "suppressed", "reopened"] },
+    "commit": {
+      "oneOf": [{ "type": "string" }, { "type": "null" }]
+    },
+    "comparisonBaseCommit": { "type": "string" },
+    "verifiedAgainstCommit": { "type": "string" },
+    "symbol": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "required": ["verifiedAgainstCommit"] },
+      "then": { "properties": { "event": { "const": "resolved" } } }
+    }
+  ],
+  "additionalProperties": true
+}