scip-query 0.19.5 → 0.19.8

package/docs/TIME_SEMANTICS.md

@@ -0,0 +1,77 @@
+# Time Semantics
+
+scip-query separates shared timestamps from local elapsed-time control so a
+system-clock correction cannot prolong a wait or impersonate ownership.
+
+A **civil timestamp** is a calendar coordinate produced by the host's system
+clock and written so different processes and later executions can compare
+records. ISO dates, `enqueuedAtMs`, `deadlineAtMs`, heartbeat times, retention
+times, and diagnostic start/completion times refer to this clock. Network time
+synchronization, administrator changes, suspend/resume behavior, virtual
+machine migration, and a reboot can move its observed value forward or
+backward.
+
+A **monotonic clock reading** is a process-local elapsed-time coordinate whose
+ordering does not move backward while that process runs. `performance.now()`
+is the JavaScript implementation used here. A monotonic reading is suitable
+for durations and local deadlines because a civil-clock adjustment cannot add
+time to or remove time from the measured interval. Its numeric value is not a
+portable timestamp and is never persisted as cross-process evidence.
+
+A **deadline** is the boundary that ends an operation when its resource budget
+is consumed. Local request waits, lock waits, service startup and stop waits,
+Rust readiness work, heartbeat throttles, activity polling, cache sweeps,
+idle shutdown, and reported elapsed durations use monotonic readings. Timer
+delivery can be late if the process is not scheduled, but moving the civil
+clock cannot make the deadline later.
+
+A **durable expiry hint** is a persisted civil timestamp that lets another
+process classify old work for bounded cleanup or rejection. It is weaker than
+ownership evidence because timestamp age cannot identify the process that
+created a record. Mailbox request deadlines, response retention, dead-letter
+retention, and heartbeat times remain durable hints. They may reject or clean
+rebuildable retained data according to the documented retention contract, but
+they do not alone authorize signaling a process, replacing a live service, or
+reclaiming an inflight claim.
+
+## Decision table
+
+| Decision                                                                 | Clock/evidence used                                                                                 | Why                                                                                 |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Stop waiting for a lock, response, startup, shutdown, or readiness phase | Process-local monotonic deadline                                                                    | The wait remains bounded across forward and backward civil-clock jumps.             |
+| Report a duration                                                        | Difference between monotonic readings                                                               | A clock correction cannot create a negative or inflated elapsed duration.           |
+| Publish a heartbeat, start time, completion time, or request expiry      | Civil timestamp                                                                                     | Other processes and later executions need an inspectable shared coordinate.         |
+| Accept a watch or mailbox service as the same owner                      | Protocol/project identity, live PID, and matching process-start identity when recorded              | A timestamp cannot distinguish PID reuse or a different executable instance.        |
+| Replace or signal a watch service                                        | Matching process-start identity plus the explicit stop/start protocol                               | An old heartbeat alone never grants process-signal authority.                       |
+| Reclaim an inflight mailbox claim                                        | Lease expired and recorded process instance is dead or replaced                                     | The civil lease is a delay hint; process-instance loss supplies ownership evidence. |
+| Reclaim a process lock                                                   | Dead recorded process or mismatched process-start identity, followed by a guarded unchanged recheck | Valid locks do not expire; malformed public locks fail closed.                      |
+
+## Cross-process handoff
+
+Absolute monotonic readings are not sent between independent processes.
+Portable mailbox requests carry relative timeout budgets and civil diagnostic
+times. The receiving Rust service converts the relative budget into a new
+deadline in its own monotonic clock domain before it hands work to its worker
+thread. TypeScript and Rust clients likewise use their own monotonic deadline
+while polling for a retained response.
+
+Legacy state without a process-start identity remains readable. A live legacy
+PID is treated conservatively: it can support availability where no process
+mutation is attempted, but it cannot authorize a signal or deletion. An
+unparseable public ownership record fails closed and requires operator review.
+
+## Verification
+
+The clock contract is covered by injected-clock tests that independently move
+civil time forward and backward, advance monotonic time, reuse a PID with a
+different process-start identity, and hold a live owner beyond a civil lease.
+Focused suites include:
+
+- `tests/domain/time.test.ts`;
+- `tests/platform/process-file-lock.test.ts`;
+- `tests/runtime/repository-cache-lifecycle.test.ts`;
+- `tests/runtime/revisioned-file.test.ts`;
+- `tests/runtime/watch-service.test.ts`;
+- `tests/storage/bounded-mailbox.test.ts`;
+- the TypeScript semantic and index mailbox suites; and
+- the durable Rust and rust-analyzer readiness suites.

