kibi-cli 2.20.0 → 2.21.2

package/dist/operations/mutation/delete.js

@@ -3,7 +3,7 @@ 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, readShard, removeRelationshipsFromShards, renderShardWithout, } from "../../relationships/shards.js";
+import { listShards, planRelationshipShardRemovals, readAllShards, readShard, removeRelationshipsFromShards, renderShardWithout, } from "../../relationships/shards.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
 import { buildEntityDeleteAuditGoal } from "./audit.js";
 import { planRecoveryNotes, settlePendingPlanApplyJournals, withPlanRecoveryNotes, } from "./plan-apply-journal.js";
@@ -48,9 +48,74 @@ function fileHash(pathname) {
         return null;
     return createHash("sha256").update(readFileSync(pathname)).digest("hex");
 }
+/** Effects a dry run or plan-only result leaves to a later call. */
+const PLAN_ONLY_SKIPPED_EFFECTS = ["kb-write", "workspace-write"];
+const DRY_RUN_FIELDS = {
+    dryRun: true,
+    outcome: "dry_run",
+    skippedEffects: PLAN_ONLY_SKIPPED_EFFECTS,
+};
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+// implements REQ-011
+/**
+ * The relationship delete a preflight-clean call would perform: the shard and
+ * authored-source writes with their hashes and the compiled edges it would
+ * retract. Nothing is written and the compiled store is not touched.
+ */
+function relationshipDeleteDryRun(shardRoot, preflight, liveByKey, sourcePatches, workspaceRoot) {
+    const planned = planRelationshipShardRemovals(shardRoot, preflight);
+    const sourceWrites = [];
+    for (const [shardPath, body] of planned.bodies) {
+        const before = readFileSync(shardPath, "utf8");
+        if (before === body)
+            continue;
+        sourceWrites.push({
+            path: path.relative(workspaceRoot, shardPath).replaceAll("\\", "/"),
+            mode: "write",
+            beforeHash: sha256(before),
+            afterHash: sha256(body),
+            created: false,
+        });
+    }
+    for (const [relative, patch] of sourcePatches) {
+        sourceWrites.push({
+            path: relative,
+            mode: "write",
+            beforeHash: sha256(patch.before),
+            afterHash: sha256(patch.after),
+            created: false,
+        });
+    }
+    const compiledEdges = preflight.filter((selector) => liveByKey.get(`${selector.type}\0${selector.from}\0${selector.to}`) ===
+        true).length;
+    return {
+        deleted: 0,
+        relationships_deleted: 0,
+        skipped: 0,
+        errors: [],
+        error_codes: [],
+        relationship_results: preflight.map((selector, index) => ({
+            ...selector,
+            deleted: false,
+            shard_records_removed: planned.removals[index]?.removed ?? false,
+            compiled_edge_retracted: liveByKey.get(`${selector.type}\0${selector.from}\0${selector.to}`) ===
+                true,
+        })),
+        wouldDelete: {
+            entities: 0,
+            relationships: preflight.length,
+            compiledEdges,
+        },
+        sync_required: planned.bodies.size > 0 || sourcePatches.size > 0,
+        sourceWrites,
+        ...DRY_RUN_FIELDS,
+    };
+}
 // implements REQ-011
 // covered_by TEST-cli-source-relationship-parity-unit
