kibi-cli 0.19.0 → 1.0.1

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.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;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,CAuOvD;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"}
+{"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"}

package/dist/commands/sync/persistence.js

@@ -369,6 +369,9 @@ prolog, results, entityIds, options = {}) {
                 if (entity.verification_perspective !== undefined) {
                     props.push(`verification_perspective=${toPrologAtom(entity.verification_perspective)}`);
                 }
+                if (entity.verification_contract !== undefined) {
+                    props.push(`verification_contract=${toPrologString(JSON.stringify(entity.verification_contract))}`);
+                }
                 if (entity.verification_receipts !== undefined) {
                     props.push(`verification_receipts=${toPrologString(JSON.stringify(entity.verification_receipts))}`);
                 }

package/dist/commands/sync.d.ts

@@ -1,4 +1,5 @@
 import type { SyncSummary } from "../diagnostics.js";
+import { acquireSymbolCompilerLock } from "../operations/mutation/symbol-compiler-lock.js";
 import { PrologProcess } from "../prolog.js";
 export declare class SyncError extends Error {
     constructor(message: string);
@@ -21,11 +22,16 @@ interface SyncCommandRuntime {
     createProlog?: (options: {
         timeout: number;
     }) => PrologProcess;
+    acquireSymbolCompilerLock?: typeof acquireSymbolCompilerLock;
 }
 export declare function syncCommand(options?: {
     validateOnly?: boolean;
     rebuild?: boolean;
     refreshSymbolCoordinates?: boolean;
+    /** Explicitly rebuild an unreadable branch store from authored sources. */
+    recoveryBackupPath?: string;
+    /** Workspace to operate on when invoked through MCP or another host. */
+    workspaceRoot?: string;
 }, runtime?: SyncCommandRuntime): Promise<SyncResult>;
 export { normalizeMarkdownPath } from "./sync/discovery.js";
 //# sourceMappingURL=sync.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyBjE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAsC7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAoDD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CAChE;AAsDD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;CAC/B,EACN,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAy6BrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyBjE,OAAO,EAEL,yBAAyB,EAE1B,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA+C7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAkMD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC/D,yBAAyB,CAAC,EAAE,OAAO,yBAAyB,CAAC;CAC9D;AA+DD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,EACN,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CA4kCrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}