pi-lens 3.8.73 → 4.0.0

package/dist/clients/project-lens-config.js

@@ -57,14 +57,34 @@
  * patterns apply to files inside that package, in addition to (and with
  * higher precedence than) the root config's `ignore` patterns.
  */
+import { logExtension } from "./extension-log.js";
+import { notifyUserDegradation } from "./user-notify.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { parseEnabledShape } from "./config-enabled-shape.js";
 import { toPositiveFinite } from "./env-utils.js";
+import { assignFlagConfigSection, flagConfigSectionKeys, GLOBAL_NON_FLAG_CONFIG_SECTIONS, LENS_FLAGS, PROJECT_FOREIGN_CONFIG_NAMESPACES, PROJECT_SCOPED_LENS_FLAGS, readFlagConfigValue, } from "./lens-flag-registry.js";
 import { isAtOrAboveHomeDir, walkUpDirs } from "./path-utils.js";
 import { findPiLensConfigMarkerInDir } from "./workspace-topology.js";
 const PROJECT_CONFIG_BASENAMES = [".pi-lens.json", "pi-lens.json"];
+/**
+ * The project loader's OWN recognized top-level keys — pi-lens-native sections,
+ * whether parsed here into typed fields (`ignore`, `rules`, `maxProjectFiles`,
+ * `reviewGraph`) or read off `PiLensProjectConfig.raw` by another pi-lens
+ * consumer (`trivy`, read via `.raw` in `trivy-client.ts`). The project-scoped
+ * flag sections (`format`, `autofix`, `actionableWarnings`) are NOT listed here;
+ * they are derived from `PROJECT_SCOPED_LENS_FLAGS` so the registry stays the
+ * single source of truth (#883). Foreign (non-pi-lens) namespaces the shared
+ * file also carries live in `PROJECT_FOREIGN_CONFIG_NAMESPACES` beside the
+ * registry.
+ */
+const PROJECT_OWN_CONFIG_KEYS = [
+    "ignore",
+    "rules",
+    "maxProjectFiles",
+    "reviewGraph",
+    "trivy",
+];
 /** Clamp bounds for `reviewGraph.maxFiles` — see the field's doc comment above. */
 const REVIEW_GRAPH_MAX_FILES_MIN = 100;
 const REVIEW_GRAPH_MAX_FILES_MAX = 20_000;