-async function executeRelationshipDeleteUnlocked(selectors, context, onCommitted = () => undefined) {
+async function executeRelationshipDeleteUnlocked(selectors, context, onCommitted = () => undefined, options = {}) {
     const prolog = requireProlog(context);
     const allowed = new Set(RELATIONSHIP_TYPES);
     const errors = [];
@@ -164,7 +229,11 @@ async function executeRelationshipDeleteUnlocked(selectors, context, onCommitted
             errors,
             error_codes: errorCodes,
             relationship_results: [],
+            ...(options.dryRun === true ? DRY_RUN_FIELDS : {}),
         };
+    if (options.dryRun === true) {
+        return relationshipDeleteDryRun(shardRoot, preflight, liveByKey, sourcePatches, context.workspaceRoot);
+    }
     // Keep byte-level before-images for rollback. Re-serializing parsed records
     // would silently discard comments, ordering, and CST trivia from unrelated
     // shard records after a later compiled-store failure.
@@ -314,9 +383,9 @@ async function executeRelationshipDeleteUnlocked(selectors, context, onCommitted
         ...(sourceWrites.length > 0 ? { sourceWrites } : {}),
     };
 }
-export async function executeRelationshipDelete(selectors, context, onCommitted = () => undefined) {
+export async function executeRelationshipDelete(selectors, context, onCommitted = () => undefined, options = {}) {
     if (!context.fs || context.sourceMutationLockHeld === true)
-        return executeRelationshipDeleteUnlocked(selectors, context, onCommitted);
+        return executeRelationshipDeleteUnlocked(selectors, context, onCommitted, options);
     const lock = await acquireWorkspaceMutationLock(context.workspaceRoot);
     let operationFailure;
     let committed = false;
@@ -324,8 +393,8 @@ export async function executeRelationshipDelete(selectors, context, onCommitted
         const result = await executeRelationshipDeleteUnlocked(selectors, context, () => {
             committed = true;
             onCommitted();
-        });
-        committed = true;
+        }, options);
+        committed = options.dryRun !== true;
         return result;
     }
     catch (error) {
@@ -337,6 +406,91 @@ export async function executeRelationshipDelete(selectors, context, onCommitted
         releaseWorkspaceMutationLock(lock, operationFailure, committed);
     }
 }
+// implements REQ-kibi-operation-interface-parity
+/** The kb_apply_plan call that applies a returned deletion plan unmodified. */
+function applyDeletionPlanNextAction(plan) {
+    return {
+        operation: "kb_apply_plan",
+        input: { plan, approvedPlanHash: plan.planHash },
+        reason: `Review deletionPlan, then apply it unmodified to delete ${plan.entityIds.join(", ")} (or call kb_delete again with the same ids and approvedPlanHash).`,
+        required: true,
+    };
+}
+// implements REQ-kibi-operation-interface-parity
+/** Requirements evolve append-only: point at the supersession upsert. */
+function supersessionNextAction(requirementIds) {
+    return {
+        operation: "kb_upsert",
+        input: {
+            type: "req",
+            id: "<REQ-replacement-id>",
+            relationships: requirementIds.map((id) => ({
+                type: "supersedes",
+                from: "<REQ-replacement-id>",
+                to: id,
+            })),
+        },
+        reason: `Authored requirements are not deleted. Upsert a replacement requirement linked with supersedes to ${requirementIds.join(", ")}, then upsert each superseded requirement with status closed.`,
+        required: true,
+    };
+}
+// implements REQ-kibi-operation-interface-parity
+/**
+ * Apply a freshly computed authored-entity deletion plan in the same call
+ * when the caller approved its hash. The plan goes through kb_apply_plan's
+ * own validation, journal and recovery path; a stale or different approval
+ * fails before anything is written.
+ */
+async function applyApprovedDeletionPlan(plan, approvedPlanHash, planErrors, context, onCommitted, reported) {
+    if (approvedPlanHash.toLowerCase() !== plan.planHash) {
+        throw new InputError("DELETE_PLAN_HASH_MISMATCH", `kb_delete: approvedPlanHash ${approvedPlanHash.slice(0, 12)} does not match the current deletion plan ${plan.planHash.slice(0, 12)} for ${plan.entityIds.join(", ")}. The ids or their sources changed since that plan was returned. Call kb_delete without approvedPlanHash, review the new plan, and approve its planHash. Nothing was written.`);
+    }
+    if (plan.supersessionRequired) {
+        throw new InputError("REQUIREMENT_SUPERSESSION_REQUIRED", "kb_delete: authored requirements evolve through a new requirement linked with supersedes; a deletion plan that requires supersession cannot be approved. Nothing was written.");
+    }
+    if (planErrors.length > 0) {
+        throw new InputError("VALIDATION_FAILED", `kb_delete: approvedPlanHash applies a plan only when every requested id is in it. Remove or fix: ${planErrors.join("; ")} Nothing was written.`);
+    }
+    // apply-plan imports this module; load it lazily to keep the cycle out of
+    // module initialization.
+    const { executeApplyPlan } = await import("../planning/apply-plan.js");
+    const applied = await executeApplyPlan({ plan, approvedPlanHash: plan.planHash }, 
+    // executeDelete already holds the workspace lock (or runs without fs).
+    { ...context, sourceMutationLockHeld: true }, onCommitted);
+    const result = applied.structuredContent;
+    const deleted = typeof result.deleted === "number" ? result.deleted : 0;
+    const repairs = result.status === "committed_with_repairs";
+    const payload = {
+        deleted,
+        skipped: plan.entityIds.length - deleted,
+        errors: [],
+        outcome: "plan_applied",
+        planHash: plan.planHash,
+        sourcePaths: Array.isArray(result.sourcePaths)
+            ? result.sourcePaths
+            : [],
+        ...(typeof result.recoveryJournalId === "string"
+            ? { recoveryJournalId: result.recoveryJournalId }
+            : {}),
+        ...(repairs
+            ? {
+                status: "committed_with_repairs",
+                nextActions: Array.isArray(result.nextActions)
+                    ? result.nextActions
+                    : [],
+            }
+            : {}),
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: reported(`Applied deletion plan ${plan.planHash.slice(0, 12)}: deleted ${deleted} entities.${repairs ? " Compiled retraction needs repair; follow nextActions." : ""}`),
+            },
+        ],
+        structuredContent: payload,
+    };
+}
 export async function executeDelete(input, context) {
     const branchAttachment = context.branchAttachment ?? resolveBranchAttachment(context.workspaceRoot);
     if ("error" in branchAttachment) {
@@ -362,19 +516,29 @@ export async function executeDelete(input, context) {
         }
         const ids = input.ids ?? [];
         const relationships = input.relationships ?? [];
+        const dryRun = input.dryRun === true;
+        const approvedPlanHash = input.approvedPlanHash;
         if ((ids.length === 0) === (relationships.length === 0))
             throw new Error("Delete requires exactly one non-empty input: ids or relationships");
+        if (approvedPlanHash !== undefined) {
+            if (dryRun)
+                throw new InputError("VALIDATION_FAILED", "kb_delete: dryRun and approvedPlanHash cannot be combined. Omit approvedPlanHash to preview the deletion plan, or omit dryRun to apply it.");
+            if (relationships.length > 0)
+                throw new InputError("VALIDATION_FAILED", "kb_delete: approvedPlanHash applies only to an authored-entity deletion plan (ids). Relationship deletes apply directly; use dryRun:true to preview them.");
+        }
         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, sourceMutationLockHeld: true }, () => {
                 committed = true;
-            });
+            }, { dryRun });
             return {
                 content: [
                     {
                         type: "text",
-                        text: reported(`Deleted ${payload.relationships_deleted ?? 0} relationships. Skipped ${payload.skipped}.${payload.sync_required ? " Run kibi sync to reconcile the relationship shard." : ""}`),
+                        text: reported(dryRun
+                            ? `Dry run: would delete ${payload.wouldDelete?.relationships ?? 0} relationships. Skipped ${payload.skipped}. Nothing was written.`
+                            : `Deleted ${payload.relationships_deleted ?? 0} relationships. Skipped ${payload.skipped}.${payload.sync_required ? " Run kibi sync to reconcile the relationship shard." : ""}`),
                     },
                 ],
                 structuredContent: payload,
@@ -383,6 +547,8 @@ export async function executeDelete(input, context) {
         const errors = [];
         const goals = [];
         const authoredIds = [];
+        // Resolved ids that a direct delete would retract (non-authored source).
+        const directIds = [];
         const authoredRequirementIds = [];
         const sourceHashes = {};
         // Keep the original body for rollback, while applying each deletion to the
@@ -451,6 +617,8 @@ export async function executeDelete(input, context) {
                     }
                 }
             }
