pi-lens 4.3.0 → 4.4.0

package/dist/clients/freshness-cadence.js

@@ -1,17 +0,0 @@
-/**
- * The shared re-check cadence for a cached "nothing here" verdict — the
- * bound both `file-utils.ts`'s nested `.gitignore`/`.pi-lens.json` matcher
- * (#2159/#2071) and `project-lens-config.ts`'s no-config discovery cache
- * (#2483 round 2) use so a negative result is neither re-statted on every
- * call nor cached for the life of the process.
- *
- * A declared leaf module, the same shape as `ledger-bounds.ts` /
- * `spawn-output-cap.ts`: it imports nothing from `clients/`, because
- * `file-utils.ts` already imports `project-lens-config.ts`, and the
- * `clients/` acyclic-imports rule (`no-client-cycles`,
- * `.dependency-cruiser.cjs`) would reject either of those two files
- * importing a constant that lived inside the other. A shared value neither
- * owns is the only way both stay on the same cadence without one importing
- * the other.
- */
-export const FRESHNESS_CADENCE_MS = 2_000;

package/dist/clients/freshness.js

@@ -1,38 +0,0 @@
-/**
- * Freshness kernel (#1739): ONE comparator and ONE verdict type for every
- * "was this file modified after my reference timestamp?" gate.
- *
- * The same staleness comparison was independently reimplemented in at least
- * six stores (advisory-provenance, blocker-freshness,
- * project-diagnostics/cache [#1711], widget-state ×3, lsp/workspace-
- * diagnostics-cache), and three of those copies carried the identical
- * mtime-tolerance defect fixed separately in #1710/#1711/#1664. This module
- * is the single implementation going forward; the registered-or-fail sweep
- * (`tests/clients/freshness-sweep.test.ts`) fails on new out-of-kernel
- * comparisons so the population cannot silently regrow.
- *
- * Deliberately NOT here: age-based checks (`Date.now() - mtime > TTL` — that
- * is expiry, not freshness against a reference event) and max-selection
- * comparisons (`mtime > best.mtimeMs`) — neither compares against a scan or
- * record timestamp, which is what this kernel's verdict means.
- */
-/** Shared drift tolerance: raised from 0 to 50ms after measured Windows mtime skew produced 42 false demotions in 50 runs (#1710 evidence). */
-export const MTIME_DRIFT_TOLERANCE_MS = 50;
-/**
- * Compare an observed mtime against a reference timestamp (the scan, record,
- * or touch instant whose validity depends on the file not having moved).
- *
- * `mtimeMs === undefined` means the caller had no readable mtime (stat
- * failed, file gone). The kernel does NOT choose a policy for that case -
- * callers differ legitimately (a diagnostics cache drops, a drift detector
- * skips) - so it reports `indeterminate` and the caller maps it.
- */
-export function freshnessFromMtime(input) {
-    const tolerance = input.toleranceMs ?? MTIME_DRIFT_TOLERANCE_MS;
-    if (input.mtimeMs === undefined) {
-        return { verdict: "indeterminate", reason: "no-mtime-evidence" };
-    }
-    return input.mtimeMs > input.referenceMs + tolerance
-        ? { verdict: "stale", reason: "modified-after-reference" }
-        : { verdict: "fresh" };
-}

package/dist/clients/generated-artifacts.js

