kibi-cli 2.0.0 → 2.2.0

package/dist/operations/mutation/upsert.js

@@ -9,11 +9,13 @@ import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
 import { appendRelationship, computeShardPath, } from "../../relationships/shards.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
+import { entityIdStyleWarnings } from "../../utils/entity-id-style.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 { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.js";
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
-import { MutationSaga } from "./saga.js";
+import { MutationRollbackFailureError, 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";
@@ -220,6 +222,7 @@ export async function executeUpsert(input, context, options = {}) {
         semanticAdvisor = semantic.receipt;
         assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
         await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships);
+        await assertPredicateArgumentVocabulary(prolog, validated.entity);
         if (context.fs !== undefined && context.sourceFirst !== false) {
             const existingRows = await loadEntities(prolog, {
                 id: input.id,
@@ -329,6 +332,57 @@ export async function executeUpsert(input, context, options = {}) {
                 source: sourceWrite.receipt.path,
             };
         }
+        if (options.deferCompiledCommit === true) {
+            let deferredState = "prepared";
+            let rollbackPromise;
+            const deferredCommit = {
+                entity: commitEntity ?? validated.entity,
+                relationships: validated.relationships,
+                skipContradictionCheck: input._skipContradictionCheck === true,
+                get state() {
+                    return deferredState;
+                },
+                finalize: () => {
+                    if (deferredState !== "prepared") {
+                        throw new Error(`Cannot finalize deferred upsert ${input.id} from state ${deferredState}`);
+                    }
+                    saga.markCommitted();
+                    deferredState = "committed";
+                },
+                rollback: () => {
+                    if (deferredState === "committed") {
+                        return Promise.reject(new Error(`Cannot roll back deferred upsert ${input.id} after its compiled commit`));
+                    }
+                    if (deferredState === "rolled_back")
+                        return Promise.resolve([]);
+                    if (rollbackPromise !== undefined)
+                        return rollbackPromise;
+                    deferredState = "rolling_back";
+                    rollbackPromise = saga.rollback().then((failures) => {
+                        deferredState = "rolled_back";
+                        return failures;
+                    });
+                    return rollbackPromise;
+                },
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Prepared ${input.id} for a batched proof commit.`,
+                    },
+                ],
+                structuredContent: {
+                    created: 0,
+                    updated: 0,
+                    relationships_created: validated.relationships.length,
+                    warnings: semantic.warnings,
+                    semanticAdvisor: semantic.receipt,
+                    deferredCommit,
+                    ...(sourceWrite ? { sourceWrites: [sourceWrite.receipt] } : {}),
+                },
+            };
+        }
         const transaction = buildUpsertCommitGoal({
             entity: commitEntity ?? validated.entity,
             relationships: validated.relationships,
@@ -349,6 +403,15 @@ export async function executeUpsert(input, context, options = {}) {
         }
         const coverage = await scenarioCoverageWarnings(prolog, validated.relationships, input.type, input.id);
         const created = changeKind === "created" ? 1 : 0;
+        const idStyleWarnings = created === 1
+            ? entityIdStyleWarnings({
+                id: input.id,
+                sourcePath: sourceWrite?.receipt.path ??
+                    (typeof validated.entity.source === "string"
+                        ? validated.entity.source
+                        : undefined),
+            })
+            : [];
         const shardWarnings = [];
         const relationshipSourceWrites = [];
         for (const [shardPath, before] of relationshipShardBefore) {
@@ -382,7 +445,12 @@ export async function executeUpsert(input, context, options = {}) {
             created,
             updated: changeKind === "updated" ? 1 : 0,
             relationships_created: validated.relationships.length,
-            warnings: [...semantic.warnings, ...coverage, ...shardWarnings],
+            warnings: [
+                ...semantic.warnings,
+                ...coverage,
+                ...idStyleWarnings,
+                ...shardWarnings,
+            ],
             semanticAdvisor: semantic.receipt,
             ...(shardWarnings.length > 0
                 ? {
@@ -480,7 +548,7 @@ export async function executeUpsert(input, context, options = {}) {
         }
         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}`);
+            const failure = new MutationRollbackFailureError([error, coordinateFailure.error], `Upsert failed and coordinate artifact rollback failed for ${input.id}`, rollbackFailures);
             operationFailure = { error: failure };
             throw failure;
         }
@@ -489,7 +557,7 @@ export async function executeUpsert(input, context, options = {}) {
             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}`);
+            const failure = new MutationRollbackFailureError([error, sourceFailure.error], `Upsert failed and authored source rollback failed for ${input.id}: ${rollbackMessage}`, rollbackFailures);
             operationFailure = { error: failure };
             throw failure;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAYxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOrE,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAoFjD"}
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAcxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAerE,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAoGjD"}

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

@@ -1,9 +1,18 @@
+// implements REQ-kibi-operation-interface-parity
+import { escapeAtom } from "../../prolog/codec.js";
+import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, validateSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
+import { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.js";
 import { validateLiveRelationshipTargets, validateRelationshipSources, } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { effectiveRelationships, validateAppendOnlyProofReceipts, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
+// implements REQ-kibi-entity-id-style
+async function entityExists(prolog, id) {
+    const result = await prolog.query(`once(kb_entity('${escapeAtom(id)}', _Type, _Props))`);
+    return result.success;
+}
 export async function executeValidateUpsert(input, context) {
     try {
         const validated = validateUpsertInput(input, context.clock());
@@ -26,11 +35,25 @@ export async function executeValidateUpsert(input, context) {
         assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
         if (context.prolog !== undefined) {
             await assertLogicalGroundingClaimKeys(context.prolog, { ...input, relationships }, relationships);
+            await assertPredicateArgumentVocabulary(context.prolog, validated.entity);
         }
+        // Style warnings apply only to entities this upsert would create, so the
+        // existence read happens only when the ID actually has a style issue.
+        const candidateIdStyleWarnings = entityIdStyleWarnings({
+            id: input.id,
+            sourcePath: typeof validated.entity.source === "string"
+                ? validated.entity.source
+                : undefined,
+        });
+        const idStyleWarnings = candidateIdStyleWarnings.length > 0 &&
+            context.prolog &&
+            !(await entityExists(context.prolog, input.id))
+            ? candidateIdStyleWarnings
+            : [];
         const payload = {
             valid: true,
             errors: [],
-            warnings: semantic.warnings,
+            warnings: [...semantic.warnings, ...idStyleWarnings],
             semanticAdvisor: semantic.receipt,
             normalizedPreview: validated.entity,
         };

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;AAkF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA0DjB;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;AA6F/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA4DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -11,7 +11,19 @@ const schema = entitySchema;
 const properties = schema.properties !== null && typeof schema.properties === "object"
     ? schema.properties
     : {};
-const validateEntity = ajv.compile({
+// Compiled on first mutation: every CLI command imports this module, and
+// most never validate an upsert.
+let entityValidator;
+let relationshipValidator;
+function entitySchemaValidator() {
+    entityValidator ??= ajv.compile(upsertEntitySchema);
+    return entityValidator;
+}
+function relationshipSchemaValidator() {
+    relationshipValidator ??= ajv.compile(relationshipSchema);
+    return relationshipValidator;
+}
+const upsertEntitySchema = {
     ...schema,
     properties: {
         ...properties,
@@ -27,8 +39,7 @@ const validateEntity = ajv.compile({
         },
         symbol_role: { type: "string", enum: [...SYMBOL_ROLES] },
     },
-});
-const validateRelationship = ajv.compile(relationshipSchema);
+};
 const ALIASES = new Map([
     ["subjectKey", "subject_key"],
     ["propertyKey", "property_key"],
@@ -83,6 +94,7 @@ export function validateUpsertInput(input, now) {
     entity.created_at ??= now.toISOString();
     entity.updated_at ??= now.toISOString();
     entity.source ??= "mcp://kibi/upsert";
+    const validateEntity = entitySchemaValidator();
     if (!validateEntity(entity)) {
         throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
     }
@@ -105,6 +117,7 @@ export function validateUpsertInput(input, now) {
         }
     }
     const relationships = input.relationships ?? [];
+    const validateRelationship = relationshipSchemaValidator();
     relationships.forEach((relationship, index) => {
         if (!validateRelationship(relationship)) {
             const details = (validateRelationship.errors ?? [])

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

@@ -1 +1 @@
-{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAGjF,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAqB/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AAggDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CA2BD"}
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAGjF,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAwB/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAmI9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AAy+CD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CA2BD"}

package/dist/operations/planning/apply-plan.js

@@ -5,14 +5,15 @@ import { OperationError } from "../../cli-errors.js";
 import { branchEnsureCommand, branchMigrateCommand, branchRecoverCommand, } from "../../commands/branch.js";
 import { migrateCommand } from "../../commands/migrate.js";
 import { syncCommand } from "../../commands/sync.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { executeStatus } from "../../public/operations/discovery-executors.js";
-import { migrationPlanHash, } from "../../public/operations/migration-plan.js";
+import { PREDICATE_SCHEMA_ALIGNMENT_CODE, migrationPlanHash, } from "../../public/operations/migration-plan.js";
 import { readMigrationConfigStatus } from "../../public/operations/migration-plan.js";
 import { readWorkspaceSnapshot } from "../../public/operations/workspace-snapshot.js";
 import { isDerivedKbPath } from "../../utils/kb-paths.js";
 import { bootstrapEmptyKbSnapshotId, bootstrapPlanHash, } from "../bootstrap/types.js";
 import { executeDelete } from "../mutation/delete.js";
-import { writePendingSourceReceipt } from "../mutation/source-authoring.js";
+import { retirePendingSourceReceipt, writePendingSourceReceipt, } from "../mutation/source-authoring.js";
 import { executeUpsert } from "../mutation/upsert.js";
 import { acquireWorkspaceMutationLock, releaseWorkspaceMutationLock, } from "../mutation/workspace-mutation-lock.js";
 import { compilePlanHash, } from "./compile-intent.js";
@@ -37,6 +38,21 @@ function isRecord(value) {
 function digest(value) {
     return createHash("sha256").update(value).digest("hex");
 }
+/**
+ * Reconcile pending-source receipts with committed source writes: a written
+ * file is bound to its exact bytes until Git tracks it, and a deleted file
+ * must not leave a receipt that later syncs would report as missing.
+ */
+function reconcilePendingSourceReceipts(workspaceRoot, writes) {
+    for (const write of writes) {
+        if ((write.mode ?? "write") === "delete") {
+            retirePendingSourceReceipt(workspaceRoot, write.path);
+        }
+        else if (write.afterHash !== null) {
+            writePendingSourceReceipt(workspaceRoot, write.path, write.afterHash);
+        }
+    }
+}
 function relationships(step) {
     if (!Array.isArray(step.relationships))
         return [];
@@ -356,11 +372,7 @@ async function applySourceWrites(context, writes, planHash, allowReplay = false,
                 throw new Error(`MUTATION_ALREADY_COMMITTED: source plan ${planHash} already crossed the authoritative commit boundary; use kb_apply_plan recoveryJournalId=${journalId} instead of retrying the original mutation`);
             }
             onCommitted();
-            for (const entry of prior.entries) {
-                if (entry.mode === "write" && entry.afterHash !== null) {
-                    writePendingSourceReceipt(context.workspaceRoot, entry.path, entry.afterHash);
-                }
-            }
+            reconcilePendingSourceReceipts(context.workspaceRoot, prior.entries);
             return { paths: priorPaths, rollback: async () => undefined, journalId };
         }
     }
@@ -518,11 +530,7 @@ async function applySourceWrites(context, writes, planHash, allowReplay = false,
         // A newly authored file is intentionally excluded from ordinary Git
         // discovery until the operator stages it. The receipt binds that pending
         // input to the exact bytes committed by this plan.
-        for (const write of writes) {
-            if ((write.mode ?? "write") === "write" && write.afterHash !== null) {
-                writePendingSourceReceipt(context.workspaceRoot, write.path, write.afterHash);
-            }
-        }
+        reconcilePendingSourceReceipts(context.workspaceRoot, writes);
     }
     catch (error) {
         if (sourceCommitted) {
@@ -609,11 +617,7 @@ async function executeSourceRecovery(args, context, onCommitted = () => undefine
         });
     }
     const sourceWrites = await applySourceWrites(context, writes, journal.planHash, true, onCommitted);
-    for (const write of writes) {
-        if (write.mode === "write" && write.afterHash !== null) {
-            writePendingSourceReceipt(context.workspaceRoot, write.path, write.afterHash);
-        }
-    }
+    reconcilePendingSourceReceipts(context.workspaceRoot, writes);
     const sync = await syncCommand({
         workspaceRoot: context.workspaceRoot,
         rebuild: true,
@@ -1272,6 +1276,7 @@ async function executeApplyPlanUnlocked(args, context, onCommitted = () => undef
         structuredContent: payload,
     };
 }
+// implements REQ-agent-guided-migration-orchestration, REQ-cli-canonical-runtime, REQ-KIBI-BOOTSTRAP-PLAN, REQ-kibi-change-to-proof-plan-compiler, REQ-kibi-predicate-vocabulary-migration
 export async function executeApplyPlan(args, context) {
     if (!context.fs || context.sourceMutationLockHeld === true)
         return executeApplyPlanUnlocked(args, context);
@@ -1508,7 +1513,46 @@ async function applyMigrationAction(action, context) {
                 throw new Error("Coordinate refresh did not complete successfully.");
             return;
         }
+        case PREDICATE_SCHEMA_ALIGNMENT_CODE:
+            await applyPredicateSchemaAlignment(action, context);
+            return;
         default:
             throw new Error(`Migration action '${action.code}' has no automatic executor.`);
     }
 }
+/**
+ * Replay the planned kb_upsert for one predicate fact after confirming the
+ * fact still has the namespace and alias spellings the plan was built from.
+ */
+// implements REQ-kibi-predicate-vocabulary-migration
+async function applyPredicateSchemaAlignment(action, context) {
+    const invocation = action.invocation;
+    if (invocation.kind !== "operation" || invocation.name !== "kb_upsert")
+        throw new Error("Predicate schema alignment requires its planned kb_upsert invocation.");
+    const input = asUpsert(invocation.input);
+    if (input.type !== "fact")
+        throw new Error("Predicate schema alignment only rewrites fact entities.");
+    const prolog = context.prolog ?? (await context.ensureProlog?.());
+    if (!prolog)
+        throw new Error("Predicate schema alignment requires a Prolog runtime.");
+    const operationContext = { ...context, prolog, sourceFirst: true };
+    const [current] = await loadEntities(prolog, { type: "fact", id: input.id });
+    const evidence = action.evidence;
+    const currentNamespace = typeof current?.predicate_namespace === "string" &&
+        current.predicate_namespace !== ""
+        ? current.predicate_namespace
+        : "default";
+    const currentArgs = Array.isArray(current?.predicate_args)
+        ? current.predicate_args
+        : [];
+    const rewrites = Array.isArray(evidence.rewrites) ? evidence.rewrites : [];
+    const unchanged = current !== undefined &&
+        current.fact_kind === "predicate" &&
+        currentNamespace === evidence.namespace &&
+        rewrites.every((rewrite) => isRecord(rewrite) &&
+            typeof rewrite.index === "number" &&
+            currentArgs[rewrite.index] === rewrite.from);
+    if (!unchanged)
+        throw new Error(`Predicate fact ${input.id} changed since planning; rerun kibi check and approve the new plan.`);
+    await executeUpsert(input, operationContext);
+}

package/dist/operations/planning/compile-intent.d.ts

@@ -90,6 +90,55 @@ export type CompilePlanV1 = Readonly<{
     steps: readonly PlanStep[];
     sourceWrites: readonly SourceWritePlan[];
     diagnostics: readonly string[];
+    /** Bounded replace/augment/shadow provenance; never changes canonical steps. */
+    capabilityPlugins?: Readonly<{
+        stamps: readonly {
+            pluginId: string;
+            pluginVersion: string;
+            capability: string;
+            mode: string;
+            external: boolean;
+            network: boolean;
+            metered: boolean;
+            fallbackUsed?: boolean;
+            model?: string;
+        }[];
+        classification: Readonly<{
+            fallbackUsed: boolean;
+            decisions: readonly {
+                claimKey: string;
+                lane: string;
+                confidence: number;
+            }[];
+            shadowComparisons: readonly {
+                pluginId: string;
+                pluginVersion: string;
+                capability: string;
+                mode: string;
+                external: boolean;
+                network: boolean;
+                metered: boolean;
+                fallbackUsed?: boolean;
+                model?: string;
+                decisions: readonly {
+                    claimKey: string;
+                    lane: string;
+                    confidence: number;
+                }[];
+            }[];
+        }> | null;
+        ontology: Readonly<{
+            replaced: boolean;
+            matchCount: number;
+            shadowMatchCount: number;
+            shadowMatches: readonly {
+                packId: string;
+                schemaId: string;
+                predicateName: string;
+                confidence: number;
+            }[];
+        }>;
+    }>;
 }>;
 export type SourceWritePlan = Readonly<{
     path: string;

package/dist/operations/planning/compile-intent.d.ts.map

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

package/dist/operations/planning/compile-intent.js

@@ -2,11 +2,12 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { dump as dumpYaml } from "js-yaml";
 import { executeIntentSearch, } from "../../intent-search.js";
+import { publicCapabilityStamp } from "../../plugins/compose-semantic-classifier.js";
 import { normalizeEntityId, parseTriples } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { executeStatus } from "../../public/operations/discovery-executors.js";
 import { configuredSourceTarget } from "../mutation/source-authoring.js";
-import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { analyzeSemanticAdvisorInputWithPlugins } from "../semantic-advisor/plugin-orchestration.js";
 import { canonicalize } from "../semantic-advisor/shared.js";
 // implements REQ-kibi-change-to-proof-plan-compiler
 export const COMPILE_PLAN_VERSION = "kibi.compile-plan.v1";
@@ -445,7 +446,9 @@ export async function executeCompileIntent(args, context) {
             diagnostics.push("Update target is unresolved: supply requirementId or improve the top candidate score and margin.");
         }
     }
-    if (args.mode === "create")
+    // A caller-chosen ID names the requirement by what it governs and wins;
+    // the content-hash ID is only a fallback when none is supplied.
+    if (args.mode === "create" && !explicitId)
         requirementId = generatedRequirementId(intent);
     if (!requirementId)
         throw new Error("Compile intent failed: could not determine requirementId");
@@ -471,7 +474,7 @@ export async function executeCompileIntent(args, context) {
     const source = text(args.sourceLocations?.[0]?.path) ||
         text(existingEntity.source) ||
         "mcp://kibi/compile-intent";
-    const advisor = analyzeSemanticAdvisorInput({
+    const orchestrated = await analyzeSemanticAdvisorInputWithPlugins({
         payload: {
             type: "req",
             id: requirementId,
@@ -486,9 +489,65 @@ export async function executeCompileIntent(args, context) {
             },
         },
         ...(args.clauses ? { clauses: args.clauses } : {}),
-        ...(args.interpretations ? { interpretations: args.interpretations } : {}),
+        ...(args.interpretations
+            ? { interpretations: args.interpretations }
+            : {}),
+    }, {
+        operationName: "kb_compile_intent",
+        ...(context.ensurePlugins
+            ? { ensurePlugins: context.ensurePlugins }
+            : {}),
     });
+    const advisor = orchestrated.analysis;
     diagnostics.push(...advisor.warnings);
+    if (orchestrated.stamps.length > 0) {
+        diagnostics.push(`Capability plugins consulted: ${orchestrated.stamps
+            .map((stamp) => `${stamp.pluginId}/${stamp.capability}`)
+            .join(", ")}.`);
+    }
+    const semanticShadowCount = orchestrated.classification?.shadowComparisons.length ?? 0;
+    if (semanticShadowCount > 0) {
+        diagnostics.push(`Semantic classifier shadow comparisons observed (${semanticShadowCount}); canonical compile plan unchanged.`);
+    }
+    if (orchestrated.ontologyShadowMatches.length > 0) {
+        diagnostics.push(`Ontology pack shadow matches observed (${orchestrated.ontologyShadowMatches.length}); canonical compile plan unchanged.`);
+    }
+    const capabilityPlugins = orchestrated.stamps.length > 0 ||
+        semanticShadowCount > 0 ||
+        orchestrated.ontologyShadowMatches.length > 0
+        ? {
+            stamps: orchestrated.stamps.map((stamp) => publicCapabilityStamp(stamp)),
+            classification: orchestrated.classification
+                ? {
+                    fallbackUsed: orchestrated.classification.fallbackUsed,
+                    decisions: orchestrated.classification.decisions.map((decision) => ({
+                        claimKey: decision.claimKey,
+                        lane: decision.lane,
+                        confidence: decision.confidence,
+                    })),
+                    shadowComparisons: orchestrated.classification.shadowComparisons.map((comparison) => ({
+                        ...publicCapabilityStamp(comparison.stamp),
+                        decisions: comparison.decisions.map((decision) => ({
+                            claimKey: decision.claimKey,
+                            lane: decision.lane,
+                            confidence: decision.confidence,
+                        })),
+                    })),
+                }
+                : null,
+            ontology: {
+                replaced: orchestrated.ontologyCatalog?.replaced ?? false,
+                matchCount: orchestrated.ontologyMatches.length,
+                shadowMatchCount: orchestrated.ontologyShadowMatches.length,
+                shadowMatches: orchestrated.ontologyShadowMatches.map((candidate) => ({
+                    packId: candidate.packId,
+                    schemaId: candidate.schemaId,
+                    predicateName: candidate.predicateName,
+                    confidence: candidate.confidence,
+                })),
+            },
+        }
+        : undefined;
     const suggestionByClaim = new Map(advisor.receipt.suggestions.map((suggestion) => [
         suggestion.claim_key,
         suggestion,
@@ -602,8 +661,11 @@ export async function executeCompileIntent(args, context) {
         sourceWrites,
         diagnostics,
     };
+    // Shadow/provenance metadata is returned for observation but must not enter
+    // planHash — shadow providers never affect canonical apply identity.
     const plan = {
         ...planBody,
+        ...(capabilityPlugins ? { capabilityPlugins } : {}),
         planHash: compilePlanHash(planBody),
     };
     return {

package/dist/operations/proof/baseline-diff.d.ts

@@ -0,0 +1,41 @@
+export declare const PROOF_BASELINE_VERSION = "kibi.proof-baseline.v2";
+export type RequirementFingerprint = {
+    readonly proofStatus: string;
+    readonly gaps: readonly string[];
+    readonly uncoveredSymbols: readonly string[];
+};
+export type RequirementFingerprints = Readonly<Record<string, RequirementFingerprint>>;
+export type CoverageRowLike = {
+    readonly id?: unknown;
+    readonly proofStatus?: unknown;
+    readonly proofGaps?: unknown;
+    readonly proofStages?: {
+        readonly productionSymbols?: {
+            readonly uncoveredSymbols?: unknown;
+            readonly explanations?: unknown;
+        };
+    };
+};
+export type FingerprintChange = {
+    readonly id: string;
+    readonly kind: "added" | "removed" | "changed";
+    readonly before?: RequirementFingerprint;
+    readonly after?: RequirementFingerprint;
+};
+export declare function fingerprintRequirements(rows: readonly CoverageRowLike[]): RequirementFingerprints;
+export declare function diffFingerprints(baseline: RequirementFingerprints | undefined, current: RequirementFingerprints): FingerprintChange[];
+type ExplanationLike = {
+    readonly symbolId?: unknown;
+    readonly reason?: unknown;
+    readonly coverageCandidates?: unknown;
+};
+export declare function explanationsForRequirement(rows: readonly CoverageRowLike[], requirementId: string): readonly ExplanationLike[];
+export declare function renderRequirementDiffs(changes: readonly FingerprintChange[], rows?: readonly CoverageRowLike[]): string;
+export declare function parseSpawnJson(result: {
+    readonly error?: unknown;
+    readonly status?: number | null;
+    readonly stdout?: string | null;
+    readonly stderr?: string | null;
+}): unknown;
+export {};
+//# sourceMappingURL=baseline-diff.d.ts.map

package/dist/operations/proof/baseline-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-diff.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/baseline-diff.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAC5C,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CACvC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,iBAAiB,CAAC,EAAE;YAC3B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;YACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;SACjC,CAAC;KACH,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CACzC,CAAC;AAUF,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,uBAAuB,CAgBzB;AAGD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,uBAAuB,GAAG,SAAS,EAC7C,OAAO,EAAE,uBAAuB,GAC/B,iBAAiB,EAAE,CA4BrB;AASD,KAAK,eAAe,GAAG;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,SAAS,eAAe,EAAE,EAChC,aAAa,EAAE,MAAM,GACpB,SAAS,eAAe,EAAE,CAM5B;AAgBD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,IAAI,GAAE,SAAS,eAAe,EAAO,GACpC,MAAM,CAwDR;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,GAAG,OAAO,CAYV"}