kibi-cli 0.18.1 → 1.0.1

package/dist/commands/sync/discovery.js

@@ -15,10 +15,152 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import * as path from "node:path";
+import { promisify } from "node:util";
 import fg from "fast-glob";
 import { getRelationshipsDir } from "../../extractors/relationships.js";
+import { CANONICAL_ENTITY_PATHS, isSymbolsManifestPath, } from "../../utils/kb-paths.js";
 const MARKDOWN_DISCOVERY_IGNORE = ["**/README.md"];
+const execFileAsync = promisify(execFile);
+async function gitTrackedPaths(cwd) {
+    const result = await execFileAsync("git", ["-C", cwd, "ls-files", "--cached", "-z", "--"], { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 });
+    return new Set(result.stdout
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean)
+        .map((value) => value.replaceAll("\\", "/")));
+}
+function pendingSourcePaths(cwd, recoverMissing) {
+    const root = path.join(cwd, ".kb", "recovery", "pending-sources");
+    if (!existsSync(root)) {
+        return { paths: new Map(), recoveredReceipts: [] };
+    }
+    const paths = new Map();
+    const recoveredReceipts = [];
+    for (const name of readdirSync(root)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const receiptPath = path.join(root, name);
+        try {
+            const raw = readFileSync(receiptPath, "utf8");
+            const receipt = JSON.parse(raw);
+            if (typeof receipt.path === "string" &&
+                receipt.path.length > 0 &&
+                typeof receipt.afterHash === "string" &&
+                /^[a-f0-9]{64}$/i.test(receipt.afterHash)) {
+                const relative = receipt.path.replaceAll("\\", "/");
+                const absolute = path.resolve(cwd, relative);
+                if (!absolute.startsWith(`${path.resolve(cwd)}${path.sep}`)) {
+                    throw new Error(`Pending source receipt escapes workspace: ${relative}`);
+                }
+                if (!existsSync(absolute)) {
+                    if (recoverMissing) {
+                        recoveredReceipts.push({
+                            receiptPath,
+                            path: relative,
+                            afterHash: receipt.afterHash,
+                            rawHash: createHash("sha256").update(raw).digest("hex"),
+                        });
+                        continue;
+                    }
+                    throw new Error(`Pending source is missing: ${relative}`);
+                }
+                const actual = createHash("sha256")
+                    .update(readFileSync(absolute))
+                    .digest("hex");
+                if (actual !== receipt.afterHash) {
+                    throw new Error(`Pending source hash drift blocks sync for ${relative}; expected ${receipt.afterHash}, found ${actual}`);
+                }
+                paths.set(relative, receipt.afterHash);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                (/Pending source/.test(error.message) ||
+                    /Pending source receipt/.test(error.message))) {
+                throw error;
+            }
+            // Malformed receipts are ignored; an operator can remove or repair the
+            // receipt through the normal recovery operation.
+        }
+    }
+    return { paths, recoveredReceipts };
+}
+export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
+    const root = path.resolve(cwd, ".kb", "recovery", "pending-sources");
+    for (const receipt of receipts) {
+        const absolute = path.resolve(receipt.receiptPath);
+        if (!absolute.startsWith(`${root}${path.sep}`)) {
+            throw new Error(`Pending source receipt escapes recovery root: ${absolute}`);
+        }
+        if (!existsSync(absolute))
+            continue;
+        // Compare-and-delete: a receipt may have been replaced while the
+        // recovery rebuild was running.  Never remove the replacement merely
+        // because it has the same receipt filename.  Failing closed here is
+        // important: publication may have completed, but recovery must not claim
+        // that pending intent was retired when a newer intent remains.
+        let raw;
+        try {
+            raw = readFileSync(absolute, "utf8");
+        }
+        catch (error) {
+            if (error !== null &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                continue;
+            }
+            throw new Error(`Failed to inspect pending source receipt for ${receipt.path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const rawHash = createHash("sha256").update(raw).digest("hex");
+        if (rawHash !== receipt.rawHash) {
+            throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
+        }
+        let current;
+        try {
+            current = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
+        }
+        if (current.path !== receipt.path ||
+            current.afterHash !== receipt.afterHash) {
+            throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
+        }
+        try {
+            unlinkSync(absolute);
+        }
+        catch (error) {
+            if (error !== null &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                // Another recovery or source publication may have consumed it
+                // already; cleanup is idempotent for that case.
+                continue;
+            }
+            throw new Error(`Failed to retire pending source receipt for ${receipt.path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+function filterTracked(cwd, files, tracked, pending) {
+    const retained = [];
+    for (const file of files) {
+        const relative = path.relative(cwd, file).replaceAll(path.sep, "/");
+        if (tracked.has(relative)) {
+            retained.push(file);
+            continue;
+        }
+        if (pending.has(relative)) {
+            retained.push(file);
+        }
+    }
+    return retained;
+}
 export function normalizeMarkdownPath(pattern) {
     if (!pattern)
         return null;
@@ -26,32 +168,71 @@ export function normalizeMarkdownPath(pattern) {
         return pattern;
     return `${pattern}/**/*.md`;
 }
-export async function discoverSourceFiles(cwd, paths) {
+export async function discoverSourceFiles(cwd, options = {}) {
     const markdownPatterns = [
-        normalizeMarkdownPath(paths.requirements),
-        normalizeMarkdownPath(paths.scenarios),
-        normalizeMarkdownPath(paths.tests),
-        normalizeMarkdownPath(paths.adr),
-        normalizeMarkdownPath(paths.flags),
-        normalizeMarkdownPath(paths.events),
-        normalizeMarkdownPath(paths.facts),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.requirements),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.scenarios),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.tests),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.adr),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.flags),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.events),
+        normalizeMarkdownPath(CANONICAL_ENTITY_PATHS.facts),
     ].filter((p) => Boolean(p));
     const markdownFiles = await fg(markdownPatterns, {
         cwd,
         absolute: true,
         ignore: [...MARKDOWN_DISCOVERY_IGNORE],
     });
-    const entityMarkdownFiles = markdownFiles.filter((file) => !file.endsWith("/README.md"));
-    const manifestFiles = paths.symbols
-        ? await fg(paths.symbols, {
-            cwd,
-            absolute: true,
-        })
-        : [];
+    let entityMarkdownFiles = markdownFiles.filter((file) => !file.endsWith("/README.md"));
+    let manifestFiles = await fg(CANONICAL_ENTITY_PATHS.symbols, {
+        cwd,
+        absolute: true,
+    });
+    const recoveredPendingReceiptPaths = [];
+    if (options.trackedOnly) {
+        const tracked = await gitTrackedPaths(cwd);
+        const pending = pendingSourcePaths(cwd, options.recoverMissingPendingSources === true);
+        recoveredPendingReceiptPaths.push(...pending.recoveredReceipts);
+        entityMarkdownFiles = filterTracked(cwd, entityMarkdownFiles, tracked, new Set(pending.paths.keys()));
+        manifestFiles = filterTracked(cwd, manifestFiles, tracked, new Set(pending.paths.keys()));
+        for (const relative of pending.paths.keys()) {
+            const absolute = path.resolve(cwd, relative);
+            if (!existsSync(absolute))
+                continue;
+            if (relative.endsWith(".md") && !entityMarkdownFiles.includes(absolute)) {
+                entityMarkdownFiles.push(absolute);
+            }
+            if (isSymbolsManifestPath(relative) &&
+                !manifestFiles.includes(absolute)) {
+                manifestFiles.push(absolute);
+            }
+        }
+        // A pending receipt is consumed as soon as Git tracks its file. This is
+        // deliberately best-effort metadata; the source hash remains authoritative.
+        const pendingRoot = path.join(cwd, ".kb", "recovery", "pending-sources");
+        if (options.consumeTrackedPendingReceipts !== false &&
+            existsSync(pendingRoot)) {
+            for (const name of readdirSync(pendingRoot)) {
+                if (!name.endsWith(".json"))
+                    continue;
+                try {
+                    const receipt = JSON.parse(readFileSync(path.join(pendingRoot, name), "utf8"));
+                    if (typeof receipt.path === "string" &&
+                        tracked.has(receipt.path.replaceAll("\\", "/"))) {
+                        unlinkSync(path.join(pendingRoot, name));
+                    }
+                }
+                catch {
+                    // Leave malformed receipts for explicit recovery diagnostics.
+                }
+            }
+        }
+    }
     const relationshipsDir = getRelationshipsDir(path.join(cwd, ".kb"));
     return {
         markdownFiles: entityMarkdownFiles,
         manifestFiles,
         relationshipsDir,
+        recoveredPendingReceiptPaths,
     };
 }