package/docs/WATCH_REFRESH_REQUESTS.md

@@ -0,0 +1,110 @@
+# Watch Refresh Requests
+
+## Contract
+
+A watch refresh request is a durable command-side intent to make one project's
+index current. Its concrete referents are the records created when a command or
+agent hook observes a stale index and asks the live watch service to reindex.
+It is a request record distinguished from ordinary watch activity by remaining
+authoritative until a corresponding refresh attempt completes or its declared
+deadline expires.
+
+Watch activity is a disposable observation that a command recently used the
+service. Its concrete referent is `watch-activity.json`; it is a
+last-writer-wins timestamp whose only effect is extending the daemon's idle
+lifetime. It is not a queue and carries no current refresh authority.
+
+An admission is the successful publication of one complete immutable request
+under `watch-refresh-requests/requests/`. Its defining property is that the
+stable request path exists before the caller is told the request was accepted.
+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.
+
+## Layout
+
+```text
+<project-cache>/
+  watch-activity.json
+  watch-refresh-requests/
+    requests/<request-id>.json
+    claims/<request-id>.json
+    completions/<request-id>.json
+    staging/
+```
+
+- `requests/` is the immutable admission log.
+- `claims/` contains exclusive, temporary ownership markers.
+- `completions/` contains immutable acknowledgements.
+- `staging/` contains same-filesystem temporary files used to publish a
+  complete record through an exclusive hard-link operation.
+
+The request ID is random unless the caller supplies an idempotency key. An
+idempotency key is a caller-chosen logical-operation identity whose hash
+becomes the stable request ID; retries with that key observe the first admitted
+request instead of appending another one. The first request's detail and
+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
+   duplicate, not an overwrite.
+3. 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`
+   refresh. Requests arriving while the watcher is busy remain pending.
+5. A successful corresponding reindex writes every completion receipt before
+   removing any claim.
+6. 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
+   the same exclusive watch lock. Completed requests remain completed; all
+   other claimed requests become pending.
+
+The default request deadline is ten minutes. An expired request gets an
+explicit `expired` completion rather than being silently deleted. Completed
+and expired history is retained for seven days; pruning removes only a receipt
+and its already-acknowledged request. Pending and claimed requests are never
+history-pruned. Idempotency is therefore guaranteed for at least the history
+retention window.
+
+## Crash and Concurrency Outcomes
+
+| 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 |
+
+## Compatibility and Diagnostics
+
+Protocol version 5 writers use the request store. During the overlap release,
+the watch server still recognizes the former
+`refreshRequestedAt`/`refreshDetail` fields if an older client writes them. On
+observation it converts that timestamp to a deduplicated durable request before
+processing it. New activity writers never place refresh intent in the activity
+file.
+
+`scip-query watch --status` reports pending, claimed, completed, expired, and
+invalid record counts. A nonzero invalid count means an on-disk record failed
+strict validation; the store does not treat malformed bytes as an accepted
+request or completion.
+
+This protocol does not promise exactly-once reindex execution. Exactly-once
+execution would require atomically committing the index generation and the
+request receipt across separate storage authorities. Reindex is safe to
+repeat, so the protocol chooses the stronger practical guarantee: accepted
+intent is never silently lost, and successful acknowledgement is never
+inferred from absence.

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
+}