scip-query 0.19.8 → 0.20.0

package/docs/INDEX_GENERATIONS.md

@@ -23,6 +23,10 @@ The worktree cache keeps this internal layout:
   meta.json                        compatibility mirror
   .scipquery-generations/
     state.json                     atomic current-generation pointer
+    gc.json                        last bounded-collection observation
+    gc.lock                        collection/reader-admission coordinator
+    readers/
+      <pid>-<token>.json           live process-generation leases
     <generation-sha256>/
       manifest.json
       index.db
@@ -30,11 +34,19 @@ The worktree cache keeps this internal layout:
       meta.json
 ```
 
-The files inside a named generation directory are immutable. The SHA-256
+The files inside a named generation directory are immutable. Their final
+read-only mode is applied before their final file synchronization, so the
+persisted inode contains both the accepted bytes and the protection metadata.
+The SHA-256
 identity incorporates the database bytes, SCIP bytes when present, and the
 generation-bearing metadata fields. `manifest.json` records the exact size and
 digest of each stored artifact. `state.json` names the accepted directory and
 is the only publication decision read by internal database consumers.
+Opening a named generation authenticates the database, SCIP, and metadata
+bytes against those digests; matching size alone is never sufficient. A
+bounded process-local validation cache is keyed by manifest identity plus
+stable device, inode, size, modification-time, and change-time evidence, so a
+same-size mutation invalidates the cached proof and is rehashed.
 
 The top-level files remain for the SCIP CLI, indexers, older scip-query
 versions, and external inspection. They are derived mirrors, not the internal
@@ -48,18 +60,26 @@ Publication proceeds in this order:
 
 1. Retain the previously published stable artifacts as an immutable
    generation when upgrading a legacy cache.
-2. Copy-on-write clone or copy every accepted candidate artifact into a
-   private staging directory.
-3. Flush the artifact files and manifest, rename the complete staging
-   directory into its content-derived identity, and flush the generation
+2. Durably establish `.scipquery-generations/` from its nearest existing
+   ancestor when this is the cache's first generation.
+3. Copy-on-write clone or copy every accepted candidate artifact into a
+   private staging directory, apply its final read-only mode, and flush the
+   resulting inode.
+4. Flush the manifest and staging namespace, rename the complete staging
+   directory into its content-derived identity, and flush the generation-root
    directory entry.
-4. Durably replace `state.json` so new internal readers select the complete
+5. Establish the versioned query layout after augmentation: add the
+   definition-only covering index, remove known redundant indexes only when
+   schema inspection proves a retained equivalent, and run `ANALYZE` so the
+   planner sees the final row distribution. Query-plan tests hold those
+   proofs.
+6. Durably replace `state.json` so new internal readers select the complete
    new directory.
-5. Replace the three compatibility mirrors and durably record their file
+7. Replace the three compatibility mirrors and durably record their file
    identities for drift diagnostics.
 
-A crash before step 4 leaves the prior pointer authoritative. A crash after
-step 4 leaves the new immutable generation authoritative even if one or more
+A crash before step 6 leaves the prior pointer authoritative. A crash after
+the pointer step leaves the new immutable generation authoritative even if one or more
 compatibility mirrors are old. `scip-query status` and freshness inspection
 report that mirror drift and a later refresh repairs it; database-backed
 queries remain generation-consistent throughout.
@@ -70,6 +90,14 @@ and TypeScript semantic mailbox requests carry the handle identity, so a
 continuation or numeric symbol identifier from an older generation is rejected
 when a service has moved to a newer one.
 
+Current metadata also records `sqliteLayoutVersion`. A current-version
+metadata record that predates this field remains readable and can reuse its
+language SCIP shards, but it cannot take the whole-SQLite unchanged fast path.
+The next refresh applies query-layout maintenance to the stable mirror,
+publishes a new immutable generation and current layout metadata, and does not
+rerun unchanged language indexers. Later unchanged refreshes resume the
+ordinary whole-generation reuse path.
+
 Mailbox protocol version 3 additionally binds that generation identity into a
 content-derived logical-operation key. The deterministic request ID lets a
 retry join an already pending, inflight, or retained completed operation,
@@ -86,18 +114,36 @@ generation implementation, which did not name an immutable artifact set, also
 uses this compatibility path. New publications upgrade either layout without
 deleting the stable files.
 
-Published local generation directories are retained conservatively. Automatic
-collection is intentionally disabled until a cross-process reader lease can
-prove that no surviving handle can later need the retained SCIP companion.
-This can temporarily consume more cache space, but it preserves the stronger
-rule that storage reclamation may never change or remove evidence owned by a
-live query.
+Published local generation directories are retained by a bounded,
+reader-aware collector. Opening an immutable `ScipDatabase` first acquires the
+generation GC lock, resolves the current pointer, and visibility-atomically
+publishes a lease containing its random token, generation identity, PID, and
+operating-system process-start identity when available. Closing the database
+removes that exact lease idempotently.
+
+Publication and collection use the same token-owned process lock. Collection
+always protects the current generation, the named recovery generation, and
+every live reader generation. It removes only oldest unprotected generations
+until both default limits hold: at most eight retained generations and at most
+2 GiB of logical artifact bytes. A lease whose recorded process instance is
+provably dead is reclaimed. A malformed lease protects every generation and
+defers deletion; uncertainty cannot authorize reclamation.
+
+`gc.json` is a visibility-atomic diagnostic containing retained counts, logical
+bytes, protected/readers counts, removed counts, limits, state, time, and any
+reason. `scip-query status` reports that observation together with the current
+retained set and oldest generation age. Collection failure does not invalidate
+the accepted index; it remains explicit bounded-storage debt for the operator.
 
 The repository-wide shared generation store is a separate cache layer. It
-warms a worktree by copying a complete generation into the worktree's private
-cache; the local publisher then creates the local immutable directory and
-pointer described here. Later worktree writes cannot mutate either the shared
-source or a retained local reader.
+warms a worktree from a complete content-addressed generation. Publication
+flushes each final read-only artifact, the manifest, the staging namespace, the
+rename into `generations/<identity>`, and `generations/` itself before
+returning `directory-durable` on supported hosts. On a host without directory
+sync, it returns `file-flushed`; readers still rehash every artifact and reject
+an incomplete generation. The local publisher then creates the private
+immutable directory and pointer described here. Later worktree writes cannot
+mutate either the shared source or a retained local reader.
 
 ## Shared worktree lease invariant
 

package/docs/MAILBOX_LIFECYCLE.md

@@ -122,7 +122,12 @@ boundaries.
 A claim is a time-bounded service ownership record made real by renaming one
 pending file into an owner-specific inflight directory. Rename is the
 ownership compare-and-set: only the process whose rename succeeds owns that
-file. The directory's owner record binds the random owner ID to a PID and,
+file. Before a first claim can remove the pending name, the service durably
+establishes the fixed mailbox skeleton, creates the owner directory, and
+flushes `inflight/` so the complete destination path survives. It then writes
+the owner record, renames the request, flushes the source directory, and
+flushes the owner directory in that order. The directory's owner record binds
+the random owner ID to a PID and,
 when the operating system exposes it, a process-start identity. A process-start
 identity is the operating-system fact that distinguishes successive
 executions occupying the same numeric PID slot.
@@ -147,6 +152,14 @@ answer-affecting operations are read-only or rebuildable, the response
 identity is stable, and exclusive completion remains a final defense against
 two observable answers.
 
+Accepted admission and successful claims expose the achieved directory-sync
+result. On POSIX hosts that complete every directory flush this is
+`directory-durable`. When Node reports directory handles unsupported on
+Windows, it is `file-flushed`: complete file bytes and process-crash recovery
+remain, but the protocol does not upgrade that bounded result into a
+machine-crash namespace claim. Any other directory synchronization error
+throws instead of acknowledging the transition.
+
 ## Fairness and maintenance
 
 Pending work is ordered by `enqueuedAtMs`, then stable request identity.
@@ -158,6 +171,19 @@ at most 64 removals or reclaims. Those caps are what let the watch and Rust
 server loops regain control to update heartbeats, observe stop signals, and
 run unrelated maintenance even when a mailbox was flooded.
 
+The TypeScript watch service initializes its two mailbox layouts once after
+acquiring service ownership. An empty poll reads the already-established
+directories; it does not recreate or chmod the full layout. Consecutive empty
+polls back off from 50 ms through 100 ms and 200 ms to a 250 ms ceiling. A poll
+that processes work returns to a 10 ms drain interval. The Rust service uses
+the same 10–250 ms adaptive range.
+
+Deadline authority is re-evaluated per claimed request. A service reads its
+clock immediately before starting each handler and again after the handler
+returns. Therefore a request that expires while an earlier request runs is
+rejected before execution, and an answer completed after its authoritative
+deadline is not published as success.
+
 Maintenance:
 
 - reclaims expired inflight ownership only after the recorded process instance
@@ -190,6 +216,7 @@ window. Clock-domain rules for these records are documented in
 Focused contract coverage lives in:
 
 - `tests/storage/bounded-mailbox.test.ts`;
+- `tests/storage/atomic-file-crash.test.ts`;
 - `tests/semantic/typescript/typescript-session-mailbox.test.ts`;
 - `tests/reindex/typescript-index-mailbox.test.ts`;
 - `tests/semantic/rust/durable-session-protocol.test.ts`;

package/docs/REINDEX_METADATA_COMPATIBILITY.md

@@ -7,7 +7,7 @@ record rather than an authority by itself: a consumer still verifies the
 database, SCIP companion, immutable-generation state, or current source
 fingerprint required by its operation.
 
-`src/domain/reindex-metadata.ts` is the dependency-free decoding boundary. It
+`src/domain/reindex-metadata.ts` is the domain decoding boundary. It
 classifies an input as:
 
 - `legacy`: a structurally valid version 2 record;
@@ -38,12 +38,20 @@ Future records are never rewritten.
 
 Recognized versions validate `status`, optional timestamp,
 requested/indexed language sets, skipped-language rows, SCIP companion state,
-and v3 shard maps. A fingerprint is an opaque JSON identity for evidence and
-stable-generation compatibility, preserving the pre-decoder v2/v3 contract;
-freshness and publication additionally require it to be an object. Language
-lists contain unique names from the same
+the optional positive `sqliteLayoutVersion`, and v3 shard maps. A fingerprint
+is an opaque JSON identity for evidence and stable-generation compatibility,
+preserving the pre-decoder v2/v3 contract; freshness and publication
+additionally require it to be an object. Language lists contain unique names
+from the same
 `SUPPORTED_LANGUAGES` catalog used by configuration.
 
+The SQLite layout field is an additive v3 upgrade boundary rather than a wire
+version migration. A v3 record without it remains queryable, evidence-usable,
+and eligible for language-shard reuse. It is not eligible for whole-SQLite
+unchanged reuse. The next refresh can therefore reuse unchanged language SCIP
+shards, establish the current post-conversion indexes and planner statistics,
+and publish a new generation without rerunning those indexers.
+
 ## Capability matrix
 
 A capability is a named permission to interpret a decoded record for one
@@ -62,14 +70,16 @@ the same version while intentionally requiring different completeness.
 Consumer-specific comparisons happen only after this matrix accepts the
 record:
 
-- freshness and unchanged-index reuse compare a publishable fingerprint and
-  sorted indexed languages with current inputs;
+- freshness compares a publishable fingerprint and sorted indexed languages
+  with current inputs; whole-SQLite unchanged reuse additionally requires the
+  current `sqliteLayoutVersion`;
 - shared-generation publication additionally verifies the immutable artifact
   set, project root, and database integrity;
 - evidence and TypeScript semantic cache keys accept complete or partial
   records and include status, so partial and complete results cannot collide;
 - SQLite and TypeScript service generation identities use the same canonical
-  projection and reject records without stable-identity capability;
+  projection, including `sqliteLayoutVersion` when present, and reject records
+  without stable-identity capability;
 - per-language and per-project reuse compare the decoded v3 shard
   fingerprints with current fingerprints and require the corresponding shard
   file to exist.

package/docs/SECURITY_MODEL.md

@@ -76,20 +76,28 @@ Every command accepts:
 ```
 
 The opaque cursor binds the command, working directory, non-pagination