package/dist/commands/sync/extraction.d.ts

@@ -7,10 +7,17 @@ export interface ExtractionOutput {
         message: string;
     }[];
 }
+/**
+ * Authored source identities are workspace-relative POSIX paths. Code symbol
+ * coordinates remain a separate `sourceFile` field, but use the same stable
+ * relative identity so branch-local snapshots do not embed host-specific
+ * absolute paths.
+ */
+export declare function normalizeExtractionSources(results: readonly ExtractionResult[], workspaceRoot: string): ExtractionResult[];
 interface ExtractionDependencies {
     extractFromMarkdown: (file: string) => ExtractionResult;
     extractFromManifest: (file: string) => ExtractionResult[];
 }
-export declare function processExtractions(changedMarkdownFiles: string[], changedManifestFiles: string[], validateOnly: boolean, dependencies?: ExtractionDependencies): Promise<ExtractionOutput>;
+export declare function processExtractions(changedMarkdownFiles: string[], changedManifestFiles: string[], validateOnly: boolean, workspaceRoot?: string, dependencies?: ExtractionDependencies): Promise<ExtractionOutput>;
 export {};
 //# sourceMappingURL=extraction.d.ts.map

package/dist/commands/sync/extraction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/extraction.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,CAAC;IACxD,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,EAAE,CAAC;CAC3D;AAOD,wBAAsB,kBAAkB,CAEtC,oBAAoB,EAAE,MAAM,EAAE,EAC9B,oBAAoB,EAAE,MAAM,EAAE,EAC9B,YAAY,EAAE,OAAO,EACrB,YAAY,GAAE,sBAAwD,GACrE,OAAO,CAAC,gBAAgB,CAAC,CA4C3B"}
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/extraction.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,aAAa,EAAE,MAAM,GACpB,gBAAgB,EAAE,CAoBpB;AAED,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,CAAC;IACxD,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,EAAE,CAAC;CAC3D;AAOD,wBAAsB,kBAAkB,CAEtC,oBAAoB,EAAE,MAAM,EAAE,EAC9B,oBAAoB,EAAE,MAAM,EAAE,EAC9B,YAAY,EAAE,OAAO,EACrB,aAAa,SAAgB,EAC7B,YAAY,GAAE,sBAAwD,GACrE,OAAO,CAAC,gBAAgB,CAAC,CAmD3B"}

