kibi-cli 0.19.0 → 2.0.0

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

@@ -22,12 +22,25 @@ export type SyncCache = {
     semanticHashes: Record<string, string>;
     semanticContracts: Record<string, boolean>;
 };
-export declare const SYNC_CACHE_VERSION = 1;
+/**
+ * v2: cache identities are workspace-root relative instead of process-cwd
+ * relative, and symbol manifests are fingerprinted together with their
+ * generated coordinate artifact so artifact-only changes are never mistaken
+ * for no-ops.
+ */
+export declare const SYNC_CACHE_VERSION = 2;
 export declare const SYNC_CACHE_TTL_MS: number;
-export declare function toCacheKey(filePath: string): string;
-export declare function hashFile(filePath: string, deps?: Partial<SyncCacheDeps>): string;
+export declare function toCacheKey(workspaceRoot: string, filePath: string): string;
+export declare function hashFile(workspaceRoot: string, filePath: string, deps?: Partial<SyncCacheDeps>): string;
 /** Deterministically hash a JSON-compatible compiler payload. */
 export declare function hashNormalized(value: unknown): string;
+/**
+ * Composite fingerprint for a symbol manifest and its generated coordinate
+ * artifact. The artifact is a compiler dependency of the manifest, so its
+ * existence, emptiness, content, and deletion must all change the effective
+ * source hash even though the authored YAML bytes stay identical.
+ */
+export declare function hashManifestWithCoordinates(workspaceRoot: string, manifestPath: string, coordinatesPath: string | null, deps?: Partial<SyncCacheDeps>): string;
 export declare function readSyncCache(cachePath: string, deps?: Partial<SyncCacheDeps>): SyncCache;
 export declare function writeSyncCache(cachePath: string, cache: SyncCache, deps?: Partial<SyncCacheDeps>): void;
 export declare function copySyncCache(livePath: string, stagingPath: string, deps?: Partial<SyncCacheDeps>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/cache.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7E,UAAU,aAAa;IACrB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAaD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C,CAAC;AAEF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,QAAQ,CAEtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAIR;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAerD;AAED,wBAAgB,aAAa,CAE3B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,SAAS,CAuDX;AAED,wBAAgB,cAAc,CAE5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CAaN;AAED,wBAAgB,aAAa,CAE3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CASN"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/cache.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7E,UAAU,aAAa;IACrB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAaD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED,wBAAgB,QAAQ,CAEtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAIR;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAerD;AAED;;;;;GAKG;AAEH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CA4FR;AAED,wBAAgB,aAAa,CAE3B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,SAAS,CAuDX;AAED,wBAAgB,cAAc,CAE5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CAaN;AAED,wBAAgB,aAAa,CAE3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CASN"}

package/dist/commands/sync/cache.js

