scip-query 0.19.8 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,103 @@ All notable changes to `scip-query` are documented here. This file starts at 0.1
 
 ## [Unreleased]
 
+## [0.20.0]
+
+### Maintained native SQLite distribution
+
+- `better-sqlite3` is upgraded to 13.0.2, whose N-API binaries ship inside
+  the dependency tarball. New installs no longer resolve the abandoned
+  `prebuild-install` helper. The repository explicitly denies npm's inferred
+  `node-gyp rebuild` fallback because the bundled binary needs no lifecycle
+  setup.
+- The public runtime floor is now Node.js 22, matching the required native
+  dependency instead of advertising the obsolete Node 18 contract; every
+  published bundle now targets the same runtime floor. Install output and the
+  README recommend Node.js 24 LTS while distinguishing it from the supported
+  minimum.
+- Runtime-contract tests and a Node 22/24/26 CI matrix exercise a real SQLite
+  database, while install guidance distinguishes bundled SQLite binaries from
+  the remaining Tree-sitter lifecycle scripts.
+
+## [0.19.10]
+
+### Safer setup and removal
+
+- Real uninstall now requires an explicit global or project scope, while a
+  scope-free dry run safely previews both. Project-hook removal no longer
+  depends on resolving an install-only command identity, and ordinary
+  uninstall output summarizes retained personal skills unless `--verbose` is
+  requested.
+- Guided setup requires an interactive terminal and rejects conflicting JSON
+  or automatic modes. Hook removal has a non-writing preview, rejects
+  installation-only force semantics, and reports removal-specific outcomes.
+- Watch timing options are explicitly process-local: status and stop reject
+  them, and an already-running daemon refuses overrides it cannot apply.
+
+### Honest outcomes and recoverable evidence
+
+- Partial reindex results identify every skipped language and reason. Project
+  initialization and agent setup derive their messages from actual
+  written/unchanged/skipped results instead of reporting categorical success.
+- Suppression receipts disclose their effective scope, reason code, evidence
+  count, expiration, and revision.
+- Verified cleanup application has a same-plan `--dry-run` that names exact
+  files, symbols, ranges, deleted lines, and the verification oracle before
+  the source-mutation boundary.
+- The final human pagination marker now names transport completion separately
+  from command-result coverage, preventing a fully retrieved bounded or
+  sampled result from being mistaken for complete semantic evidence.
+
+## [0.19.9]
+
+### Agent-readable command output
+
+- Human output is now the default evidence format for agents. `code` renders
+  only the resolved path, one-based range, symbol identity, language, and
+  whitespace-preserved numbered source; complete output no longer receives a
+  pagination wrapper merely because a page size was supplied.
+- Every public JSON-capable command exposes the same `--json`,
+  `--result-only`, and `--compact` modes. The stable envelope remains
+  compatible for programs, while result-only output removes transport
+  metadata and `code` returns a minimal ordered line representation.
+- Partial human pages retain multiline hierarchy and split at complete line
+  boundaries whenever possible. Exact resumable continuations remain
+  mandatory for genuinely partial output, and malformed numeric flags now
+  fail explicitly instead of accepting a numeric prefix.
+- Bundled Claude, Codex, and shared-agent skills prefer ordinary output,
+  reserve JSON for programmatic consumers, and no longer preselect page sizes
+  or recommend compact JSON for model-readable evidence.
+
+### Durable state and concurrency
+
+- Atomic file replacement, committed outcome and suppression records,
+  generation pointers, shared-cache leases, watcher refresh requests, and
+  semantic mailboxes now preserve explicit operation identity across crashes,
+  retries, concurrent owners, stale completions, and partial legacy records.
+- SQLite and SCIP publication use immutable generation artifacts with
+  conservative recovery, retained-reader protection, corruption detection,
+  and bounded garbage collection. Incremental publication rejects incomplete
+  affected sets and preserves rich metadata owned by unaffected documents.
+- Stop hooks and diff-gate runs share bounded evidence leases and execution
+  deadlines. Automatic suppression requires versioned policy evidence,
+  expiration and content-hash checks, and anomaly escalation instead of
+  treating repository-writable metadata as independent authority.
+
+### Query performance and evidence integrity
+
+- SQL-backed navigation, graph-risk, file-resolution, coupling, and re-export
+  analysis reuse prepared data products, parameterized scopes, bounded
+  batches, and indexed lookup paths instead of repeated broad scans. Recorded
+  before/after ledgers preserve command-output equivalence alongside the
+  measured latency gains.
+- Watch refreshes distinguish rebuilt and reused work, suppress redundant
+  requests, preserve cache ownership, and avoid competing manual reindexes.
+  Diff-gate containment now completes the current repository-wide change in
+  seconds rather than allowing duplicate long-running detector processes.
+- Public configuration, reindex metadata, committed records, TypeScript
+  declarations, schemas, command documentation, and downstream consumer
+  fixtures were evolved together with explicit compatibility handling.
+
 ## [0.19.8]
 
 ### Complete agent evidence

package/README.md

@@ -75,10 +75,22 @@ For automation, use `scip-query setup --yes` to accept recommended defaults or
 scope is intentionally managed elsewhere. Or run without a global install:
 `npx scip-query@latest setup`.
 
-Every public `--json` response identifies its envelope schema, command result
-schema, and producing package version. See the
-[CLI JSON output contract](docs/CLI_JSON_OUTPUT.md) for the compatibility
-policy, decoder API, and machine-readable schema.
+Human output is the default for people and agents: reports retain their
+sections, while `code` preserves indentation and one-based source line
+numbers. Oversized human results paginate at complete line boundaries whenever
+possible, so continuation pages preserve that hierarchy. Every public
+JSON-capable command also supports the same structured forms: `--json` emits
+the stable envelope, `--json --result-only` emits only the command result, and
+`--json --compact` minifies output for a program. See the
+[CLI output contract](docs/CLI_JSON_OUTPUT.md) for mode selection,
+compatibility, pagination, the decoder API, and machine-readable schemas.
+
+Logical `refs --limit` pages use a generation-bound `(path, line)` cursor, so
+ordinary continuations resume after the prior row instead of rebuilding and
+discarding it. Follow every emitted `refs --cursor` continuation before
+claiming a complete reference set. JSON identifies semantic, Ruby, or SCIP
+fallback providers that still require complete analysis as
+`pagination.producer: "complete-only"`.
 
 Contributors changing exported TypeScript declarations should also follow the
 [public API evolution workflow](docs/API_EVOLUTION.md). Its committed manifest
@@ -88,12 +100,20 @@ makes every package-subpath signature change explicit before release.
 
 On npm setups with script approval enabled (`allow-scripts`), the install prints warnings like
 `15 packages have install scripts not yet covered by allowScripts` — and **skips those scripts**,
-which leaves the native modules unbuilt. Every script on that list is expected:
+which leaves the affected native modules unbuilt. Every remaining script on that list is expected:
 
 - `scip-query` — its own postinstall (non-fatal by construction: `... || true`)
-- `better-sqlite3` — builds/downloads the native SQLite binding that backs the index
 - `tree-sitter` + the per-language grammars — native parsers behind multi-language source facts
 
+`better-sqlite3` 13 does not need lifecycle-script approval: it ships stable
+N-API SQLite binaries for the supported platforms inside its npm package.
+Although npm infers a default `node-gyp rebuild` from the addon's source
+metadata, scip-query explicitly denies that unnecessary fallback in its own
+development install policy. A real database test verifies that the bundled
+binary works with scripts disabled.
+Seeing `prebuild-install` during a scip-query install therefore means an older
+scip-query dependency tree was selected.
+
 Approve them and re-run the builds (`--allow-scripts-pending` only _lists_ — the approving forms
 are `npm approve-scripts <pkg> ...` or `--all`):
 
@@ -121,7 +141,7 @@ scip-query incomplete-migration
 
 # Before declaring the work complete: gate the diff. Reindex only when status
 # reports stale and no live watcher or hook refresh is already responsible.
-scip-query diff-gate --json
+scip-query diff-gate
 ```
 
 For a repository-wide cleanup pass:
@@ -212,6 +232,12 @@ Batch 0: COMPILER-VERIFIED
 ```
 
 When verification _fails_, the errors name the exact references the static evidence missed — that failure has caught real detector mistakes and stopped build-breaking deletions.
+Before applying a verified batch, run
+`scip-query cleanup-apply --verified --batch <n> --dry-run`. The preview reruns
+the verifier and dirty-tree checks, names every file, symbol range, and LOC,
+and stops at the source-mutation boundary. Apply by repeating the command
+without `--dry-run`; use `--all` only when the entire printed target set is
+intended.
 
 **5. Trim speculative generality.** `unused-params` finds trailing parameters no body ever uses (the classic "options for later"), scoped to removals that are type-safe by construction.
 