-arguments, next character offset, private output snapshot, and complete output
-hash. The first invocation streams the output to current-user temporary
-storage with private permissions while retaining only one page in memory.
-Continuations read that immutable snapshot instead of re-running a command
-whose timestamps or durations may change. Snapshots expire after one hour and
-are removed after the final page; an unavailable snapshot produces the exact
-page-one restart command.
-
-Continue until `page.complete` is `true`. Do not pipe output through `head`,
-`tail`, or a line-range `sed`; those programs discard data without creating a
-resumable position. Every incomplete JSON page repeats this obligation in
-`agentInstruction`; an incomplete page must not support a conclusion or
-completion claim. See [CLI JSON output](CLI_JSON_OUTPUT.md) and the
-[output-page schema](schemas/cli-output-page.schema.json).
+arguments, immutable page number and size, private output snapshot, and
+complete output hash. The first invocation records UTF-8 byte ranges and a
+hash for each page while retaining only one page in memory. A continuation
+reads and verifies only its own range instead of re-running the command or
+rescanning the complete output.
+
+One snapshot is limited to 32 million rendered characters, 64 MiB, and 32,768
+pages. The current user's snapshot pool is limited to 32 snapshots and 256 MiB
+under a process-identity-aware lock. Abandoned writers are reclaimed without
+removing a live writer; complete snapshots expire after one hour and are
+removed after their final page.
+
+Run commands normally without selecting a page size. If human output is
+oversized, the readable multiline page prints one `Continue exactly:` command;
+run it unchanged until the transport-complete marker. That marker proves every
+rendered character was retrieved; command coverage remains a separate claim.
+Explicit paged `--json`
+returns the versioned object envelope and must be followed until
+`page.complete` is `true`. Do not pipe output through `head`, `tail`, or a
+line-range `sed`; those programs discard data without creating a resumable
+position. See [CLI JSON output](CLI_JSON_OUTPUT.md) and the [output-page
+schema](schemas/cli-output-page.schema.json).
 
 ## Diff-gate process containment
 