package/dist/commands/sync/extraction.js

@@ -15,16 +15,45 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
-import { extractFromManifest } from "../../extractors/manifest.js";
+import * as path from "node:path";
+import { ManifestError, extractFromManifest, } from "../../extractors/manifest.js";
 import { FrontmatterError, extractFromMarkdown, } from "../../extractors/markdown.js";
 import { toCacheKey } from "./cache.js";
+/**
+ * Authored source identities are workspace-relative POSIX paths. Code symbol
+ * coordinates remain a separate `sourceFile` field, but use the same stable
+ * relative identity so branch-local snapshots do not embed host-specific
+ * absolute paths.
+ */
+export function normalizeExtractionSources(results, workspaceRoot) {
+    const root = path.resolve(workspaceRoot);
+    const normalize = (value) => {
+        if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value))
+            return value;
+        const absolute = path.isAbsolute(value) ? path.resolve(value) : undefined;
+        if (absolute?.startsWith(`${root}${path.sep}`)) {
+            return path.relative(root, absolute).replaceAll(path.sep, "/");
+        }
+        return value.replaceAll("\\", "/");
+    };
+    return results.map((result) => ({
+        ...result,
+        entity: {
+            ...result.entity,
+            source: normalize(result.entity.source),
+        },
+        ...(result.sourceFile !== undefined
+            ? { sourceFile: normalize(result.sourceFile) }
+            : {}),
+    }));
+}
 const DEFAULT_EXTRACTION_DEPENDENCIES = {
     extractFromMarkdown,
     extractFromManifest,
 };
 export async function processExtractions(
 // implements REQ-003
-changedMarkdownFiles, changedManifestFiles, validateOnly, dependencies = DEFAULT_EXTRACTION_DEPENDENCIES) {
+changedMarkdownFiles, changedManifestFiles, validateOnly, workspaceRoot = process.cwd(), dependencies = DEFAULT_EXTRACTION_DEPENDENCIES) {
     const results = [];
     const failedCacheKeys = new Set();
     const errors = [];
@@ -45,7 +74,7 @@ changedMarkdownFiles, changedManifestFiles, validateOnly, dependencies = DEFAULT
             else {
                 console.warn(`Warning: Failed to extract from ${file}: ${message}`);
             }
-            failedCacheKeys.add(toCacheKey(file));
+            failedCacheKeys.add(toCacheKey(workspaceRoot, file));
         }
     }
     for (const file of changedManifestFiles) {
@@ -55,13 +84,18 @@ changedMarkdownFiles, changedManifestFiles, validateOnly, dependencies = DEFAULT
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            if (error instanceof ManifestError &&
+                error.classification === "coordinate-artifact" &&
+                !validateOnly) {
+                throw error;
+            }
             if (validateOnly) {
                 errors.push({ file, message });
             }
             else {
                 console.warn(`Warning: Failed to extract from ${file}: ${message}`);
             }
-            failedCacheKeys.add(toCacheKey(file));
+            failedCacheKeys.add(toCacheKey(workspaceRoot, file));
         }
     }
     return { results, failedCacheKeys, errors };

