kibi-cli 0.18.1 → 1.0.1

package/dist/commands/sync/persistence.js

@@ -114,6 +114,117 @@ function serializeTypedFactFields(entity) {
     }
     return fields;
 }
+function parsePrologList(value) {
+    if (typeof value !== "string")
+        return [];
+    const text = value.trim();
+    if (text.length < 2 || !text.startsWith("[") || !text.endsWith("]")) {
+        return [];
+    }
+    const body = text.slice(1, -1).trim();
+    if (body.length === 0)
+        return [];
+    const values = [];
+    // IDs are atoms in the Kibi schema. Keep the parser deliberately narrow so
+    // a malformed response cannot turn into a destructive path or goal.
+    for (const part of body.split(",")) {
+        const valuePart = part.trim();
+        if (!valuePart)
+            continue;
+        if (valuePart.startsWith("'") && valuePart.endsWith("'")) {
+            values.push(valuePart.slice(1, -1).replaceAll("''", "'"));
+        }
+        else if (/^[A-Za-z0-9_.:/@+-]+$/.test(valuePart)) {
+            values.push(valuePart);
+        }
+    }
+    return values;
+}
+async function entityIdsForSource(prolog, sourceFile) {
+    const candidates = new Set([
+        sourceFile,
+        path.relative(process.cwd(), sourceFile),
+        path.basename(sourceFile),
+    ]);
+    const ids = new Set();
+    for (const candidate of candidates) {
+        const result = await prolog.query(`kb_entities_by_source(${toPrologString(candidate)}, Ids)`);
+        if (result.success) {
+            for (const id of parsePrologList(result.bindings?.Ids))
+                ids.add(id);
+        }
+    }
+    return [...ids];
+}
+/** Remove entities owned by changed/deleted source files before re-upserting. */
+export async function retractEntitiesForSources(prolog, sourceFiles) {
+    const ids = new Set();
+    for (const sourceFile of sourceFiles) {
+        for (const id of await entityIdsForSource(prolog, sourceFile))
+            ids.add(id);
+    }
+    if (ids.size === 0)
+        return 0;
+    const goals = [...ids].map((id) => `kb_retract_entity(${toPrologAtom(id)})`);
+    const batchRunner = prolog.queryBatch?.bind(prolog);
+    if (batchRunner) {
+        const result = await batchRunner(goals);
+        if (!result.success) {
+            throw new Error(result.error ?? "Failed to retract changed source entities");
+        }
+    }
+    else {
+        for (const goal of goals) {
+            const result = await prolog.query(goal);
+            if (!result.success) {
+                throw new Error(result.error ?? "Failed to retract changed source entity");
+            }
+        }
+    }
+    return ids.size;
+}
+/** Remove an exact entity delta without scanning every indexed source. */
+export async function retractEntitiesById(prolog, entityIds) {
+    const ids = [...new Set(entityIds)];
+    if (ids.length === 0)
+        return 0;
+    const goals = ids.map((id) => `kb_retract_entity(${toPrologAtom(id)})`);
+    const batchRunner = prolog.queryBatch?.bind(prolog);
+    const result = batchRunner
+        ? await batchRunner(goals)
+        : await prolog.query(`rdf_transaction((${goals.join(", ")}))`);
+    if (!result.success) {
+        throw new Error(result.error ?? "Failed to retract entity delta");
+    }
+    return ids.length;
+}
+/** Clear outgoing inline relationships for entities whose payload changed. */
+export async function retractEntityRelationshipsById(prolog, entityIds) {
+    const ids = [...new Set(entityIds)];
+    if (ids.length === 0)
+        return;
+    const goals = ids.map((id) => `kb_retract_entity_relationships(${toPrologAtom(id)})`);
+    const batchRunner = prolog.queryBatch?.bind(prolog);
+    const result = batchRunner
+        ? await batchRunner(goals)
+        : await prolog.query(`rdf_transaction((${goals.join(", ")}))`);
+    if (!result.success) {
+        throw new Error(result.error ?? "Failed to retract relationship delta");
+    }
+}
+export async function retractRelationships(prolog, relationships) {
+    if (relationships.length === 0)
+        return 0;
+    const goals = relationships.map((relationship) => `kb_retract_relationship(${toPrologAtom(relationship.type)}, ${toPrologAtom(relationship.from)}, ${toPrologAtom(relationship.to)})`);
+    const batchRunner = prolog.queryBatch?.bind(prolog);
+    const result = batchRunner
+        ? await batchRunner(goals)
+        : await prolog.query(`rdf_transaction((${goals.join(", ")}))`);
+    if (!result.success) {
+        throw new Error(result.error ?? "Failed to retract relationship shard delta");
+    }
+    return relationships.length;
+}
 function isQueryFailedError(error) {
     const lowered = error.toLowerCase();
     // Only match session-corruption errors that might benefit from a Prolog process restart.
@@ -140,21 +251,26 @@ async function tryResetPrologProcess(prolog) {
 }
 export async function persistEntities(
 // implements REQ-009
-prolog, results, entityIds) {
+prolog, results, entityIds, options = {}) {
     let entityCount = 0;
     let kbModified = false;
     const existingEntityIds = new Set();
-    // Query existing entity IDs to include unchanged entities
-    const existingIdsResult = await prolog.query("findall(Id, kb_entity(Id, _, _), ExistingIds)");
-    if (existingIdsResult.success && existingIdsResult.bindings?.ExistingIds) {
-        const raw = existingIdsResult.bindings.ExistingIds;
-        const cleaned = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
-        if (cleaned) {
-            for (const atom of cleaned.split(",")) {
-                const id = atom.trim().replace(/^'|'$/g, "");
-                if (id) {
-                    entityIds.add(id);
-                    existingEntityIds.add(id);
+    const pendingEntityGoals = [];
+    if (options.loadExistingEntityIds !== false) {
+        // Generation rebuilds need the complete endpoint inventory for local
+        // relationship validation. Journal deltas rely on Prolog's authoritative
+        // endpoint checks and must not materialize 10,000 IDs for one upsert.
+        const existingIdsResult = await prolog.query("findall(Id, kb_entity(Id, _, _), ExistingIds)");
+        if (existingIdsResult.success && existingIdsResult.bindings?.ExistingIds) {
+            const raw = existingIdsResult.bindings.ExistingIds;
+            const cleaned = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+            if (cleaned) {
+                for (const atom of cleaned.split(",")) {
+                    const id = atom.trim().replace(/^'|'$/g, "");
+                    if (id) {
+                        entityIds.add(id);
+                        existingEntityIds.add(id);
+                    }
                 }
             }
         }
@@ -253,24 +369,65 @@ prolog, results, entityIds) {
                 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))}`);
                 }
             }
             const propsList = `[${props.join(", ")}]`;
             const goal = `kb_assert_entity(${entity.type}, ${propsList})`;
-            const result = await prolog.query(goal);
-            if (!result.success) {
-                throw new Error(result.error || `kb_assert_entity failed for ${entity.id}`);
-            }
-            entityCount++;
-            kbModified = true;
+            pendingEntityGoals.push({
+                entity,
+                sourceFile: sourceFile ?? entity.source,
+                goal,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             throw new Error(`Failed to upsert entity ${entity.id}: ${message}${semanticEntityContext(entity, sourceFile ?? entity.source)}`);
         }
     }
+    // Persist a changed source as a bounded set of RDF edits.  This retains the
+    // per-entity fallback diagnostics while avoiding one Prolog round-trip and
+    // journal flush for every symbol/document in the common case.
+    const batchRunner = prolog.queryBatch?.bind(prolog);
+    const batchSize = 250;
+    for (let offset = 0; offset < pendingEntityGoals.length; offset += batchSize) {
+        const chunk = pendingEntityGoals.slice(offset, offset + batchSize);
+        const result = batchRunner
+            ? await batchRunner(chunk.map(({ goal }) => goal))
+            : { success: false, error: "batch unsupported" };
+        if (result.success) {
+            entityCount += chunk.length;
+            kbModified = true;
+            continue;
+        }
+        // A malformed entity should retain the precise existing error.  The batch
+        // transaction has rolled back, so retrying sequentially is safe.
+        for (const item of chunk) {
+            try {
+                const single = await prolog.query(item.goal);
+                if (!single.success) {
+                    const detail = single.error ||
+                        (batchRunner ? result.error : undefined) ||
+                        `kb_assert_entity failed for ${item.entity.id}`;
+                    throw new Error(`Failed to upsert entity ${item.entity.id}: ${detail}${semanticEntityContext(item.entity, item.sourceFile)}`);
+                }
+                entityCount++;
+                kbModified = true;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.startsWith("Failed to upsert entity ")) {
+                    throw error;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to upsert entity ${item.entity.id}: ${message}${semanticEntityContext(item.entity, item.sourceFile)}`);
+            }
+        }
+    }
     return { entityCount, kbModified };
 }
 function semanticEntityContext(entity, sourceFile) {
@@ -306,25 +463,14 @@ export async function persistRelationships(prolog, results, shardRelationships)
     }
     // Collect all relationships from results and shards
     const failedRelationships = [];