@@ -105,6 +113,15 @@ parent terminates and reaps that child before releasing the lease. An operator
 may set `SCIP_QUERY_DIFF_GATE_TIMEOUT_MS` to a positive millisecond value; the
 runtime caps it at 10 minutes.
 
+The parent creates a unique, private progress path and one-run token while it
+owns the lease. The child visibility-atomically records the current gate phase
+and detector immediately before and after each detector. A timed-out parent
+accepts only the record carrying its token, reports the active detector or
+phase plus the last completed detector, and removes the record before releasing
+the lease. The progress record is diagnostic evidence, not authority: failure
+to write it cannot turn a passing gate into a failure, and a stale or malformed
+record cannot alter the gate result.
+
 Outcome reconciliation rechecks at most one historical comparison base per
 gate. Deferred bases remain open and the result reports their exact base and
 finding counts, so accumulated event history cannot silently multiply one

package/docs/TELEMETRY_RETENTION.md

@@ -58,10 +58,17 @@ mailbox-response, and release records use their own durable protocols.
 
 Lock timeout and ownership-changed release are typed failures at the shared
 helper boundary. The reindex-activity and affected-shadow production writers
-remain best effort: they catch telemetry failure so an observation cannot
-change the authoritative reindex result. Callers that invoke the shared helper
-directly can distinguish lock timeout, count repaired tail bytes, and count
-partial bytes ignored during reads.
+remain best effort: telemetry failure cannot change the authoritative reindex
+result. A reindex-activity writer returns either `recorded` or `failed` with a
+reason; reindex, foreground watch, and daemon watch surface that failure as a
+warning or watch-state error rather than silently losing the observation.
+
+A retained-set summary carries an activity-confidence state. `complete` means
+every selected non-empty record decoded; `partial` means a valid subset was
+used while exact invalid/skipped/read-error or incomplete-tail counts are
+reported; `unavailable` means no reliable summary could be formed. The summary
+also exposes records read and ignored partial-tail bytes, so consumers can
+distinguish zero activity from missing evidence.
 
 The regression suite forces:
 

package/docs/WATCH_REFRESH_REQUESTS.md

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

package/docs/WINDOWS_SIDECAR_RELEASE.md

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

package/docs/analyzer-inventory.md

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

package/docs/analyzer-validation-ledger.md

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