+            if (!sourceIsAuthored(source))
+                directIds.push(id);
             goals.push(buildEntityDeleteAuditGoal(entity));
         }
         if (authoredIds.length > 0 && context.sourcePlanApplication !== true) {
@@ -496,23 +664,61 @@ export async function executeDelete(input, context) {
             const planHash = createHash("sha256")
                 .update(JSON.stringify(planBody))
                 .digest("hex");
+            const deletionPlan = { ...planBody, planHash };
+            // A plan covers only authored ids; any other resolved id in the same
+            // call is left for a separate direct delete.
+            const planErrors = [
+                ...errors,
+                ...directIds.map((id) => `Entity ${id} was not deleted: this call returned an authored-entity deletion plan. Delete ${id} in a separate kb_delete call.`),
+            ];
+            if (approvedPlanHash !== undefined) {
+                return await applyApprovedDeletionPlan(deletionPlan, approvedPlanHash, planErrors, { ...context, branchAttachment, prolog }, () => {
+                    committed = true;
+                }, reported);
+            }
             const payload = {
                 deleted: 0,
-                skipped: authoredIds.length,
-                errors: [
-                    supersessionRequired
-                        ? "Authored requirements require an explicit supersession plan; no direct delete is performed."
-                        : "Authored entity deletion returns a hash-bound plan for kb_apply_plan.",
-                ],
-                deletionPlan: { ...planBody, planHash },
+                skipped: authoredIds.length + planErrors.length,
+                errors: planErrors,
+                outcome: supersessionRequired
+                    ? "supersession_required"
+                    : "plan_returned",
+                deletionPlan,
+                nextActions: supersessionRequired
+                    ? [supersessionNextAction(authoredRequirementIds)]
+                    : [applyDeletionPlanNextAction(deletionPlan)],
                 // Only kb_apply_plan writes; this call returns the plan.
-                skippedEffects: ["kb-write", "workspace-write"],
+                skippedEffects: PLAN_ONLY_SKIPPED_EFFECTS,
+                ...(dryRun ? { dryRun: true } : {}),
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: reported(supersessionRequired
+                            ? `Authored requirements ${authoredRequirementIds.join(", ")} cannot be deleted: supersede them with kb_upsert (supersedes) and close them instead. Nothing was written.`
+                            : `Returned deletion plan ${planHash.slice(0, 12)} for ${authoredIds.join(", ")}. Nothing was written; apply it with kb_apply_plan (nextActions[0].input), or call kb_delete again with approvedPlanHash.`),
+                    },
+                ],
+                structuredContent: payload,
+            };
+        }
+        if (approvedPlanHash !== undefined &&
+            context.sourcePlanApplication !== true)
+            throw new InputError("VALIDATION_FAILED", `kb_delete: approvedPlanHash was given but ${ids.join(", ")} produced no authored-entity deletion plan to approve. Omit approvedPlanHash to delete these ids directly.`);
+        if (dryRun) {
+            const payload = {
+                deleted: 0,
+                skipped: errors.length,
+                errors,
+                wouldDelete: { entities: goals.length, ids: directIds },
+                ...DRY_RUN_FIELDS,
             };
             return {
                 content: [
                     {
                         type: "text",
-                        text: reported(`Deletion plan ${planHash.slice(0, 12)} must be applied through kb_apply_plan.`),
+                        text: reported(`Dry run: would delete ${goals.length} entities. Skipped ${errors.length}. Nothing was written.${errors.length > 0 ? ` Errors: ${errors.join("; ")}` : ""}`),
                     },
                 ],
                 structuredContent: payload,

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

@@ -1 +1 @@
-{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAwDpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAyDpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}

package/dist/operations/mutation/serialization.js

@@ -13,6 +13,7 @@ const ATOM_FIELDS = [
     "value_type",
     "polarity",
     "expects",
+    "firmness",
 ];
 const STRING_FIELDS = [
     "id",

package/dist/operations/mutation/source-authoring.d.ts

@@ -26,6 +26,14 @@ export declare function restoreFileTimes(absolutePath: string, times: FileTimes
  * removed file makes every later sync fail on a missing pending source.
  */
 export declare function retirePendingSourceReceipt(workspaceRoot: string, relativePath: string): void;
+/**
+ * Rebind the pending receipt of an untracked source that a migration rewrote
+ * in place. A receipt pins the file to exact bytes; a rewrite that leaves the
+ * old hash behind makes every later sync refuse the file as "hash drift", so
+ * a migration republishes the receipt it finds, and leaves a file without
+ * one alone (tracked sources carry no receipt). Returns whether one existed.
+ */
+export declare function republishPendingSourceReceipt(workspaceRoot: string, relativePath: string, afterHash: string): boolean;
 export declare function resolveContainedSourcePath(workspaceRoot: string, relative: string): string;
 export declare function normalizeAuthoredSourcePath(workspaceRoot: string, source: string): string;
 /**

package/dist/operations/mutation/source-authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-authoring.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/source-authoring.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source-authoring.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/source-authoring.ts"],"names":[],"mappings":"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"}

package/dist/operations/mutation/source-authoring.js

@@ -82,6 +82,39 @@ export function retirePendingSourceReceipt(workspaceRoot, relativePath) {
             throw error;
     }
 }
+/**
+ * Rebind the pending receipt of an untracked source that a migration rewrote
+ * in place. A receipt pins the file to exact bytes; a rewrite that leaves the
+ * old hash behind makes every later sync refuse the file as "hash drift", so
+ * a migration republishes the receipt it finds, and leaves a file without
+ * one alone (tracked sources carry no receipt). Returns whether one existed.
+ */
+// implements REQ-cli-schema-migration, REQ-core-atomic-upsert-persistence
+export function republishPendingSourceReceipt(workspaceRoot, relativePath, afterHash) {
+    const receiptPath = pendingReceiptPath(workspaceRoot, relativePath);
+    const raw = readPendingSourceReceiptBytes(receiptPath);
+    if (raw === null)
+        return false;
+    let receipt;
+    try {
+        const parsed = JSON.parse(raw);
+        receipt =
+            parsed !== null && typeof parsed === "object"
+                ? parsed
+                : {};
+    }
+    catch {
+        receipt = {};
+    }
+    fs.writeFileSync(receiptPath, `${JSON.stringify({
+        version: 1,
+        ...receipt,
+        path: relativePath,
+        afterHash,
+        rebasedAt: new Date().toISOString(),
+    }, null, 2)}\n`, { mode: 0o600 });
+    return true;
+}
 /**
  * Authored YAML round-trips keep long scalars on one line, matching sync and
  * coordinate refresh output, so editing one entry never refolds the others.

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

@@ -53,6 +53,12 @@ export type UpsertPayload = {
     readonly relationships_created: number;
     readonly warnings: readonly string[];
     readonly semanticAdvisor: SemanticAdvisorReceipt;
+    /**
+     * For a fact that carries claim_text: the stored claim_key, derived from
+     * claim_text when the payload did not supply it, so the writer learns the
+     * grounding key without a kb_query.
+     */
+    readonly claimKey?: string;
     readonly status?: "committed_with_repairs";
     readonly effectFailures?: readonly {
         readonly kind: string;
@@ -119,8 +125,17 @@ export type DeleteInput = {
         readonly to: string;
     }[];
     readonly _requestId?: string;
+    /** Applies the authored-entity deletion plan whose planHash this is. */
     readonly approvedPlanHash?: string;
+    /** Preview the delete without writing sources or the compiled store. */
+    readonly dryRun?: boolean;
 };
+/**
+ * What a kb_delete call did when it was not a direct delete: returned an
+ * authored-entity deletion plan, refused a requirement that must be
+ * superseded, applied an approved plan, or previewed a dry run.
+ */
+export type DeleteOutcome = "plan_returned" | "supersession_required" | "plan_applied" | "dry_run";
 export type DeletePayload = {
     readonly deleted: number;
     readonly relationships_deleted?: number;
@@ -131,6 +146,28 @@ export type DeletePayload = {
     readonly sync_required?: boolean;
     /** Declared effects this call did not perform, such as a plan-only result. */
     readonly skippedEffects?: readonly string[];
+    /** Absent on a direct delete. */
+    readonly outcome?: DeleteOutcome;
+    readonly dryRun?: true;
+    /** Dry run only: what a commit would delete. */
+    readonly wouldDelete?: Readonly<{
+        readonly entities: number;
+        readonly ids?: readonly string[];
+        readonly relationships?: number;
+        readonly compiledEdges?: number;
+    }>;
+    /** Applied plan only: the plan hash and the source files it changed. */
+    readonly planHash?: string;
+    readonly sourcePaths?: readonly string[];
+    readonly recoveryJournalId?: string;
+    readonly status?: "committed_with_repairs";
+    readonly nextActions?: readonly Readonly<{
+        readonly operation: string;
+        readonly input: unknown;
+        readonly reason: string;
+        readonly required: boolean;
+        readonly detail?: string;
+    }>[];
     readonly sourceWrites?: readonly {
         readonly path: string;
         readonly mode?: "write" | "delete";

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/types.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA8BnF,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAgDpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAgF3B;AAGD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAyhBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA8BnF,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA8DpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAiF3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}

package/dist/operations/mutation/upsert.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { OperationError } from "../../cli-errors.js";
+import { DEFAULT_FIRMNESS, carriesFirmness, firmnessRef, isFirmness, } from "../../decision-firmness.js";
 import { readManifestWithCoordinateOverlay } from "../../extractors/manifest.js";
 import { extractManifestSymbolRecords } from "../../extractors/manifest.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
@@ -47,6 +48,17 @@ function parseChangeKind(value) {
         ? normalized
         : null;
 }
+/**
+ * The claim_key a written fact carries, derived from claim_text at
+ * validation when the payload did not supply it, echoed so the writer
+ * knows the grounding key without a kb_query.
+ */
+// implements REQ-upsert-committed-claim-key
+function storedClaimKey(entity) {
+    return entity.type === "fact" && typeof entity.claim_key === "string"
+        ? { claimKey: entity.claim_key }
+        : {};
+}
 function fileHash(pathname) {
     if (!existsSync(pathname))
         return null;
@@ -220,14 +232,52 @@ export async function validateUpsertForCommit(payload, context, options = {}) {
     // The origin the write records is added last: none of the checks above
     // reads it, and a rejected payload never pays for the stored-origin read.
     const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged, lookup);
+    const decided = await resolveUpsertFirmness(recorded, staged, lookup);
     return {
-        validated: recorded === input
+        validated: decided === input
             ? validated
-            : validateUpsertInput(recorded, context.clock()),
+            : validateUpsertInput(decided, context.clock()),
         relationships,
         semantic,
     };
 }
+/**
+ * The firmness a requirement or ADR write records. An update that omits
+ * `firmness` keeps the stored value, so the compiled entity matches the
+ * authored front matter. A decision left firm must name the human words it
+ * rests on, so an agent cannot promote its own choice: it is judged as it
+ * will be written, with the origin this write records and the stored
+ * `approval_ref` when the write omits one. kb_check enforces the same rule on
+ * authored sources.
+ */
+// implements REQ-kb-decision-firmness
+async function resolveUpsertFirmness(input, staged, lookup) {
+    if (!carriesFirmness(input.type))
+        return input;
+    const properties = input.properties;
+    if (properties.firmness !== undefined && properties.firmness !== "firm")
+        return input;
+    const stored = properties.firmness === undefined || properties.approval_ref === undefined
+        ? (staged?.entities.get(input.id) ?? (await lookup.entity()) ?? undefined)
+        : undefined;
+    const firmness = properties.firmness ?? stored?.firmness;
+    if (!isFirmness(firmness) || firmness === DEFAULT_FIRMNESS)
+        return input;
+    if (firmness === "firm" &&
+        firmnessRef({
+            type: input.type,
+            origin: properties.origin,
+            approval_ref: properties.approval_ref ?? stored?.approval_ref,
+        }) === undefined) {
+        throw new Error(`Entity validation failed: firmness: firm needs origin.ref${input.type === "req" ? " (or approval_ref)" : ""} pointing at the human words that state the rule; use firmness: default for a delegated or agent choice`);
+    }
+    return properties.firmness === firmness
+        ? input
+        : {
+            ...input,
+            properties: { ...input.properties, firmness },
+        };
+}
 // implements REQ-kibi-operation-interface-parity
 /**
  * A dry run is the former kb_validate_upsert preflight on the kb_upsert
@@ -461,6 +511,7 @@ export async function executeUpsert(input, context, options = {}) {
                     relationships_created: validated.relationships.length,
                     warnings: [...planRecoveryWarnings, ...semantic.warnings],
                     semanticAdvisor: semantic.receipt,
+                    ...storedClaimKey(commitEntity ?? validated.entity),
                     deferredCommit,
                     ...(sourceWrite ? { sourceWrites: [sourceWrite.receipt] } : {}),
                 },
@@ -540,6 +591,7 @@ export async function executeUpsert(input, context, options = {}) {
                 ...shardWarnings,
             ],
             semanticAdvisor: semantic.receipt,
+            ...storedClaimKey(commitEntity ?? validated.entity),
             ...(shardWarnings.length > 0
                 ? {
                     status: "committed_with_repairs",

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":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqI/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA4DjB;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;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqI/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -4,7 +4,7 @@ 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 { semanticClaimKey } from "../semantic-advisor/clauses.js";
+import { deriveFactClaimKey, semanticClaimKey, } from "../semantic-advisor/clauses.js";
 import { factKindShapeHints, validateFactModelingShape, valueFieldHint, } from "./strict-fact.js";
 const ajv = new Ajv({ strict: false });
 const schema = entitySchema;
@@ -128,6 +128,7 @@ export function validateUpsertInput(input, now) {
     if (!validateEntity(entity)) {
         throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
     }
+    deriveFactClaimKey(entity);
     validateSymbolSourceFile(entity);
     validateProofExemptionPairing(entity);
     if (entity.type === "test" && Array.isArray(entity.proof_receipts)) {

package/dist/operations/planning/apply-plan.d.ts

@@ -17,7 +17,12 @@ export declare function orderBootstrapActions(actions: readonly BootstrapAction[
  * The apply itself repeats every check under the workspace lock.
  */
 export declare function preflightApplyPlan(args: ApplyPlanArgs, context: OperationContext): Promise<void>;
-export declare function executeApplyPlan(args: ApplyPlanArgs, context: OperationContext): Promise<{
+export declare function executeApplyPlan(args: ApplyPlanArgs, context: OperationContext, 
+/**
+ * Called once the plan's commit is authoritative, for a caller that holds
+ * the workspace lock and must classify a later failure as committed.
+ */
+onCommitted?: () => void): Promise<{
     content: Array<{
         type: "text";
         text: string;