@@ -222,18 +248,20 @@ When verification _fails_, the errors name the exact references the static evide
 **8. Gate every diff.** `diff-gate` runs a defined set of checks scoped to what a change _introduces_ and exits nonzero with remediation text for each finding. Baseline regressions are included when you pass `--baseline`.
 
 <!-- BEGIN GENERATED DIFF-GATE CHECKS -->
-| Check | What it catches | When it runs |
-| --- | --- | --- |
-| `echo` | Changed symbols that newly echo established code elsewhere. | Default diff gate. |
-| `incomplete-migration` | New helpers or abstractions wired into some sites while older inline sites remain. | Default diff gate. |
-| `co-change-partner` | Historically coupled files that usually change together but are missing from this diff. | Default diff gate. |
-| `twin-partner` | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched. | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves. |
-| `coverage-contract` | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed. |
-| `architecture` | A declared architecture boundary rule has a violation absent from the committed health baseline. | Default diff gate when closed dependency rows, requireCompletePolicy, requireAcyclic, requireResolvedBoundaries, requireMinimalPolicy, maxBoundaryFanOut/maxBoundaryFiles, or testPaths are configured and a baseline exists. |
-| `doc-reference` | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy. | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed. |
-| `unused-params` | Fresh trailing parameters or options that no changed body uses. | Default diff gate. |
-| `new-dead` | Changed production symbols with zero indexed consumers. | Default diff gate. |
-| `baseline` | New health finding identities compared with the committed health baseline. | Only with `diff-gate --baseline`. |
+
+| Check                  | What it catches                                                                                                                   | When it runs                                                                                                                                                                                                                  |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `echo`                 | Changed symbols that newly echo established code elsewhere.                                                                       | Default diff gate.                                                                                                                                                                                                            |
+| `incomplete-migration` | New helpers or abstractions wired into some sites while older inline sites remain.                                                | Default diff gate.                                                                                                                                                                                                            |
+| `co-change-partner`    | Historically coupled files that usually change together but are missing from this diff.                                           | Default diff gate.                                                                                                                                                                                                            |
+| `twin-partner`         | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched.            | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves.                                                                                                                                     |
+| `coverage-contract`    | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed.                                                                                                                                                    |
+| `architecture`         | A declared architecture boundary rule has a violation absent from the committed health baseline.                                  | Default diff gate when closed dependency rows, requireCompletePolicy, requireAcyclic, requireResolvedBoundaries, requireMinimalPolicy, maxBoundaryFanOut/maxBoundaryFiles, or testPaths are configured and a baseline exists. |
+| `doc-reference`        | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy.     | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed.                                                                       |
+| `unused-params`        | Fresh trailing parameters or options that no changed body uses.                                                                   | Default diff gate.                                                                                                                                                                                                            |
+| `new-dead`             | Changed production symbols with zero indexed consumers.                                                                           | Default diff gate.                                                                                                                                                                                                            |
+| `baseline`             | New health finding identities compared with the committed health baseline.                                                        | Only with `diff-gate --baseline`.                                                                                                                                                                                             |
+
 <!-- END GENERATED DIFF-GATE CHECKS -->
 
 Illustrative output:
@@ -254,10 +282,37 @@ Baseline finding identities are keyed as `detector:file:shortName`. A rename can
 Accepted findings can be recorded without weakening the rest of the gate:
 
 ```bash
-scip-query suppress SQABC123DEF456 --check echo --reason "intentional compatibility shim"
+scip-query suppress SQABC123DEF456 \
+  --check echo \
+  --reason-code compatibility-shim \
+  --evidence source:src/compat.ts \
+  --reason "the v1 export remains an intentional compatibility surface"
 ```
 
-This writes one file per suppression under `.scipquery/suppressions/` — commit it with your change. One-file-per-suppression means two branches suppressing different findings merge without conflict; the legacy `suppressions[]` array in `.scipquery.json` is still honored (read-only). Every suppression requires a reason plus either a stable finding id or a `check` (optionally narrowed by `file`). Check+file suppressions are allowed but warn because they waive every matching finding in that file. `diff-gate --json` reports both active and suppressed findings.
+This writes one file per suppression under `.scipquery/suppressions/` — commit
+it with your change. One-file-per-suppression means two branches suppressing
+different findings merge without conflict. The command requires an exact
+current finding ID, a controlled reason code, and at least one inspectable
+counterevidence referent. `source:`, `config:`, and `test:` referents are
+content-hashed when the record is written, so changing their bytes reopens the
+finding. A `graph:` referent is an exact `scip-query ...` command:
+
+```bash
+scip-query suppress SQABC123DEF456 \
+  --reason-code detector-counterexample \
+  --evidence 'graph:scip-query refs CompatExport --full' \
+  --reason "all compiler-resolved consumers still require this export"
+```
+
+The model may create these narrow records without human approval. Admission is
+still decided by scip-query's policy: broad, legacy, expired, invalidated,
+incompatible, or anomalously high-volume decisions remain findings and appear
+as policy escalations. A successful gate with accepted records reports
+`pass-with-suppressions`, not an ordinary clean pass. The legacy
+`suppressions[]` array in `.scipquery.json` and v1 record files remain readable,
+but do not automatically waive findings until explicitly replaced with
+structured counterevidence. `diff-gate` reports active findings,
+accepted suppressions, escalation reasons, and summary counts.
 
 The first suppression for an identity is created exclusively. Repeating the
 same decision is idempotent, but a different reason, expiry, check, or file is
