kibi-cli 1.0.1 → 2.1.0

package/dist/operations/modeling/suggest-predicates.js

@@ -1,5 +1,6 @@
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
+import { composeOntologyCatalogForOperation } from "../semantic-advisor/plugin-orchestration.js";
 import { STRONG_APPLICABILITY_SCORE, WEAK_CANDIDATE_MARGIN, evaluateSemanticApplicability, } from "./predicate-applicability.js";
 import { buildGapApplyPlan, buildPredicateApplyPlan, buildPredicateSchemaDraft, buildRelationshipPlan, buildSuggestion, } from "./predicate-applyplan.js";
 import { BUILT_IN_PREDICATE_SCHEMAS } from "./predicate-catalog.js";
@@ -14,15 +15,14 @@ const NON_ASSERTIVE_PROPOSITION_ROLES = new Set([
     "example",
     "subjective",
 ]);
-function assertivePropositionCount(text) {
-    const analysis = analyzeSemanticAdvisorInput({
+function analyzeInputPropositions(text) {
+    return analyzeSemanticAdvisorInput({
         payload: {
             type: "req",
             id: "REQ-KIBI-PREDICATE-SUGGESTION-INPUT",
             properties: { semantic_text: text },
         },
-    });
-    return analysis.receipt.propositions.filter((proposition) => !NON_ASSERTIVE_PROPOSITION_ROLES.has(proposition.role)).length;
+    }).receipt.propositions;
 }
 function compoundInputAbstention(args, text, subject, propositionCount) {
     const claimKey = semanticClaimKey(text);
@@ -52,6 +52,34 @@ function compoundInputAbstention(args, text, subject, propositionCount) {
         applyPlan,
     };
 }
+function nonlogicalInputRouting(args, text, subject) {
+    const claimKey = semanticClaimKey(text);
+    const warning = "The semantic advisor classifies this prose as nonlogical (rationale, example, or subjective context); it does not assert a verifiable domain proposition. Advisor routing wins: no predicate candidates, schema draft, or write plan were generated, and the claim was not added to logic_claims.";
+    const applyPlan = [];
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Predicate suggestion abstained because the semantic advisor classifies this prose as nonlogical (rationale, example, or subjective context). Keep it outside logic_claims; no candidate, ontology-gap observation, or schema draft was generated.",
+            },
+        ],
+        structuredContent: {
+            text,
+            claimKey,
+            logicClaims: Array.from(new Set(args.existingLogicClaims ?? [])),
+            source: args.source ?? null,
+            requirementId: args.requirementId ?? null,
+            subject,
+            candidates: [],
+            recommendedAction: "review_nonlogical",
+            recommendedPredicateSchema: null,
+            applyPlan,
+            relationshipPlan: null,
+            warnings: [warning],
+        },
+        applyPlan,
+    };
+}
 function uniqueSchemas(schemas) {
     const seen = new Set();
     return schemas.filter((schema) => {
@@ -62,14 +90,36 @@ function uniqueSchemas(schemas) {
         return true;
     });
 }
+function ontologyPackSchemasToCandidates(schemas) {
+    return schemas.map((schema) => ({
+        id: schema.schemaId,
+        predicate_name: schema.predicateName,
+        title: schema.title ?? schema.predicateName,
+        description: schema.description ?? schema.predicateName,
+        argument_names: [...schema.argumentNames],
+        argument_types: [...schema.argumentTypes],
+        keywords: [schema.predicateName, ...(schema.aliases ?? [])],
+        ...(schema.aliases ? { aliases: [...schema.aliases] } : {}),
+        examples: [],
+        tags: ["ontology-pack"],
+    }));
+}
+export function compareEligibleByApplicabilityThenName(left, right) {
+    if (right.applicability_score !== left.applicability_score)
+        return right.applicability_score - left.applicability_score;
+    return left.predicate_name.localeCompare(right.predicate_name);
+}
+export function compareEligibleByApplicabilityScoreThenName(left, right) {
+    if (right.applicability_score !== left.applicability_score)
+        return right.applicability_score - left.applicability_score;
+    if (right.score !== left.score)
+        return right.score - left.score;
+    return left.predicate_name.localeCompare(right.predicate_name);
+}
 function withMarginRejection(candidates) {
     const eligible = candidates
         .filter((candidate) => candidate.eligibility === "eligible")
-        .sort((left, right) => {
-        if (right.applicability_score !== left.applicability_score)
-            return right.applicability_score - left.applicability_score;
-        return left.predicate_name.localeCompare(right.predicate_name);
-    });
+        .sort(compareEligibleByApplicabilityThenName);
     const top = eligible[0];
     const second = eligible[1];
     if (!top ||
@@ -94,20 +144,36 @@ function withMarginRejection(candidates) {
     });
 }
 // implements REQ-mcp-suggest-predicates
-export async function handleKbSuggestPredicates(prolog, args) {
+export async function handleKbSuggestPredicates(prolog, args, context) {
     const text = normalizeText(args.text);
     const subject = inferSubject(text, args.subjectHint);
-    const propositionCount = assertivePropositionCount(text);
-    if (propositionCount > 1) {
-        return compoundInputAbstention(args, text, subject, propositionCount);
+    const propositions = analyzeInputPropositions(text);
+    const assertivePropositionCount = propositions.filter((proposition) => !NON_ASSERTIVE_PROPOSITION_ROLES.has(proposition.role)).length;
+    if (propositions.length > 0 && assertivePropositionCount === 0) {
+        return nonlogicalInputRouting(args, text, subject);
+    }
+    if (assertivePropositionCount > 1) {
+        return compoundInputAbstention(args, text, subject, assertivePropositionCount);
     }
     const maxCandidates = clampInteger(args.maxCandidates, DEFAULT_MAX_CANDIDATES, 1, 20);
     const minScore = clampScore(args.minScore ?? DEFAULT_MIN_SCORE);
     const warnings = [];
     const existingSchemas = await loadExistingPredicateSchemas(prolog, args.includeExistingSchemas ?? true, warnings);
+    const composedCatalog = await composeOntologyCatalogForOperation(context, "kb_suggest_predicates");
+    const packSchemas = composedCatalog
+        ? ontologyPackSchemasToCandidates(composedCatalog.schemas)
+        : [];
+    // When ontology resolution is in replace mode and the replace pack
+    // successfully supplied its catalog, do not silently re-append the builtin
+    // *provider* catalog. Persisted/project KB schemas remain available.
+    const includeBuiltinProviderCatalog = !(composedCatalog?.replaced === true);
+    if (composedCatalog?.diagnostics?.length) {
+        warnings.push(...composedCatalog.diagnostics);
+    }
     const schemas = uniqueSchemas([
         ...existingSchemas,
-        ...BUILT_IN_PREDICATE_SCHEMAS,
+        ...(includeBuiltinProviderCatalog ? BUILT_IN_PREDICATE_SCHEMAS : []),
+        ...packSchemas,
     ]);
     const selectedSchemas = args.schemaId
         ? schemas.filter((schema) => schema.id === args.schemaId)
@@ -163,13 +229,7 @@ export async function handleKbSuggestPredicates(prolog, args) {
         : [];
     const recommendedCandidate = candidates
         .filter((candidate) => candidate.eligibility === "eligible")
-        .sort((left, right) => {
-        if (right.applicability_score !== left.applicability_score)
-            return right.applicability_score - left.applicability_score;
-        if (right.score !== left.score)
-            return right.score - left.score;
-        return left.predicate_name.localeCompare(right.predicate_name);
-    })[0];
+        .sort(compareEligibleByApplicabilityScoreThenName)[0];
     if (candidates.length === 0 && !args.schemaId) {
         warnings.push("No predicate candidate met minScore. If this is recurring domain language, create a fact_kind=predicate_schema fact; otherwise keep the generated review:ontology-gap observation. Do not invent unsupported predicate names without a predicate_schema.");
     }
@@ -222,5 +282,5 @@ export async function handleKbSuggestPredicates(prolog, args) {
     };
 }
 export async function executeSuggestPredicates(args, context) {
-    return handleKbSuggestPredicates(context.prolog ?? null, args);
+    return handleKbSuggestPredicates(context.prolog ?? null, args, context);
 }

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

@@ -1,3 +1,4 @@
+import type { PrologErrorRecord } from "../../prolog/error-terms.js";
 import type { RelationshipInput } from "./types.js";
 type TransactionInput = {
     readonly entity: Readonly<Record<string, unknown>>;
@@ -5,6 +6,6 @@ type TransactionInput = {
     readonly skipContradictionCheck: boolean;
 };
 export declare function buildUpsertCommitGoal(input: TransactionInput): string;
-export declare function formatUpsertError(entityId: string, raw?: string): string;
+export declare function formatUpsertError(entityId: string, raw?: string, record?: PrologErrorRecord): string;
 export {};
 //# sourceMappingURL=contradictions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/contradictions.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C,CAAC;AAGF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAGD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA6CxE"}
+{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/contradictions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AASrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C,CAAC;AAGF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAGD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAOR"}

package/dist/operations/mutation/contradictions.js

@@ -1,5 +1,5 @@
 import { escapeAtom } from "../../prolog/codec.js";
-import { formatInvalidRelationshipError } from "./relationships.js";
+import { formatInvalidRelationshipError, formatInvalidRelationshipTuple, } from "./relationships.js";
 import { buildPropertyList, buildRelationshipMetadata, } from "./serialization.js";
 // implements REQ-kibi-operation-interface-parity
 export function buildUpsertCommitGoal(input) {
@@ -8,12 +8,33 @@ export function buildUpsertCommitGoal(input) {
     return `kb_commit_upsert(${type}, ${buildPropertyList(input.entity)}, [${relationships.join(", ")}], ${input.skipContradictionCheck ? "true" : "false"}, ChangeKind)`;
 }
 // implements REQ-kibi-operation-interface-parity
-export function formatUpsertError(entityId, raw) {
+export function formatUpsertError(entityId, raw, record) {
+    const stage = raw?.match(/\(stage=([^)]+)\)/)?.[1];
+    const stageSuffix = stage === undefined ? "" : ` (stage=${stage})`;
+    if (record) {
+        return formatStructuredUpsertError(entityId, record, stageSuffix);
+    }
+    return formatTextUpsertError(entityId, raw, stageSuffix);
+}
+function formatStructuredUpsertError(entityId, record, stageSuffix) {
+    if (record.code === "contradiction") {
+        const conflicts = [
+            ...new Set((record.conflicts ?? []).map((conflict) => `  - Conflicts with ${conflict.otherId}: ${conflict.reason}`)),
+        ];
+        if (conflicts.length > 0) {
+            return `Contradiction detected for requirement ${entityId}:\n${conflicts.join("\n")}\n\nTo resolve:\n  1. Add a supersedes relationship from the new requirement to the conflicting one, OR\n  2. Deprecate the conflicting requirement before creating the new one.${stageSuffix}`;
+        }
+        return `Contradiction detected for entity ${entityId}: This requirement conflicts with existing requirements. Add a supersedes relationship to the conflicting requirement, or deprecate the old requirement before creating the new one.${stageSuffix}`;
+    }
+    if (record.code === "invalid_relationship" && record.relationship) {
+        return `Failed to upsert entity ${entityId}: ${formatInvalidRelationshipTuple(record.relationship)}${stageSuffix}`;
+    }
+    return `Failed to upsert entity ${entityId}: ${record.message}${stageSuffix}`;
+}
+function formatTextUpsertError(entityId, raw, stageSuffix) {
     if (!raw)
         return `Failed to upsert entity ${entityId}: Unknown error`;
-    const stage = raw.match(/\(stage=([^)]+)\)/)?.[1];
-    const stageSuffix = stage === undefined ? "" : ` (stage=${stage})`;
-    const diagnosticFree = raw.replace(/^__KIBI_(?:STAGE|RUNTIME)__:[^\r\n]*\r?\n?/gm, "");
+    const diagnosticFree = raw.replace(/^__KIBI_(?:STAGE|RUNTIME|ERROR)__:[^\r\n]*\r?\n?/gm, "");
     if (diagnosticFree.includes("stale_snapshot")) {
         return `Failed to upsert entity ${entityId}: KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)${stageSuffix}`;
     }

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

@@ -1,5 +1,8 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
+import { type RelationshipSelector } from "../../relationships/shards.js";
 import type { DeleteInput, DeletePayload } from "./types.js";
+export declare function assertFilesystemCapableRuntime(fs: OperationContext["fs"]): asserts fs is NonNullable<OperationContext["fs"]>;
+export declare function executeRelationshipDelete(selectors: readonly RelationshipSelector[], context: OperationContext, onCommitted?: () => void): Promise<DeletePayload>;
 export declare function executeDelete(input: DeleteInput, context: OperationContext): Promise<OperationResult<DeletePayload>>;
 //# sourceMappingURL=delete.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/delete.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAsBxE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkW7D,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA4MzC"}
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/delete.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EACL,KAAK,oBAAoB,EAI1B,MAAM,+BAA+B,CAAC;AAgBvC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAc7D,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,gBAAgB,CAAC,IAAI,CAAC,GACzB,OAAO,CAAC,EAAE,IAAI,WAAW,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAMnD;AAuWD,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,OAAO,EAAE,gBAAgB,EACzB,WAAW,GAAE,MAAM,IAAsB,GACxC,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA6OzC"}

package/dist/operations/mutation/delete.js

@@ -1,6 +1,7 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { InputError, OperationError } from "../../cli-errors.js";
 import { parseEntityFromList, parseListOfLists, toPrologAtom, } from "../../prolog/codec.js";
 import { listShards, readAllShards, removeRelationshipsFromShards, } from "../../relationships/shards.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
@@ -8,11 +9,17 @@ import { buildEntityDeleteAuditGoal } from "./audit.js";
 import { RELATIONSHIP_TYPES, dependentRelationshipsGoal, } from "./relationships.js";
 import { saveAtomicMutation, saveMutation } from "./save.js";
 import { normalizeAuthoredSourcePath, renderMarkdownRelationshipDeletion, renderSourceDeletion, renderYamlRelationshipDeletion, resolveContainedSourcePath, writePendingSourceReceipt, } from "./source-authoring.js";
+import { acquireWorkspaceMutationLock, classifySourceMutationFailure, releaseWorkspaceMutationLock, } from "./workspace-mutation-lock.js";
 function requireProlog(context) {
     if (context.prolog === undefined)
         throw new Error("Delete operation requires a Prolog runtime");
     return context.prolog;
 }
+export function assertFilesystemCapableRuntime(fs) {
+    if (!fs) {
+        throw new Error("Relationship source patch requires a filesystem-capable runtime");
+    }
+}
 async function loadEntity(prolog, id) {
     const safeId = id.replaceAll("'", "''");
     const result = await prolog.query(`findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`);
@@ -40,7 +47,9 @@ function fileHash(pathname) {
         return null;
     return createHash("sha256").update(readFileSync(pathname)).digest("hex");
 }
-async function executeRelationshipDelete(selectors, context) {
+// implements REQ-011
+// covered_by TEST-cli-source-relationship-parity-unit
+async function executeRelationshipDeleteUnlocked(selectors, context, onCommitted = () => undefined) {
     const prolog = requireProlog(context);
     const allowed = new Set(RELATIONSHIP_TYPES);
     const errors = [];
@@ -84,41 +93,40 @@ async function executeRelationshipDelete(selectors, context) {
             record.to === selector.to);
         const liveResult = await prolog.query(`once(kb_relationship(${toPrologAtom(selector.type)}, ${toPrologAtom(selector.from)}, ${toPrologAtom(selector.to)}))`);
         let sourceRemoved = false;
-        let authoredYamlSource = false;
+        let authoredSourceKind;
         if (context.fs) {
             // Authored YAML symbol relationships remain authoritative even when the
             // compiled edge or relationship shard is present. Patch the source first
             // so the next sync cannot recreate a relationship the caller deleted.
-            // Legacy Markdown declarations retain their fallback-only behavior.
+            // Legacy Markdown declarations are authoritative by the same rule.
             try {
                 const entity = await loadEntity(prolog, selector.from);
                 const source = typeof entity.source === "string" ? entity.source : "";
                 if (sourceIsAuthored(source)) {
-                    authoredYamlSource = /\.(?:ya?ml)$/i.test(source);
+                    authoredSourceKind = /\.(?:ya?ml)$/i.test(source.replaceAll("\\", "/"))
+                        ? "YAML"
+                        : "Markdown";
                     const relative = normalizeAuthoredSourcePath(context.workspaceRoot, source);
                     const absolute = resolveContainedSourcePath(context.workspaceRoot, relative);
                     const isYaml = /\.(?:ya?ml)$/i.test(relative);
-                    authoredYamlSource = isYaml;
-                    if (isYaml || (!liveResult.success && matchingShard.length === 0)) {
-                        const previous = sourcePatches.get(relative);
-                        const before = previous?.before ?? (await context.fs.readFile(absolute));
-                        const current = previous?.after ?? before;
-                        const rendered = isYaml
-                            ? renderYamlRelationshipDeletion(relative, current, selector)
-                            : renderMarkdownRelationshipDeletion(relative, current, selector);
-                        if (rendered.removed) {
-                            sourcePatches.set(relative, {
-                                before,
-                                after: rendered.body,
-                            });
-                            sourceRemoved = true;
-                        }
+                    const previous = sourcePatches.get(relative);
+                    const before = previous?.before ?? (await context.fs.readFile(absolute));
+                    const current = previous?.after ?? before;
+                    const rendered = isYaml
+                        ? renderYamlRelationshipDeletion(relative, current, selector)
+                        : renderMarkdownRelationshipDeletion(relative, current, selector);
+                    if (rendered.removed) {
+                        sourcePatches.set(relative, {
+                            before,
+                            after: rendered.body,
+                        });
+                        sourceRemoved = true;
                     }
                 }
             }
             catch (error) {
-                if (authoredYamlSource) {
-                    throw new Error(`Authored YAML relationship deletion failed for ${selector.from}: ${error instanceof Error ? error.message : String(error)}`);
+                if (authoredSourceKind !== undefined) {
+                    throw new Error(`Authored ${authoredSourceKind} relationship deletion failed for ${selector.from}: ${error instanceof Error ? error.message : String(error)}`);
                 }
                 // The normal typed preflight below reports a deterministic not-found
                 // or inspection error when no authored source can prove the edge.
@@ -183,17 +191,24 @@ async function executeRelationshipDelete(selectors, context) {
         throw new Error(`Relationship shard update failed before compiled mutation: ${error instanceof Error ? error.message : String(error)}`);
     }
     const writeSourcePatch = async (relative, body) => {
-        if (!context.fs)
-            throw new Error("Relationship source patch requires a filesystem-capable runtime");
+        assertFilesystemCapableRuntime(context.fs);
         const absolute = resolveContainedSourcePath(context.workspaceRoot, relative);
         await context.fs.mkdir(path.dirname(absolute));
-        const temporary = `${absolute}.kibi-relationship-${process.pid}-${Date.now()}`;
-        await context.fs.writeFile(temporary, body);
-        if (context.fs.rename)
-            await context.fs.rename(temporary, absolute);
-        else {
-            await context.fs.writeFile(absolute, body);
+        const temporary = `${absolute}.kibi-relationship-${process.pid}-${randomUUID()}`;
+        try {
+            await context.fs.writeFile(temporary, body);
+            if (context.fs.rename)
+                await context.fs.rename(temporary, absolute);
+            else {
+                await context.fs.writeFile(absolute, body);
+                await context.fs.unlink?.(temporary).catch(() => undefined);
+            }
+        }
+        catch (error) {
+            // A failed rename must not leak the unique temp file into the authored
+            // tree; the published target (if any) is untouched at this point.
             await context.fs.unlink?.(temporary).catch(() => undefined);
+            throw error;
         }
     };
     try {
@@ -226,6 +241,9 @@ async function executeRelationshipDelete(selectors, context) {
         }
         if (retracted > 0)
             await saveMutation(prolog, "delete");
+        // The compiled mutation is now authoritative. Receipt publication below
+        // must not make the enclosing operation look retryable.
+        onCommitted();
     }
     catch (error) {
         const paths = [
@@ -295,6 +313,29 @@ async function executeRelationshipDelete(selectors, context) {
         ...(sourceWrites.length > 0 ? { sourceWrites } : {}),
     };
 }
+export async function executeRelationshipDelete(selectors, context, onCommitted = () => undefined) {
+    if (!context.fs || context.sourceMutationLockHeld === true)
+        return executeRelationshipDeleteUnlocked(selectors, context, onCommitted);
+    const lock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+    let operationFailure;
+    let committed = false;
+    try {
+        const result = await executeRelationshipDeleteUnlocked(selectors, context, () => {
+            committed = true;
+            onCommitted();
+        });
+        committed = true;
+        return result;
+    }
+    catch (error) {
+        const failure = classifySourceMutationFailure("Relationship delete", error, committed);
+        operationFailure = { error: failure };
+        throw failure;
+    }
+    finally {
+        releaseWorkspaceMutationLock(lock, operationFailure, committed);
+    }
+}
 export async function executeDelete(input, context) {
     const branchAttachment = context.branchAttachment ?? resolveBranchAttachment(context.workspaceRoot);
     if ("error" in branchAttachment) {
@@ -305,7 +346,13 @@ export async function executeDelete(input, context) {
         throw new Error(`Delete 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);
+    let sourceMutationLock;
+    let committed = false;
+    let operationFailure;
     try {
+        if (context.fs && context.sourceMutationLockHeld !== true) {
+            sourceMutationLock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+        }
         const ids = input.ids ?? [];
         const relationships = input.relationships ?? [];
         if ((ids.length === 0) === (relationships.length === 0))
@@ -313,7 +360,9 @@ export async function executeDelete(input, context) {
         if (relationships.length > 0) {
             if (relationships.some((value) => !isSelector(value)))
                 throw new Error("Each relationship selector requires non-empty type, from, and to strings");
-            const payload = await executeRelationshipDelete(relationships, context);
+            const payload = await executeRelationshipDelete(relationships, { ...context, sourceMutationLockHeld: true }, () => {
+                committed = true;
+            });
             return {
                 content: [
                     {
@@ -435,6 +484,7 @@ export async function executeDelete(input, context) {
                 await saveAtomicMutation(prolog, goals, "delete");
             else
                 await saveMutation(prolog, "delete");
+            committed = true;
         }
         catch (error) {
             for (const [source, body] of sourceBodies) {
@@ -458,6 +508,24 @@ export async function executeDelete(input, context) {
         };
     }
     catch (error) {
-        throw new Error(`Delete execution failed: ${error instanceof Error ? error.message : String(error)}`);
+        // Typed operation errors keep their code and retryability. After the
+        // commit milestone, a generic failure is already a committed mutation:
+        // wrap it as non-retryable immediately instead of only when lock release
+        // also fails.
+        if (error instanceof OperationError || error instanceof InputError) {
+            operationFailure = { error };
+            throw error;
+        }
+        if (committed) {
+            const failure = classifySourceMutationFailure("Delete", error, true);
+            operationFailure = { error: failure };
+            throw failure;
+        }
+        const failure = new Error(`Delete execution failed: ${error instanceof Error ? error.message : String(error)}`);
+        operationFailure = { error: failure };
+        throw failure;
+    }
+    finally {
+        releaseWorkspaceMutationLock(sourceMutationLock, operationFailure, committed);
     }
 }

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

@@ -2,6 +2,7 @@ import type { PrologPort } from "../../public/operations/runtime-types.js";
 import type { RelationshipInput } from "./types.js";
 export declare const RELATIONSHIP_TYPES: readonly ["depends_on", "specified_by", "verified_by", "validates", "implements", "covered_by", "executable_for", "constrained_by", "constrains", "requires_property", "requires_predicate", "requires_rule", "guards", "publishes", "consumes", "supersedes", "relates_to"];
 export type RelationshipType = (typeof RELATIONSHIP_TYPES)[number];
+export declare function wrongKindRelationshipError(type: string, target: string, wrongKind: string): Error;
 export declare function dependentRelationshipsGoal(entityId: string): string;
 type RelationshipTuple = {
     readonly relType: string;

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

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/relationships.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,kBAAkB,8QAkBrB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,KAAK,iBAAiB,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAgCF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAER;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,IAAI,CAMN;AAED,KAAK,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D,KAAK,qBAAqB,GAAG,QAAQ,CAAC;IACpC,mBAAmB,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9E,UAAU,EAAE,CACV,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,KACf,OAAO,GAAG,IAAI,CAAC;CACrB,CAAC,CAAC;AAMH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAef;AAsBD,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,IAAI,GAAE,IAAI,CACR,qBAAqB,EACrB,YAAY,CACqB,GAClC,iBAAiB,CAenB;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,qBAAuD,GAC5D,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,iBAAiB,GAC9B,MAAM,CAIR;AAuBD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAevC"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/relationships.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,kBAAkB,8QAkBrB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,KAAK,CAKP;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,KAAK,iBAAiB,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAgCF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAER;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,IAAI,CAMN;AAED,KAAK,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D,KAAK,qBAAqB,GAAG,QAAQ,CAAC;IACpC,mBAAmB,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9E,UAAU,EAAE,CACV,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,KACf,OAAO,GAAG,IAAI,CAAC;CACrB,CAAC,CAAC;AAMH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAef;AAsBD,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,IAAI,GAAE,IAAI,CACR,qBAAqB,EACrB,YAAY,CACqB,GAClC,iBAAiB,CAenB;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,qBAAuD,GAC5D,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,iBAAiB,GAC9B,MAAM,CAIR;AAuBD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAevC"}

package/dist/operations/mutation/relationships.js

@@ -20,6 +20,10 @@ export const RELATIONSHIP_TYPES = [
     "supersedes",
     "relates_to",
 ];
+export function wrongKindRelationshipError(type, target, wrongKind) {
+    const expected = type === "constrains" ? "subject" : "property_value";
+    return new Error(`Relationship '${type}' requires target '${target}' to be a ${expected}, observation, or meta fact. ${wrongKind[0]?.toUpperCase()}${wrongKind.slice(1)} facts cannot be direct targets of ${type} relationships.`);
+}
 export function dependentRelationshipsGoal(entityId) {
     return `findall([RelType,From], (member(RelType, [${RELATIONSHIP_TYPES.join(", ")}]), kb_relationship(RelType, From, '${escapeAtom(entityId)}')), Dependents)`;
 }
@@ -192,10 +196,8 @@ export async function validateStrictLanePairing(prolog, relationships) {
         if (wrongKind === null)
             continue;
         const result = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, ${wrongKind})))`);
-        if (result.success) {
-            const expected = relationship.type === "constrains" ? "subject" : "property_value";
-            throw new Error(`Relationship '${String(relationship.type)}' requires target '${target}' to be a ${expected}, observation, or meta fact. ${wrongKind[0]?.toUpperCase()}${wrongKind.slice(1)} facts cannot be direct targets of ${String(relationship.type)} relationships.`);
-        }
+        if (result.success)
+            throw wrongKindRelationshipError(String(relationship.type), target, wrongKind);
     }
 }
 export async function existingRelationships(prolog, entityId) {

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

@@ -0,0 +1,51 @@
+/**
+ * Declared compensation list for multi-surface mutations.
+ *
+ * An upsert touches authored sources, relationship shards, generated
+ * coordinate artifacts, and the compiled KB — in that order — and a failed
+ * attempt must undo them in reverse order without masking the original
+ * failure. Instead of tracking rollback state in scattered locals, steps
+ * register a named rollback as they succeed; one rollback() call walks the
+ * list backwards exactly once.
+ */
+export type SagaStep = Readonly<{
+    /** Stable identifier used in rollback diagnostics. */
+    name: string;
+    /**
+     * Undo the step. Implementations should target idempotence (guards against
+     * concurrent writers, tolerating an already-restored surface); rollback()
+     * never re-throws a rollback error.
+     */
+    rollback: () => void | Promise<void>;
+    /**
+     * `swallow` (default): preserve the original mutation failure; the recovery
+     * journal / next check reconciles. `capture`: report the rollback failure
+     * alongside the original error (e.g. as an AggregateError).
+     */
+    onError?: "swallow" | "capture";
+}>;
+export type SagaRollbackFailure = Readonly<{
+    step: string;
+    error: unknown;
+}>;
+export declare class MutationSaga {
+    private readonly steps;
+    private rollbackCompleted;
+    private committedAt;
+    /** Register a completed step. Call only after the step fully succeeded. */
+    add(step: SagaStep): void;
+    /**
+     * The durable commit point: once marked, rollback() is a no-op — the
+     * compiled KB holds the change and post-commit failures surface as
+     * committed-with-repairs results instead of undoing committed state.
+     */
+    markCommitted(): void;
+    get committed(): boolean;
+    /**
+     * Roll back every registered step in reverse order, exactly once. Rollback
+     * errors never throw; capture-policy failures are returned so the caller
+     * can decide whether to aggregate them into the propagated error.
+     */
+    rollback(): Promise<readonly SagaRollbackFailure[]>;
+}
+//# sourceMappingURL=saga.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"saga.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/saga.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;GASG;AAGH,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACjC,CAAC,CAAC;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAGH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,WAAW,CAAuB;IAE1C,2EAA2E;IAE3E,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAIzB;;;;OAIG;IAEH,aAAa,IAAI,IAAI;IAKrB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;OAIG;IAEG,QAAQ,IAAI,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;CAkB1D"}

package/dist/operations/mutation/saga.js

@@ -0,0 +1,67 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ 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/>.
+ */
+// implements REQ-014
+export class MutationSaga {
+    steps = [];
+    rollbackCompleted = false;
+    committedAt = null;
+    /** Register a completed step. Call only after the step fully succeeded. */
+    // implements REQ-014
+    add(step) {
+        this.steps.push(step);
+    }
+    /**
+     * The durable commit point: once marked, rollback() is a no-op — the
+     * compiled KB holds the change and post-commit failures surface as
+     * committed-with-repairs results instead of undoing committed state.
+     */
+    // implements REQ-014
+    markCommitted() {
+        this.committedAt = this.steps.length;
+    }
+    // implements REQ-014
+    get committed() {
+        return this.committedAt !== null;
+    }
+    /**
+     * Roll back every registered step in reverse order, exactly once. Rollback
+     * errors never throw; capture-policy failures are returned so the caller
+     * can decide whether to aggregate them into the propagated error.
+     */
+    // implements REQ-014
+    async rollback() {
+        if (this.rollbackCompleted || this.committedAt !== null)
+            return [];
+        this.rollbackCompleted = true;
+        const captured = [];
+        for (const step of [...this.steps].reverse()) {
+            try {
+                await step.rollback();
+            }
+            catch (error) {
+                if (step.onError === "capture") {
+                    captured.push({ step: step.name, error });
+                }
+                // Swallow-policy failures keep the original mutation error intact;
+                // the recovery journal and the next check/sync report what could not
+                // be restored.
+            }
+        }
+        return captured;
+    }
+}