@@ -1,394 +0,0 @@
-/**
- * Centralized generated/artifact detection.
- *
- * This module is intentionally lightweight and synchronous because it is used by
- * hot-path source collection and dispatch role detection. It combines cheap
- * path/name heuristics with optional header inspection for common generated-code
- * banners.
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { isWindowsPath } from "./path-utils.js";
-import { BoundedLruCache } from "./bounded-cache.js";
-const DEFAULT_HEADER_BYTES = 4096;
-const GENERATED_DIR_NAMES = new Set([
-    "generated",
-    "__generated__",
-    "codegen",
-    "__codegen__",
-    "generated-sources",
-    "generated_sources",
-    "dist",
-    "openapi-generated",
-    ".openapi-generator",
-]);
-const GENERATED_HEADER_PATTERNS = [
-    /@generated\b/i,
-    /@ts-nocheck\b/i,
-    /\bcode generated\b/i,
-    /\bdo not edit\b/i,
-    /\bautomatically generated\b/i,
-    /\bthis file was generated\b/i,
-    /\bgenerated by protoc\b/i,
-    /\bgenerated by graphql-code-generator\b/i,
-    /\bgenerated by openapi-generator\b/i,
-    /\bgenerated by swagger codegen\b/i,
-];
-// Package-manager lockfiles are generated, never hand-written source — and
-// often huge (a 10MB package-lock.json is unremarkable). Broadened enumeration
-// (#894) made the .json/.yaml ones visible to project-wide walks; filtering
-// them here (the generated-file authority) removes them from every collector
-// at once. Compared lowercased, like GENERATED_DIR_NAMES.
-const LOCKFILE_NAMES = new Set([
-    "package-lock.json",
-    "packages.lock.json",
-    "npm-shrinkwrap.json",
-    "pnpm-lock.yaml",
-    "yarn.lock",
-    "bun.lock",
-    "cargo.lock",
-    "composer.lock",
-    "gemfile.lock",
-    "poetry.lock",
-    "uv.lock",
-    "go.sum",
-]);
-const GENERATED_FILE_PATTERNS = [
-    /(^|[._-])generated([._-]|$)/i,
-    /(^|[._-])gen([._-])/i,
-    /_generated\.(go|rs|py|rb|java|kt|ts|tsx|js|jsx|mjs|cjs)$/i,
-    /_gen\.(go|rs|py|rb|java|kt|ts|tsx|js|jsx|mjs|cjs)$/i,
-    /\.pb\.(go|ts|tsx|js|jsx|mjs|cjs)$/i,
-    /_pb2(_grpc)?\.py$/i,
-    /\.sql\.(go|ts|js)$/i,
-    /_sqlc\.go$/i,
-    /\.g\.([jt]sx?|mjs|cjs|rs|go)$/i,
-];
-// #1107 phase 2 review (P2, maintainer decision): minified/bundle/chunk
-// output is intentionally NOT eligible for the content-probe escape hatch
-// below and lives in the STRONG tier instead, alongside lockfiles — the
-// escape hatch's premises fail structurally for this class:
-//  - Hand-written-with-this-name probability is ~0 (nobody names a source
-//    file `app.min.js`/`vendor.bundle.js` by hand).
-//  - The header-probe leg is dead for it: minifiers strip comments/banners
-//    by design, so a real minified bundle essentially never carries a
-//    `GENERATED_HEADER_PATTERNS` match — the probe can never confirm it, so
-//    under the WEAK-tier escape hatch this class would ALWAYS be "kept" via
-//    the no-evidence branch, not "kept sometimes." That inverts the
-//    heuristic from "usually right, occasionally rescued" to "never right."
-//  - The sibling-probe leg is also dead for it: `findSourceSibling` looks
-//    for a `.ts`/`.tsx`/etc. twin at the SAME stem (`app.min.ts` next to
-//    `app.min.js`), which is never how minified bundles are produced — the
-//    real source twin is `app.ts`/`app.js` at a DIFFERENT stem, which the
-//    sibling probe does not check. So the "does a hand-written source twin
-//    exist" question this class actually needs answered is structurally
-//    unreachable, not merely unresolved.
-// Both dead legs mean this class would be a permanent override — never
-// re-confirmed by either evidence check — so it is excluded from the WEAK
-// tier entirely and always skipped, like a lockfile.
-const MINIFIED_BUNDLE_FILE_PATTERNS = [
-    /\.min\.(js|mjs|cjs|css)$/i,
-    /\.(bundle|chunk)\.(js|mjs|cjs|css)$/i,
-];
-const DECLARATION_FILE_PATTERNS = [/\.d\.ts$/i, /\.d\.mts$/i, /\.d\.cts$/i];
-function pathSegments(filePath) {
-    return path
-        .normalize(filePath)
-        .split(/[\\/]+/)
-        .filter(Boolean);
-}
-/**
- * Shape-aware basename: a WINDOWS-SHAPED path (drive letter or UNC prefix,
- * per `isWindowsPath`) is parsed with `path.win32.basename` regardless of the
- * running OS, mirroring the `detectFileRole` fix in `file-role.ts` (refs
- * #1152, #1150, #1161 — defect shape 2: a host-default `path` fn inside a
- * shape-committed branch follows the *host* OS, so on Linux CI a `C:\...`
- * path has no POSIX separator and the module-default `basename` returns the
- * whole string unchanged, missing exact-name lookups like `LOCKFILE_NAMES`).
- * Native same-OS paths (POSIX on Linux, win32 on Windows) are unaffected —
- * on win32 this is a no-op since `win32.basename` already equals the module
- * default there.
- */
-function basenameForShape(filePath) {
-    return isWindowsPath(filePath)
-        ? path.win32.basename(filePath)
-        : path.basename(filePath);
-}
-export function isGeneratedArtifactDirectoryName(dirName) {
-    return GENERATED_DIR_NAMES.has(dirName.trim().toLowerCase());
-}
-export function isDeclarationFile(filePath) {
-    const base = basenameForShape(filePath).toLowerCase();
-    return DECLARATION_FILE_PATTERNS.some((pattern) => pattern.test(base));
-}
-/**
- * STRONG evidence a path is generated/artifact output: it lives under a
- * directory segment that itself looks generated (`generated/`, `codegen/`,
- * …), its basename is a known package-manager lockfile, or it matches a
- * minified/bundle/chunk output pattern (see
- * {@link MINIFIED_BUNDLE_FILE_PATTERNS}'s doc for why that class is STRONG,
- * not WEAK). All three are treated as conclusive — no content-probe escape
- * hatch (#1107 phase 2) applies to any of them. A lockfile is never
- * hand-written; a generated-dir SEGMENT match here only fires for callers
- * that check a single path without having walked (directory-level pruning
- * already removes the walk-time case in `shouldRecurseIntoDir`, so this
- * branch is effectively a belt-and-braces check for non-walk callers like
- * `file-role.ts` and `project-scan-policy.ts`).
- */
-function hasStrongGeneratedArtifactPath(filePath) {
-    const segments = pathSegments(filePath);
-    const dirSegments = segments.slice(0, -1);
-    if (dirSegments.some((segment) => isGeneratedArtifactDirectoryName(segment))) {
-        return true;
-    }
-    const base = basenameForShape(filePath);
-    if (LOCKFILE_NAMES.has(base.toLowerCase()))
-        return true;
-    return MINIFIED_BUNDLE_FILE_PATTERNS.some((pattern) => pattern.test(base));
-}
-/**
- * WEAK evidence: the basename alone matches a generated-file NAME pattern
- * (e.g. `gen.ts`, `foo_generated.go`, `user.pb.go`). Unlike the strong path
- * check above, a name-only match is not conclusive — a hand-written file can
- * innocently contain "gen" in its name. #1107 phase 2's content-probe escape
- * hatch (see `classifyGeneratedOrArtifactDetailed`) requires corroborating
- * evidence (a source sibling, checked upstream by walk-driven callers, or a
- * generated-code header) before treating a WEAK-only match as an artifact.
- * Minified/bundle/chunk output (`bar.min.js`, `vendor.bundle.js`) is
- * deliberately NOT in this WEAK set — see
- * {@link MINIFIED_BUNDLE_FILE_PATTERNS}'s doc for why that class is STRONG
- * instead (the escape hatch's evidence checks are structurally dead for it).
- */
-function hasWeakGeneratedFileNamePattern(filePath) {
-    const base = basenameForShape(filePath);
-    return GENERATED_FILE_PATTERNS.some((pattern) => pattern.test(base));
-}
-function hasGeneratedArtifactContent(content) {
-    const header = content.slice(0, DEFAULT_HEADER_BYTES);
-    return GENERATED_HEADER_PATTERNS.some((pattern) => pattern.test(header));
-}
-/**
- * Content-shape classifier for machine-emitted text (refs #2346).
- *
- * A saved/scraped page, a minified bundle, or an embedded data blob is one
- * giant line or a handful, so mean non-empty line length on already-loaded
- * content is a language-agnostic generated signature. Extensions covered by
- * name patterns can never cover it (`.html` has no `.min.`-style convention),
- * which is the exact gap #2346 hit: a 269 KB scraped page on 38 lines (mean
- * ~7084/line) drew the full auxiliary scanner stack.
- *
- * The threshold is derived from measurement ON THE SHIPPED STATISTIC (the
- * 4096-byte header/prefix mean, not full-content means — the two differ by
- * 3-7x on long-paragraph prose). Measured 2026-08-28 across all 3,331 text
- * files in this repo: the maximum hand-authored prefix mean is 453.2
- * (`docs/analysisall.md`, unwrapped prose paragraphs); the widest
- * hand-authored one-line shape observed anywhere probed is a ~2048-char
- * barrel re-export. The threshold of 2500 sits ~5.5x above the repo's worst
- * prose file and above every observed hand-authored shape, while the #2346
- * evidence file (269 KB / 38 lines) remains far above it. Direction of
- * error is deliberate per #1107: a borderline machine-emitted file that
- * slips through (false KEEP) costs noise once; a hand-authored file
- * silently classified generated (false DROP) vanishes from scans with no
- * signal. Both constants are exported so the tuning claim is checkable and
- * the regression tests pin the margin probes on both sides.
- *
- * Prefix-path quantization: on the 4096-byte header/prefix paths the
- * achievable means are quantized (~4096 for a one-line prefix, ~2048 for
- * two lines), so any threshold in (2048, 4096] behaves as "is the first
- * line longer than 4096 bytes". A machine-emitted file with 2500-4000-char
- * lines is missed on the prefix path even though its full content would
- * classify — the deliberate false-KEEP direction, not a continuous 5.5x
- * margin there. The full-content path (dispatch) has no such quantization.
- *
- * Degenerate cases are guarded: content below the minimum byte length never
- * classifies generated on line shape alone (a 500-byte single-line config
- * file is not machine-emitted evidence), and an empty or whitespace-only
- * file yields a zero mean and stays source.
- */
-const MACHINE_EMITTED_LINE_SHAPE_MIN_CONTENT = 2048;
-export const MACHINE_EMITTED_LINE_SHAPE_MEAN_THRESHOLD = 2500;
-export function classifyMachineEmittedLineShape(content) {
-    const contentLength = content.length;
-    if (contentLength < MACHINE_EMITTED_LINE_SHAPE_MIN_CONTENT) {
-        return { generated: false, meanLineLength: 0 };
-    }
-    // Single O(contentLength) pass. Deliberately no `split(/\r?\n/)`: a
-    // minified blob's single line can be megabytes, and splitting allocates a
-    // copy of the whole content. `\r` contributes nothing to line length so a
-    // CRLF line is measured by its display width.
-    let nonEmptyLineTotal = 0;
-    let nonEmptyLineCount = 0;
-    let currentLineLength = 0;
-    for (let i = 0; i < contentLength; i++) {
-        const code = content.charCodeAt(i);
-        if (code === 10 /* \n */) {
-            if (currentLineLength > 0) {
-                nonEmptyLineTotal += currentLineLength;
-                nonEmptyLineCount += 1;
-            }
-            currentLineLength = 0;
-        }
-        else if (code !== 13 /* \r */) {
-            currentLineLength += 1;
-        }
-    }
-    if (currentLineLength > 0) {
-        nonEmptyLineTotal += currentLineLength;
-        nonEmptyLineCount += 1;
-    }
-    if (nonEmptyLineCount === 0)
-        return { generated: false, meanLineLength: 0 };
-    const meanLineLength = nonEmptyLineTotal / nonEmptyLineCount;
-    return {
-        generated: meanLineLength > MACHINE_EMITTED_LINE_SHAPE_MEAN_THRESHOLD,
-        meanLineLength,
-    };
-}
-// Memoize the header analysis (banner + line shape) per (path, mtimeMs, size,
-// maxBytes). The 4 KB header read (openSync + readSync + closeSync) is ~70% of
-// the per-file cost in `collectSourceFiles`, and the same files are re-scanned
-// by multiple background scanners (todo, project-diagnostics, language-profile)
-// every session/turn. Keying on mtime+size makes the memo self-invalidating:
-// an edited file misses the cache and is re-read. A single stat replaces the
-// open/read/close on a hit. Bounded to avoid unbounded growth on giant repos.
-const HEADER_VERDICT_MEMO_CAP = 50_000;
-const headerAnalysisMemo = new BoundedLruCache(HEADER_VERDICT_MEMO_CAP);
-/** Test-only: drop the header-analysis memo so fixtures don't leak across cases. */
-export function _resetGeneratedArtifactCaches() {
-    headerAnalysisMemo.clear();
-}
-function readFileHeader(filePath, maxBytes = DEFAULT_HEADER_BYTES) {
-    let fd;
-    try {
-        fd = fs.openSync(filePath, "r");
-        const buffer = Buffer.alloc(Math.max(0, maxBytes));
-        const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
-        return buffer.toString("utf8", 0, bytesRead);
-    }
-    catch {
-        return undefined;
-    }
-    finally {
-        if (fd !== undefined) {
-            try {
-                fs.closeSync(fd);
-            }
-            catch {
-                /* ignore close errors */
-            }
-        }
-    }
-}
-function analyzeFileHeader(filePath, maxBytes) {
-    let key;
-    try {
-        const st = fs.statSync(filePath);
-        key = `${st.mtimeMs}:${st.size}:${maxBytes}:${filePath}`;
-    }
-    catch {
-        return undefined;
-    }
-    const cached = headerAnalysisMemo.get(key);
-    if (cached !== undefined)
-        return cached;
-    const header = readFileHeader(filePath, maxBytes);
-    // A header that cannot be read classifies as clean (no banner, no shape
-    // signal) and is memoized as such, mirroring the pre-#2346 fallback.
-    const analysis = header === undefined
-        ? { banner: false, shape: { generated: false, meanLineLength: 0 } }
-        : {
-            banner: hasGeneratedArtifactContent(header),
-            shape: classifyMachineEmittedLineShape(header),
-        };
-    headerAnalysisMemo.set(key, analysis);
-    return analysis;
-}
-/**
- * The full verdict (+ evidence tier) behind {@link isGeneratedOrArtifact}'s
- * boolean, exposing the #1107 phase 2 content-probe escape hatch: a WEAK
- * name-only match (see {@link hasWeakGeneratedFileNamePattern}) is no longer
- * skipped on the name alone — it additionally requires a generated-code
- * header in the first few KB (`hasGeneratedArtifactContent`/
- * `fileHeaderLooksGenerated`) before being treated as an artifact. Evidence
- * check order is cheapest-first: STRONG path (dir segment/lockfile/minified-
- * bundle, no filesystem probe) → declaration opt-in → content/header probe,
- * so the (often already-open) file read only happens for the WEAK-match case
- * that actually needs it.
- *
- * Evidence class (a) from the issue — "does a higher-precedence hand-written
- * source SIBLING exist?" — is deliberately NOT re-implemented here: it is
- * `source-filter.ts`'s `findSourceSibling`/`isBuildArtifact` (this module has
- * no filesystem-sibling-probe cache, and `source-filter.ts` already imports
- * this module, so adding a reverse import would be circular). Both call
- * sites that matter (`classifyEntry`, `filterSourceFiles` in
- * `source-filter.ts`) already probe for a sibling BEFORE reaching this
- * function and short-circuit on a hit, so by the time this function runs for
- * those callers evidence (a) has already come back negative. Non-walk
- * callers with no upstream sibling probe (`file-role.ts`'s content-based
- * check) evaluate evidence (b) only — a documented, narrower guarantee than the
- * walk path's.
- *
- * Tradeoff (documented per the issue): when NEITHER piece of evidence
- * confirms a WEAK name match, the file is KEPT. This can rescue a real
- * headerless generated file with no source twin into a walk/graph/index that
- * previously silently dropped it — accepted per #1107: a false-KEEP (an
- * agent sees one extra file it must itself judge) is strictly less harmful
- * than a silent false-DROP (a real file invisibly never analyzed at all).
- * This tradeoff deliberately does NOT extend to minified/bundle/chunk output
- * — see {@link MINIFIED_BUNDLE_FILE_PATTERNS}'s doc for why that class is
- * STRONG (always skipped, no escape hatch) rather than WEAK.
- */
-export function classifyGeneratedOrArtifactDetailed(filePath, options = {}) {
-    if (hasStrongGeneratedArtifactPath(filePath)) {
-        return { verdict: "generated", evidence: "strong" };
-    }
-    if (options.includeDeclarations && isDeclarationFile(filePath)) {
-        return { verdict: "generated", evidence: "strong" };
-    }
-    const weakNameMatch = hasWeakGeneratedFileNamePattern(filePath);
-    if (options.content !== undefined) {
-        if (hasGeneratedArtifactContent(options.content)) {
-            return { verdict: "generated", evidence: "content" };
-        }
-        const shape = classifyMachineEmittedLineShape(options.content);
-        if (shape.generated) {
-            return {
-                verdict: "generated",
-                evidence: "line-shape",
-                lineShapeMean: shape.meanLineLength,
-            };
-        }
-        return { verdict: weakNameMatch ? "override" : "clean" };
-    }
-    if (options.readContentHeader) {
-        const analysis = analyzeFileHeader(filePath, options.maxHeaderBytes ?? DEFAULT_HEADER_BYTES);
-        if (analysis?.banner) {
-            return { verdict: "generated", evidence: "content" };
-        }
-        if (analysis?.shape.generated) {
-            return {
-                verdict: "generated",
-                evidence: "line-shape",
-                lineShapeMean: analysis.shape.meanLineLength,
-            };
-        }
-        return { verdict: weakNameMatch ? "override" : "clean" };
-    }
-    // No content/header probe was supplied or enabled: there is no cheap way
-    // to evaluate evidence (b) here, so a WEAK name match falls back to the
-    // pre-#1107-phase-2 behavior (trust the name, skip it) rather than
-    // silently activating the escape hatch for callers that opted out of the
-    // probe for performance. The escape hatch only activates when a header
-    // probe actually ran and did not confirm. Evidence "name-only" — the one
-    // residual at-risk bucket, see {@link GeneratedArtifactEvidence}.
-    return weakNameMatch
-        ? { verdict: "generated", evidence: "name-only" }
-        : { verdict: "clean" };
-}
-/** Verdict-only convenience wrapper over {@link classifyGeneratedOrArtifactDetailed}. */
-function classifyGeneratedOrArtifact(filePath, options = {}) {
-    return classifyGeneratedOrArtifactDetailed(filePath, options).verdict;
-}
-export function isGeneratedOrArtifact(filePath, options = {}) {
-    return classifyGeneratedOrArtifact(filePath, options) === "generated";
-}

