knodin 0.6.0 → 0.7.4

package/dist/src/repository-management.js

@@ -11,6 +11,139 @@ const MAX_GIT_ERROR_BYTES = 16 * 1024;
 const MAX_TRACKED_PATH_BYTES = 1024 * 1024;
 const MAX_DOCUMENT_CANDIDATES = 20;
 const SKIPPED_DIRECTORIES = new Set([".git", ".knodin", "node_modules"]);
+export function repositorySignalInspectionLimit(options) {
+    const bytes = Math.min(options.byteBudget ?? 65_536, (options.tokenBudget ?? 16_384) * 4);
+    return Math.max(1, Math.min(options.itemBudget ?? 100, Math.floor(bytes / 256)));
+}
+const SIGNAL_MARKERS = [
+    ".circleci/config.yml",
+    ".github/workflows",
+    ".gitlab-ci.yml",
+    ".mcp.json",
+    ".vscode/mcp.json",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "Jenkinsfile",
+    "azure-pipelines.yml",
+    "sonar-project.properties",
+];
+const HOOK_CONFIGS = [
+    { path: "lefthook.yml", manager: "lefthook", readPaths: ["lefthook.yml"] },
+    { path: "lefthook.yaml", manager: "lefthook", readPaths: ["lefthook.yaml"] },
+    {
+        path: ".husky",
+        manager: "husky",
+        readPaths: [".husky/pre-commit", ".husky/commit-msg", ".husky/pre-push"],
+    },
+    {
+        path: ".pre-commit-config.yaml",
+        manager: "pre-commit",
+        readPaths: [".pre-commit-config.yaml"],
+    },
+];
+const MAX_HOOK_CONFIG_BYTES = 64 * 1024;
+function parseRemote(name, raw) {
+    try {
+        const normalized = /^[^@/:]+@[^:]+:.+/.test(raw)
+            ? raw.replace(/^([^@/:]+)@([^:]+):/, "ssh://$1@$2/")
+            : raw;
+        const url = new URL(normalized);
+        const owner = url.pathname.replace(/^\//, "").split("/")[0];
+        if (!url.hostname || !owner)
+            return undefined;
+        return { name, host: url.hostname.toLowerCase(), owner };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Inspect a fixed, path-only allowlist plus bounded hook configuration. */
+export async function detectRepositorySignals(repository) {
+    const markerFiles = [];
+    for (const marker of SIGNAL_MARKERS) {
+        try {
+            await fs.promises.lstat(path.join(repository, marker));
+            markerFiles.push(marker);
+        }
+        catch { }
+    }
+    let hookManager;
+    let aidevTrackReferenced;
+    for (const config of HOOK_CONFIGS) {
+        try {
+            await fs.promises.lstat(path.join(repository, config.path));
+            if (!hookManager) {
+                hookManager = config.manager;
+                aidevTrackReferenced = false;
+            }
+            let remainingBytes = MAX_HOOK_CONFIG_BYTES;
+            for (const readPath of config.readPaths) {
+                if (remainingBytes === 0 || aidevTrackReferenced)
+                    break;
+                try {
+                    const readStat = await fs.promises.lstat(path.join(repository, readPath));
+                    if (!readStat.isFile())
+                        continue;
+                    const handle = await fs.promises.open(path.join(repository, readPath), "r");
+                    try {
+                        const buffer = Buffer.alloc(Math.min(readStat.size, remainingBytes));
+                        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                        remainingBytes -= bytesRead;
+                        aidevTrackReferenced = /(?:^|[^\w-])aidev-track(?:$|[^\w-])/m.test(buffer.subarray(0, bytesRead).toString("utf8"));
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                }
+                catch { }
+            }
+            break;
+        }
+        catch { }
+    }
+    const remotes = [];
+    try {
+        const lines = child_process.execFileSync(gitExecutable(), ["remote", "-v"], {
+            cwd: repository,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: MAX_GIT_ERROR_BYTES,
+        });
+        const seen = new Set();
+        for (const line of lines.split("\n")) {
+            const [name, raw] = line.trim().split(/\s+/);
+            if (!name || !raw || seen.has(name))
+                continue;
+            const remote = parseRemote(name, raw);
+            if (remote) {
+                seen.add(name);
+                remotes.push(remote);
+            }
+        }
+    }
+    catch { }
+    remotes.sort((a, b) => a.name.localeCompare(b.name));
+    const ciProviders = [
+        markerFiles.includes(".github/workflows") ? "github-actions" : undefined,
+        markerFiles.includes(".gitlab-ci.yml") ? "gitlab-ci" : undefined,
+        markerFiles.includes(".circleci/config.yml") ? "circleci" : undefined,
+        markerFiles.includes("azure-pipelines.yml") ? "azure-pipelines" : undefined,
+        markerFiles.includes("Jenkinsfile") ? "jenkins" : undefined,
+    ].filter((value) => Boolean(value));
+    const agentConfigs = markerFiles.filter((marker) => marker === "AGENTS.md" || marker === "CLAUDE.md");
+    return {
+        ...(hookManager ? { hookManager } : {}),
+        ...(markerFiles.length ? { markerFiles } : {}),
+        ...(remotes.length ? { remotes } : {}),
+        ...(ciProviders.length ? { ciProviders } : {}),
+        ...(agentConfigs.length ? { agentConfigs } : {}),
+        ...(aidevTrackReferenced === undefined ? {} : { aidevTrackReferenced }),
+    };
+}
+/** Preserve the pre-C79 byte shape unless the caller explicitly opts in. */
+export function withRepositorySignals(record, enabled, signals) {
+    return enabled ? { ...record, signals } : record;
+}
 function gitTopLevel(directory) {
     return child_process
         .execFileSync(gitExecutable(), ["rev-parse", "--show-toplevel"], {
@@ -175,6 +308,9 @@ function parseRepositoryOption(args, index, cwd, command, state) {
         case "--json":
             state.json = true;
             return index;
+        case "--signals":
+            state.signals = true;
+            return index;
         case "--allow-partial":
             state.allowPartial = true;
             return index;
@@ -232,6 +368,7 @@ export function parseRepositoryCommandArgs(args, cwd) {
         include: [],
         exclude: [],
         allowPartial: false,
+        signals: false,
     };
     let index = 1;
     while (index < args.length) {
@@ -250,17 +387,22 @@ export function parseRepositoryCommandArgs(args, cwd) {
         throw new Error(`knodin repos ${command}: --dry-run applies only to init`);
     if (state.manifestPath && command !== "init")
         throw new Error(`knodin repos ${command}: --manifest applies only to init`);
+    if (state.signals && command !== "discover")
+        throw new Error(`knodin repos ${command}: --signals applies only to discover`);
     if (command !== "search" &&
         command !== "init" &&
         (state.include.length > 0 || state.exclude.length > 0))
         throw new Error(`knodin repos ${command}: repository selectors apply only to init or search`);
     if (command !== "search" &&
+        !(command === "discover" && state.signals) &&
         (state.allowPartial ||
             state.itemBudget ||
             state.byteBudget ||
             state.tokenBudget ||
             state.cursor))
         throw new Error(`knodin repos ${command}: search options apply only to search`);
+    if (command === "discover" && state.cursor)
+        throw new Error("knodin repos discover: --cursor applies only to search");
     return { command, ...state };
 }
 /**

package/dist/src/response-budget.js

@@ -1,5 +1,6 @@
 const encoder = new TextEncoder();
 export const MIN_RESPONSE_BUDGET_BYTES = 256;
+const MAX_REPORTED_TOTAL_PATHS = 128;
 function bytes(value) {
     return encoder.encode(JSON.stringify(value)).byteLength;
 }
@@ -67,8 +68,14 @@ export function applyResponseBudget(value, operation, request, defaults) {
             : { result: payload };
     const totals = {};
     let truncated = false;
-    for (const entry of collectArrays(root)) {
+    const initialArrays = collectArrays(root);
+    const reportedTotals = [...initialArrays]
+        .sort((left, right) => left.path.split("/").length - right.path.split("/").length ||
+        left.path.localeCompare(right.path))
+        .slice(0, MAX_REPORTED_TOTAL_PATHS);
+    for (const entry of reportedTotals)
         totals[entry.path] = entry.value.length;
+    for (const entry of initialArrays) {
         if (entry.value.length > itemLimit) {
             entry.value.splice(itemLimit);
             truncated = true;
@@ -82,6 +89,9 @@ export function applyResponseBudget(value, operation, request, defaults) {
         estimatedTokens: 0,
         truncated: false,
         totals,
+        ...(initialArrays.length > reportedTotals.length
+            ? { omittedTotalPaths: initialArrays.length - reportedTotals.length }
+            : {}),
     };
     root.responseBudget = metadata;
     // Preserve collection contracts and identifiers where possible: large source,

package/dist/src/server.js

@@ -11,12 +11,25 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { recordDiagnosticFailure } from "./diagnostics.js";
 import { getKnodinTools, handleKnodinTool } from "./tools/knodin-tools.js";
 import { KNODIN_VERSION } from "./version.js";
+export function recordMcpDiagnosticFailure(args, error, defaultRepo = process.cwd()) {
+    const effectiveRepo = typeof args?.repoPath === "string" ? args.repoPath : defaultRepo;
+    const diagnostic = recordDiagnosticFailure(effectiveRepo, {
+        surface: "mcp",
+        operation: typeof args?.operation === "string" ? args.operation : "unknown",
+        phase: "dispatch",
+        error,
+    });
+    return diagnostic.recorded
+        ? new Error(`${error instanceof Error ? error.message : String(error)} [diagnostic ${diagnostic.correlationId}]`, { cause: error })
+        : error;
+}
 export function createServer() {
     const server = new Server({ name: "knodin", version: KNODIN_VERSION }, {
         capabilities: { tools: {} },
-        instructions: "Use knodin first for cold or unfamiliar codebase work: context to orient, explain for source-evidenced symbol context, query impact before meaningful edits, and review before handoff. Prefer direct reads for exact literals, non-code files, or files just edited this turn. If status reports repair-needed, repair before relying on graph evidence.",
+        instructions: "Use knodin first for cold or unfamiliar codebase work: context to orient, explain for source-evidenced symbol context, query impact before meaningful edits, and review before handoff. Prefer direct reads for exact literals, non-code files, or files just edited this turn. If status reports repair-needed, follow its typed repair steps: repair graph damage or init displaced lifecycle routing before relying on graph evidence.",
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: getKnodinTools(),
@@ -26,7 +39,14 @@ export function createServer() {
         if (name !== "knodin") {
             throw new Error(`unknown tool: ${name}`);
         }
-        const result = await handleKnodinTool(args);
+        let result;
+        try {
+            result = await handleKnodinTool(args);
+        }
+        catch (error) {
+            const values = args;
+            throw recordMcpDiagnosticFailure(values, error);
+        }
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };

package/dist/src/structural-fast-path.js

@@ -0,0 +1,338 @@
+import fs from "node:fs";
+import path from "node:path";
+import { contentFingerprint, readStructuralSnapshot, } from "./structural-snapshot.js";
+function exactFile(repo, file) {
+    try {
+        return (contentFingerprint(fs.readFileSync(path.resolve(repo, file.path))) === file.contentFingerprint);
+    }
+    catch {
+        return false;
+    }
+}
+const DIRECT_FILE_EXTENSIONS = new Set([
+    ".cjs",
+    ".cs",
+    ".cts",
+    ".go",
+    ".java",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".mts",
+    ".py",
+    ".rs",
+    ".ts",
+    ".tsx",
+]);
+function lexicalEndLine(lines, startIndex, python) {
+    if (python) {
+        const indent = /^\s*/.exec(lines[startIndex])?.[0].length ?? 0;
+        let end = startIndex + 1;
+        for (let index = startIndex + 1; index < lines.length; index++) {
+            const line = lines[index];
+            if (line.trim() && (/^\s*/.exec(line)?.[0].length ?? 0) <= indent)
+                break;
+            end = index + 1;
+        }
+        return end;
+    }
+    let depth = 0;
+    let opened = false;
+    for (let index = startIndex; index < lines.length; index++) {
+        for (const character of lines[index]) {
+            if (character === "{") {
+                opened = true;
+                depth++;
+            }
+            else if (character === "}")
+                depth--;
+        }
+        if (opened && depth <= 0)
+            return index + 1;
+        if (!opened && /[;}]\s*$/.test(lines[index]))
+            return index + 1;
+    }
+    return startIndex + 1;
+}
+function genericFunctionSymbol(line) {
+    const opening = line.indexOf("(");
+    if (opening <= 0)
+        return null;
+    let depth = 0;
+    let closing = -1;
+    for (let index = opening; index < line.length; index += 1) {
+        if (line[index] === "(")
+            depth += 1;
+        if (line[index] !== ")")
+            continue;
+        depth -= 1;
+        if (depth === 0) {
+            closing = index;
+            break;
+        }
+    }
+    if (closing < 0)
+        return null;
+    const suffix = line.slice(closing + 1).trimStart();
+    if (!suffix.startsWith("{") && !suffix.startsWith("=>"))
+        return null;
+    const prefix = line.slice(0, opening).trim();
+    if (/[=;{}()]/.test(prefix))
+        return null;
+    const tokens = prefix.split(/\s+/);
+    const symbol = tokens.at(-1) ?? "";
+    return tokens.length >= 2 && /^[A-Za-z_$][\w$]*$/.test(symbol) ? symbol : null;
+}
+function firstPatternSymbol(line, patterns) {
+    for (const { kind, expression } of patterns) {
+        const match = expression.exec(line);
+        if (match)
+            return { kind, symbol: match[1] };
+    }
+    return null;
+}
+function directSymbols(filePath, content) {
+    const extension = path.extname(filePath).toLowerCase();
+    const python = extension === ".py";
+    const lines = content.split(/\r?\n/);
+    const symbols = [];
+    const patterns = python
+        ? [
+            { kind: "class", expression: /^\s*class\s+([A-Za-z_$][\w$]*)\b/ },
+            { kind: "function", expression: /^\s*(?:async\s+)?def\s+([A-Za-z_$][\w$]*)\s*\(/ },
+        ]
+        : [
+            {
+                kind: "class",
+                expression: /^\s*(?:(?:export|public|private|protected|internal|abstract|final|sealed|static)\s+)*(?:class|interface|enum|struct|trait|record|type)\s+([A-Za-z_$][\w$]*)\b/,
+            },
+            {
+                kind: "function",
+                expression: /^\s*(?:(?:export|public|private|protected|internal|async|static|final|pub(?:\([^)]*\))?)\s+)*(?:func|fn|function)\s+([A-Za-z_$][\w$]*)\s*\(/,
+            },
+            {
+                kind: "function",
+                expression: /^\s*(?:(?:export|const|let|var|public|private|protected|static|readonly)\s+)*([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/,
+            },
+        ];
+    for (const [index, line] of lines.entries()) {
+        let found = firstPatternSymbol(line, patterns);
+        if (!found && !python) {
+            const symbol = genericFunctionSymbol(line);
+            if (symbol)
+                found = { kind: "function", symbol };
+        }
+        if (found) {
+            const { kind, symbol } = found;
+            const visibility = line.match(/\b(public|private|protected|internal)\b/)?.[1] ??
+                (python && symbol.startsWith("_") ? "private" : "default");
+            symbols.push({
+                identity: null,
+                symbol,
+                kind,
+                line: index + 1,
+                endLine: lexicalEndLine(lines, index, python),
+                signature: line
+                    .trim()
+                    .split(/\s*(?:\{|=>)\s*/, 1)[0]
+                    .slice(0, 500),
+                visibility,
+                exported: /\bexport\b/.test(line) || /\bpub\b/.test(line),
+                evidenceQuality: "lexical-structural-fallback",
+            });
+        }
+    }
+    return symbols;
+}
+function directFile(repo, filePath) {
+    if (!DIRECT_FILE_EXTENSIONS.has(path.extname(filePath).toLowerCase()))
+        return null;
+    const root = fs.realpathSync(repo);
+    const absolute = path.resolve(root, filePath);
+    let real;
+    try {
+        real = fs.realpathSync(absolute);
+    }
+    catch {
+        return null;
+    }
+    const relative = path.relative(root, real);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    const content = fs.readFileSync(real, "utf8");
+    return {
+        path: relative.split(path.sep).join("/"),
+        sizeBytes: Buffer.byteLength(content),
+        mtimeMs: fs.statSync(real).mtimeMs,
+        contentFingerprint: contentFingerprint(content),
+        symbols: directSymbols(filePath, content),
+    };
+}
+export function runStructuralFastPath(repo, pattern, target, limit = 100) {
+    const snapshot = readStructuralSnapshot(repo);
+    if (!snapshot && pattern !== "file_summary")
+        return null;
+    let matching = (snapshot?.files ?? []).filter((file) => !target || file.path.includes(target));
+    if (pattern === "file_summary") {
+        const indexed = matching.find((file) => file.path === target);
+        if (!indexed || !exactFile(repo, indexed)) {
+            const direct = directFile(repo, target);
+            if (!direct)
+                return null;
+            matching = [direct];
+        }
+    }
+    else if (pattern === "batch_outline") {
+        matching = matching.flatMap((file) => {
+            if (exactFile(repo, file))
+                return [file];
+            const direct = directFile(repo, file.path);
+            return direct ? [direct] : [];
+        });
+    }
+    let rows = [];
+    let fingerprint;
+    let fresh = false;
+    if (pattern === "project_overview") {
+        fresh = matching.every((file) => {
+            try {
+                const stat = fs.statSync(path.resolve(repo, file.path));
+                return stat.size === file.sizeBytes && stat.mtimeMs === file.mtimeMs;
+            }
+            catch {
+                return false;
+            }
+        });
+        const directories = new Map();
+        for (const file of matching) {
+            const directory = file.path.includes("/") ? file.path.split("/", 1)[0] : ".";
+            const value = directories.get(directory) ?? { fileCount: 0, sizeBytes: 0 };
+            value.fileCount += 1;
+            value.sizeBytes += file.sizeBytes;
+            directories.set(directory, value);
+        }
+        rows = [...directories]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([symbol, value]) => ({ symbol, kind: "directory", ...value }));
+        fingerprint = contentFingerprint(JSON.stringify(matching.map(({ path: file, contentFingerprint: hash }) => [file, hash])));
+    }
+    else {
+        const files = pattern === "file_summary" ? matching.filter((file) => file.path === target) : matching;
+        fresh = files.length > 0 && files.every((file) => exactFile(repo, file));
+        fingerprint =
+            files.length === 1
+                ? files[0].contentFingerprint
+                : contentFingerprint(JSON.stringify(files.map((file) => [file.path, file.contentFingerprint])));
+        rows = files.flatMap((file) => file.symbols.map((symbol) => ({ ...symbol, file: file.path })));
+    }
+    const selected = rows.slice(0, limit);
+    return {
+        pattern,
+        target,
+        count: selected.length,
+        results: selected,
+        ...(rows.length > selected.length ? { hasMore: true } : {}),
+        staleness: fresh ? "fresh" : "unknown",
+        graphEnriched: false,
+        evidence: {
+            ...(pattern === "file_summary" ? { path: target } : {}),
+            contentFingerprint: fingerprint,
+            evidenceQuality: matching.some((file) => file.symbols.some((symbol) => symbol.evidenceQuality === "lexical-structural-fallback"))
+                ? "direct-lexical-parser"
+                : "indexed-structural-snapshot",
+            uniqueness: pattern === "project_overview" ? "not-applicable" : "file-scoped-only",
+            evidenceGeneratedAt: snapshot?.generatedAt ?? new Date().toISOString(),
+        },
+        upgrade: pattern === "file_summary"
+            ? { operation: "explain", target }
+            : pattern === "project_overview"
+                ? { operation: "query", pattern: "architecture_overview", target: "" }
+                : { operation: "query", pattern: "impact", target },
+    };
+}
+export function runExactSymbolFastPath(repo, symbol, filePath) {
+    const snapshot = readStructuralSnapshot(repo);
+    const indexed = snapshot?.files.find((candidate) => candidate.path === filePath);
+    const file = indexed && exactFile(repo, indexed) ? indexed : directFile(repo, filePath);
+    if (!file)
+        return null;
+    const matches = file.symbols.filter((candidate) => candidate.symbol === symbol);
+    if (matches.length === 0)
+        return null;
+    const fresh = exactFile(repo, file);
+    const evidence = {
+        path: filePath,
+        contentFingerprint: file.contentFingerprint,
+        evidenceQuality: file.symbols.some((candidate) => candidate.evidenceQuality === "lexical-structural-fallback")
+            ? "direct-lexical-parser"
+            : "indexed-structural-snapshot",
+        uniqueness: "file-scoped-only",
+        evidenceGeneratedAt: snapshot?.generatedAt ?? new Date().toISOString(),
+    };
+    if (matches.length > 1) {
+        return {
+            symbol,
+            file: filePath,
+            ambiguity: {
+                candidates: matches.map((match) => ({
+                    identity: match.identity ?? "",
+                    file: filePath,
+                    kind: match.kind,
+                    line: match.line,
+                })),
+            },
+            staleness: fresh ? "fresh" : "unknown",
+            graphEnriched: false,
+            evidence,
+            upgrade: { operation: "explain", target: symbol },
+        };
+    }
+    const match = matches[0];
+    const lines = fs.readFileSync(path.resolve(repo, filePath), "utf8").split(/\r?\n/);
+    const source = fresh
+        ? lines
+            .slice(match.line - 1, match.endLine)
+            .map((line, offset) => `${match.line + offset}: ${line}`)
+            .join("\n")
+        : undefined;
+    return {
+        symbol,
+        ...(match.identity ? { identity: match.identity } : {}),
+        file: filePath,
+        ...(source ? { source } : {}),
+        staleness: fresh ? "fresh" : "unknown",
+        graphEnriched: false,
+        evidence,
+        upgrade: { operation: "explain", target: symbol },
+    };
+}
+export function tryStructuralFastPath(argv, cwd = process.cwd()) {
+    const valueAfter = (flag) => {
+        const index = argv.indexOf(flag);
+        return index >= 0
+            ? argv[index + 1]
+            : argv.find((value) => value.startsWith(`${flag}=`))?.slice(flag.length + 1);
+    };
+    if (argv[0] === "explain" && argv[1] && valueAfter("--file")) {
+        const repo = path.resolve(valueAfter("--repo") ?? cwd);
+        const result = runExactSymbolFastPath(repo, argv[1], valueAfter("--file"));
+        if (!result)
+            return false;
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return true;
+    }
+    if (argv[0] !== "query" ||
+        !["file_summary", "batch_outline", "project_overview"].includes(argv[1] ?? ""))
+        return false;
+    const pattern = argv[1];
+    const repo = path.resolve(valueAfter("--repo") ?? cwd);
+    const target = pattern === "project_overview" ? "" : (argv[2] ?? "");
+    const limit = Number(valueAfter("--limit") ?? 100);
+    if (!target && pattern !== "project_overview")
+        return false;
+    const result = runStructuralFastPath(repo, pattern, target, Number.isInteger(limit) && limit > 0 ? limit : 100);
+    if (!result)
+        return false;
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return true;
+}

package/dist/src/structural-snapshot.js

@@ -0,0 +1,33 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export const STRUCTURAL_SNAPSHOT_VERSION = 1;
+export function contentFingerprint(content) {
+    return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+export function structuralSnapshotPath(repo) {
+    return path.join(path.resolve(repo), ".knodin", "structural-v1.json");
+}
+export function writeStructuralSnapshot(repo, files) {
+    const destination = structuralSnapshotPath(repo);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    const snapshot = {
+        schemaVersion: STRUCTURAL_SNAPSHOT_VERSION,
+        generatedAt: new Date().toISOString(),
+        files: [...files].sort((left, right) => left.path.localeCompare(right.path)),
+    };
+    const temporary = `${destination}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(snapshot)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, destination);
+}
+export function readStructuralSnapshot(repo) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(structuralSnapshotPath(repo), "utf8"));
+        return parsed?.schemaVersion === STRUCTURAL_SNAPSHOT_VERSION && Array.isArray(parsed.files)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}