+    const pendingRelationships = [];
     for (const { relationships } of results) {
         for (const rel of relationships) {
             try {
                 const fromId = idLookup.get(rel.from) || rel.from;
                 const toId = idLookup.get(rel.to) || rel.to;
                 const goal = `kb_assert_relationship(${toPrologAtom(rel.type)}, ${toPrologAtom(fromId)}, ${toPrologAtom(toId)}, [])`;
-                const result = await prolog.query(goal);
-                if (result.success) {
-                    relCount++;
-                    kbModified = true;
-                }
-                else {
-                    failedRelationships.push({
-                        rel,
-                        fromId,
-                        toId,
-                        error: result.error || "Unknown error",
-                    });
-                }
+                pendingRelationships.push({ rel, fromId, toId, goal });
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -338,19 +484,12 @@ export async function persistRelationships(prolog, results, shardRelationships)
     for (const rel of shardRelationships) {
         try {
             const goal = `kb_assert_relationship(${toPrologAtom(rel.type)}, ${toPrologAtom(rel.from)}, ${toPrologAtom(rel.to)}, [])`;
-            const result = await prolog.query(goal);
-            if (result.success) {
-                relCount++;
-                kbModified = true;
-            }
-            else {
-                failedRelationships.push({
-                    rel,
-                    fromId: rel.from,
-                    toId: rel.to,
-                    error: result.error || "Unknown error",
-                });
-            }
+            pendingRelationships.push({
+                rel,
+                fromId: rel.from,
+                toId: rel.to,
+                goal,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -362,6 +501,46 @@ export async function persistRelationships(prolog, results, shardRelationships)
             });
         }
     }
+    const relationshipBatchRunner = prolog.queryBatch?.bind(prolog);
+    const relationshipBatchSize = 250;
+    for (let offset = 0; offset < pendingRelationships.length; offset += relationshipBatchSize) {
+        const chunk = pendingRelationships.slice(offset, offset + relationshipBatchSize);
+        const batch = relationshipBatchRunner
+            ? await relationshipBatchRunner(chunk.map(({ goal }) => goal))
+            : { success: false, error: "batch unsupported" };
+        if (batch.success) {
+            relCount += chunk.length;
+            kbModified = true;
+            continue;
+        }
+        for (const item of chunk) {
+            try {
+                const single = await prolog.query(item.goal);
+                if (single.success) {
+                    relCount++;
+                    kbModified = true;
+                }
+                else {
+                    failedRelationships.push({
+                        rel: item.rel,
+                        fromId: item.fromId,
+                        toId: item.toId,
+                        error: single.error ||
+                            (relationshipBatchRunner ? batch.error : undefined) ||
+                            "Unknown error",
+                    });
+                }
+            }
+            catch (error) {
+                failedRelationships.push({
+                    rel: item.rel,
+                    fromId: item.fromId,
+                    toId: item.toId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
     // Retry failed relationships
     const retryCount = 3;
     let resetAttempted = false;

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { copyFileSync } from "node:fs";
 import fg from "fast-glob";
 import { copyCleanSnapshot } from "../../utils/branch-resolver.js";
@@ -13,11 +13,20 @@ interface StagingDeps {
     moduleDir: string;
     renameSync: typeof renameSync;
     rmSync: typeof rmSync;
+    writeFileSync: typeof writeFileSync;
 }
 export declare function createUniqueStagingPath(currentBranch: string, rootDir: string, pid?: number, now?: number): string;
 export declare function cleanupAbandonedStagingDirectories(stagingPath: string, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;
+/**
+ * Publish a rebuilt journal generation without replacing the branch directory.
+ * The legacy backup, sync metadata, and sentinel stay in place; only the
+ * journal database and CURRENT pointer move.  A short-lived rollback pair is
+ * retained until both moves succeed so an interrupted publication can be
+ * repaired on the next engine start.
+ */
+export declare function atomicPublishGeneration(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;
 export declare function cleanupStaging(stagingPath: string, deps?: Partial<StagingDeps>): void;
 export {};
 //# sourceMappingURL=staging.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AA8BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AA+BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Cf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CA6DN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -15,7 +15,7 @@
  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, mkdirSync, renameSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { copyFileSync } from "node:fs";
 import * as path from "node:path";
 import fg from "fast-glob";
@@ -42,6 +42,7 @@ function resolveDeps(overrides) {
         moduleDir: import.meta.dirname,
         renameSync,
         rmSync,
+        writeFileSync,
         ...overrides,
     };
 }
@@ -104,6 +105,22 @@ stagingPath, livePath, rebuild, deps) {
         // Start fresh with schema only
         await copySchemaToStaging(stagingPath, resolved);
     }
+    // Every new staging generation uses the journaled store format.  This also
+    // makes `--rebuild` publish a native RDF database instead of recreating the
+    // legacy full-snapshot path.
+    const markerPath = path.join(stagingPath, "storage.json");
+    const canWriteMetadata = deps === undefined || deps.writeFileSync !== undefined;
+    if (canWriteMetadata &&
+        resolved.existsSync(stagingPath) &&
+        !resolved.existsSync(markerPath)) {
+        resolved.mkdirSync(path.join(stagingPath, "rdf"), { recursive: true });
+        resolved.writeFileSync(markerPath, '{"format":"kibi.rdf-journal.v1","schemaVersion":1}\n', { mode: 0o600 });
+        const generation = rebuild
+            ? `generation-${process.pid}-${Date.now()}`
+            : "generation-1";
+        resolved.writeFileSync(path.join(stagingPath, "CURRENT"), `${generation}:0\n`, { mode: 0o600 });
+        resolved.writeFileSync(path.join(stagingPath, "kb.rdf"), "KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1\n", { mode: 0o600 });
+    }
 }
 async function copySchemaToStaging(stagingPath, deps) {
     const possibleSchemaPaths = [
@@ -154,6 +171,72 @@ stagingPath, livePath, deps) {
         resolved.renameSync(stagingPath, livePath);
     }
 }
+/**
+ * Publish a rebuilt journal generation without replacing the branch directory.
+ * The legacy backup, sync metadata, and sentinel stay in place; only the
+ * journal database and CURRENT pointer move.  A short-lived rollback pair is
+ * retained until both moves succeed so an interrupted publication can be
+ * repaired on the next engine start.
+ */
+export function atomicPublishGeneration(stagingPath, livePath, deps) {
+    const resolved = resolveDeps(deps);
+    const liveParent = path.dirname(livePath);
+    if (!resolved.existsSync(liveParent)) {
+        resolved.mkdirSync(liveParent, { recursive: true });
+    }
+    if (!resolved.existsSync(livePath)) {
+        resolved.renameSync(stagingPath, livePath);
+        return;
+    }
+    const generationStamp = `${Date.now()}.${process.pid}`;
+    const liveRdf = path.join(livePath, "rdf");
+    const stagedRdf = path.join(stagingPath, "rdf");
+    const oldRdf = `${liveRdf}.old.${generationStamp}`;
+    const liveCurrent = path.join(livePath, "CURRENT");
+    const stagedCurrent = path.join(stagingPath, "CURRENT");
+    const oldCurrent = `${liveCurrent}.old.${generationStamp}`;
+    if (!resolved.existsSync(stagedRdf) || !resolved.existsSync(stagedCurrent)) {
+        throw new Error("Rebuilt journal generation is missing rdf or CURRENT");
+    }
+    let oldRdfMoved = false;
+    let oldCurrentMoved = false;
+    try {
+        if (resolved.existsSync(liveRdf)) {
+            resolved.renameSync(liveRdf, oldRdf);
+            oldRdfMoved = true;
+        }
+        resolved.renameSync(stagedRdf, liveRdf);
+        if (resolved.existsSync(liveCurrent)) {
+            resolved.renameSync(liveCurrent, oldCurrent);
+            oldCurrentMoved = true;
+        }
+        resolved.renameSync(stagedCurrent, liveCurrent);
+    }
+    catch (error) {
+        // Restore the old pointer/database whenever publication fails.  If the
+        // process itself crashes, ensureJournaledBranchStoreAsync performs the
+        // same recovery from the `.old.<stamp>` siblings.
+        try {
+            if (resolved.existsSync(liveCurrent))
+                resolved.rmSync(liveCurrent, { force: true });
+            if (oldCurrentMoved && resolved.existsSync(oldCurrent))
+                resolved.renameSync(oldCurrent, liveCurrent);
+            if (resolved.existsSync(liveRdf))
+                resolved.rmSync(liveRdf, { recursive: true, force: true });
+            if (oldRdfMoved && resolved.existsSync(oldRdf))
+                resolved.renameSync(oldRdf, liveRdf);
+        }
+        catch {
+            // Preserve the original publication error; startup recovery will report
+            // the remaining sibling paths if the rollback itself was interrupted.
+        }
+        throw error;
+    }
+    if (resolved.existsSync(oldRdf))
+        resolved.rmSync(oldRdf, { recursive: true, force: true });
+    if (resolved.existsSync(oldCurrent))
+        resolved.rmSync(oldCurrent, { force: true });
+}
 export function cleanupStaging(
 // implements REQ-003
 stagingPath, deps) {

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;AAiBjE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,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;AAGD,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,CAsfrB;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"}