package/dist/clients/generation-guard.js

@@ -1,215 +0,0 @@
-/**
- * Capture-generation-before-await, check-after — as one primitive (#1754).
- *
- * The shape: a write that follows an `await` must prove the world it captured
- * still exists. A session reset, a cache refresh, or a newer request for the
- * same key can land while the write's producer is in flight, and the late
- * write then publishes an answer the caller no longer wants — or, in the
- * eviction direction, deletes an entry a SUCCESSOR already installed.
- *
- * This module was extracted after the pattern was hand-rolled four times and
- * its absence was a review finding twice:
- *
- * - `clients/dispatch/runners/utils/runner-helpers.ts` held the guarded form
- *   at one site and the unguarded form at another IN THE SAME FILE; #1674's
- *   F5 round copied the guard by hand to three more write sites.
- * - `clients/lsp/client.ts`'s per-(path, identifier) pull sequences (#1682),
- *   whose first guard was vacuous until a review round bound it.
- * - `clients/lsp/workspace-diagnostics-cache.ts`'s per-cwd epochs (#1669),
- *   where the epoch guarded `persist()` but not `lookup()`.
- * - `clients/review-graph/builder.ts`'s workspace-cache epoch, the shape the
- *   one above was modelled on.
- *
- * Two things every one of those needed and at least one got wrong:
- *
- * 1. The check must run at WRITE time, not only at capture time.
- * 2. The stale branch must be OBSERVABLE. A silently dropped write looks
- *    exactly like a write that never happened, which is why the vacuous
- *    guards survived review. `guardedWrite` emits one bounded degradation
- *    record per (source, subject) with the count of repeats, so a dogfood
- *    session can tell "the guard is working" from "the guard never fires".
- *
- * ## Scope and lifetime
- *
- * A `GenerationSource` is a plain counter owned by the RESETTING SEAM — the
- * function that already clears the state the generation protects. This module
- * holds no session state of its own: sources live in the modules that create
- * them, and their reset policy is that module's declaration in
- * `tests/support/session-state-registry.ts`. The only module-level state here
- * is the name registry below, which exists so the #1754 sweep can ask "which
- * stores declare a generation" instead of guessing from identifier names.
- *
- * ## Cost
- *
- * `isCurrent()` on an unkeyed source is a field read and a compare. On a
- * keyed map it is a compare while nothing has been invalidated, and a
- * normalize plus one `Map.get` once something has. The hand-rolled form it
- * replaces normalized on EVERY call, and this repo's normalizer runs
- * `realpathSync.native` on Windows and, since #3098, on POSIX as well, so an
- * uninterrupted sweep pays that syscall once rather than once per file. See
- * `GenerationMapOptions.normalizeKey` for the correctness reason the slow
- * path exists at all.
- */
-import { BoundedFifoMap } from "./bounded-cache.js";
-import { incrementDegradationCount } from "./degradation-ledger.js";
-/**
- * Names of every generation-carrying store created through this module.
- *
- * Registration is by CONSTRUCTION: you cannot make a `GenerationSource`
- * without appearing here. `tests/clients/generation-guard-sweep.test.ts`
- * reads this to enforce the ratchet — a file that hand-rolls the pattern
- * instead of declaring it here must carry an explicit exemption reason.
- *
- * Process-lifetime and bounded: names are compile-time literals from module
- * initialization, so this cannot grow with workload.
- */
-const declaredSources = new Set();
-const MAX_DECLARED_SOURCES = 128;
-function declare(name) {
-    if (!name.trim()) {
-        throw new Error("generation source needs a non-empty name");
-    }
-    if (declaredSources.size < MAX_DECLARED_SOURCES)
-        declaredSources.add(name);
-    return name;
-}
-/** Every generation-carrying store name declared this process. */
-export function listDeclaredGenerationSources() {
-    return [...declaredSources].sort((a, b) => a.localeCompare(b));
-}
-function recordStaleWrite(sourceName, subject, captured, observed) {
-    incrementDegradationCount({
-        kind: "generation-guard-stale-write",
-        subject: `${sourceName}:${subject}`,
-        reason: `write dropped: captured generation ${captured}, current ${observed}`,
-    });
-}
-function makeHandle(sourceName, generation, read) {
-    return {
-        generation,
-        isCurrent() {
-            return read() === generation;
-        },
-        guardedWrite(subject, write) {
-            const observed = read();
-            if (observed !== generation) {
-                recordStaleWrite(sourceName, subject, generation, observed);
-                return undefined;
-            }
-            return write();
-        },
-    };
-}
-/**
- * Create a counter for a store invalidated as a whole.
- *
- * `name` appears in the stale-write ledger subject and in the sweep's
- * declaration list, so it must name the STORE, not the module.
- */
-export function createGenerationSource(name) {
-    declare(name);
-    let generation = 0;
-    const read = () => generation;
-    return {
-        name,
-        current: read,
-        bump() {
-            generation += 1;
-            return generation;
-        },
-        capture() {
-            return makeHandle(name, generation, read);
-        },
-    };
-}
-const DEFAULT_MAX_KEYS = 512;
-/**
- * Create a per-key family of counters.
- *
- * Use this when invalidation is scoped: a cache refresh for ONE cwd must not
- * drop an in-flight write for another, and a newer pull request for one
- * (path, source) pair must not invalidate a different pair's.
- */
-export function createGenerationMap(name, options = {}) {
-    declare(name);
-    const normalize = options.normalizeKey ?? ((key) => key);
-    const maxKeys = Math.max(1, options.maxKeys ?? DEFAULT_MAX_KEYS);
-    // Insertion-ordered: the oldest key is evicted first. Re-stamping a key
-    // refreshes its position so a hot cwd is not evicted by a burst of
-    // one-shot ones.
-    const stamps = new BoundedFifoMap(maxKeys);
-    // ONE ticket counter for the whole map. See GenerationMap's doc comment:
-    // per-key counters starting at 0 make eviction and forget() fail OPEN.
-    // 0 is reserved for "this key holds no stamp" and is never issued.
-    let nextTicket = 0;
-    // Counts every mutation that can change what a key's stamp reads: a bump,
-    // a forget, an eviction. A handle records this at capture and re-derives
-    // its key only when it has moved. See normalizeKey's doc comment.
-    let invalidations = 0;
-    const read = (key) => stamps.get(key) ?? 0;
-    function issue(key) {
-        nextTicket += 1;
-        stamps.delete(key);
-        const evicted = stamps.set(key, nextTicket);
-        invalidations += evicted.length;
-        return nextTicket;
-    }
-    return {
-        name,
-        current(key) {
-            return read(normalize(key));
-        },
-        bump(key) {
-            invalidations += 1;
-            return issue(normalize(key));
-        },
-        capture(key) {
-            const normalized = normalize(key);
-            // A first-use capture ISSUES a stamp rather than reading 0. A handle
-            // holding 0 would be indistinguishable from one whose key was later
-            // forgotten or evicted, which is the fail-open hole this closes.
-            const stamp = read(normalized) || issue(normalized);
-            const capturedInvalidations = invalidations;
-            return makeHandle(`${name}[${normalized}]`, stamp, () => {
-                // Fast path: nothing has been invalidated since capture, so no key
-                // can have changed stamps and the normalizer need not run again.
-                if (invalidations === capturedInvalidations)
-                    return stamp;
-                // Something moved. Re-derive the key from the ORIGINAL string: a
-                // normalizer that consults the filesystem can resolve the same
-                // input to a different key once the path exists, and a stamp read
-                // under the stale spelling would falsely read current.
-                return read(normalize(key));
-            });
-        },
-        forget(key) {
-            invalidations += 1;
-            stamps.delete(normalize(key));
-        },
-        clear() {
-            invalidations += 1;
-            stamps.clear();
-        },
-        size() {
-            return stamps.size;
-        },
-    };
-}
-/**
- * Capture the generation, run `fn`, and hand it the handle.
- *
- * Sugar for the common `const handle = source.capture(); ... await ...;
- * handle.guardedWrite(...)` sequence. Use `capture()` directly when the
- * handle must outlive the function that made it — an eviction guard in a
- * `.finally()` is the usual case, and it is what both #1754 migrations do.
- *
- * This ships ahead of its first production caller. Both migrated sites need
- * the handle to outlive its producer, so neither uses this form; it exists
- * because the issue specifies it and because the sites still to migrate
- * (`runtime-coordinator.ts`, `runtime-turn.ts`) write inside the async
- * function that captured. Said plainly rather than left for a reader to
- * discover by grep.
- */
-export async function withGeneration(source, fn) {
-    return fn(source.capture());
-}