package/dist/commands/sync/manifest.d.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { writeCoordinateArtifact } from "../../extractors/symbol-coordinates.js";
 import { type ManifestSymbolEntry, enrichSymbolCoordinates } from "../../extractors/symbols-coordinator.js";
@@ -10,19 +10,22 @@ interface ManifestDeps {
     existsSync: typeof existsSync;
     parseYAML: typeof parseYAML;
     readFileSync: typeof readFileSync;
+    renameSync: typeof renameSync;
+    unlinkSync: typeof unlinkSync;
     writeFileSync: typeof writeFileSync;
     writeCoordinateArtifact: typeof writeCoordinateArtifact;
     resolveSymbolsManifestPaths: typeof resolveSymbolsManifestPaths;
 }
 export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# Generated coordinates are stored separately in symbol-coordinates.yaml.\n# Run `kibi sync --refresh-symbol-coordinates` to refresh them.\n";
 /**
- * Coarse symbol anchors for which per-symbol coordinates are not expected.
+ * Coarse symbol anchors for which AST per-declaration coordinates are not
+ * expected.
  *
  * Test-suite, module-level-behavior, and config-artifact symbols represent a
  * whole file or configuration unit, and `extractor-miss` explicitly documents
- * that the extractor cannot locate a declaration. These entries legitimately
- * carry no generated coordinates, so coordinate refresh counts them as
- * unchanged instead of flagging them as failures.
+ * that the extractor cannot locate a declaration. Refresh still counts those
+ * entries as unchanged instead of failures, but it persists title-match or
+ * whole-file coordinates so proof-bearing executable symbols can resolve.
  */
 export { COARSE_GRANULARITY_REASONS };
 export declare function isCoarseGranularityAnchor(entry: ManifestSymbolEntry): boolean;

