peaks-loop 4.0.51 → 4.0.52

package/dist/services/codegraph/codegraph-config-repair-writer.js

@@ -0,0 +1,322 @@
+// src/services/codegraph/codegraph-config-repair-writer.ts
+//
+// The pure repair plans (`repairCodegraphExclude` for the exclude axis,
+// `repairCodegraphInclude` for the include axis) and the writer that applies
+// them to `<projectRoot>/.codegraph/config.json` in ONE atomic rewrite, plus
+// the byte-exact `config.json.bak` copy it keeps for rollback.
+//
+// Extracted verbatim from `codegraph-exclude-repair.ts` (rid
+// 2026-09-17-oversize-followup, G1 — the 800-line file-size cap). Every moved
+// line is byte-identical and no behaviour changed; `codegraph-exclude-repair.ts`
+// re-exports this module's public surface, so every existing import site
+// (`applyCodegraphConfigRepair`, `repairCodegraphExclude`,
+// `repairCodegraphInclude`, `CODEGRAPH_CONFIG_BACKUP_SUFFIX`, and the three
+// plan/outcome types) keeps working unchanged.
+//
+// The dependency edge is ONE-WAY and must stay that way: this module must not
+// import `codegraph-exclude-repair.ts`, which imports this one.
+import { randomBytes } from 'node:crypto';
+import { chmodSync, lstatSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertStringArray, CODEGRAPH_CONFIG_FILENAME } from './codegraph-exclude-reconciler.js';
+import { assertCodegraphDirContained, CODEGRAPH_DIR_NAME } from './codegraph-service.js';
+/** Suffix of the byte-exact pre-repair copy kept next to the config. */
+export const CODEGRAPH_CONFIG_BACKUP_SUFFIX = '.bak';
+/**
+ * Pure: given the current `exclude` list and the rules to drop, return
+ * the new list. No fs, no clock, no serialization.
+ *
+ * A rule named in `rulesToRemove` but absent from `exclude` is NOT
+ * invented — the result is a subset of the input, so a caller can
+ * never add a rule by accident. Removing an already-absent rule is a
+ * no-op, which is what makes the whole repair idempotent: feeding the
+ * repaired list back in yields `changed: false`.
+ */
+export function repairCodegraphExclude(input) {
+    const removable = new Set(input.rulesToRemove);
+    // De-duplicated, order-preserving. A config that lists the same rule
+    // twice would otherwise be counted twice here, and this array is what
+    // the caller reports to the user as "rules removed".
+    const removedRules = [...new Set(input.exclude.filter((rule) => removable.has(rule)))];
+    if (removedRules.length === 0) {
+        return { changed: false, exclude: input.exclude, removedRules: [] };
+    }
+    return {
+        changed: true,
+        exclude: input.exclude.filter((rule) => !removable.has(rule)),
+        removedRules
+    };
+}
+/**
+ * Pure: given the current `include` list and the patterns to append, return
+ * the new list. The mirror of `repairCodegraphExclude`, in the other
+ * direction — a SUPERSET operation instead of a subset one.
+ *
+ * A pattern already present is not appended twice: the include reconciler
+ * already guarantees that, but this function is the writer's own last line
+ * of defence, and a duplicated glob in a third-party config would be a
+ * visible defect even though it changes no matching behaviour.
+ */
+export function repairCodegraphInclude(input) {
+    const existing = new Set(input.include);
+    const additions = input.patternsToAdd.filter((pattern) => !existing.has(pattern));
+    if (additions.length === 0) {
+        return { changed: false, include: input.include, addedPatterns: [] };
+    }
+    return { changed: true, include: [...input.include, ...additions], addedPatterns: additions };
+}
+/**
+ * Detect the indentation the config already uses so the rewrite keeps
+ * the file's shape instead of reformatting a third-party tool's file.
+ *
+ * A single-line (minified) config has no indentation to copy: `0` tells
+ * `JSON.stringify` to emit compact JSON, so the file comes back as the
+ * one-liner it went in as. `0` is NOT the same as "not set" here — an
+ * omitted indent would also be compact, but returning a number keeps the
+ * intent explicit at the call site.
+ *
+ * Falls back to two spaces when the file spans lines but has no indented
+ * member.
+ */
+function detectIndent(text) {
+    if (!text.trimEnd().includes('\n')) {
+        return 0;
+    }
+    const match = /\n([ \t]+)"/.exec(text);
+    return match?.[1] ?? 2;
+}
+function serializeConfig(config, originalText) {
+    const body = JSON.stringify(config, null, detectIndent(originalText));
+    return originalText.endsWith('\n') ? `${body}\n` : body;
+}
+/**
+ * Write `content` to `filePath` atomically: same-directory temp file,
+ * then `renameSync` over the target.
+ *
+ * The file being written belongs to a THIRD-PARTY tool, so a crash or a
+ * full disk mid-`writeFileSync` must never leave a half-written config
+ * behind. `rename` within one directory is atomic, so a reader sees
+ * either the old bytes or the new ones, never a prefix of the new ones.
+ * The temp file lives next to the target (same directory ⇒ same
+ * filesystem ⇒ the rename cannot degrade to a cross-device copy) and is
+ * removed if the write or the rename fails.
+ *
+ * N5: the temp name carries the pid plus 6 random bytes. A FIXED
+ * `${filePath}.tmp` is single-writer only, and this writer has three
+ * reachable concurrent callers — a fresh `peaks codegraph init` (which
+ * repairs then indexes), the pre-dispatch preflight, and the post-slice
+ * autorefresh. Two overlapping writers sharing one temp name let one
+ * `renameSync` publish a file the other was still writing, which is
+ * exactly the half-written config the temp file exists to prevent. The
+ * suffix keeps the temp in the SAME directory, so the rename stays
+ * within one filesystem and therefore stays atomic.
+ */
+function writeConfigAtomic(filePath, content, mode) {
+    const tempPath = `${filePath}.${String(process.pid)}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        writeFileSync(tempPath, content, 'utf8');
+        if (mode !== undefined) {
+            // The mode is applied to the TEMP, before the rename, so the
+            // published file has it in the same atomic step — a `chmod` after
+            // the rename would leave a window in which the file exists at the
+            // process umask instead of the original's mode.
+            chmodSync(tempPath, mode);
+            // Windows cannot REPLACE a read-only destination: `renameSync` over
+            // one throws EPERM (measured, `2026-09-17-codegraph-msg-and-refresh`).
+            // The only destination this branch ever sees read-only is this
+            // writer's own previous `.bak`, which under A4 carries the original
+            // config's mode — so a read-only config would make the SECOND repair
+            // fail at the rename. Clear the bit and let the rename plus the mode
+            // above put it back. A destination that is not a regular file is left
+            // alone: `writeConfigBackup`'s link/directory guard has already
+            // refused those before this function is reached.
+            const existing = lstatSync(filePath, { throwIfNoEntry: false });
+            if (existing !== undefined && existing.isFile() && (existing.mode & 0o200) === 0) {
+                chmodSync(filePath, existing.mode | 0o200);
+            }
+        }
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+/**
+ * Copy the config's ORIGINAL bytes to `config.json.bak`, refusing to write
+ * through a link that already occupies that path.
+ *
+ * The backup path is FIXED (`<configPath>.bak`) and therefore guessable, and
+ * `.codegraph/config.json.bak` is committable in a consumer project. So a
+ * repository can ship that path as a link to an arbitrary file of the
+ * attacker's choosing plus a `config.json` that merely OMITS an extension —
+ * which is the DEFAULT state of every config written before the include axis
+ * existed — and any repair-seam run (a fresh `peaks codegraph init`, the
+ * pre-dispatch preflight, the post-slice autorefresh, or either explicit
+ * repair verb) would write the whole attacker-authored config file through
+ * that link. Arbitrary file overwrite, as the invoking user, with no
+ * operator action. `writeFileSync`'s default `'w'` flag is
+ * `O_WRONLY|O_CREAT|O_TRUNC`: it follows a symlink and it truncates a hard
+ * link's shared inode, so it is the wrong primitive here.
+ *
+ * Two independent refusals, because either one alone leaves a case open:
+ *
+ *   1. `lstat` (never `stat`) rejects a SYMBOLIC LINK — `stat` would follow
+ *      it and report the victim's regular-file type — and a HARD LINK, which
+ *      `lstat` cannot distinguish by type but the link count exposes
+ *      (`nlink > 1` means another name shares this inode, so writing here
+ *      writes to that file too). Both are refusals, not repairs: silently
+ *      replacing someone else's link is not this writer's decision to make.
+ *   2. The copy goes through `writeConfigAtomic` (CSPRNG temp + `renameSync`),
+ *      so even an entry that appears between the `lstat` and the write is
+ *      REPLACED rather than written through — `rename` never follows the
+ *      destination's link, and it never truncates the destination's inode.
+ *      That also makes the backup atomic, which the module header's
+ *      byte-exact-rollback promise needs and a bare `writeFileSync` did not
+ *      provide.
+ *
+ * What is NOT refused: a regular file at the backup path with a link count
+ * of 1. That is this writer's own previous backup (a project may legitimately
+ * drift and be repaired twice), and replacing it atomically is exactly what
+ * the `rename` in (2) does. `O_EXCL` alone would have refused that legitimate
+ * case along with the attack, which is why the guard is a link test rather
+ * than an existence test.
+ *
+ * `writeFileSync` there is called only after parsing and planning have both
+ * succeeded, so a refusal leaves the config BYTES UNTOUCHED — the throw
+ * propagates out of `applyCodegraphConfigRepair` before the rewrite.
+ *
+ * A4 (`2026-09-17-codegraph-msg-and-refresh`, the L1 half left over from
+ * slice-002's S1): the copy carries the ORIGINAL CONFIG'S MODE, because the
+ * mode is part of what a rollback restores. The `.bak` exists so an operator
+ * can put the previous config back with a `mv`, and a restore that hands
+ * back a file whose permissions were decided by this process's umask is not
+ * a restore: a `0600` config would come back as `0644` — group- and
+ * world-readable, a permission the project never granted it.
+ *
+ * The mode is read with `statSync` on the config (not `lstatSync`, and not
+ * from the caller): the caller has just read that file's bytes, so it
+ * exists, and a config that is itself a symlink is a case upstream's own
+ * reader follows — the permissions that matter are the ones the operator
+ * sees on the config.
+ *
+ * NOT applied to the config rewrite beside it, deliberately: that path
+ * (`writeConfigAtomic(configPath, …)` with no mode) keeps the process
+ * default, which is what upstream's own `init` produces. Stated rather than
+ * left silent — see this batch's RD artifact, section A4.
+ */
+function writeConfigBackup(configPath, originalText) {
+    const backupPath = `${configPath}${CODEGRAPH_CONFIG_BACKUP_SUFFIX}`;
+    const existing = lstatSync(backupPath, { throwIfNoEntry: false });
+    if (existing !== undefined &&
+        (existing.isSymbolicLink() || existing.isDirectory() || existing.nlink > 1)) {
+        const kind = existing.isSymbolicLink()
+            ? 'a symbolic link'
+            : existing.isDirectory()
+                ? 'a directory'
+                : `a hard link (link count ${String(existing.nlink)})`;
+        // "through" for a link (the bytes land in whatever it points at), "at" for
+        // a directory (there is nowhere for them to land).
+        const preposition = existing.isDirectory() ? 'at' : 'through';
+        throw new Error(`codegraph config backup ${backupPath}: refusing to write ${preposition} ${kind} occupying ` +
+            'this path. Another file or directory shares it, so a backup written here would overwrite ' +
+            'that. Remove it (or point `peaks` at a project root whose `.codegraph/` it owns) and re-run.');
+    }
+    // A4: the ORIGINAL config's mode travels with the copy. `& 0o777` drops
+    // the file-type bits `statSync` packs above the permission bits — `chmod`
+    // takes permission bits only.
+    writeConfigAtomic(backupPath, originalText, statSync(configPath).mode & 0o777);
+    return backupPath;
+}
+/**
+ * Apply BOTH config repairs to `<projectRoot>/.codegraph/config.json` in one
+ * atomic rewrite.
+ *
+ * No-op (and no write, no mtime change, no backup) when both lists are
+ * empty. Otherwise: back up the original bytes to `config.json.bak`, then
+ * rewrite the file with `exclude` reduced by exactly the rules that were
+ * both requested and present, and `include` extended by exactly the
+ * patterns that were both requested and absent.
+ *
+ * ONE rewrite, not two. A caller that widened `include` in one write and
+ * dropped the newly-offending `exclude` rules in a second would leave a
+ * window in which the config on disk is worse than it started (the widened
+ * include admits a file that a surviving rule then hides from the index),
+ * and would need two backups to stay rollback-exact. One rewrite through
+ * the same-directory temp file has neither property.
+ *
+ * Throws only on real fs/parse failures and on the containment refusal
+ * above — the caller decides whether that is fatal (`repair-exclude` /
+ * `repair-index` → non-zero exit) or a surfaced warning (`init` → keep
+ * going, the init itself already succeeded). Both are refusals BEFORE
+ * anything is written, so a throw can never half-apply.
+ */
+export function applyCodegraphConfigRepair(projectRoot, repair) {
+    if (repair.rulesToRemove.length === 0 && repair.includePatternsToAdd.length === 0) {
+        return {
+            applied: false,
+            reason: 'nothing-to-repair',
+            removedRules: [],
+            addedIncludePatterns: []
+        };
+    }
+    // Containment FIRST — before even reading (S12 / security R1). The `.bak`
+    // guard below protects a FILE path; this protects the DIRECTORY it lives
+    // in, so `<root>/.codegraph` as a junction cannot redirect the rewrite (or
+    // the parsed read) into another project. Called for its refusal only: the
+    // write target stays derived from the caller's `projectRoot`, so this
+    // verb's canonicalization remains where L2/S5 put it, at the CLI edge.
+    assertCodegraphDirContained(projectRoot);
+    const configPath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME);
+    const originalText = readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(originalText);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`codegraph config ${configPath}: expected a JSON object`);
+    }
+    const record = parsed;
+    const exclude = assertStringArray(record.exclude, 'exclude', configPath);
+    // An ABSENT `include` key is tolerated, and is NOT the same as a malformed
+    // one: this writer predates the include axis and callers exist whose
+    // config carries only `exclude` (a hand-written minimal file; the S2
+    // hardening fixtures are exactly that). Throwing here would make the
+    // whole repair fail — including the exclude half that used to succeed —
+    // so the include axis simply has nothing to extend, and the key is never
+    // invented. A key that is PRESENT but is not an array of strings is still
+    // an error: that is a genuinely malformed config, and silently ignoring it
+    // is how a wrong `include` would survive a repair that reported success.
+    const include = record.include === undefined ? [] : assertStringArray(record.include, 'include', configPath);
+    const excludePlan = repairCodegraphExclude({ exclude, rulesToRemove: repair.rulesToRemove });
+    const includePlan = repairCodegraphInclude({ include, patternsToAdd: repair.includePatternsToAdd });
+    if (!excludePlan.changed && !includePlan.changed) {
+        return {
+            applied: false,
+            reason: 'nothing-to-repair',
+            removedRules: [],
+            addedIncludePatterns: []
+        };
+    }
+    const backupPath = writeConfigBackup(configPath, originalText);
+    // Spread first, then replace the keys that changed — every other key keeps
+    // its original value AND its original position in the serialized object.
+    // `include` is only written back when it actually changed, so a config
+    // without that key does not gain one from a repair that did not touch it.
+    const nextRecord = { ...record, exclude: excludePlan.exclude };
+    if (includePlan.changed) {
+        nextRecord.include = includePlan.include;
+    }
+    writeConfigAtomic(configPath, serializeConfig(nextRecord, originalText));
+    return {
+        applied: true,
+        configPath,
+        backupPath,
+        removedRules: excludePlan.removedRules,
+        // The patterns that ACTUALLY landed (a caller-supplied pattern that was
+        // already present is not an addition), so the report cannot overstate
+        // what changed on disk.
+        addedIncludePatterns: includePlan.addedPatterns,
+        excludeCountBefore: exclude.length,
+        excludeCountAfter: excludePlan.exclude.length,
+        includeCountBefore: include.length,
+        includeCountAfter: includePlan.include.length
+    };
+}

package/dist/services/codegraph/codegraph-exclude-integrity.d.ts

@@ -1,4 +1,4 @@
-import { type CodegraphExcludeViolation } from './codegraph-exclude-reconciler.js';
+import { type CodegraphExcludeViolation, type ReadCodegraphExcludeConfig, type ReadTrackedFiles } from './codegraph-exclude-reconciler.js';
 /**
  * Exit code `peaks codegraph status` uses when the index is
  * demonstrably incomplete. Distinct from the upstream pass-through
@@ -48,8 +48,26 @@ export declare function isCodegraphExcludeConfigPresent(projectRoot: string): bo
  * Throws (never silently degrades) when the project is not a git work
  * tree, when the config is missing, or when it is malformed — callers
  * that must stay alive (doctor, `status`) catch and surface the reason.
+ *
+ * `inputs` is the optional shared-read seam (perf audit F1): a caller
+ * that runs BOTH codegraph axes in one process reads
+ * `readCodegraphProjectInputs(projectRoot)` once and passes it here and
+ * to `inspectCodegraphIndexIntegrity`, so the `git ls-files` spawn, the
+ * config read and the `include` glob compilation happen once instead of
+ * twice. Omitted (the default) the readers run exactly as they always
+ * did, so this is additive for every existing caller.
+ *
+ * Both fields are read-marked (code review R4-1): a caller may hand over a
+ * value that came out of the readers, never one it built itself. An
+ * explicit `[]` used to be accepted and silently meant "nothing is
+ * tracked", turning a real gap into a clean report; it is now a compile
+ * error, and a run-time throw for a caller the type system cannot see.
+ * `undefined` still means "read it yourself" — unchanged.
  */
-export declare function inspectCodegraphExcludeIntegrity(projectRoot: string): CodegraphExcludeIntegrityReport;
+export declare function inspectCodegraphExcludeIntegrity(projectRoot: string, inputs?: {
+    readonly trackedFiles?: ReadTrackedFiles | undefined;
+    readonly config?: ReadCodegraphExcludeConfig | undefined;
+}): CodegraphExcludeIntegrityReport;
 /**
  * Human-readable detail lines for a gapped report: the headline count,
  * then the offending rules, then a sample of the blocked files so an

package/dist/services/codegraph/codegraph-exclude-integrity.js

@@ -15,7 +15,7 @@
 // `peaks codegraph repair-exclude` command. Read stays read.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { CODEGRAPH_CONFIG_FILENAME, reconcileCodegraphExcludeFromProject } from './codegraph-exclude-reconciler.js';
+import { CODEGRAPH_CONFIG_FILENAME, resolveSharedConfig, resolveSharedTrackedFiles, reconcileCodegraphExclude } from './codegraph-exclude-reconciler.js';
 import { CODEGRAPH_DIR_NAME } from './codegraph-service.js';
 /**
  * Exit code `peaks codegraph status` uses when the index is
@@ -49,9 +49,30 @@ export function isCodegraphExcludeConfigPresent(projectRoot) {
  * Throws (never silently degrades) when the project is not a git work
  * tree, when the config is missing, or when it is malformed — callers
  * that must stay alive (doctor, `status`) catch and surface the reason.
+ *
+ * `inputs` is the optional shared-read seam (perf audit F1): a caller
+ * that runs BOTH codegraph axes in one process reads
+ * `readCodegraphProjectInputs(projectRoot)` once and passes it here and
+ * to `inspectCodegraphIndexIntegrity`, so the `git ls-files` spawn, the
+ * config read and the `include` glob compilation happen once instead of
+ * twice. Omitted (the default) the readers run exactly as they always
+ * did, so this is additive for every existing caller.
+ *
+ * Both fields are read-marked (code review R4-1): a caller may hand over a
+ * value that came out of the readers, never one it built itself. An
+ * explicit `[]` used to be accepted and silently meant "nothing is
+ * tracked", turning a real gap into a clean report; it is now a compile
+ * error, and a run-time throw for a caller the type system cannot see.
+ * `undefined` still means "read it yourself" — unchanged.
  */
-export function inspectCodegraphExcludeIntegrity(projectRoot) {
-    const result = reconcileCodegraphExcludeFromProject(projectRoot);
+export function inspectCodegraphExcludeIntegrity(projectRoot, inputs = {}) {
+    const trackedFiles = resolveSharedTrackedFiles(inputs.trackedFiles, projectRoot);
+    const config = resolveSharedConfig(inputs.config, projectRoot);
+    const result = reconcileCodegraphExclude({
+        trackedFiles,
+        include: config.include,
+        exclude: config.exclude
+    });
     const blockedCounts = new Map();
     for (const violation of result.violations) {
         blockedCounts.set(violation.matchedRule, (blockedCounts.get(violation.matchedRule) ?? 0) + 1);

package/dist/services/codegraph/codegraph-exclude-reconciler.d.ts

@@ -1,4 +1,8 @@
 export declare function matchesCodegraphGlob(filePath: string, pattern: string): boolean;
+export type CompiledCodegraphGlobs = {
+    readonly matchesAny: (filePath: string) => boolean;
+};
+export declare function compileCodegraphGlobs(patterns: readonly string[]): CompiledCodegraphGlobs;
 export type CodegraphExcludeReconcileInput = {
     readonly trackedFiles: readonly string[];
     readonly include: readonly string[];
@@ -14,13 +18,30 @@ export type CodegraphExcludeReconcileResult = {
     readonly trackedSourceCount: number;
     readonly excludedTrackedCount: number;
 };
+export declare function filterAdmittedTrackedFiles(trackedFiles: readonly string[], include: readonly string[]): readonly string[];
 export declare function reconcileCodegraphExclude(input: CodegraphExcludeReconcileInput): CodegraphExcludeReconcileResult;
 export declare const CODEGRAPH_CONFIG_FILENAME = "config.json";
 export type CodegraphExcludeConfig = {
     readonly include: readonly string[];
     readonly exclude: readonly string[];
 };
-export declare function readTrackedFiles(projectRoot: string): readonly string[];
+declare const READ_PROVENANCE: unique symbol;
+type ReadProvenance = {
+    readonly [READ_PROVENANCE]: true;
+};
+/** A tracked-file list that provably came out of `readTrackedFiles`. */
+export type ReadTrackedFiles = readonly string[] & ReadProvenance;
+/** A config that provably came out of `readCodegraphExcludeConfig`. */
+export type ReadCodegraphExcludeConfig = CodegraphExcludeConfig & ReadProvenance;
+export declare function readTrackedFiles(projectRoot: string): ReadTrackedFiles;
 export declare function assertStringArray(value: unknown, field: string, configPath: string): readonly string[];
-export declare function readCodegraphExcludeConfig(projectRoot: string): CodegraphExcludeConfig;
+export declare function readCodegraphExcludeConfig(projectRoot: string): ReadCodegraphExcludeConfig;
+export type CodegraphProjectInputs = {
+    readonly trackedFiles: ReadTrackedFiles;
+    readonly config: ReadCodegraphExcludeConfig;
+};
+export declare function readCodegraphProjectInputs(projectRoot: string): CodegraphProjectInputs;
+export declare function resolveSharedTrackedFiles(supplied: ReadTrackedFiles | undefined, projectRoot: string): ReadTrackedFiles;
+export declare function resolveSharedConfig(supplied: ReadCodegraphExcludeConfig | undefined, projectRoot: string): ReadCodegraphExcludeConfig;
 export declare function reconcileCodegraphExcludeFromProject(projectRoot: string): CodegraphExcludeReconcileResult;
+export {};

package/dist/services/codegraph/codegraph-exclude-reconciler.js

@@ -120,6 +120,39 @@ export function matchesCodegraphGlob(filePath, pattern) {
     }
     return compileGlob(pattern).match(normalizePath(filePath));
 }
+export function compileCodegraphGlobs(patterns) {
+    const rules = compileRules(patterns);
+    return {
+        matchesAny: (filePath) => {
+            const normalizedPath = normalizePath(filePath);
+            return rules.some((rule) => rule.match(normalizedPath));
+        }
+    };
+}
+// The project-relative paths of the tracked files the config's `include`
+// globs admit, normalized. This is the ONE place the "would the index
+// ingest this path" question is answered, so this reconciler and the
+// index-integrity inspector cannot drift apart on glob semantics: the
+// `include`-axis gap is computed as a set difference against exactly the
+// set this function returns.
+//
+// Pure: no fs, no spawn, no clock. Compiling per rule (not per file x
+// rule) keeps it linear in the number of tracked files.
+//
+// Unmatchable `include` entries are dropped before compiling (see
+// `isUnmatchableRule`). An empty `include` entry admits nothing, which is
+// the same verdict as an explicitly empty `include` list.
+export function filterAdmittedTrackedFiles(trackedFiles, include) {
+    const includeRules = compileRules(include);
+    const admitted = [];
+    for (const candidate of trackedFiles) {
+        const normalizedPath = normalizePath(candidate);
+        if (includeRules.some((rule) => rule.match(normalizedPath))) {
+            admitted.push(normalizedPath);
+        }
+    }
+    return admitted;
+}
 // Reconcile the codegraph `exclude` list against the set of git-tracked
 // source files. Pure: no fs, no spawn, no clock.
 //
@@ -131,15 +164,8 @@ export function reconcileCodegraphExclude(input) {
     // `isUnmatchableRule`. An empty `include` entry admits nothing, which
     // is the same verdict as an explicitly empty `include` list, so it
     // needs no special case here.
-    const includeRules = compileRules(input.include);
     const excludeRules = compileRules(input.exclude);
-    const trackedSourceFiles = [];
-    for (const candidate of input.trackedFiles) {
-        const normalizedPath = normalizePath(candidate);
-        if (includeRules.some((rule) => rule.match(normalizedPath))) {
-            trackedSourceFiles.push(normalizedPath);
-        }
-    }
+    const trackedSourceFiles = filterAdmittedTrackedFiles(input.trackedFiles, input.include);
     const violations = [];
     const offendingRules = new Set();
     const blockedFiles = new Set();
@@ -165,6 +191,59 @@ export function reconcileCodegraphExclude(input) {
 // ─────────────────────────────────────────────────────────────────────
 // Upstream `CONFIG_FILENAME` inside `<projectRoot>/.codegraph/`.
 export const CODEGRAPH_CONFIG_FILENAME = 'config.json';
+// ─────────────────────────────────────────────────────────────────────
+// Read provenance — why the shared-input seam refuses a fabricated value
+// ─────────────────────────────────────────────────────────────────────
+// Code review R4-1. The shared-input seam (perf F1) hands an inspector the
+// ALREADY-READ inputs. Before this block, `trackedFiles?: readonly string[]`
+// could not tell "field omitted" (read it yourself) from "field supplied as
+// `[]`" (silently: nothing is tracked) — and the second one turned a real
+// gap into a CLEAN verdict on BOTH axes:
+//
+//     E(root, { trackedFiles: [] })
+//       exclude axis: gap true -> false, trackedSourceCount 1 -> 0, violations [] -> dropped
+//       index   axis: includeGap ['scripts/tool.mjs'] -> []
+//
+// That is a silent false pass inside the guard built to prevent silent false
+// passes. Emptiness alone cannot be the discriminator — a repository that
+// genuinely tracks nothing has a legitimately EMPTY list, and rejecting that
+// would turn `peaks codegraph status` on such a repo from "clean" into a
+// spurious warning. Provenance can discriminate, so that is what we key on.
+//
+// Every value this module's readers produce is marked, non-enumerably, with
+// this symbol at the ONE place that owns the readers; the seam accepts only
+// marked values. A hand-built `[]` is therefore unreachable at compile time
+// (the brand is a required property) AND loud at run time (a JS caller or a
+// cast trips the assertion instead of silently reporting clean).
+//
+// `Symbol.for` rather than `Symbol()` so the mark survives the same module
+// being loaded twice (dual ESM/CJS evaluation of a linked package).
+const READ_PROVENANCE = Symbol.for('peaks-loop.codegraph.read-provenance');
+// `enumerable: false` on purpose: the mark is provenance, not content. A
+// `JSON.stringify`, a spread or a deep-equality assertion over the list must
+// not see it, so branding stays invisible to every existing consumer.
+function markAsRead(value) {
+    Object.defineProperty(value, READ_PROVENANCE, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    return value;
+}
+// The run-time half of the brand. Reached only by a caller the type system
+// could not police (JS, a cast, or a future `as` in a hurry), so it must be
+// loud and must say what the silent alternative would have done.
+function assertReadProvenance(value, field, producer) {
+    if (!Object.prototype.hasOwnProperty.call(value, READ_PROVENANCE)) {
+        throw new Error(`codegraph shared inputs: "${field}" did not come from ${producer}(), so it is not a ` +
+            'value this module can trust. A hand-built value is indistinguishable from a real read, ' +
+            'and an empty one means "nothing is tracked / nothing is admitted" — which reports a ' +
+            'real gap as CLEAN on both codegraph axes. Pass the result of ' +
+            'readCodegraphProjectInputs(projectRoot) verbatim, or omit the field to read from disk.');
+    }
+    return value;
+}
 // Project-relative paths of every git-tracked file, exactly as
 // `git ls-files` reports them. Why git and not an fs walk: the index
 // must cover what git tracks (see the anti-fake-green contract in
@@ -173,17 +252,20 @@ export const CODEGRAPH_CONFIG_FILENAME = 'config.json';
 //
 // Throws when `projectRoot` is not inside a git work tree — callers
 // decide whether that is fatal; this function never swallows it.
+//
+// Returns a READ-MARKED list: the seam helpers below accept only marked
+// values, so a fabricated `[]` cannot be passed off as this read's result.
 export function readTrackedFiles(projectRoot) {
     const stdout = execFileSync('git', ['-C', projectRoot, 'ls-files'], {
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
         windowsHide: true
     });
-    return stdout
+    return markAsRead(stdout
         .split('\n')
         .map((line) => line.trim())
         .filter((line) => line.length > 0)
-        .map((line) => normalizePath(line));
+        .map((line) => normalizePath(line)));
 }
 // Exported for S2's repair writer, which re-validates `exclude` on the
 // way out so the read and write paths agree on what a valid config is.
@@ -195,7 +277,7 @@ export function assertStringArray(value, field, configPath) {
 }
 // Read `<projectRoot>/.codegraph/config.json` and return just the two
 // glob lists the reconciler needs. Read-only: this module never writes
-// that file.
+// that file. Returns a READ-MARKED config — see `readTrackedFiles`.
 export function readCodegraphExcludeConfig(projectRoot) {
     const configPath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME);
     const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
@@ -203,11 +285,40 @@ export function readCodegraphExcludeConfig(projectRoot) {
         throw new Error(`codegraph config ${configPath}: expected a JSON object`);
     }
     const record = parsed;
-    return {
+    return markAsRead({
         include: assertStringArray(record.include, 'include', configPath),
         exclude: assertStringArray(record.exclude, 'exclude', configPath)
+    });
+}
+// Read both shared inputs exactly once, in the one place that owns the
+// readers. Callers that need both axes (the CLI, and anything added later)
+// should call this and pass the result to each inspector rather than
+// letting each inspector read for itself.
+export function readCodegraphProjectInputs(projectRoot) {
+    return {
+        trackedFiles: readTrackedFiles(projectRoot),
+        config: readCodegraphExcludeConfig(projectRoot)
     };
 }
+// ─────────────────────────────────────────────────────────────────────
+// Seam resolution — what each inspector's shared-input seam resolves through
+// ─────────────────────────────────────────────────────────────────────
+// OMITTED (or `undefined`) always means "read it yourself": that is the
+// original, seam-free behaviour and it must stay bit-identical. SUPPLIED
+// means "here is a value you already read" — and the only way to prove that
+// is the read mark, which is why an unmarked value is refused rather than
+// used. An empty marked list is perfectly legal (a repo that tracks nothing
+// really does have none); an empty unmarked one is the false clean.
+export function resolveSharedTrackedFiles(supplied, projectRoot) {
+    return supplied === undefined
+        ? readTrackedFiles(projectRoot)
+        : assertReadProvenance(supplied, 'trackedFiles', 'readTrackedFiles');
+}
+export function resolveSharedConfig(supplied, projectRoot) {
+    return supplied === undefined
+        ? readCodegraphExcludeConfig(projectRoot)
+        : assertReadProvenance(supplied, 'config', 'readCodegraphExcludeConfig');
+}
 // Read-only entry point: resolve the project's tracked files + codegraph
 // config from disk and reconcile them. S2's repair path consumes this
 // result and writes the reduced `exclude` list back; S1 only computes.