@@ -89,11 +109,17 @@ export function loadPiLensProjectConfig(startDir, preloadedInfo = findPiLensProj
     if (!configInfo)
         return EMPTY_PROJECT_CONFIG;
     const cached = configCache.get(configInfo.path);
-    if (cached && cached.mtimeMs === configInfo.mtimeMs) {
+    if (cached &&
+        cached.mtimeMs === configInfo.mtimeMs &&
+        cached.size === configInfo.size) {
         return cached.config;
     }
     const config = parseConfigFile(configInfo.path);
-    configCache.set(configInfo.path, { mtimeMs: configInfo.mtimeMs, config });
+    configCache.set(configInfo.path, {
+        mtimeMs: configInfo.mtimeMs,
+        size: configInfo.size,
+        config,
+    });
     return config;
 }
 /** For tests + callers that need to force a re-read (e.g. config-watcher hooks). */
@@ -119,14 +145,19 @@ export function findPiLensConfigInDir(dir) {
     const marker = findPiLensConfigMarkerInDir(dir);
     if (!marker)
         return undefined;
-    return { path: marker.path, dir: marker.dir, mtimeMs: marker.mtimeMs };
+    return {
+        path: marker.path,
+        dir: marker.dir,
+        mtimeMs: marker.mtimeMs,
+        size: marker.size,
+    };
 }
 /**
  * Find the closest config, between an edited file and the project root, that
  * explicitly defines one mutation flag. The walk uses the shared primitive
  * and refuses to inspect HOME or any ancestor of HOME.
  */
-export function findNestedProjectMutationValue(name, editedFilePath, projectRoot, homeDir = os.homedir()) {
+export function findNestedProjectMutationValue(spec, editedFilePath, projectRoot, homeDir = os.homedir()) {
     const root = path.resolve(projectRoot);
     const start = path.dirname(path.resolve(editedFilePath));
     for (const dir of walkUpDirs(start)) {
@@ -136,11 +167,7 @@ export function findNestedProjectMutationValue(name, editedFilePath, projectRoot
         if (rel.startsWith("..") || path.isAbsolute(rel))
             break;
         const config = loadPiLensConfigInDir(dir);
-        const enabled = name === "no-autoformat"
-            ? config.format?.enabled
-            : name === "no-autofix"
-                ? config.autofix?.enabled
-                : config.actionableWarnings?.autoFix?.enabled;
+        const enabled = readFlagConfigValue(config, spec.configKey);
         if (enabled !== undefined)
             return { value: enabled, dir };
         if (dir === root)
@@ -160,11 +187,11 @@ export function loadPiLensConfigInDir(dir) {
     if (!info)
         return EMPTY_PROJECT_CONFIG;
     const cached = configCache.get(info.path);
-    if (cached && cached.mtimeMs === info.mtimeMs) {
+    if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size) {
         return cached.config;
     }
     const config = parseConfigFile(info.path);
-    configCache.set(info.path, { mtimeMs: info.mtimeMs, config });
+    configCache.set(info.path, { mtimeMs: info.mtimeMs, size: info.size, config });
     return config;
 }
 export function findPiLensProjectConfig(startDir) {
@@ -175,7 +202,7 @@ export function findPiLensProjectConfig(startDir) {
             return undefined;
         const stat = safeFileStat(cached.info.path);
         if (stat?.isFile())
-            return { ...cached.info, mtimeMs: stat.mtimeMs };
+            return { ...cached.info, mtimeMs: stat.mtimeMs, size: stat.size };
     }
     const discovered = discoverPiLensProjectConfig(cacheKey);
     discoveryCache.set(cacheKey, discovered);
@@ -209,7 +236,7 @@ function discoverPiLensProjectConfig(startDir) {
             const stat = safeFileStat(candidate);
             if (stat?.isFile()) {
                 return {
-                    info: { path: candidate, dir, mtimeMs: stat.mtimeMs },
+                    info: { path: candidate, dir, mtimeMs: stat.mtimeMs, size: stat.size },
                     dirMtimes,
                 };
             }
@@ -222,10 +249,41 @@ function warnInvalidConfigOnce(configPath, reason) {
     if (warnedInvalidConfigs.has(key))
         return;
     warnedInvalidConfigs.add(key);
-    console.error(`[pi-lens] ignoring invalid project config ${configPath}: ${reason}`);
+    const message = `ignoring invalid project config ${configPath}: ${reason}`;
+    logExtension({
+        subsystem: "project-lens-config",
+        level: "warn",
+        message,
+        metadata: { configPath, reason },
+    });
+    // HUMAN-audience too: the user's own `.pi-lens.json` is being ignored.
+    notifyUserDegradation(`pi-lens: ${message}`);
 }
-function parseEnabledConfig(configPath, fieldPath, value) {
-    return parseEnabledShape(value, fieldPath, (reason) => warnInvalidConfigOnce(configPath, reason));
+function parseRulePolicyList(configPath, ruleId, key, value) {
+    if (!Array.isArray(value)) {
+        warnInvalidConfigOnce(configPath, `rules.${ruleId}.${key} must be an array of strings`);
+        return { list: [], invalid: true };
+    }
+    const list = [];
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            continue;
+        const trimmed = entry.trim();
+        if (trimmed.length > 0)
+            list.push(trimmed);
+    }
+    if (list.length === 0) {
+        // #1087: an explicitly empty array (`"disable": []`) is a well-formed
+        // no-op, not an error — don't warn. Only warn when the array HAD entries
+        // but none were usable strings (all blank / non-string), which is a real
+        // authoring mistake that must not fail silently.
+        if (value.length > 0) {
+            warnInvalidConfigOnce(configPath, `rules.${ruleId}.${key} must contain at least one non-empty string`);
+            return { list: [], invalid: true };
+        }
+        return { list: [], invalid: false };
+    }
+    return { list, invalid: false };
 }
 function parseConfigFile(configPath) {
     let raw;
@@ -245,36 +303,56 @@ function parseConfigFile(configPath) {
     const ignore = Array.isArray(obj.ignore)
         ? obj.ignore.filter((p) => typeof p === "string")
         : [];
-    const format = parseEnabledConfig(configPath, "format", obj.format);
-    const autofix = parseEnabledConfig(configPath, "autofix", obj.autofix);
-    const actionableWarningsRaw = obj.actionableWarnings &&
-        typeof obj.actionableWarnings === "object" &&
-        !Array.isArray(obj.actionableWarnings)
-        ? obj.actionableWarnings
-        : undefined;
-    if (obj.actionableWarnings !== undefined && !actionableWarningsRaw) {
-        warnInvalidConfigOnce(configPath, "actionableWarnings must be an object");
+    const mutations = {};
+    for (const spec of PROJECT_SCOPED_LENS_FLAGS) {
+        assignFlagConfigSection(obj, mutations, spec.configKey, (reason) => warnInvalidConfigOnce(configPath, reason));
     }
-    const actionableWarningsAutoFix = parseEnabledConfig(configPath, "actionableWarnings.autoFix", actionableWarningsRaw?.autoFix);
-    const actionableWarnings = actionableWarningsRaw
-        ? { autoFix: actionableWarningsAutoFix }
-        : undefined;
     const rules = {};
     if (obj.rules && typeof obj.rules === "object" && !Array.isArray(obj.rules)) {
         const rawRules = obj.rules;
         for (const [ruleId, ruleCfg] of Object.entries(rawRules)) {
+            // #444's own example writes the lists directly under `rules` (`rules.
+            // disable`), which lands here as an array and would otherwise be
+            // dropped without a word — the one shape a user is most likely to try.
             if (!ruleCfg || typeof ruleCfg !== "object" || Array.isArray(ruleCfg)) {
+                warnInvalidConfigOnce(configPath, `rules.${ruleId} must be an object with threshold, disable, or select; ignored`);
                 continue;
             }
             const r = ruleCfg;
+            const entry = {};
             if (typeof r.threshold === "number" &&
                 Number.isFinite(r.threshold) &&
                 r.threshold > 0) {
-                rules[ruleId] = { threshold: r.threshold };
+                entry.threshold = r.threshold;
             }
             else if ("threshold" in r) {
                 warnInvalidConfigOnce(configPath, `rules.${ruleId}.threshold must be a positive finite number`);
             }
+            if ("disable" in r) {
+                const parsed = parseRulePolicyList(configPath, ruleId, "disable", r.disable);
+                // #1087: an explicitly empty list is valid-but-empty (no warning);
+                // don't store a pointless no-op entry for it.
+                if (!parsed.invalid && parsed.list.length > 0)
+                    entry.disable = parsed.list;
+            }
+            if ("select" in r) {
+                const parsed = parseRulePolicyList(configPath, ruleId, "select", r.select);
+                if (!parsed.invalid && parsed.list.length > 0)
+                    entry.select = parsed.list;
+            }
+            // Honor both threshold-only and policy-only entries; only drop if
+            // the entry had no recognized fields at all (e.g. { unrelated: true }).
+            // A recognized-but-malformed field already warned above, so only warn
+            // here when nothing recognized was spelled at all — #444 proposed
+            // `only` rather than `select`, and that typo must not fail silent.
+            if (entry.threshold !== undefined || entry.disable || entry.select) {
+                rules[ruleId] = entry;
+            }
+            else if (!("threshold" in r) &&
+                !("disable" in r) &&
+                !("select" in r)) {
+                warnInvalidConfigOnce(configPath, `rules.${ruleId} has no recognized setting (threshold, disable, select); ignored`);
+            }
         }
     }
     let maxProjectFiles;
@@ -309,12 +387,38 @@ function parseConfigFile(configPath) {
             }
         }
     }
+    // #533 hygiene: mirror the global loader's unknown-key warn so a typo in a
+    // shared `.pi-lens.json` (e.g. `maxProjectFile`, `lps`) produces a signal
+    // instead of silently doing nothing. The recognized set is single-sourced
+    // (#883): the project loader's own keys + the project-scoped flag sections
+    // (registry-derived) + the foreign namespaces the LSP loader reads from this
+    // same file. A key recognized ONLY at global scope (e.g. `lsp`, `tests`,
+    // `delta`) gets a distinct, honest signal that it does nothing here rather
+    // than being lumped in with typos — docs previously called this "silently
+    // ignored".
+    const knownProjectKeys = new Set([
+        ...PROJECT_OWN_CONFIG_KEYS,
+        ...flagConfigSectionKeys(PROJECT_SCOPED_LENS_FLAGS),
+        ...PROJECT_FOREIGN_CONFIG_NAMESPACES,
+    ]);
+    const globalScopeOnlyKeys = new Set([
+        ...flagConfigSectionKeys(LENS_FLAGS),
+        ...GLOBAL_NON_FLAG_CONFIG_SECTIONS,
+    ].filter((key) => !knownProjectKeys.has(key)));
+    for (const key of Object.keys(obj)) {
+        if (knownProjectKeys.has(key))
+            continue;
+        if (globalScopeOnlyKeys.has(key)) {
+            warnInvalidConfigOnce(configPath, `"${key}" is a global-only pi-lens setting and is not honored in a project .pi-lens.json (set it in ~/.pi-lens/config.json or pass the matching CLI flag); ignored`);
+        }
+        else {
+            warnInvalidConfigOnce(configPath, `unknown key "${key}" is not a recognized pi-lens setting (check for a typo); ignored`);
+        }
+    }
     return {
         ignore,
         rules,
-        format,
-        autofix,
-        actionableWarnings,
+        ...mutations,
         maxProjectFiles,
         reviewGraph,
         raw,

package/dist/clients/project-report.js

@@ -34,9 +34,8 @@
  * into symbol-node metadata so this path can read it for free.
  */
 import * as path from "node:path";
-import { normalizeMapKey } from "./path-utils.js";
-import { isAtOrAboveHomeDir } from "./path-utils.js";
-import { loadProjectSnapshot } from "./project-snapshot.js";
+import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
+import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
 const DEFAULT_LIMIT = 10;
 const STALE_THRESHOLD_MS = 15 * 60_000; // 15 minutes
 const LOW_COVERAGE_THRESHOLD = 0.8;
@@ -48,14 +47,19 @@ function clampLimit(limit) {
 }
 // Same display-path convention as module-report.ts's toDisplayPath: cwd-relative
 // + forward-slashed under the project root, else the absolute (slash-normalized)
-// path.
+// path. Delegates to the shape-aware toProjectRelativePath (#1163/#1194) instead
+// of hand-rolling with host-default path.isAbsolute/path.relative, which
+// mis-parses a Windows-shaped path (e.g. a persisted graph symbol-key path) on
+// Linux CI: path.isAbsolute("C:\\repo\\x.ts") is false there, short-circuiting
+// to the raw absolute path instead of relativizing (#1024 divergence class).
 function toDisplayPath(p, projectRoot) {
-    if (!path.isAbsolute(p))
-        return p.replace(/\\/g, "/");
-    const rel = path.relative(projectRoot, p);
-    return rel && !rel.startsWith("..")
-        ? rel.replace(/\\/g, "/")
-        : p.replace(/\\/g, "/");
+    return toProjectRelativePath(p, projectRoot);
+}
+/** Test-only export (refs #1194) so the shape-aware delegation can be verified
+ * directly without standing up a full review graph — mirrors the
+ * `_reset*ForTests` underscore convention used elsewhere in this file. */
+export function _toDisplayPathForTests(p, projectRoot) {
+    return toDisplayPath(p, projectRoot);
 }
 function suggestedNext(displayPath) {
     return { tool: "module_report", path: displayPath };
@@ -111,9 +115,10 @@ function buildFileDegrees(graph) {
 // --- section 1: trust header --------------------------------------------------
 function computeTrust(graph, cwd) {
     const filesCovered = graph.fileNodes.size;
-    const snapshot = loadProjectSnapshot(cwd);
+    const snapshot = loadProjectSnapshotWithoutWordIndex(cwd);
     const snapshotFileCount = snapshot ? Object.keys(snapshot.files).length : 0;
-    const filesTotal = Math.max(filesCovered, snapshotFileCount);
+    const persistedTotal = graph.persistCoverage?.totalFiles ?? 0;
+    const filesTotal = Math.max(filesCovered, snapshotFileCount, persistedTotal);
     const coverage = filesTotal > 0 ? filesCovered / filesTotal : 1;
     let exact = 0;
     let imp = 0;
@@ -143,14 +148,28 @@ function computeTrust(graph, cwd) {
     const frac = (n) => (sampleSize > 0 ? n / sampleSize : 0);
     const ageMs = Date.now() - Date.parse(graph.builtAt);
     const stale = Number.isFinite(ageMs) && ageMs > STALE_THRESHOLD_MS;
-    const lowCoverage = coverage < LOW_COVERAGE_THRESHOLD;
+    const lowCoverage = coverage < LOW_COVERAGE_THRESHOLD ||
+        graph.persistCoverage?.partial === true;
     const notes = [];
     if (stale) {
         const ageMin = Math.round(ageMs / 60_000);
         notes.push(`Graph is stale: built ${ageMin}m ago. Sections below may miss recent edits — run pilens_rebuild or re-analyze to refresh.`);
     }
     if (lowCoverage) {
-        notes.push(`Low coverage: only ${filesCovered}/${filesTotal} project files (${Math.round(coverage * 100)}%) are in the graph — whole subsystems may be invisible below.`);
+        if (graph.persistCoverage?.partial) {
+            const p = graph.persistCoverage;
+            const totalFiles = p.totalFiles ?? filesCovered;
+            const persistedFiles = p.persistedFiles ?? filesCovered;
+            if (p.sourceFilesTruncated) {
+                notes.push(`Partial source walk: at least ${totalFiles} source files were represented before the visited-entry budget stopped enumeration; ${persistedFiles} files are in this graph.`);
+            }
+            else {
+                notes.push(`Partial persisted graph: ${p.persistedNodes}/${p.totalNodes} nodes, ${p.persistedEdges}/${p.totalEdges} edges, and ${persistedFiles}/${totalFiles} files were retained under the ${p.cap}-element cap — whole subsystems may be invisible below.`);
+            }
+        }
+        else {
+            notes.push(`Low coverage: only ${filesCovered}/${filesTotal} project files (${Math.round(coverage * 100)}%) are in the graph — whole subsystems may be invisible below.`);
+        }
     }
     return {
         graphBuiltAt: graph.builtAt,
@@ -166,6 +185,9 @@ function computeTrust(graph, cwd) {
         },
         stale,
         lowCoverage,
+        persistCoverage: graph.persistCoverage?.partial
+            ? graph.persistCoverage
+            : undefined,
         notes,
     };
 }
@@ -473,10 +495,8 @@ export function _resetProjectReportBuildGuardForTests() {
 }
 function triggerBackgroundGraphBuild(cwd) {
     const key = normalizeMapKey(path.resolve(cwd));
-    if (isAtOrAboveHomeDir(key))
-        return;
     if (inFlightGraphBuilds.has(key))
-        return;
+        return false;
     inFlightGraphBuilds.add(key);
     void (async () => {
         try {
@@ -485,12 +505,13 @@ function triggerBackgroundGraphBuild(cwd) {
             await buildOrUpdateGraph(key, [], new FactStore());
         }
         catch {
-            // Best-effort warmth, not a request the caller is waiting on.
+            // buildOrUpdateGraph records the durable failure and surfaced status.
         }
         finally {
             inFlightGraphBuilds.delete(key);
         }
     })();
+    return true;
 }
 // --- entry point ---------------------------------------------------------------
 /**
@@ -502,7 +523,7 @@ export async function projectReport(cwd, options) {
     const limit = clampLimit(options?.limit);
     const focusTerms = normalizeFocus(options?.focus);
     const view = options?.view;
-    const { getCachedReviewGraph, getReviewGraphSizeSkipVerdict } = await import("./review-graph/builder.js");
+    const { getCachedReviewGraph, getReviewGraphSizeSkipVerdict, getLastReviewGraphBuildAttempt, } = await import("./review-graph/builder.js");
     let graph;
     try {
         graph = getCachedReviewGraph(cwd);
@@ -523,19 +544,29 @@ export async function projectReport(cwd, options) {
             sizeSkip = undefined;
         }
         if (sizeSkip) {
+            const lastBuildAttempt = getLastReviewGraphBuildAttempt(cwd);
             return {
                 available: false,
-                hint: `review graph disabled: project has ${sizeSkip.sourceFileCount} files, ` +
-                    `cap is ${sizeSkip.maxFileCount} — raise maxProjectFiles in .pi-lens.json ` +
-                    "or set PI_LENS_REVIEW_GRAPH_MAX_FILES",
+                hint: `review graph disabled: project has more than ${sizeSkip.maxFileCount} files ` +
+                    `(cap ${sizeSkip.maxFileCount}) — raise maxProjectFiles in .pi-lens.json ` +
+                    "or set PI_LENS_REVIEW_GRAPH_MAX_FILES; for CI/cron, run " +
+                    "npx pi-lens build-graph after configuring the cap",
+                ...(lastBuildAttempt ? { lastBuildAttempt } : {}),
                 ...(view ? { view } : {}),
             };
         }
-        triggerBackgroundGraphBuild(cwd);
+        const previousAttempt = getLastReviewGraphBuildAttempt(cwd);
+        const kickedOff = triggerBackgroundGraphBuild(cwd);
+        const lastBuildAttempt = previousAttempt ?? getLastReviewGraphBuildAttempt(cwd);
         return {
             available: false,
-            hint: "No review graph cached for this workspace yet — a build was kicked " +
-                "off in the background; retry this call shortly.",
+            hint: lastBuildAttempt?.outcome === "failed" ||
+                lastBuildAttempt?.outcome === "skipped"
+                ? `Review graph unavailable: ${lastBuildAttempt.reason ?? lastBuildAttempt.outcome}. A retry was ${kickedOff ? "started" : "not started"}.`
+                : kickedOff
+                    ? "No review graph cached for this workspace yet — a build was kicked off in the background; retry this call shortly."
+                    : "No review graph cached for this workspace yet — the background build is still running; retry this call shortly.",
+            ...(lastBuildAttempt ? { lastBuildAttempt } : {}),
             ...(view ? { view } : {}),
         };
     }
@@ -546,8 +577,10 @@ export async function projectReport(cwd, options) {
     const subsystems = computeSubsystems(graph, cwd, limit);
     const riskHotspots = computeRiskHotspots(graph, degrees, cwd, limit, focusTerms);
     const deadWeight = computeDeadWeight(graph, degrees, entryPointFiles, cwd, limit);
+    const lastBuildAttempt = getLastReviewGraphBuildAttempt(cwd);
     return {
         available: true,
+        ...(lastBuildAttempt ? { lastBuildAttempt } : {}),
         ...(view ? { view } : {}),
         trust,
         hubs,
@@ -571,6 +604,12 @@ export function renderCompactProjectReport(report) {
         return `project_report — unavailable${report.hint ? `: ${report.hint}` : ""}`;
     }
     const lines = [];
+    // #919: an available graph whose persist failed serves this process fine
+    // but leaves the NEXT session cold — compact view must say so, not only
+    // the JSON view.
+    if (report.lastBuildAttempt?.reason) {
+        lines.push(`! build: ${report.lastBuildAttempt.reason}`);
+    }
     const t = report.trust;
     if (t) {
         lines.push(`TRUST: built ${t.graphBuiltAt} — ${t.filesCovered}/${t.filesTotal} files (${fmtPct(t.coverage)} coverage)` +

package/dist/clients/project-scale.js

@@ -151,19 +151,17 @@ export function getProjectDiagnosticsScannerMaxFiles(cwd) {
  *
  * {@link REVIEW_GRAPH_HARD_CEILING} (5,000) is grounded FIRST by the
  * strongest real constraint on this number — `review-graph/builder.ts`'s
- * persist circuit-breaker (`GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT`, 200,000
+ * persist circuit-breaker (`GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT`, 500,000
  * graph elements: file/symbol nodes + cross-file edges). Above that element
- * count the graph is NEVER persisted to disk (logged + skipped, #260's OOM
- * guard) — not "slow", but PERMANENTLY uncached, so every session pays a
- * full cold build instead of the ~20 ms cached path (see the CHANGELOG
- * timing note below) engaging exactly once. For symbol-dense repos, element
+ * count only a centrality-ranked, honestly-marked partial graph is persisted
+ * (#936). Read-only orientation can use it, but the build tier rejects it as
+ * a complete incremental base. For symbol-dense repos, element
  * count runs on the order of ~30/file (file node + per-symbol nodes +
  * import/call/reference edges), so a hard ceiling must leave real headroom
- * below 200,000 elements, not creep up to it: 5,000 files x ~30 ⇒ ~150,000
- * elements, a ~25% margin. The earlier 6,000-file candidate (~180,000
- * elements) left too little margin — a slightly denser-than-average repo at
- * exactly the ceiling could tip over and silently lose persistence forever,
- * the opposite of this issue's "no silent caps" goal. 5,000 is also still
+ * below 500,000 elements. The file ceiling remains conservative because it
+ * also bounds cold-build latency; the persist cap has independent measured
+ * headroom through a roughly 420,000-element / 10,000-file graph (#936).
+ * 5,000 is also still
  * coherent with the jscpd/wordIndex 3x-ratio precedent (6,000 at the
  * default base) as "the ceiling sits just below that established top
  * tier" rather than an exact match, so it isn't a fresh unrelated

package/dist/clients/project-snapshot-persist-worker.js

@@ -0,0 +1,6 @@
+import { serveGzipStageWorker, } from "./gzip-stage-write.js";
+serveGzipStageWorker((request) => ({
+    id: request.id,
+    generation: request.generation,
+    stagePath: request.stagePath,
+}));