package/dist/commands/sync/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAEL,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAE3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAgBD,eAAO,MAAM,8BAA8B,oQAK1C,CAAC;AAwBF;;;;;;;;GAQG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAED,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CAuIf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAE3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,oQAK1C,CAAC;AAwBF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAsGD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CA0Kf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}

package/dist/commands/sync/manifest.js

@@ -15,10 +15,10 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
-import { writeCoordinateArtifact, } from "../../extractors/symbol-coordinates.js";
+import { coarseCoordinateSpan, coordinateIdentityHash, coordinateSourceHash, parseCoordinateArtifact, writeCoordinateArtifact, } from "../../extractors/symbol-coordinates.js";
 import { enrichSymbolCoordinates, } from "../../extractors/symbols-coordinator.js";
 import { COARSE_GRANULARITY_REASONS, isCoarseGranularityReason, } from "../../public/symbol-granularity.js";
 import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
@@ -29,6 +29,8 @@ function resolveDeps(overrides) {
         existsSync,
         parseYAML,
         readFileSync,
+        renameSync,
+        unlinkSync,
         writeFileSync,
         writeCoordinateArtifact,
         resolveSymbolsManifestPaths,
@@ -62,19 +64,94 @@ const GENERATED_MANIFEST_FIELDS = new Set([
     "coordinatesGeneratedAt",
 ]);
 /**
- * Coarse symbol anchors for which per-symbol coordinates are not expected.
+ * Coarse symbol anchors for which AST per-declaration coordinates are not
+ * expected.
  *
  * Test-suite, module-level-behavior, and config-artifact symbols represent a
  * whole file or configuration unit, and `extractor-miss` explicitly documents
- * that the extractor cannot locate a declaration. These entries legitimately
- * carry no generated coordinates, so coordinate refresh counts them as
- * unchanged instead of flagging them as failures.
+ * that the extractor cannot locate a declaration. Refresh still counts those
+ * entries as unchanged instead of failures, but it persists title-match or
+ * whole-file coordinates so proof-bearing executable symbols can resolve.
  */
 export { COARSE_GRANULARITY_REASONS };
 export function isCoarseGranularityAnchor(entry) {
     const reason = entry.granularity_reason;
     return isCoarseGranularityReason(reason);
 }
+function extractedCoordinates(entry) {
+    const { sourceFile, sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, } = entry;
+    return typeof sourceFile === "string" &&
+        typeof sourceLine === "number" &&
+        typeof sourceColumn === "number" &&
+        typeof sourceEndLine === "number" &&
+        typeof sourceEndColumn === "number"
+        ? {
+            sourceFile,
+            sourceLine,
+            sourceColumn,
+            sourceEndLine,
+            sourceEndColumn,
+        }
+        : null;
+}
+function readSourceText(sourceFile, workspaceRoot, deps) {
+    const absolute = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    if (!deps.existsSync(absolute))
+        return null;
+    try {
+        const content = deps.readFileSync(absolute, "utf8");
+        return typeof content === "string" ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+function fallbackCoarseCoordinates(entry, workspaceRoot, deps) {
+    if (!isCoarseGranularityAnchor(entry))
+        return null;
+    const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : undefined;
+    const title = typeof entry.title === "string" ? entry.title : "";
+    if (sourceFile === undefined)
+        return null;
+    const content = readSourceText(sourceFile, workspaceRoot, deps);
+    if (content === null)
+        return null;
+    return coarseCoordinateSpan(sourceFile, title, content);
+}
+/** Atomically replace `targetPath` with `content` via temp file + rename. */
+function publishAtomically(targetPath, content, deps) {
+    const temporary = `${targetPath}.kibi-tmp-${process.pid}`;
+    try {
+        deps.writeFileSync(temporary, content, "utf8");
+        deps.renameSync(temporary, targetPath);
+    }
+    catch (error) {
+        try {
+            deps.unlinkSync(temporary);
+        }
+        catch {
+            // Temp cleanup is best effort; the original failure propagates.
+        }
+        throw error;
+    }
+}
+function manifestEntryIdentity(entry) {
+    const title = typeof entry.title === "string" ? entry.title : undefined;
+    const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : undefined;
+    const granularityReason = typeof entry.granularity_reason === "string"
+        ? entry.granularity_reason
+        : undefined;
+    return {
+        id: String(entry.id),
+        ...(title === undefined ? {} : { title }),
+        ...(sourceFile === undefined ? {} : { sourceFile }),
+        ...(granularityReason === undefined
+            ? {}
+            : { granularity_reason: granularityReason }),
+    };
+}
 export async function refreshManifestCoordinates(
 // implements REQ-003
 manifestPath, workspaceRoot, deps) {
@@ -83,48 +160,52 @@ manifestPath, workspaceRoot, deps) {
     const rawContent = resolved.readFileSync(manifestPath, "utf8");
     const parsed = resolved.parseYAML(rawContent);
     if (!isRecord(parsed)) {
-        console.warn(`Warning: symbols manifest ${manifestPath} is not a YAML object; skipping coordinate refresh`);
-        return;
+        throw new Error(`symbols manifest ${manifestPath} is not a YAML object; refusing coordinate refresh`);
     }
     const rawSymbols = parsed.symbols;
     if (!Array.isArray(rawSymbols)) {
-        console.warn(`Warning: symbols manifest ${manifestPath} has no symbols array; skipping coordinate refresh`);
-        return;
+        throw new Error(`symbols manifest ${manifestPath} has no symbols array; refusing coordinate refresh`);
     }
     const before = rawSymbols.map((entry) => isRecord(entry)
         ? { ...entry }
         : {});
-    const enriched = await resolved.enrichSymbolCoordinates(before, workspaceRoot);
-    // Build coordinates map keyed by symbol id
-    const coordinatesMap = {};
-    for (const entry of enriched) {
-        const id = typeof entry?.id === "string" ? entry.id : undefined;
-        if (!id)
-            continue;
-        if (typeof entry.sourceFile === "string" &&
-            typeof entry.sourceLine === "number" &&
-            typeof entry.sourceColumn === "number" &&
-            typeof entry.sourceEndLine === "number" &&
-            typeof entry.sourceEndColumn === "number") {
-            coordinatesMap[id] = {
-                sourceFile: entry.sourceFile,
-                sourceLine: entry.sourceLine,
-                sourceColumn: entry.sourceColumn,
-                sourceEndLine: entry.sourceEndLine,
-                sourceEndColumn: entry.sourceEndColumn,
-            };
+    let coordinatesPath = null;
+    if (shouldRefreshCoordinates) {
+        coordinatesPath =
+            resolved.resolveSymbolsManifestPaths(workspaceRoot).coordinatesPath;
+        if (resolved.existsSync(coordinatesPath)) {
+            const existing = parseCoordinateArtifact(String(resolved.readFileSync(coordinatesPath, "utf8")));
+            if (existing.status === "invalid") {
+                throw new Error(`Failed to parse coordinate artifact ${coordinatesPath}: ${existing.reason}`);
+            }
         }
     }
-    // Optionally write the coordinate artifact to the coordinates path when explicitly requested
+    const enriched = await resolved.enrichSymbolCoordinates(before, workspaceRoot);
+    // Publish the generated coordinate artifact when explicitly requested.
+    // Parse and I/O failures are fatal so sync never advances cache state on a
+    // partially published compiler dependency. Symbols without extractable
+    // coordinates stay absent from the artifact; coverage keeps their gap visible.
+    let refreshedArtifactBytes = null;
     if (shouldRefreshCoordinates) {
-        try {
-            const coordinatesPath = resolved.resolveSymbolsManifestPaths(workspaceRoot).coordinatesPath;
-            const artifactContent = resolved.writeCoordinateArtifact(coordinatesMap);
-            resolved.writeFileSync(coordinatesPath, artifactContent, "utf8");
-        }
-        catch (err) {
-            console.warn(`Warning: Failed to write symbol-coordinates artifact: ${String(err)}`);
+        const boundEntries = {};
+        for (const entry of enriched) {
+            const id = typeof entry?.id === "string" ? entry.id : undefined;
+            if (!id)
+                continue;
+            const span = extractedCoordinates(entry) ??
+                fallbackCoarseCoordinates(entry, workspaceRoot, resolved);
+            if (span === null)
+                continue;
+            const sourceText = readSourceText(span.sourceFile, workspaceRoot, resolved);
+            if (sourceText === null)
+                continue;
+            boundEntries[id] = {
+                ...span,
+                identityHash: coordinateIdentityHash(manifestEntryIdentity(entry)),
+                sourceHash: coordinateSourceHash(sourceText),
+            };
         }
+        refreshedArtifactBytes = resolved.writeCoordinateArtifact(boundEntries);
     }
     // Coordinates belong exclusively to the generated artifact. Always strip
     // them from the authored manifest so consecutive refreshes are idempotent.
@@ -162,8 +243,30 @@ manifestPath, workspaceRoot, deps) {
         sortKeys: false,
     });
     const nextContent = `${SYMBOLS_MANIFEST_COMMENT_BLOCK}${dumped}`;
-    if (rawContent !== nextContent) {
-        resolved.writeFileSync(manifestPath, nextContent, "utf8");
+    let manifestPublished = false;
+    try {
+        if (rawContent !== nextContent) {
+            publishAtomically(manifestPath, nextContent, resolved);
+            manifestPublished = true;
+        }
+        if (refreshedArtifactBytes !== null && coordinatesPath !== null) {
+            publishAtomically(coordinatesPath, refreshedArtifactBytes, resolved);
+        }
+    }
+    catch (error) {
+        if (manifestPublished) {
+            try {
+                const current = resolved.readFileSync(manifestPath, "utf8");
+                if (current !== nextContent) {
+                    throw new Error(`symbol manifest changed after publication; refusing rollback: ${manifestPath}`);
+                }
+                publishAtomically(manifestPath, rawContent, resolved);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], `Coordinate artifact publication failed and manifest rollback failed: ${manifestPath}`);
+            }
+        }
+        throw error;
     }
     console.log(`\u2713 Refreshed symbol coordinates in ${path.relative(workspaceRoot, manifestPath)} (refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed})`);
 }

package/dist/commands/sync/persistence.d.ts

@@ -5,7 +5,16 @@ export interface PersistenceResult {
     relationshipCount: number;
     kbModified: boolean;
 }
-export declare function persistEntities(prolog: PrologProcess, results: ExtractionResult[], entityIds: Set<string>): Promise<{
+/** Remove entities owned by changed/deleted source files before re-upserting. */
+export declare function retractEntitiesForSources(prolog: PrologProcess, sourceFiles: readonly string[]): Promise<number>;
+/** Remove an exact entity delta without scanning every indexed source. */
+export declare function retractEntitiesById(prolog: PrologProcess, entityIds: readonly string[]): Promise<number>;
+/** Clear outgoing inline relationships for entities whose payload changed. */
+export declare function retractEntityRelationshipsById(prolog: PrologProcess, entityIds: readonly string[]): Promise<void>;
+export declare function retractRelationships(prolog: PrologProcess, relationships: readonly ExtractedRelationship[]): Promise<number>;
+export declare function persistEntities(prolog: PrologProcess, results: ExtractionResult[], entityIds: Set<string>, options?: {
+    loadExistingEntityIds?: boolean;
+}): Promise<{
     entityCount: number;
     kbModified: boolean;
 }>;

package/dist/commands/sync/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgHrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAwKvD;AA6BD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA+K7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgHrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA8CD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA4OvD;AA6BD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA0N7D"}