kibi-cli 1.0.1 → 2.1.0

package/dist/operations/mutation/upsert.js

@@ -6,19 +6,21 @@ import { readManifestWithCoordinateOverlay } from "../../extractors/manifest.js"
 import { extractManifestSymbolRecords } from "../../extractors/manifest.js";
 import { escapeAtom } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
-import { appendOnlyVerificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
+import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
 import { appendRelationship, computeShardPath, } from "../../relationships/shards.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
+import { MutationSaga } from "./saga.js";
 import { writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
 import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "./symbol-compiler-lock.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { refreshSymbolCoordinatesForManifest } from "./symbol-refresh.js";
 import { validateUpsertInput } from "./validation.js";
 import { scenarioCoverageWarnings } from "./warnings.js";
+import { acquireWorkspaceMutationLock, releaseWorkspaceMutationLock, } from "./workspace-mutation-lock.js";
 function requireProlog(context) {
     if (context.prolog === undefined) {
         throw new Error("Upsert operation requires a Prolog runtime");
@@ -90,18 +92,18 @@ function restoreRelationshipShard(shardPath, before, expectedAfterHash) {
     }
     writeFileSync(shardPath, before, "utf8");
 }
-export async function validateAppendOnlyVerificationReceipts(entity, context) {
+export async function validateAppendOnlyProofReceipts(entity, context) {
     if (entity.type !== "test")
         return;
     const existing = await loadEntities(requireProlog(context), {
         id: String(entity.id),
         type: "test",
     });
-    const previous = receiptRecords(existing[0]?.verification_receipts);
+    const previous = receiptRecords(existing[0]?.proof_receipts);
     if (!previous || previous.length === 0)
         return;
-    const next = receiptRecords(entity.verification_receipts);
-    const errors = appendOnlyVerificationReceiptHistoryErrors(previous, next);
+    const next = receiptRecords(entity.proof_receipts);
+    const errors = appendOnlyProofReceiptHistoryErrors(previous, next);
     if (errors.length > 0) {
         throw new Error(`Entity validation failed: ${errors.join("; ")}`);
     }
@@ -159,7 +161,7 @@ function reextractCanonicalSymbolEntity(symbolId, authoredRelativePath, workspac
             : { sourceFile: result.sourceFile }),
     };
 }
-export async function executeUpsert(input, context) {
+export async function executeUpsert(input, context, options = {}) {
     const branchAttachment = context.branchAttachment ?? resolveBranchAttachment(context.workspaceRoot);
     if ("error" in branchAttachment) {
         throw new Error(`Unable to resolve KB branch: ${branchAttachment.error}`);
@@ -169,22 +171,31 @@ export async function executeUpsert(input, context) {
         throw new Error(`Upsert blocked: KB is attached through legacy branch storage (${branchAttachment.gitBranch} -> ${branchAttachment.kbBranch}). Run 'kibi branch migrate --from ${branchAttachment.kbBranch} --to ${branchAttachment.gitBranch} --apply' first.`);
     }
     const prolog = requireProlog(context);
+    // Declared compensation list for the multi-surface mutation. Steps register
+    // as they succeed (authored source -> relationship shards -> coordinates);
+    // a failure rolls them back in reverse under the symbol compiler lock, and
+    // the compiled commit marks the point of no return.
+    const saga = new MutationSaga();
     let sourceWrite = null;
     let commitEntity;
-    let sourceRolledBack = false;
-    let compiledCommitted = false;
     let relationshipCount = 0;
     let changeKind = null;
     let semanticAdvisor;
     let compilerLock;
-    let coordinatePublication;
+    let sourceMutationLock;
     let operationFailure;
     const relationshipShardBefore = new Map();
     const relationshipShardAfterHash = new Map();
     const holdsSymbolCompilerLock = input.type === "symbol" &&
         context.fs !== undefined &&
         context.sourceFirst !== false;
+    const holdsSourceMutationLock = context.fs !== undefined &&
+        context.sourceFirst !== false &&
+        context.sourceMutationLockHeld !== true;
     try {
+        if (holdsSourceMutationLock) {
+            sourceMutationLock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+        }
         if (holdsSymbolCompilerLock) {
             // Symbol source publication, coordinate refresh, canonical
             // re-extraction, and the RDF commit form one read-modify-write cycle.
@@ -193,7 +204,9 @@ export async function executeUpsert(input, context) {
             compilerLock = await acquireSymbolCompilerLock(context.workspaceRoot);
         }
         const validated = validateUpsertInput(input, context.clock());
-        await validateAppendOnlyVerificationReceipts(validated.entity, context);
+        if (options.allowReceiptsPrune !== true) {
+            await validateAppendOnlyProofReceipts(validated.entity, context);
+        }
         validateRelationshipSources(input.id, validated.relationships);
         await validateSymbolGranularity(validated.entity, validated.relationships, context);
         const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context);
@@ -227,8 +240,14 @@ export async function executeUpsert(input, context) {
                 // when configuration has zero or multiple writable targets, rather
                 // than silently creating compiled-only state.
                 existing === undefined) {
-                sourceWrite = await writeSourceForUpsert(input, validated.entity, existing, context);
+                sourceWrite = await writeSourceForUpsert(input, validated.entity, existing, context, options.sourceDocumentOverride);
                 if (sourceWrite !== null) {
+                    const sourceStep = sourceWrite;
+                    saga.add({
+                        name: "authored-source",
+                        rollback: () => sourceStep.rollback(),
+                        onError: "capture",
+                    });
                     // The authored path is the entity's canonical identity. Runtime
                     // transport provenance (mcp://...) must never survive a source-first
                     // write or a later delete/sync cycle.
@@ -243,6 +262,17 @@ export async function executeUpsert(input, context) {
         // the compiled transaction so a failed commit can restore exact bytes and
         // a successful commit never leaves a compiled-only relationship behind.
         if (context.fs !== undefined && validated.relationships.length > 0) {
+            // Register the rollback before appending so a failure on any shard (for
+            // example the second write of a multi-shard batch) unwinds the shards
+            // that were already appended.
+            saga.add({
+                name: "relationship-shards",
+                rollback: () => {
+                    for (const [shardPath, before] of relationshipShardBefore) {
+                        restoreRelationshipShard(shardPath, before, relationshipShardAfterHash.get(shardPath) ?? null);
+                    }
+                },
+            });
             for (const relationship of validated.relationships) {
                 const type = typeof relationship.type === "string" ? relationship.type : "";
                 const from = typeof relationship.from === "string" ? relationship.from : input.id;
@@ -276,7 +306,14 @@ export async function executeUpsert(input, context) {
             context.sourceFirst !== false &&
             sourceWrite !== null) {
             const refresh = await refreshSymbolCoordinatesForManifest(input.id, path.resolve(context.workspaceRoot, sourceWrite.receipt.path), context);
-            coordinatePublication = refresh.publication;
+            const coordinatePublication = refresh.publication;
+            if (coordinatePublication !== undefined) {
+                saga.add({
+                    name: "symbol-coordinates",
+                    rollback: () => coordinatePublication.rollback(),
+                    onError: "capture",
+                });
+            }
             if (!refresh.found || refresh.outcome === "removed") {
                 throw new Error(`Coordinate refresh could not find ${input.id} in the authored symbol manifest`);
             }
@@ -299,14 +336,9 @@ export async function executeUpsert(input, context) {
         });
         const written = await prolog.query(transaction);
         if (!written.success) {
-            await sourceWrite?.rollback();
-            sourceRolledBack = sourceWrite !== null;
-            for (const [shardPath, before] of relationshipShardBefore) {
-                restoreRelationshipShard(shardPath, before, relationshipShardAfterHash.get(shardPath) ?? null);
-            }
-            throw new Error(formatUpsertError(input.id, written.error));
+            throw new Error(formatUpsertError(input.id, written.error, written.errorRecord));
         }
-        compiledCommitted = true;
+        saga.markCommitted();
         // The combined commit is the sole mutation boundary. Invalidate reads only
         // after Prolog reports success so a failed/rolled-back commit does not
         // disturb callers' view of the current snapshot.
@@ -322,7 +354,17 @@ export async function executeUpsert(input, context) {
         for (const [shardPath, before] of relationshipShardBefore) {
             const afterHash = fileHash(shardPath);
             const beforeHash = before === null ? null : textHash(before);
-            if (afterHash === null || afterHash === beforeHash)
+            const expectedAfterHash = relationshipShardAfterHash.get(shardPath) ?? null;
+            if (afterHash === null) {
+                if (expectedAfterHash !== null) {
+                    const relative = path
+                        .relative(context.workspaceRoot, shardPath)
+                        .replaceAll("\\", "/");
+                    shardWarnings.push(`Relationship shard vanished after write: ${relative}`);
+                }
+                continue;
+            }
+            if (afterHash === beforeHash)
                 continue;
             const relative = path
                 .relative(context.workspaceRoot, shardPath)
@@ -393,37 +435,12 @@ export async function executeUpsert(input, context) {
         };
     }
     catch (error) {
-        let coordinateRollbackError;
-        if (!compiledCommitted && coordinatePublication !== undefined) {
-            try {
-                coordinatePublication.rollback();
-            }
-            catch (rollbackError) {
-                coordinateRollbackError = rollbackError;
-            }
-        }
-        if (!compiledCommitted) {
-            for (const [shardPath, before] of relationshipShardBefore) {
-                try {
-                    restoreRelationshipShard(shardPath, before, relationshipShardAfterHash.get(shardPath) ?? null);
-                }
-                catch {
-                    // Preserve the original failure; the next check/sync reports any
-                    // canonical source path that could not be restored.
-                }
-            }
-        }
-        if (!compiledCommitted && sourceWrite !== null && !sourceRolledBack) {
-            try {
-                await sourceWrite.rollback();
-                sourceRolledBack = true;
-            }
-            catch {
-                // Preserve the original mutation error; the recovery journal can
-                // reconcile a failed source rollback on the next sync.
-            }
-        }
-        if (compiledCommitted) {
+        // Roll back every completed pre-commit surface in reverse order, exactly
+        // once. After the compiled commit this is a no-op: post-commit failures
+        // return committed-with-repairs results instead of undoing committed
+        // state.
+        const rollbackFailures = await saga.rollback();
+        if (saga.committed) {
             const detail = error instanceof Error ? error.message : String(error);
             return {
                 content: [
@@ -461,8 +478,18 @@ export async function executeUpsert(input, context) {
                 },
             };
         }
-        if (coordinateRollbackError !== undefined) {
-            const failure = new AggregateError([error, coordinateRollbackError], `Upsert failed and coordinate artifact rollback failed for ${input.id}`);
+        const coordinateFailure = rollbackFailures.find((failure) => failure.step === "symbol-coordinates");
+        if (coordinateFailure !== undefined) {
+            const failure = new AggregateError([error, coordinateFailure.error], `Upsert failed and coordinate artifact rollback failed for ${input.id}`);
+            operationFailure = { error: failure };
+            throw failure;
+        }
+        const sourceFailure = rollbackFailures.find((failure) => failure.step === "authored-source");
+        if (sourceFailure !== undefined) {
+            const rollbackMessage = sourceFailure.error instanceof Error
+                ? sourceFailure.error.message
+                : String(sourceFailure.error);
+            const failure = new AggregateError([error, sourceFailure.error], `Upsert failed and authored source rollback failed for ${input.id}: ${rollbackMessage}`);
             operationFailure = { error: failure };
             throw failure;
         }
@@ -476,6 +503,11 @@ export async function executeUpsert(input, context) {
         throw failure;
     }
     finally {
-        releaseSymbolCompilerLock(compilerLock, operationFailure);
+        try {
+            releaseSymbolCompilerLock(compilerLock, operationFailure, saga.committed);
+        }
+        finally {
+            releaseWorkspaceMutationLock(sourceMutationLock, operationFailure, saga.committed);
+        }
     }
 }

package/dist/operations/mutation/validate-upsert.js

@@ -2,12 +2,12 @@ import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.j
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, validateSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { validateLiveRelationshipTargets, validateRelationshipSources, } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
-import { effectiveRelationships, validateAppendOnlyVerificationReceipts, } from "./upsert.js";
+import { effectiveRelationships, validateAppendOnlyProofReceipts, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
 export async function executeValidateUpsert(input, context) {
     try {
         const validated = validateUpsertInput(input, context.clock());
-        await validateAppendOnlyVerificationReceipts(validated.entity, context);
+        await validateAppendOnlyProofReceipts(validated.entity, context);
         validateRelationshipSources(input.id, validated.relationships);
         await validateSymbolGranularity(validated.entity, validated.relationships, context);
         const previewSemantic = analyzeSemanticAdvisorInput({

package/dist/operations/mutation/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAQ5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAkF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CAwDjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAkF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA0DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -1,9 +1,9 @@
 import Ajv from "ajv";
+import { proofReceiptHistoryErrors } from "../../public/proof-receipt.js";
 import entitySchema from "../../public/schemas/entity.js";
 import relationshipSchema from "../../public/schemas/relationship.js";
 // implements REQ-kibi-operation-interface-parity
 import { SYMBOL_ROLES, isAllowedGranularityReason, } from "../../public/symbol-granularity.js";
-import { verificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { factKindShapeHints, validateFactModelingShape, valueFieldHint, } from "./strict-fact.js";
 const ajv = new Ajv({ strict: false });
@@ -86,9 +86,11 @@ export function validateUpsertInput(input, now) {
     if (!validateEntity(entity)) {
         throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
     }
-    if (entity.type === "test" && Array.isArray(entity.verification_receipts)) {
-        const receipts = entity.verification_receipts.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value));
-        const receiptErrors = verificationReceiptHistoryErrors(input.id, entity.verification_scope, receipts);
+    validateSymbolSourceFile(entity);
+    validateProofExemptionPairing(entity);
+    if (entity.type === "test" && Array.isArray(entity.proof_receipts)) {
+        const receipts = entity.proof_receipts.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value));
+        const receiptErrors = proofReceiptHistoryErrors(input.id, entity.verification_scope, receipts);
         if (receiptErrors.length > 0) {
             throw new Error(`Entity validation failed: ${receiptErrors.join("; ")}`);
         }
@@ -114,3 +116,43 @@ export function validateUpsertInput(input, now) {
     return { entity, relationships };
 }
 export { isAllowedGranularityReason };
+/**
+ * A symbol whose sourceFile points into .kb/ can publish coordinates to the
+ * artifact, but the engine never merges coordinates for KB-internal paths —
+ * coverage then reports missing_symbol_coordinates forever with no signal.
+ * Reject the configuration at upsert time instead.
+ */
+function validateSymbolSourceFile(entity) {
+    if (entity.type !== "symbol")
+        return;
+    const sourceFile = entity.sourceFile;
+    if (typeof sourceFile !== "string" || sourceFile.trim() === "")
+        return;
+    const normalized = sourceFile.replaceAll("\\", "/").trim();
+    if (normalized === ".kb" || normalized.startsWith(".kb/")) {
+        throw new Error(`Entity validation failed: symbol sourceFile must point at a real code file in the workspace, not into the knowledge base ('${sourceFile}'). Coordinates for .kb/ paths are never merged into the engine, so coverage would report missing_symbol_coordinates permanently. Point the symbol at the implementing or verifying code file instead.`);
+    }
+}
+/**
+ * proof_exempt parks a current requirement outside E2E-proof scope. Without a
+ * reason the requirement would disappear from the proof ladder silently, so
+ * the exemption only exists with its justification attached (mirrored in
+ * requirement_proof.pl, which ignores an exemption without a reason).
+ */
+function validateProofExemptionPairing(entity) {
+    if (entity.type !== "req")
+        return;
+    const flag = entity.proof_exempt;
+    const isExempt = flag === true ||
+        flag === "true" ||
+        flag === "yes" ||
+        flag === "on" ||
+        flag === 1 ||
+        flag === "1";
+    if (!isExempt)
+        return;
+    const reason = entity.proof_exempt_reason;
+    if (typeof reason !== "string" || reason.trim() === "") {
+        throw new Error("Entity validation failed: proof_exempt requires a non-empty proof_exempt_reason explaining why the requirement is outside E2E-proof scope");
+    }
+}

package/dist/operations/mutation/warnings.d.ts

@@ -1,4 +1,5 @@
 import type { PrologPort } from "../../public/operations/runtime-types.js";
 import type { RelationshipInput } from "./types.js";
+export declare function scenarioCoverageWarning(entityId: string): readonly string[];
 export declare function scenarioCoverageWarnings(prolog: PrologPort, relationships: readonly RelationshipInput[], entityType: string, entityId: string): Promise<readonly string[]>;
 //# sourceMappingURL=warnings.d.ts.map

package/dist/operations/mutation/warnings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/warnings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAc5B"}
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/warnings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAI3E;AAGD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAU5B"}

package/dist/operations/mutation/warnings.js

@@ -1,4 +1,9 @@
 import { escapeAtom } from "../../prolog/codec.js";
+export function scenarioCoverageWarning(entityId) {
+    return [
+        `Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`,
+    ];
+}
 // implements REQ-kibi-operation-interface-parity
 export async function scenarioCoverageWarnings(prolog, relationships, entityType, entityId) {
     if (entityType !== "req")
@@ -7,11 +12,8 @@ export async function scenarioCoverageWarnings(prolog, relationships, entityType
         if (relationship.type !== "verified_by")
             continue;
         const result = await prolog.query(`once(kb_relationship(specified_by, '${escapeAtom(entityId)}', ScenarioId))`);
-        if (result.success) {
-            return [
-                `Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`,
-            ];
-        }
+        if (result.success)
+            return scenarioCoverageWarning(entityId);
     }
     return [];
 }

package/dist/operations/mutation/workspace-mutation-lock.d.ts

@@ -0,0 +1,60 @@
+export interface WorkspaceMutationLockFileSystem {
+    readonly mkdirSync: (target: string, options?: {
+        readonly recursive?: boolean;
+    }) => void;
+    readonly readFileSync: (target: string) => string;
+    readonly writeFileSync: (target: string, data: string, options: {
+        readonly encoding: "utf8";
+        readonly flag: "wx";
+    }) => void;
+    readonly unlinkSync: (target: string) => void;
+    readonly rmdirSync: (target: string) => void;
+}
+export interface WorkspaceMutationLockOptions {
+    readonly lockFileRelative?: string;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly fileSystem?: WorkspaceMutationLockFileSystem;
+    readonly isProcessAlive?: (pid: number) => boolean;
+}
+export declare class WorkspaceMutationLockError extends Error {
+    readonly name = "WorkspaceMutationLockError";
+}
+export interface WorkspaceMutationLockHandle {
+    /**
+     * Remove this handle's validated owner metadata and then its empty lock
+     * directory. Transient cleanup errors are retried; exhausted or permanent
+     * failures leave the lock fail-closed and may require verified manual
+     * cleanup. Successful release is idempotent, and a stale handle never
+     * removes a different owner token.
+     */
+    readonly release: () => void;
+}
+export declare function releaseWorkspaceMutationLock(handle: WorkspaceMutationLockHandle | undefined, operationFailure?: {
+    readonly error: unknown;
+}, committed?: boolean): void;
+/**
+ * Classify the failure of an operation whose authoritative commit already
+ * happened. Typed operation errors keep their code and retryability; generic
+ * failures are wrapped immediately as non-retryable so callers never read a
+ * committed mutation as an invitation to retry.
+ */
+export declare function classifySourceMutationFailure(operation: string, error: unknown, committed: boolean): unknown;
+/**
+ * Acquire the workspace workspace mutation lock without a callback shape, for
+ * operations whose lock must span several awaits (source publication,
+ * coordinate refresh, canonical re-extraction, and the RDF commit).
+ */
+export declare function acquireWorkspaceMutationLock(workspaceRoot: string, options?: WorkspaceMutationLockOptions): Promise<WorkspaceMutationLockHandle>;
+/**
+ * Run `operation` while holding the workspace mutation lock.
+ *
+ * Atomic directory creation is the sole lock authority. Owner metadata is
+ * release authorization and diagnostics. Every existing target, including a
+ * legacy file or a directory with missing/corrupt metadata, blocks or fails
+ * closed without mutating the lock path. Release failures propagate so
+ * successful work is never reported unlocked.
+ */
+export declare function withWorkspaceMutationLock<T>(workspaceRoot: string, operation: () => Promise<T>, options?: WorkspaceMutationLockOptions): Promise<T>;
+//# sourceMappingURL=workspace-mutation-lock.d.ts.map

package/dist/operations/mutation/workspace-mutation-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-mutation-lock.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/workspace-mutation-lock.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KACvC,IAAI,CAAC;IACV,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KACxD,IAAI,CAAC;IACV,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAeD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,+BAA+B,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACpD;AAGD,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAkB,IAAI,gCAAgC;CACvD;AAwMD,MAAM,WAAW,2BAA2B;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAGD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,2BAA2B,GAAG,SAAS,EAC/C,gBAAgB,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAC9C,SAAS,UAAQ,GAChB,IAAI,CAoBN;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,GACjB,OAAO,CAWT;AAED;;;;GAIG;AAEH,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,2BAA2B,CAAC,CA4KtC;AAED;;;;;;;;GAQG;AAEH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAWZ"}