@@ -273,38 +328,44 @@ After reviewing the committed decision, replace exactly that revision:
 
 ```bash
 scip-query suppress SQABC123DEF456 --check echo \
+  --reason-code compatibility-shim \
+  --evidence source:src/compat.ts \
   --reason "superseded by a narrower compatibility exception" \
   --replace 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
 If another writer changes the record first, the stale replacement is rejected
 and the newer bytes remain intact. New records declare their schema version,
-record kind, stable suppression identity, and writer version. Older
-unversioned and pre-discriminator v1 records remain readable and are upgraded
-only by an explicit replacement. If a malformed or future record cannot be
-used, `diff-gate` reports exact incomplete-coverage counts and keeps findings
-conservatively unsuppressed. The wire schemas and merge rules are documented
-in [`docs/COMMITTED_RECORD_COMPATIBILITY.md`](docs/COMMITTED_RECORD_COMPATIBILITY.md).
+record kind, stable suppression identity, writer version, adjudication policy,
+counterevidence, and invalidation conditions. Older unversioned and v1 records
+remain readable and are upgraded only by an explicit replacement. If a
+malformed or future record cannot be used, `diff-gate` reports exact
+incomplete-coverage counts and keeps findings conservatively unsuppressed. The
+wire schemas and merge rules are documented in
+[`docs/COMMITTED_RECORD_COMPATIBILITY.md`](docs/COMMITTED_RECORD_COMPATIBILITY.md).
 
-**12. Measure whether the gate is earning its keep.** Every completed `diff-gate` run, including JSON and installed Stop-hook runs, writes each finding transition to its own committed `.scipquery/events/*.json` file. Independent branches add independent paths instead of editing one shared ledger file, so ordinary event writes do not create merge conflicts. Each event stores the immutable Git commit used as its comparison base. A finding is a verified fix when it disappears under that same comparison—either directly or after scip-query cleanly replays the original base against a newer committed `HEAD`. Merely committing the finding cannot clear it: if replay still finds it, the outcome stays open; if the worktree is dirty or Git cannot reproduce the base, verification waits. Historical reconciliation is deliberately incremental: one run replays at most one stored comparison base, reports the exact deferred base and finding counts, and leaves every deferred finding open for a later gate. A suppressed finding was noise or an accepted trade-off:
+**12. Observe how the gate is handled.** Every completed `diff-gate` run, including JSON and installed Stop-hook runs, writes each finding transition to its own committed `.scipquery/events/*.json` file. Independent branches add independent paths instead of editing one shared ledger file, so ordinary event writes do not create merge conflicts. Each event stores the logical gate-run identity, observer provenance, index/worktree receipt, and immutable Git commit used as its comparison base. A finding is a verified fix when it disappears under that same comparison—either directly or after scip-query cleanly replays the original base against a newer committed `HEAD`. Merely committing the finding cannot clear it: if replay still finds it, the outcome stays open; if the worktree is dirty or Git cannot reproduce the base, verification waits. Historical reconciliation is deliberately incremental: one run replays at most one stored comparison base, reports the exact deferred base and finding counts, and leaves every deferred finding open for a later gate. A suppressed finding was noise or an accepted trade-off:
 
 ```bash
 scip-query effectiveness --since 30d
 ```
 
 ```
-check       caught  fixed  suppressed  open  moved  unverified  precision  median-days-to-fix
-echo        14      10     2           1     0      1           83%        0.8
-new-dead    6       5      0           1     0      0           100%       0.3
+check       caught  fixed  suppressed  open  moved  unverified  resolution-vs-suppression  evaluation-precision  authority                 median-days-to-fix
+echo        14      10     2           1     0      1           83%                        -                     local-writable-telemetry  0.8
+new-dead    6       5      0           1     0      0           100%                       -                     local-writable-telemetry  0.3
 ```
 
-`precision` is verified fixed ÷ (verified fixed + suppressed). `moved` separates rename churn, while `unverified` is reserved for legacy or otherwise non-comparable resolutions that lack replay proof. Run diff-gate once to record the finding and again after the repair; a pre-commit rerun uses the same base directly, while clean post-commit runs advance through stored bases incrementally. Filter with `--check <name>`, window with `--since 30d|12w|<ISO date>`, and get machine-readable output with `--json`. Because the event files are committed, the numbers survive re-clones and aggregate across every machine and agent working the repo. Current event files carry an additive v1 discriminator, stable semantic identity, and writer version; existing unversioned files remain readable. `effectiveness` reports accepted and omitted record counts when history is partial, and cross-HEAD verification defers fixes rather than trusting an incomplete lifecycle. Legacy `.scipquery/ledger/events.jsonl` records remain readable and are migrated to individual files on the next gate write only when every non-empty line is compatible; otherwise the source ledger is preserved. Historical cross-`HEAD` events without stored comparison evidence remain unverified rather than being reclassified speculatively. Standalone health/cleanup commands are not yet outcome-tracked because they do not all expose a complete-scan contract.
+`resolution-vs-suppression` is verified fixed ÷ (verified fixed + suppressed). Repository-local event and suppression files are writable by the same agent doing the work, so this ratio is operational telemetry, not an independent correctness grade. `evaluation-precision` is populated only when a protected external evaluator supplies both protected-CI records and a separately controlled attestation for their gate-run IDs; a JSON field cannot attest itself. Ordinary local-agent and local-human runs leave it blank. `moved` separates rename churn, while `unverified` is reserved for legacy or otherwise non-comparable resolutions that lack replay proof. Run diff-gate once to record the finding and again after the repair; a pre-commit rerun uses the same base directly, while clean post-commit runs advance through stored bases incrementally. Filter with `--check <name>`, window with `--since 30d|12w|<ISO date>`, and get machine-readable provenance, anomaly samples, and record-compatibility counts with `--json`. Local runs default to `local-agent`; a person running the gate directly may set `SCIP_QUERY_OUTCOME_OBSERVER_KIND=local-human` and optionally `SCIP_QUERY_OUTCOME_OBSERVER_SOURCE=<label>`. Both remain `repository-writable`; neither environment variable can claim protected authority. Because the event files are committed, the numbers survive re-clones and aggregate across every machine and agent working the repo, but missing or deliberately deleted history cannot be inferred from the remaining directory. Current event files carry an additive v1 discriminator, stable semantic identity, writer version, gate-run identity, observer authority, and observation receipt; existing unversioned files remain readable. `effectiveness` reports accepted and omitted record counts when history is partial, and cross-HEAD verification defers fixes rather than trusting an incomplete lifecycle. Legacy `.scipquery/ledger/events.jsonl` records remain readable and are migrated to individual files on the next gate write only when every non-empty line is compatible; otherwise the source ledger is preserved. Historical cross-`HEAD` events without stored comparison evidence remain unverified rather than being reclassified speculatively. Standalone health/cleanup commands are not yet outcome-tracked because they do not all expose a complete-scan contract.
 
 `diff-gate` is also single-flight per project: a second CLI or Stop-hook gate
 returns the live owner's PID and start time instead of duplicating the same
 CPU-heavy work. The gate runs in an owned child process with a 60-second
 deadline, or 180 seconds with `--full`; timeout terminates and reaps that child
-and fails the gate explicitly. Operators may set
+and fails the gate explicitly. Before and after every detector, the child
+publishes a private progress record; a timeout therefore names the active
+detector or phase and the last completed detector instead of reporting only
+the total elapsed time. Operators may set
 `SCIP_QUERY_DIFF_GATE_TIMEOUT_MS` to a positive millisecond value, capped at
 10 minutes.
 
@@ -394,11 +455,12 @@ classifies current evidence, while `scip-improve` changes confirmed findings.
 challenges a concrete finished diff. `scip-explore` explains working behavior;
 `scip-diagnose` starts from a failure or contradiction.
 
-Project setup writes reviewable checkout-local lifecycle hooks for Codex and Claude Code (`.codex/hooks.json` and `.claude/settings.local.json`). A checkout-local hook is an agent-tool preference whose defining trait is that it applies to one clone rather than expressing team policy. Setup adds both paths to that clone's `.git/info/exclude`, so they do not appear in commits, and refuses to rewrite either path if it is already tracked. `setup-hooks --shared` remains accepted only as a deprecated compatibility flag; it no longer writes `.claude/settings.json`. These hooks add scip-query context at session start, route prompts toward the right skill, and run an advisory Stop-hook wrapper around the diff gate only for that repository. The Stop hook sends feedback to the agent by default instead of blocking; set `SCIP_QUERY_STOP_HOOK_MODE=warn` for a warning-only hook response, or `SCIP_QUERY_STOP_HOOK_MODE=block` to enforce the gate. Set `SCIP_QUERY_SKIP_HOOK_INSTALL=1` or run `scip-query setup --no-hooks` to skip hook installation during setup, and run `scip-query setup-hooks --json` later to repair the current checkout's hooks.
+Project setup writes reviewable checkout-local lifecycle hooks for Codex and Claude Code (`.codex/hooks.json` and `.claude/settings.local.json`). A checkout-local hook is an agent-tool preference whose defining trait is that it applies to one clone rather than expressing team policy. Setup adds both paths to that clone's `.git/info/exclude`, so they do not appear in commits, and refuses to rewrite either path if it is already tracked. `setup-hooks --shared` remains accepted only as a deprecated compatibility flag; it no longer writes `.claude/settings.json`. These hooks add scip-query context at session start, route prompts toward the right skill, and run an advisory Stop-hook wrapper around the diff gate only for that repository. The Stop hook sends feedback to the agent by default instead of blocking; set `SCIP_QUERY_STOP_HOOK_MODE=warn` for a warning-only hook response, or `SCIP_QUERY_STOP_HOOK_MODE=block` to enforce the gate. Set `SCIP_QUERY_SKIP_HOOK_INSTALL=1` or run `scip-query setup --no-hooks` to skip hook installation during setup, and run `scip-query setup-hooks --json` later to repair the current checkout's hooks. Preview hook removal with `scip-query setup-hooks --remove --dry-run`; `--force` is an installation-only mode and cannot be combined with removal. A scope-free `scip-query uninstall --dry-run` safely previews both global and project integrations, while real uninstall requires exactly one of `--global` or `--project`.
 
 Setup/configuration writers are conflict-aware. They reread the latest file
 under a short token-owned lock, preserve unknown JSON fields and prose outside
-owned Markdown markers, and publish complete bytes durably. An unrelated
+owned Markdown markers, and publish complete bytes with flushed files and,
+where the host supports it, a synchronized complete directory path. An unrelated
 intervening JSON edit is merged; a stale decision about the same project-config
 field, malformed latest JSON, malformed managed markers, or an edit that wins
 the final revision check produces an explicit conflict and leaves the latest
@@ -419,8 +481,9 @@ refreshes the index, smoke-tests representative command families, writes
 selected, reports the health score and items needing attention, and seeds
 AGENTS.md/CLAUDE.md guidance. Use
 the default terminal checklist to accept or decline the recommended automatic
-indexing action and other project-local changes (`--guided` reopens it
-explicitly). After setup,
+indexing action and other project-local changes (`--guided` requires an
+interactive terminal and reopens it explicitly; automation should use
+`--yes` or `--json`). After setup,
 `scip-audit` confirms raw signals and `scip-improve` keeps
 fixing the worst confirmed items until no safe confirmed cleanup remains. Use
 `scip-query setup --git-hook` when you also want a local pre-commit diff gate.
@@ -476,15 +539,16 @@ scip-query status --capabilities
 scip-query stats
 scip-query system src/auth
 scip-query plan-context login
-scip-query diff-impact --json
-scip-query health --json
+scip-query diff-impact
+scip-query health
 scip-query cleanup-plan --verify
 scip-query health --write-baseline   # start the ratchet
 ```
 
 ## Prerequisites
 
-- Node.js >= 18
+- Node.js 24 LTS is recommended. Node.js 22 is the minimum supported runtime;
+  Node.js 22, 24, and 26 are tested.
 - `scip` CLI, from [Sourcegraph SCIP releases](https://github.com/sourcegraph/scip/releases)
 - A language-specific SCIP indexer for your project
 
@@ -546,8 +610,14 @@ selects the database, SCIP companion, and metadata as one unit; every
 `index.db`, `index.scip`, and `meta.json` files remain compatibility mirrors,
 but internal queries do not reread them after opening a generation. This keeps
 cursor identities and semantic requests attached to the same rows even during
-a concurrent reindex. The publication, crash, legacy-overlap, and retention
-rules are documented in [Local Index Generations](docs/INDEX_GENERATIONS.md).
+a concurrent reindex. Each live reader publishes a process-identity lease.
+Automatic collection retains the current and recovery generations, every
+live-reader generation, and enough recent generations to stay within both an
+eight-generation and 2 GiB logical default bound. Malformed reader ownership
+fails closed; dead readers are reclaimed. `status` reports retained count,
+logical bytes, oldest age, protected/readers counts, limits, and the last
+collection result. The publication, crash, legacy-overlap, and retention rules
+are documented in [Local Index Generations](docs/INDEX_GENERATIONS.md).
 
 All `meta.json` consumers share one version decoder and an explicit capability
 matrix. Version 2 remains readable, version 3 is current, and version 4 is a
@@ -646,6 +716,14 @@ replacement, and manual preemption verify both values before signaling. A
 legacy record or a platform lookup failure therefore fails closed with an
 explicit recovery error instead of treating a reused PID as the old
 tool-owned process.
+Watcher shutdown stops new work and gives subscriptions and active reindex
+ownership five seconds to drain. A dedicated watch service that cannot prove a
+clean stop reports a degraded shutdown and exits so the operating system can
+close stuck descriptors. `watch stop` allows six seconds for that graceful
+path, then revalidates the exact process-start identity before forced
+termination and waits up to one additional second to observe exit. A changed
+or unavailable identity is never signaled, and ownership files are not cleaned
+until the original process is known to have exited.
 
 Finite subprocesses use explicit wall-time and output budgets. Quick binary
 probes default to 10 seconds, Git operations to 30 seconds, isolated analysis
@@ -685,10 +763,20 @@ Clojure projects can pass a project-local `scip-clojure` config file through `.s
 }
 ```
 
-Most read-only commands accept `--json` and use the same envelope:
+Most read-only commands accept `--json` and use the same versioned envelope.
+Add `--result-only` when a program needs just the command payload:
 
 ```json
-{ "command": "fan-in", "args": ["login"], "options": { "json": true }, "result": [] }
+{
+  "kind": "scip-query-result",
+  "schemaVersion": 1,
+  "producer": { "name": "scip-query", "version": "0.20.0" },
+  "command": "fan-in",
+  "resultSchemaVersion": 1,
+  "args": ["login"],
+  "options": { "json": true },
+  "result": []
+}
 ```
 
 ## Configuration
@@ -709,7 +797,7 @@ It creates a minimal `.scipquery.json`:
   "watch": {
     "enabled": true,
     "debounceMs": 250,
-    "cooldownMs": 0,
+    "cooldownMs": 5000,
     "gitPollMs": 2000,
     "idleTimeoutMs": 600000,
     "autoRefresh": true
@@ -739,7 +827,13 @@ background service. Relevant file/Git activity keeps it alive; it exits after
 `idleTimeoutMs` of clean inactivity and wakes on the next command. Set the idle
 timeout to `0` to keep it running. `scip-query watch` still provides foreground
 mode, while `watch --daemon`, `watch --status`, and `watch --stop` expose the
-background lifecycle. Both modes share one project lock, so only one can own an
+background lifecycle. Command-line timing flags are process-local and apply
+only when a foreground watcher or daemon starts; a live daemon refuses those
+flags and names the required stop/start sequence instead of pretending its
+timing changed. The default 5-second cooldown coalesces change bursts
+into one refresh plus, when necessary, one trailing refresh; explicitly setting
+`cooldownMs` to `0` opts into immediate scheduling. Both modes share one project
+lock, so only one can own an
 index cache. Stopping is an asynchronous drain: the watcher first rejects new
 refreshes, continuously consumes a bounded tail of the active worker's output,
 closes every source subscription, and waits for the worker to exit after
@@ -763,13 +857,24 @@ owner-expiring claims, retained idempotent completions, FIFO enqueue ordering,
 typed item/byte backpressure, bounded cleanup, and pressure telemetry. Client
 timeout or exit no longer deletes shared work; a service crash before response
 is reclaimable, while a response published before a crash prevents
-re-execution. The precise state machine, default limits, legacy overlap, and
+re-execution. The service rereads the clock before each claimed operation and
+again after handler completion, so time spent on an earlier request cannot let
+a later expired request begin or publish success. Idle mailbox polling backs
+off from 50 ms to 250 ms and returns to 10 ms while draining work; mailbox
+directories are initialized once per service ownership rather than on every
+poll. The precise state machine, default limits, legacy overlap, and
 failure matrix are documented in
 [`docs/MAILBOX_LIFECYCLE.md`](docs/MAILBOX_LIFECYCLE.md).
 Rust v3 additionally binds every accepted response to its request ID,
 operation ID, mailbox-session identity, and authoritative absolute deadline;
 its old/current/future compatibility matrix is in
 [`docs/RUST_DURABLE_SESSION_PROTOCOL.md`](docs/RUST_DURABLE_SESSION_PROTOCOL.md).
+The Rust semantic worker retains at most four rust-analyzer sessions. Linked
+Cargo projects are resolved, deduplicated, and sorted before session reuse, so
+equivalent project sets share one session regardless of input order. When the
+capacity is full, the least-recently-used session completes its LSP shutdown
+and process-tree reap before a replacement starts; an unproven shutdown blocks
+replacement instead of allowing overlapping language servers.
 It also reports a rolling 24-hour reindex activity summary: rebuilt, reused,
 failed, and freshness-proven suppressed refreshes plus estimated logical output
 bytes. The estimate counts scip-query artifacts emitted by rebuilt refreshes;
@@ -777,7 +882,12 @@ it is not a measurement of physical SSD writes. The underlying
 `reindex-activity.jsonl` history uses two bounded 1 MiB segments. Append,
 rotation, and retained-set reads share a process-instance lock; incomplete
 crash tails are trimmed or ignored without deleting earlier complete lines.
-These observations are process-visible rather than crash-durable. See
+Status labels the resulting summary `complete`, `partial`, or `unavailable`
+and reports read, invalid, skipped, read-error, and incomplete-tail counts.
+Telemetry append failure never changes the authoritative reindex result, but
+it is returned to the caller and surfaced as a warning or watch-state error
+instead of disappearing. These observations are process-visible rather than
+crash-durable. See
 [`docs/TELEMETRY_RETENTION.md`](docs/TELEMETRY_RETENTION.md).
 The refresh-request counters reported beside it describe durable demand
 admission and processing state, not reindex frequency.

package/dist/augment-vue-worker.js

@@ -1,2 +1,2 @@
-import{c as t}from"./chunk-3ZSJ3PWF.js";import"./chunk-IF6FP6B2.js";import"./chunk-C5Q44Q5D.js";import"./chunk-46XGSFNI.js";import{writeFileSync as s}from"fs";import{workerData as o}from"worker_threads";var r=o;try{let e=t({projectRoot:r.projectRoot,dbPath:r.dbPath,tsconfig:r.tsconfig,vueFiles:r.vueFiles,tasks:r.tasks});s(r.resultPath,JSON.stringify({version:1,runId:r.runId,workerId:r.workerId,taskIds:r.taskIds,ok:!0,result:e}))}catch(e){s(r.resultPath,JSON.stringify({version:1,runId:r.runId,workerId:r.workerId,taskIds:r.taskIds,ok:!1,error:e instanceof Error?e.message:String(e)}))}
+import{c as t}from"./chunk-PBUQFCNB.js";import"./chunk-FJH2NW7J.js";import"./chunk-WUPW3UN3.js";import"./chunk-46XGSFNI.js";import{writeFileSync as s}from"fs";import{workerData as o}from"worker_threads";var r=o;try{let e=t({projectRoot:r.projectRoot,dbPath:r.dbPath,tsconfig:r.tsconfig,vueFiles:r.vueFiles,tasks:r.tasks});s(r.resultPath,JSON.stringify({version:1,runId:r.runId,workerId:r.workerId,taskIds:r.taskIds,ok:!0,result:e}))}catch(e){s(r.resultPath,JSON.stringify({version:1,runId:r.runId,workerId:r.workerId,taskIds:r.taskIds,ok:!1,error:e instanceof Error?e.message:String(e)}))}
 //# sourceMappingURL=augment-vue-worker.js.map

package/dist/chunk-26QA6FAI.js

@@ -0,0 +1,8 @@
+import{a as k}from"./chunk-DHEQMPLW.js";import{a as $}from"./chunk-C43RDDP4.js";import{a as O,e as P,s as A}from"./chunk-EKZTZXHZ.js";import{o as R}from"./chunk-UJPRPGCO.js";import{E as S,F as w,G as j,K as T}from"./chunk-WCCFZ7V7.js";import{a as d}from"./chunk-NGEXCJJW.js";import{d as g}from"./chunk-7S5E7KWT.js";import{c as f}from"./chunk-C3KV2II6.js";import{existsSync as b,readdirSync as M}from"fs";import{join as p}from"path";var Q={files:new Set,pathPrefixes:[]},z={reasonsByFile:new Map},x=/^(?:dist|build|lib|out|output|esm|cjs|umd)\//,tt=/\.(?:d\.ts|d\.mts|d\.cts|ts|tsx|mts|cts|js|jsx|mjs|cjs)$/,C=[".ts",".tsx",".mts",".cts",".js",".jsx",".mjs",".cjs"],et=new Set([".git",".next",".turbo","build","coverage","dist","node_modules","out"]),rt=4,nt=g("package-surface",{clearGroups:["whole-project"]}),st=g("package-operational-surface",{clearGroups:["whole-project"]});function it(t){return nt.get(t,()=>ot(t.config.projectRoot))}function y(t,e){let r=it(t);return r.files.has(e)?!0:r.pathPrefixes.some(n=>e.startsWith(n))}function at(t){return st.get(t,()=>ct(t.config.projectRoot))}function ee(t,e){return at(t).reasonsByFile.get(e)??[]}function ot(t){let e=new Set,r=[];for(let{manifest:n,packageRoot:i}of N(t))for(let s of ut(n))V(t,i,s,e,r);return e.size===0&&r.length===0?Q:{files:e,pathPrefixes:r}}function ct(t){let e=new Map;for(let{manifest:r,packageRoot:n}of N(t)){let i=ft(r);for(let a of i)F(t,n,a,"package binary",e);let s=r.scripts;if(!(!s||typeof s!="object")){for(let[a,o]of Object.entries(s))if(typeof o=="string")for(let c of gt(o))F(t,n,c,`package script "${a}"`,e)}}return e.size===0?z:{reasonsByFile:e}}function N(t){let e=[],r=v(t,"");return r&&e.push({manifest:r,packageRoot:""}),L(t,"",e,0),e}function L(t,e,r,n){if(n>=rt)return;let i=p(t,e);if(b(i))for(let s of M(i,{withFileTypes:!0})){if(!s.isDirectory()||et.has(s.name))continue;let a=e?`${e}/${s.name}`:s.name,o=v(t,a);o&&r.push({manifest:o,packageRoot:a}),L(t,a,r,n+1)}}function v(t,e){let r;try{r=S(t,p(e,"package.json"),{maxBytes:8*1024*1024,inputKind:"package manifest"})}catch(n){if(!w(n))throw n;return null}try{let n=JSON.parse(r);return n&&typeof n=="object"?n:null}catch{return null}}function ut(t){let e=[];for(let n of["main","module","types","browser"])typeof t[n]=="string"&&e.push(t[n]);let r=t.bin;if(typeof r=="string")e.push(r);else if(r&&typeof r=="object")for(let n of Object.values(r))typeof n=="string"&&e.push(n);return I(t.exports,e),e}function ft(t){let e=t.bin;return typeof e=="string"?[e]:!e||typeof e!="object"?[]:Object.values(e).filter(r=>typeof r=="string")}function gt(t){let e=[],r=/(?:^|&&|\|\||;)\s*(?:(?:cross-env|env)(?:\s+[A-Za-z_][A-Za-z0-9_]*=\S+)*\s+)?(?:node|bun|tsx|ts-node|vite-node|python3?|deno\s+run)\s+(?:(?:--?[A-Za-z0-9-]+(?:=\S+)?)\s+)*["']?([^"'`\s]+\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py))["']?/g;for(let n of t.matchAll(r)){let i=n[1];i&&!i.startsWith("node_modules/")&&!i.startsWith("./node_modules/")&&e.push(i)}return e}function F(t,e,r,n,i){let s=new Set;V(t,e,r,s,[]);for(let a of s){let o=i.get(a)??[];o.includes(n)||o.push(n),i.set(a,o)}}function I(t,e){if(typeof t=="string"){e.push(t);return}if(!(!t||typeof t!="object"))for(let r of Object.values(t))I(r,e)}function V(t,e,r,n,i){let s=r.replace(/\\/g,"/").replace(/^\.\//,"");if(s===""||s.startsWith(".."))return;let a=s.indexOf("*");if(a>=0){let c=s.slice(0,a);for(let l of D(c))l!==""&&i.push(u(e,l));return}let o=s.replace(tt,"");for(let c of D(o)){c===o&&c===s&&n.add(u(e,s));for(let l of C)lt(t,n,e,c+l)}n.add(u(e,s))}function D(t){let e=[t];return x.test(t)&&(e.push(t.replace(x,"src/")),e.push(t.replace(x,""))),e}function lt(t,e,r,n){let i=u(r,n);if(e.add(i),!n.startsWith("src/")||b(p(t,i)))return;let s=C.find(m=>n.endsWith(m));if(!s)return;let a=n.slice(0,-s.length);pt(t,e,r,a,s);let o=a.lastIndexOf("/");if(o<=4)return;let c=a.slice(0,o),l=a.slice(o+1);for(let m of B(t,r,c,`${l}${s}`))e.add(m)}function pt(t,e,r,n,i){let s=u(r,`${n}/index${i}`);b(p(t,s))&&e.add(s)}function B(t,e,r,n){let i=p(t,e,r);if(!b(i))return[];let s=[];for(let a of M(i,{withFileTypes:!0})){let o=`${r}/${a.name}`;a.isDirectory()?s.push(...B(t,e,o,n)):a.isFile()&&a.name===n&&s.push(u(e,o))}return s}function u(t,e){return t?`${t}/${e}`:e}import{existsSync as E,readdirSync as dt}from"fs";import{dirname as St,join as _}from"path";var bt={rootFiles:new Set,sourcePrefixes:[]},ht=new Set([".git",".scipquery","node_modules","target"]),mt=6,Pt=g("rust-library-surface",{clearGroups:["whole-project"]});function W(t,e,r){if(!r.endsWith(".rs")||!Et(xt(t),r))return!1;let n=A(t,r).find(i=>i.symbol===e);return n?_t(T(t,r)[n.startLine]??""):!1}function xt(t){return Pt.get(t,()=>yt(t.config.projectRoot))}function yt(t){let e=new Set,r=new Set;for(let n of kt(t)){let i=S(t,_(n,"Cargo.toml"),{maxBytes:8388608,inputKind:"Cargo manifest"}),s=wt(i),a=u(n,"src/lib.rs"),o=s?u(n,s):!jt(i)&&j(t,a)?a:null;if(!o)continue;e.add(o);let c=St(o).replaceAll("\\","/");r.add(c==="."?"":`${c}/`)}return e.size===0?bt:{rootFiles:e,sourcePrefixes:[...r].sort()}}function Et(t,e){return e.endsWith(".rs")?t.rootFiles.has(e)?!0:Tt(e)?!1:t.sourcePrefixes.some(r=>e.startsWith(r)):!1}function _t(t){return/^\s*pub\s+(?!\()/.test(t)}function kt(t){if(!E(t))return[];let e=[];return X(t,"",e,0),e}function X(t,e,r,n){let i=_(t,e);if(E(i)&&(E(_(i,"Cargo.toml"))&&r.push(e),!(n>=mt)))for(let s of dt(i,{withFileTypes:!0})){if(!s.isDirectory()||ht.has(s.name))continue;let a=e?`${e}/${s.name}`:s.name;X(t,a,r,n+1)}}function wt(t){let e=!1;for(let r of t.split(`
+`)){let n=r.replace(/\s+#.*$/,"").trim(),i=/^\[([^\]]+)\]$/.exec(n);if(i){e=i[1]==="lib";continue}if(!e)continue;let s=/^path\s*=\s*["']([^"']+)["']/.exec(n)?.[1];if(s)return s.replaceAll("\\","/").replace(/^\.\//,"")}return null}function jt(t){let e=!1;for(let r of t.split(`
+`)){let n=r.replace(/\s+#.*$/,"").trim(),i=/^\[([^\]]+)\]$/.exec(n);if(i){e=i[1]==="package";continue}if(e&&/^autolib\s*=\s*false\b/.test(n))return!0}return!1}function Tt(t){return/(?:^|\/)src\/main\.rs$/.test(t)||/(?:^|\/)src\/bin\//.test(t)||/(?:^|\/)(?:examples|tests|benches)\//.test(t)}function h(t){let e=f(t);return Ht(e)?"test":Kt(e)?"worker":Yt(e)?"entry":Zt(e)?"barrel":"source"}function Rt(t){return h(t)==="barrel"}function U(t){return $t.get(t,()=>{let r=d(t,{includeIgnored:!1}).filter(a=>{let o=h(a);return o==="entry"||o==="worker"});if(r.length===0)return new Set;let n=$(t),i=new Set,s=new Set;for(;r.length>0;){let a=r.shift();if(!i.has(a)){i.add(a),h(a)==="barrel"&&s.add(a);for(let o of n.get(a)??[])i.has(o)||r.push(o)}}return s})}var $t=g("live-barrels",{clearGroups:["whole-project"]});function Ot(t,e){return U(t).has(f(e))}function ye(t){let e=U(t);return d(t,{includeIgnored:!1}).filter(r=>Rt(r)&&!e.has(r)&&!At(t,r))}function At(t,e){let r=f(e),n=O(t).forFile(r,{facts:!0}).facts?.callables;return n&&n.length>0?!0:(t.get(`SELECT COUNT(*) AS n
+     FROM defn_enclosing_ranges der
+     JOIN documents d ON d.id = der.document_id
+     WHERE d.relative_path = ?
+       AND der.end_line - der.start_line >= 2`,r)?.n??0)>0}function Ee(t,e){let r=f(e),n=h(e);return n==="entry"||n==="worker"||Xt(r)||Ot(t,r)}function _e(t,e,r){let n=f(r);if(y(t,n)||Dt(t,e,n)||W(t,e,n)||Wt(e,n))return!0;let i=t.config.entryRoots;return i?!!(i.files?.some(s=>f(s)===n)||i.pathPrefixes?.some(s=>n.startsWith(f(s)))||i.qualifiedVars?.some(s=>qt(e,s))||i.symbolPatterns?.some(s=>{try{return k(s,"entryRoots.symbolPatterns entry").test(e)}catch{return!1}})):!1}var Ft=g("package-surface-reachability",{clearGroups:["whole-project"]});function Dt(t,e,r){let n=Mt(t).get(r);return n===void 0?!1:n===null||n.has(P(e))}function Mt(t){return Ft.get(t,()=>{let e=new Map,r=[];for(let n of d(t,{includeIgnored:!1}))y(t,n)&&(e.set(n,null),r.push(n));for(;r.length>0;){let n=r.shift(),i=e.get(n);if(i!==void 0)for(let s of R(t,n)){if(!s.sourcePath||t.isIgnored(s.sourcePath))continue;let a=Ct(i,s);a!==void 0&&Nt(e,s.sourcePath,a)&&r.push(s.sourcePath)}}return e})}function Ct(t,e){if(t===null)return e.kind==="named"?new Set(e.names):null;if(e.kind==="star")return new Set(t);if(e.kind==="star-as")return;let r=e.names.filter(n=>t.has(n));return r.length>0?new Set(r):void 0}function Nt(t,e,r){if(!t.has(e))return t.set(e,r),!0;let n=t.get(e);if(n===void 0)return!1;if(n===null||r===null)return n===null?!1:(t.set(e,null),!0);let i=!1;for(let s of r)n.has(s)||(n.add(s),i=!0);return i}var H=new Set(["GET","POST","PUT","PATCH","DELETE","HEAD","OPTIONS"]),Lt=new Set(["default","generateMetadata","generateStaticParams"]),vt=new Set(["default","getStaticProps","getServerSideProps","getStaticPaths","config"]),It=new Set(["default","loader","action","clientLoader","clientAction","headers","links","meta","shouldRevalidate","ErrorBoundary","HydrateFallback"]),Vt=new Set(["load","actions","entries",...H]),Bt=new Set(["default"]);function Wt(t,e){let r=P(t);return r===""?!1:K(e)?H.has(r):Y(e)?Lt.has(r):Z(e)?vt.has(r):q(e)?It.has(r):J(e)?Vt.has(r):Ut(e)?Bt.has(r):!1}function Xt(t){return K(t)||Y(t)||Z(t)||Gt(t)||q(t)||J(t)}function K(t){return/(?:^|\/)app(?:\/[^/]+)*\/route\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(t)}function Y(t){return/(?:^|\/)app(?:\/[^/]+)*\/(?:page|layout|template|loading|error|not-found|global-error|head|default)\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(t)}function Z(t){return/(?:^|\/)pages\/.+\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(t)}function Gt(t){let e="(?:middleware|proxy|instrumentation)\\.(?:ts|js|mts|mjs)";return new RegExp(`^(?:src/)?${e}$`).test(t)||new RegExp(`(?:^|/)src/${e}$`).test(t)||new RegExp(`(?:^|/)(?:apps|services|packages)/[^/]+/(?:src/)?${e}$`).test(t)}function q(t){return/(?:^|\/)app\/routes\/.+\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(t)}function J(t){return/(?:^|\/)src\/routes\/(?:.*\/)?\+(?:page|page\.server|layout|layout\.server|server)\.(?:ts|js)$/.test(t)}function Ut(t){return/(?:^|\/)src\/(?:pages|views|routes)\/.+\.(?:ts|tsx|js|jsx|vue)$/.test(t)}function Ht(t){return!!(/\.(?:test|spec)\.[a-z0-9]+$/i.test(t)||/(?:^|\/)(?:_)?test_[^/]+$/i.test(t)||/(?:^|\/)spec_[^/]+$/i.test(t)||/(?:^|\/)[^/]+_test\.[a-z0-9]+$/i.test(t)||/(?:^|\/)[^/]+_tests\.rs$/i.test(t)||/(?:^|\/)tests\.rs$/i.test(t)||/(?:^|\/)[^/]+_spec\.[a-z0-9]+$/i.test(t)||/(?:^|\/)__tests__\//i.test(t)||/(?:^|\/)test\//i.test(t)||/(?:^|\/)tests\//i.test(t)||/(?:^|\/)__fixtures__\//i.test(t)||/(?:^|\/)__mocks__\//i.test(t)||/(?:^|\/)test-support\//i.test(t)||/(?:^|\/)test-utils\//i.test(t)||/(?:^|\/)testing\//i.test(t))}function Kt(t){return/(?:^|\/)[^/]*worker\.(?:ts|tsx|js|mjs|cjs|rs|py|go)$/.test(t)}function Yt(t){let e=t.split("/"),r=e[e.length-1]??t;return r==="cli.ts"||r==="cli.js"||r==="postinstall.ts"||r==="postinstall.js"||r==="main.ts"||r==="main.js"||r==="main.rs"||r==="main.go"||r==="main.py"||r==="build.rs"||r==="lib.rs"||/\bsrc\/bin\/[^/]+\.rs$/.test(t)||/(?:^|\/)examples\/[^/]+\.rs$/.test(t)||/(?:^|\/)tests\/[^/]+\.rs$/.test(t)||/(?:^|\/)benches\/[^/]+\.rs$/.test(t)?!0:r==="index.ts"||r==="index.js"?/(?:^|\/)(?:apps|services)\/[^/]+\/src\/index\.(?:ts|js)$/.test(t)?!0:e.length<=2:!1}function Zt(t){return t==="index.ts"||t==="index.js"||t.endsWith("/index.ts")||t.endsWith("/index.js")||t.endsWith("/mod.rs")||t.endsWith("/__init__.py")}function qt(t,e){let r=e.lastIndexOf("/");if(r<0)return!1;let n=e.slice(0,r),i=e.slice(r+1);return t.includes(G(n)+"/")&&t.includes(G(i)+".")}function G(t){return/^[A-Za-z0-9_$+-]+$/.test(t)?t:"`"+t.replace(/`/g,"``")+"`"}export{y as a,ee as b,h as c,Rt as d,Ot as e,ye as f,Ee as g,_e as h,Xt as i};
+//# sourceMappingURL=chunk-26QA6FAI.js.map

package/dist/{chunk-KJ2IIBZN.js → chunk-2HPVVXM5.js}

@@ -1,2 +1,2 @@
-import{b as A}from"./chunk-3EDFLQ6A.js";import{a as _}from"./chunk-X6RKPDY7.js";import{f as R,g as L}from"./chunk-6M7RONVB.js";import{c as E}from"./chunk-2SNGN6U4.js";import{f as x,g as I}from"./chunk-LP3ARJKF.js";import{b as D}from"./chunk-B75HZHUP.js";import{a as w}from"./chunk-BGBBVSH4.js";import{d as N}from"./chunk-RA3AYNWP.js";import{b as T,c as h}from"./chunk-MZZBAITE.js";import{O as S}from"./chunk-JORHF5AL.js";import{a as g}from"./chunk-64MNV6AB.js";var F={caller:3,"entry-surface":2,rooted:1},O=/not\s*yet\s*implement|not\s*implement|unimplement|\bnyi\b|\btodo\b|\bstub\b|not\s*supported|coming\s*soon/i,P=/^throw\s+new\s+[\w.]*Error\s*\(([\s\S]*)\)\s*;?$/,C=/^return(\s+(null|undefined|false|0|''|""|``|\[\]|\{\}))?\s*;?$/,v=/\/\/\s*TODO\b|\/\*\s*TODO\b/i,K=/(?:=>|\))\s*(?::\s*[^{;=]+)?\s*\{\s*\}\s*;?\s*$/;function et(e,n={}){let{scope:o,limit:r=30,scanLimit:l,semantic:a=!0}=n,s=new E(e),t=D(s.productionCallableDefinitions({scope:o,minLoc:1,requireFunctionLikeSymbol:!0,excludeTypesFiles:!0}),l),c=[];for(let i of t){let m=M(e,i);m&&c.push(m)}if(c.length===0)return[];let d=j(e,c,t),f=c.filter(i=>!d.has(i.def.symbol));if(f.length===0)return[];let p=_(e,s).forDefinitions(f.map(i=>i.def),{semantic:a}),u=[];for(let i of f){let b=p.get(i.def.symbolId)?.realConsumers.length??0,y=B(e,i.def,b);y&&u.push({symbol:i.def.symbol,shortName:N(i.def.symbol),file:i.def.relativePath,startLine:i.def.startLine,endLine:i.def.endLine,loc:w(i.def),stubKind:i.stubKind,reachability:y,callerFanIn:b,stubText:i.stubText})}return u.sort((i,m)=>F[m.reachability]-F[i.reachability]||m.callerFanIn-i.callerFanIn||i.file.localeCompare(m.file)||i.startLine-m.startLine),r?u.slice(0,r):u}function B(e,n,o){return o>0?"caller":I(e,n.symbol,n.relativePath)?"rooted":x(e,n.relativePath)?"entry-surface":null}function M(e,n){let o=R(e,n);if(!o)return null;let r=L(o),l=r.trim();if(l==="")return!z(o)||!A(e,n)?null:{def:n,stubKind:"empty-body",stubText:"(empty body)"};let a=h(r),s=T(r),t=$(a,s);if(t.length!==1)return null;let c=t[0];return U(c)?{def:n,stubKind:"throw-stub",stubText:c.trim()}:v.test(r)&&C.test(c.trim())?{def:n,stubKind:"todo-return-default",stubText:l}:null}function $(e,n){let o=[],r=0,l="";for(let a=0;a<n.length;a+=1){let s=n[a];if(s==="("||s==="["||s==="{"?r+=1:(s===")"||s==="]"||s==="}")&&(r=Math.max(0,r-1)),s===";"&&r===0){o.push(l),l="";continue}l+=e[a]??""}return l.trim()&&o.push(l),o.map(a=>a.trim()).filter(a=>a.length>0)}function U(e){let n=P.exec(e.trim());return n?O.test(n[1]??""):!1}function z(e){return K.test(e.trimEnd())}function j(e,n,o){let r=new Set,l=new Set(n.map(t=>t.def.parentTypeName).filter(t=>t!==null));if(l.size===0)return r;let a=k(e,l),s=new Map;for(let t of o){if(!t.parentTypeName)continue;let c=s.get(t.leaf)??new Set;c.add(t.parentTypeName),s.set(t.leaf,c)}for(let t of n){let c=t.def.parentTypeName;if(!c)continue;let d=a.get(c);if(!d||d.size===0)continue;let f=s.get(t.def.leaf)??new Set;[...d].every(u=>f.has(u))&&r.add(t.def.symbol)}return r}var Y=/\bclass\s+([A-Za-z_$][\w$]*)\s+extends\s+([A-Za-z_$][\w$]*)/g;function k(e,n){let o=new Map;for(let r of g(e,{includeIgnored:!1})){let l=S(e,r);if(l)for(let a of l.matchAll(Y)){let s=a[1],t=a[2];if(!s||!t||!n.has(t))continue;let c=o.get(t)??new Set;c.add(s),o.set(t,c)}}return o}export{et as a};
-//# sourceMappingURL=chunk-KJ2IIBZN.js.map
+import{b as A}from"./chunk-6O5TICIZ.js";import{a as _}from"./chunk-MV7OWDUX.js";import{f as R,g as L}from"./chunk-JVYA47YU.js";import{c as E}from"./chunk-UJCOIXDY.js";import{g as x,h as I}from"./chunk-26QA6FAI.js";import{b as D}from"./chunk-B75HZHUP.js";import{a as w}from"./chunk-BGBBVSH4.js";import{d as N}from"./chunk-EKZTZXHZ.js";import{b as T,c as h}from"./chunk-UJPRPGCO.js";import{J as S}from"./chunk-WCCFZ7V7.js";import{a as g}from"./chunk-NGEXCJJW.js";var F={caller:3,"entry-surface":2,rooted:1},O=/not\s*yet\s*implement|not\s*implement|unimplement|\bnyi\b|\btodo\b|\bstub\b|not\s*supported|coming\s*soon/i,P=/^throw\s+new\s+[\w.]*Error\s*\(([\s\S]*)\)\s*;?$/,C=/^return(\s+(null|undefined|false|0|''|""|``|\[\]|\{\}))?\s*;?$/,v=/\/\/\s*TODO\b|\/\*\s*TODO\b/i,K=/(?:=>|\))\s*(?::\s*[^{;=]+)?\s*\{\s*\}\s*;?\s*$/;function et(e,n={}){let{scope:o,limit:r=30,scanLimit:l,semantic:a=!0}=n,s=new E(e),t=D(s.productionCallableDefinitions({scope:o,minLoc:1,requireFunctionLikeSymbol:!0,excludeTypesFiles:!0}),l),c=[];for(let i of t){let m=M(e,i);m&&c.push(m)}if(c.length===0)return[];let d=j(e,c,t),f=c.filter(i=>!d.has(i.def.symbol));if(f.length===0)return[];let p=_(e,s).forDefinitions(f.map(i=>i.def),{semantic:a}),u=[];for(let i of f){let b=p.get(i.def.symbolId)?.realConsumers.length??0,y=B(e,i.def,b);y&&u.push({symbol:i.def.symbol,shortName:N(i.def.symbol),file:i.def.relativePath,startLine:i.def.startLine,endLine:i.def.endLine,loc:w(i.def),stubKind:i.stubKind,reachability:y,callerFanIn:b,stubText:i.stubText})}return u.sort((i,m)=>F[m.reachability]-F[i.reachability]||m.callerFanIn-i.callerFanIn||i.file.localeCompare(m.file)||i.startLine-m.startLine),r?u.slice(0,r):u}function B(e,n,o){return o>0?"caller":I(e,n.symbol,n.relativePath)?"rooted":x(e,n.relativePath)?"entry-surface":null}function M(e,n){let o=R(e,n);if(!o)return null;let r=L(o),l=r.trim();if(l==="")return!z(o)||!A(e,n)?null:{def:n,stubKind:"empty-body",stubText:"(empty body)"};let a=h(r),s=T(r),t=$(a,s);if(t.length!==1)return null;let c=t[0];return U(c)?{def:n,stubKind:"throw-stub",stubText:c.trim()}:v.test(r)&&C.test(c.trim())?{def:n,stubKind:"todo-return-default",stubText:l}:null}function $(e,n){let o=[],r=0,l="";for(let a=0;a<n.length;a+=1){let s=n[a];if(s==="("||s==="["||s==="{"?r+=1:(s===")"||s==="]"||s==="}")&&(r=Math.max(0,r-1)),s===";"&&r===0){o.push(l),l="";continue}l+=e[a]??""}return l.trim()&&o.push(l),o.map(a=>a.trim()).filter(a=>a.length>0)}function U(e){let n=P.exec(e.trim());return n?O.test(n[1]??""):!1}function z(e){return K.test(e.trimEnd())}function j(e,n,o){let r=new Set,l=new Set(n.map(t=>t.def.parentTypeName).filter(t=>t!==null));if(l.size===0)return r;let a=k(e,l),s=new Map;for(let t of o){if(!t.parentTypeName)continue;let c=s.get(t.leaf)??new Set;c.add(t.parentTypeName),s.set(t.leaf,c)}for(let t of n){let c=t.def.parentTypeName;if(!c)continue;let d=a.get(c);if(!d||d.size===0)continue;let f=s.get(t.def.leaf)??new Set;[...d].every(u=>f.has(u))&&r.add(t.def.symbol)}return r}var Y=/\bclass\s+([A-Za-z_$][\w$]*)\s+extends\s+([A-Za-z_$][\w$]*)/g;function k(e,n){let o=new Map;for(let r of g(e,{includeIgnored:!1})){let l=S(e,r);if(l)for(let a of l.matchAll(Y)){let s=a[1],t=a[2];if(!s||!t||!n.has(t))continue;let c=o.get(t)??new Set;c.add(s),o.set(t,c)}}return o}export{et as a};
+//# sourceMappingURL=chunk-2HPVVXM5.js.map

package/dist/chunk-2KAZEZ6M.js

@@ -0,0 +1,2 @@
+import{closeSync as p,fstatSync as g,openSync as l,readFileSync as B,readSync as y}from"fs";import{createHash as P}from"crypto";var h=8*1024*1024,A=64*1024*1024,F=512*1024*1024,L=256*1024*1024,c=class extends Error{constructor(r,o,i,n,a){let s=i==="too-large"?`is ${n} bytes; the safety limit is ${a} bytes`:i==="not-regular"?"is not a regular file":"changed while it was being read";super(`${r} ${JSON.stringify(o)} ${s}`);this.inputKind=r;this.inputPath=o;this.reason=i;this.observedBytes=n;this.limitBytes=a;this.name="BoundedFileReadError"}inputKind;inputPath;reason;observedBytes;limitBytes;code="SCIP_QUERY_BOUNDED_FILE_READ"};function x(e,t){m(t.maxBytes);let r=String(e),o=l(e,"r");try{let i=g(o);R(i,t,r);let n=B(o),a=g(o);if(a.dev!==i.dev||a.ino!==i.ino||a.size!==i.size||n.byteLength!==i.size)throw new c(t.inputKind,r,"changed-during-read",a.size,t.maxBytes);return n}finally{p(o)}}function b(e,t,r="utf8"){return x(e,t).toString(r)}function T(e,t){return b(e,{maxBytes:h,inputKind:t})}function f(e,t){m(t.maxBytes);let r=[],o=Buffer.allocUnsafe(64*1024),i=0;for(;;){let n=y(e,o,0,o.length,null);if(n===0)break;if(i+=n,!Number.isSafeInteger(i)||i>t.maxBytes)throw new c(t.inputKind,`file descriptor ${e}`,"too-large",i,t.maxBytes);r.push(Buffer.from(o.subarray(0,n)))}return Buffer.concat(r,i)}function v(e,t,r="utf8"){return f(e,t).toString(r)}function S(e,t){let r=l(e,"r");try{return f(r,t)}finally{p(r)}}function k(e,t,r="utf8"){return S(e,t).toString(r)}function C(e,t,r){m(t.maxBytes);let o=String(e),i=l(e,"r");try{let n=g(i);R(n,t,o);let a=Buffer.allocUnsafe(Math.min(1024*1024,Math.max(1,n.size))),s=0;for(;s<n.size;){let d=y(i,a,0,Math.min(a.length,n.size-s),s);if(d===0)break;r(a.subarray(0,d)),s+=d}let u=g(i);if(u.dev!==n.dev||u.ino!==n.ino||u.size!==n.size||s!==n.size)throw new c(t.inputKind,o,"changed-during-read",u.size,t.maxBytes);return s}finally{p(i)}}function E(e,t){let r=P("sha256");return C(e,t,o=>r.update(o)),r.digest("hex")}function R(e,t,r){if(!e.isFile())throw new c(t.inputKind,r,"not-regular",Number(e.size),t.maxBytes);if(e.size>t.maxBytes)throw new c(t.inputKind,r,"too-large",Number(e.size),t.maxBytes)}function m(e){if(!Number.isSafeInteger(e)||e<0)throw new RangeError(`maxBytes must be a non-negative safe integer; received ${e}`)}function D(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function W(e){return typeof e=="string"&&Number.isFinite(Date.parse(e))}function z(e){return typeof e=="number"&&Number.isSafeInteger(e)&&e>=0}var K=["typescript","javascript","java","scala","kotlin","rust","python","ruby","go","cpp","c","csharp","vb","dart","php","clojure"],Y=["entry-surface","generated-code","compatibility-shim","reflection-or-registration","test-fixture","intentional-twin","historical-coupling-ended","detector-counterexample"];export{D as a,W as b,z as c,K as d,Y as e,h as f,A as g,F as h,L as i,c as j,x as k,b as l,T as m,v as n,k as o,C as p,E as q};
+//# sourceMappingURL=chunk-2KAZEZ6M.js.map

package/dist/chunk-32LVLCLN.js

@@ -0,0 +1,40 @@
+import{b as y}from"./chunk-6O5TICIZ.js";import{b as f}from"./chunk-T7YQSHPQ.js";import{c as h,d as w}from"./chunk-MTDBHTSF.js";import{d as u,e as m,h as b,p,q as g}from"./chunk-EKZTZXHZ.js";import{dirname as $,isAbsolute as k,relative as x,resolve as v}from"path";var C=new Set(w());function R(t,e){return`tests/generated/twin-ab/${d(t)}-vs-${d(e)}.test.ts`}function d(t){return(t.split(/[/#]/).pop()||t).replace(/[^A-Za-z0-9_-]+/g,"-").replace(/^-+|-+$/g,"")||"symbol"}function P(t,e,a,n){let{refA:l,refB:s,outFile:r}=typeof e=="string"?{refA:e,refB:a,outFile:n}:e;if(typeof l!="string"||typeof s!="string"||typeof r!="string")throw new TypeError("twinAb requires refA, refB, and outFile.");if(!k(r))throw new TypeError("twinAb outFile must be an absolute path.");let i=A(t,l);if(!i.ok)return i;let o=A(t,s);if(!o.ok)return o;let c=i.symbol.paramCount===null||o.symbol.paramCount===null?null:i.symbol.paramCount===o.symbol.paramCount,S=N(i.symbol,o.symbol,t.config.projectRoot,r,c);return{ok:!0,a:i.symbol,b:o.symbol,signatureCompatible:c,testSource:S}}function A(t,e){let n=f(t,e).match;if(!n)return{ok:!1,reason:`${e} does not resolve to an indexed symbol.`};let s=t.get("SELECT kind FROM global_symbols WHERE id = ?",n.symbolId)?.kind??null;if(!(s!==null?C.has(s):b(n.symbol)))return{ok:!1,reason:`${e} resolves to ${u(n.symbol)}${s!==null?` with SCIP kind ${h(s)}`:""} \u2014 twin-ab compares call outputs, so both referents must be functions or methods.`};if(!y(t,n))return{ok:!1,reason:`${e} (${u(n.symbol)} at ${n.relativePath}:${n.startLine+1}) is not exported \u2014 twin-ab needs an importable named binding for both twins.`};let i=t.get("SELECT documentation FROM global_symbols WHERE id = ?",n.symbolId),o=p(g(i?.documentation??null));return{ok:!0,symbol:{ref:e,symbol:n.symbol,shortName:m(n.symbol)||u(n.symbol),file:n.relativePath,startLine:n.startLine,signature:o,paramCount:o?E(o):null}}}function E(t){let e=t.indexOf("(");if(e===-1)return null;let a=0,n=-1;for(let i=e;i<t.length;i+=1){let o=t[i];if(o==="(")a+=1;else if(o===")"&&(a-=1,a===0)){n=i;break}}if(n===-1)return null;let l=t.slice(e+1,n).trim();if(!l)return 0;let s=1,r=0;for(let i of l)i==="("||i==="["||i==="{"?r+=1:i===")"||i==="]"||i==="}"?r=Math.max(0,r-1):i===","&&r===0&&(s+=1);return s}function T(t,e,a){let n=$(e),l=v(t,a),r=x(n,l).replace(/\\/g,"/").replace(/\.tsx?$/,".js");return r.startsWith(".")?r:`./${r}`}function N(t,e,a,n,l){let s=T(a,n,t.file),r=T(a,n,e.file),i=l===null?"Signature comparison: unknown (one or both signatures unavailable in the index) \u2014 check by hand.":l?"Signature comparison: param counts match.":"Signature comparison: param counts DIFFER \u2014 twins may not be directly comparable; check by hand.";return`/**
+ * Generated by 'scip-query twin-ab'. scip-audit integrity scenario.
+ * ("cross-examine same-concept twins"): where one concept is computed in
+ * more than one place, feed both the same input and require the same
+ * answer. Disagreement between twins means at least one is wrong \u2014
+ * determine which before consolidating.
+ *
+ * Twin A: ${t.shortName}  (${t.file}:${t.startLine+1})
+ *   ${t.signature??"(signature unavailable)"}
+ * Twin B: ${e.shortName}  (${e.file}:${e.startLine+1})
+ *   ${e.signature??"(signature unavailable)"}
+ * ${i}
+ *
+ * Fill in the TODO input table below with inputs both twins should agree
+ * on, then run this file with vitest.
+ */
+import { describe, expect, it } from 'vitest';
+import { ${t.shortName} as twinA } from '${s}';
+import { ${e.shortName} as twinB } from '${r}';
+
+// TODO: fill in shared inputs both twins should agree on \u2014 one arg array per call.
+const inputs: any[][] = [
+  // [/* arg1, arg2, ... */],
+];
+
+// Cast to a variadic signature so the input table can hold any arg shape \u2014
+// the real twins have fixed, non-rest parameter lists, and TS rejects
+// spreading a generic args array into those (TS2556) even when the array
+// itself is 'any'; casting the callee's signature, not the args, satisfies
+// the checker without weakening the twins' real exported types elsewhere.
+const callA = twinA as (...callArgs: any[]) => any;
+const callB = twinB as (...callArgs: any[]) => any;
+
+describe.skipIf(inputs.length === 0)('twin-ab: ${t.shortName} vs ${e.shortName}', () => {
+  it.each(inputs)('agrees on input %#', (...args) => {
+    expect(callA(...args)).toEqual(callB(...args));
+  });
+});
+`}export{R as a,P as b};
+//# sourceMappingURL=chunk-32LVLCLN.js.map