@@ -18,6 +18,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
+import { load as parseYAML } from "js-yaml";
 function resolveDeps(overrides) {
     return {
         createHash,
@@ -28,14 +29,24 @@ function resolveDeps(overrides) {
         ...overrides,
     };
 }
-export const SYNC_CACHE_VERSION = 1;
+/**
+ * v2: cache identities are workspace-root relative instead of process-cwd
+ * relative, and symbol manifests are fingerprinted together with their
+ * generated coordinate artifact so artifact-only changes are never mistaken
+ * for no-ops.
+ */
+export const SYNC_CACHE_VERSION = 2;
 export const SYNC_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-export function toCacheKey(filePath) {
-    return path.relative(process.cwd(), filePath).split(path.sep).join("/");
+export function toCacheKey(workspaceRoot, filePath) {
+    const root = path.resolve(workspaceRoot);
+    const target = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(root, filePath);
+    return path.relative(root, target).split(path.sep).join("/");
 }
 export function hashFile(
 // implements REQ-003
-filePath, deps) {
+workspaceRoot, filePath, deps) {
     const resolved = resolveDeps(deps);
     const content = resolved.readFileSync(filePath);
     return resolved.createHash("sha256").update(content).digest("hex");
@@ -56,6 +67,102 @@ export function hashNormalized(value) {
         .update(JSON.stringify(normalize(value)))
         .digest("hex");
 }
+/**
+ * Composite fingerprint for a symbol manifest and its generated coordinate
+ * artifact. The artifact is a compiler dependency of the manifest, so its
+ * existence, emptiness, content, and deletion must all change the effective
+ * source hash even though the authored YAML bytes stay identical.
+ */
+// implements REQ-generated-coordinate-persistence
+export function hashManifestWithCoordinates(workspaceRoot, manifestPath, coordinatesPath, deps) {
+    const resolved = resolveDeps(deps);
+    const manifestContent = resolved.readFileSync(manifestPath);
+    const manifestHash = resolved
+        .createHash("sha256")
+        .update(manifestContent)
+        .digest("hex");
+    let artifactState = "missing";
+    let artifactHash = "";
+    if (coordinatesPath !== null && resolved.existsSync(coordinatesPath)) {
+        const content = resolved.readFileSync(coordinatesPath);
+        artifactState = content.length > 0 ? "present" : "empty";
+        artifactHash = resolved.createHash("sha256").update(content).digest("hex");
+    }
+    const referencedSources = [];
+    let symbols = [];
+    try {
+        const parsed = parseYAML(manifestContent.toString());
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed) &&
+            Array.isArray(parsed.symbols)) {
+            symbols = parsed.symbols;
+        }
+    }
+    catch {
+        // Extraction owns the user-facing YAML diagnostic. Fingerprinting must
+        // still complete so malformed manifests cannot look cache-current.
+    }
+    const sourcePaths = new Set();
+    for (const value of symbols) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            continue;
+        }
+        const symbol = value;
+        const sourceFile = typeof symbol.sourceFile === "string"
+            ? symbol.sourceFile
+            : typeof symbol.source === "string"
+                ? symbol.source
+                : undefined;
+        if (sourceFile !== undefined && sourceFile.length > 0) {
+            sourcePaths.add(sourceFile);
+        }
+    }
+    const root = path.resolve(workspaceRoot);
+    for (const sourceFile of [...sourcePaths].sort()) {
+        try {
+            const absolute = path.isAbsolute(sourceFile)
+                ? path.resolve(sourceFile)
+                : path.resolve(root, sourceFile);
+            const relative = path.relative(root, absolute);
+            if (relative === ".." || relative.startsWith(`..${path.sep}`)) {
+                referencedSources.push({
+                    path: sourceFile,
+                    state: "outside-workspace",
+                });
+            }
+            else if (!resolved.existsSync(absolute)) {
+                referencedSources.push({ path: sourceFile, state: "missing" });
+            }
+            else {
+                try {
+                    referencedSources.push({
+                        path: sourceFile,
+                        state: "present",
+                        sha256: resolved
+                            .createHash("sha256")
+                            .update(resolved.readFileSync(absolute))
+                            .digest("hex"),
+                    });
+                }
+                catch {
+                    referencedSources.push({ path: sourceFile, state: "unreadable" });
+                }
+            }
+        }
+        catch {
+            referencedSources.push({ path: sourceFile, state: "unreadable" });
+        }
+    }
+    return resolved
+        .createHash("sha256")
+        .update(JSON.stringify({
+        manifest: manifestHash,
+        coordinates: { state: artifactState, sha256: artifactHash },
+        referencedSources,
+    }))
+        .digest("hex");
+}
 export function readSyncCache(
 // implements REQ-003
 cachePath, deps) {

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

@@ -1,8 +1,32 @@
-import type { KbConfigPaths } from "../../utils/config.js";
+export type DiscoveryOptions = Readonly<{
+    trackedOnly?: boolean;
+    recoverMissingPendingSources?: boolean;
+    /** Read-only callers must not consume receipts merely by discovering files. */
+    consumeTrackedPendingReceipts?: boolean;
+}>;
+/**
+ * A missing-source receipt selected for explicit recovery.
+ *
+ * The receipt path alone is not enough: another Kibi process may publish a
+ * newer receipt between discovery and the derived-store publication.  The
+ * raw digest lets the recovery boundary compare-and-delete the exact receipt
+ * it observed, leaving a newer receipt available for its owner to handle.
+ */
+export type PendingSourceReceiptSnapshot = Readonly<{
+    receiptPath: string;
+    path: string;
+    afterHash: string;
+    rawHash: string;
+}>;
+export declare function isFsEnoent(error: unknown): boolean;
+export declare function readTextOrEnoent(absolute: string): string | null;
+export declare function unlinkOrEnoent(absolute: string): boolean;
+export declare function clearRecoveredPendingSourceReceipts(cwd: string, receipts: readonly PendingSourceReceiptSnapshot[]): void;
 export declare function normalizeMarkdownPath(pattern: string | undefined): string | null;
-export declare function discoverSourceFiles(cwd: string, paths: KbConfigPaths): Promise<{
+export declare function discoverSourceFiles(cwd: string, options?: DiscoveryOptions): Promise<{
     markdownFiles: string[];
     manifestFiles: string[];
     relationshipsDir: string;
+    recoveredPendingReceiptPaths: PendingSourceReceiptSnapshot[];
 }>;
 //# sourceMappingURL=discovery.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC,CAkCD"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+EAA+E;IAC/E,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAyFH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOlD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAUxD;AAED,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,IAAI,CA6CN;AAsBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;CAC9D,CAAC,CA+FD"}

package/dist/commands/sync/discovery.js

@@ -15,10 +15,157 @@
  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 * as fs from "node:fs";
+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 isFsEnoent(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export function readTextOrEnoent(absolute) {
+    try {
+        return fs.readFileSync(absolute, "utf8");
+    }
+    catch (error) {
+        if (isFsEnoent(error))
+            return null;
+        throw new Error(`Failed to inspect pending source receipt for ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function unlinkOrEnoent(absolute) {
+    try {
+        fs.unlinkSync(absolute);
+        return true;
+    }
+    catch (error) {
+        if (isFsEnoent(error))
+            return false;
+        throw new Error(`Failed to retire pending source receipt for ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+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.
+        const raw = readTextOrEnoent(absolute);
+        if (raw === null)
+            continue;
+        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`);
+        }
+        unlinkOrEnoent(absolute);
+    }
+}
+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 +173,74 @@ 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 = (Array.isArray(markdownFiles) ? markdownFiles : []).filter((file) => !file.endsWith("/README.md"));
+    let manifestFiles = await fg(CANONICAL_ENTITY_PATHS.symbols, {
+        cwd,
+        absolute: true,
+    });
+    if (!Array.isArray(manifestFiles)) {
+        manifestFiles = [];
+    }
+    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";
+export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK: string;
 /**
- * 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,EAG3B,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,QAc1C,CAAC;AAaF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAoHD,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,CAqMf;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"}