kibi-cli 2.19.0 → 2.20.0

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

@@ -1,6 +1,7 @@
 import { escapeAtom } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { parsePrologList } from "../mutation/serialization.js";
+import { compileGroundingPlan } from "../planning/compile-intent.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { composeOntologyCatalogForOperation } from "../semantic-advisor/plugin-orchestration.js";
@@ -51,6 +52,7 @@ function compoundInputAbstention(args, text, subject, propositionCount) {
             recommendedPredicateSchema: null,
             applyPlan,
             relationshipPlan: null,
+            plan: null,
             warnings: [warning],
         },
         applyPlan,
@@ -79,6 +81,7 @@ function nonlogicalInputRouting(args, text, subject) {
             recommendedPredicateSchema: null,
             applyPlan,
             relationshipPlan: null,
+            plan: null,
             warnings: [warning],
         },
         applyPlan,
@@ -414,6 +417,17 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
                                 ? "No predicate candidate passed the semantic applicability gate; keep the existing grounding and record the ontology-gap observation in applyPlan so the missing schema stays visible."
                                 : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.");
     const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
+    const plan = relationshipPlan !== null && plannedFactId !== null && args.requirementId
+        ? await groundingPlan(prolog, context, {
+            requirementId: args.requirementId,
+            claimKey,
+            text,
+            factStep: predicatePlan[0] ?? {},
+            relationship: relationshipPlan.relationship,
+            logicClaims,
+            warnings,
+        })
+        : null;
     return {
         content: [{ type: "text", text: textSummary }],
         structuredContent: {
@@ -428,6 +442,7 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
             recommendedPredicateSchema,
             applyPlan,
             relationshipPlan,
+            plan,
             relationshipTarget,
             existingGrounding,
             replacementPlan,
@@ -459,6 +474,102 @@ const RESTATED_REQUIREMENT_FIELDS = [
     "owner",
     "tags",
 ];
+// implements REQ-model-what-if-planned-facts
+/**
+ * The hash-bound plan behind applyPlan + relationshipPlan: the predicate fact,
+ * then the requirement restated with the merged logic_claims manifest and the
+ * requires_predicate link. kb_apply_plan applies both in one transaction, and
+ * the plan's contradictionAnalysis says what the batch would introduce.
+ */
+async function groundingPlan(prolog, context, input) {
+    if (prolog === null || context === undefined)
+        return null;
+    const stored = await storedRequirementContract(prolog, input.requirementId, input.warnings);
+    if (stored === null) {
+        input.warnings.push(`No hash-bound plan: requirement ${input.requirementId} is not stored, so its upsert step cannot restate the stored title and status. Apply applyPlan and relationshipPlan with kb_upsert.`);
+        return null;
+    }
+    // A stored ledger is restated with this claim marked modeled, so the
+    // proposition-complete check sees one modeled entry per grounding link.
+    // A claim the ledger does not carry cannot be grounded by this plan.
+    const inventory = Array.isArray(stored.semantic_inventory)
+        ? stored.semantic_inventory
+        : null;
+    if (inventory !== null) {
+        const entry = inventory.find((row) => row !== null &&
+            typeof row === "object" &&
+            row.claim_key === input.claimKey);
+        if (entry === undefined) {
+            input.warnings.push(`No hash-bound plan: the ledger of ${input.requirementId} has no proposition ${input.claimKey} for this text. Run kb_model mode analyze with the requirement's complete prose and pass one of its clauses as text; applyPlan can still be written with kb_upsert.`);
+            return null;
+        }
+        stored.semantic_inventory = inventory.map((row) => row === entry
+            ? {
+                ...entry,
+                status: "modeled",
+                reason: `Grounded by the ${String(input.factStep.id)} predicate fact this plan writes.`,
+            }
+            : row);
+    }
+    try {
+        const plan = await compileGroundingPlan(context, prolog, {
+            requirementId: input.requirementId,
+            claimKey: input.claimKey,
+            text: input.text,
+            steps: [
+                input.factStep,
+                {
+                    type: "req",
+                    id: input.requirementId,
+                    properties: { ...stored, logic_claims: [...input.logicClaims] },
+                    relationships: [input.relationship],
+                },
+            ],
+        });
+        if (plan.status === "blocked") {
+            const reasons = plan.contradictionAnalysis.witnesses
+                .map((witness) => witness.reason)
+                .filter(Boolean);
+            input.warnings.push(`Applying this grounding would contradict the current KB, so plan.status is blocked: ${reasons.join("; ")}. Supersede or close the conflicting requirement before grounding this claim.`);
+        }
+        else if (plan.status !== "ready") {
+            input.warnings.push(`The hash-bound plan needs resolution before kb_apply_plan can run it: ${plan.diagnostics.join("; ")}`);
+        }
+        return plan;
+    }
+    catch (error) {
+        input.warnings.push(`No hash-bound plan could be compiled (${error instanceof Error ? error.message : String(error)}); apply applyPlan and relationshipPlan with kb_upsert.`);
+        return null;
+    }
+}
+const STORED_LEDGER_FIELDS = [
+    "text_ref",
+    "semantic_text",
+    "semantic_clauses",
+    "semantic_inventory",
+    "semantic_inventory_version",
+    "semantic_source_field",
+    "semantic_source_hash",
+];
+// implements REQ-model-what-if-planned-facts
+/**
+ * The stored requirement as a plan step restates it: title, status and
+ * metadata plus its proposition ledger, so the upsert kb_apply_plan runs is
+ * validated as given and keeps the ledger instead of replacing it.
+ */
+async function storedRequirementContract(prolog, requirementId, warnings) {
+    const restated = await storedRequirementProperties(prolog, requirementId, warnings);
+    if (restated === null)
+        return null;
+    const [stored] = await loadEntities(prolog, {
+        id: requirementId,
+        type: "req",
+    });
+    for (const field of STORED_LEDGER_FIELDS)
+        if (stored?.[field] !== undefined && stored[field] !== null)
+            restated[field] = stored[field];
+    return restated;
+}
 /**
  * The requirement fields the replacement's requirement upsert restates, so
  * the step is a complete kb_upsert payload (title and status are required)

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

@@ -14,9 +14,23 @@ export type UpsertInput = {
     };
     /** Validate and preview the write without mutating the KB. */
     readonly dryRun?: boolean;
+    /**
+     * Dry run only: fact upserts an earlier step will write before this one
+     * (the kb_model applyPlan entries). They are validated in order and staged
+     * with the payload, so grounding targets resolve and the contradiction
+     * preview sees the KB as it would be after the whole batch.
+     */
+    readonly plannedFacts?: readonly PlannedFactInput[];
     readonly _skipContradictionCheck?: boolean;
     readonly _requestId?: string;
 };
+/** One planned fact write staged ahead of a dry run. */
+export type PlannedFactInput = {
+    readonly type: string;
+    readonly id: string;
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly relationships?: readonly RelationshipInput[];
+};
 /**
  * Store state an upsert's validation must see in addition to the live KB:
  * what earlier steps of the same plan will have written by the time this
@@ -84,6 +98,18 @@ export type ValidateUpsertPayload = {
     readonly warnings: readonly string[];
     readonly semanticAdvisor: SemanticAdvisorReceipt | null;
     readonly normalizedPreview: Readonly<Record<string, unknown>> | null;
+    /** Planned fact ids staged ahead of the payload, in order. */
+    readonly stagedFacts?: readonly string[];
+    /**
+     * With plannedFacts: the contradiction and scenario-feasibility witnesses
+     * the KB would hold after the planned facts and this payload, split into
+     * what the batch introduces, removes and leaves unchanged.
+     */
+    readonly whatIf?: Readonly<{
+        introduced: readonly Readonly<Record<string, unknown>>[];
+        removed: readonly Readonly<Record<string, unknown>>[];
+        unchanged: readonly Readonly<Record<string, unknown>>[];
+    }>;
 };
 export type DeleteInput = {
     readonly ids?: readonly string[];

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;AA6CpB,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,CA4gBzC"}
+{"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"}

package/dist/operations/mutation/upsert.js

@@ -26,7 +26,7 @@ import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "./symbol-
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { refreshSymbolCoordinatesForManifest } from "./symbol-refresh.js";
 import { validateUpsertInput } from "./validation.js";
-import { scenarioCoverageWarnings } from "./warnings.js";
+import { scenarioCoverageWarnings, symbolCoverageWarnings, } from "./warnings.js";
 import { acquireWorkspaceMutationLock, releaseWorkspaceMutationLock, } from "./workspace-mutation-lock.js";
 function requireProlog(context) {
     if (context.prolog === undefined) {
@@ -250,6 +250,9 @@ async function dryRunUpsert(input, context) {
 export async function executeUpsert(input, context, options = {}) {
     if (input.dryRun === true)
         return dryRunUpsert(input, context);
+    // implements REQ-model-what-if-planned-facts
+    if (input.plannedFacts !== undefined)
+        throw new Error(`Upsert of ${input.id} rejected: plannedFacts is a dryRun-only input. Write the planned facts first (kb_upsert each, or kb_apply_plan with the kb_model plan), then upsert ${input.id} without plannedFacts.`);
     const branchAttachment = context.branchAttachment ?? resolveBranchAttachment(context.workspaceRoot);
     if ("error" in branchAttachment) {
         throw new Error(`Unable to resolve KB branch: ${branchAttachment.error}`);
@@ -481,7 +484,10 @@ export async function executeUpsert(input, context, options = {}) {
         if (changeKind === null) {
             throw new Error(`Upsert commit completed without a created/updated result for ${input.id}`);
         }
-        const coverage = await scenarioCoverageWarnings(prolog, validated.relationships, input.type, input.id);
+        const coverage = [
+            ...(await scenarioCoverageWarnings(prolog, validated.relationships, input.type, input.id)),
+            ...(await symbolCoverageWarnings(prolog, validated.relationships, input.type, input.id)),
+        ];
         const created = changeKind === "created" ? 1 : 0;
         const idStyleWarnings = created === 1
             ? entityIdStyleWarnings({

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":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAWxE,OAAO,KAAK,EAEV,WAAW,EACX,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA2EpB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAuEjD"}
+{"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;AAYxE,OAAO,KAAK,EAIV,WAAW,EACX,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA2MpB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAgHjD"}

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

@@ -4,11 +4,13 @@ import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertSemanticInventoryBoundary } from "../semantic-advisor/ingestion-boundary.js";
 import { entityContextWarnings } from "./context-warning.js";
-import { buildUpsertContradictionPreviewGoal, formatUpsertError, } from "./contradictions.js";
+import { buildUpsertContradictionPreviewGoal, buildWhatIfAnalysisGoal, formatUpsertError, } from "./contradictions.js";
 import { validateRelationshipSources } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
+import { symbolCoverageWarnings } from "./warnings.js";
+import { isBlockingWitness, parseWhatIfAnalysis } from "./what-if.js";
 // implements REQ-kibi-entity-id-style
 async function entityExists(prolog, id) {
     const result = await prolog.query(`once(kb_entity('${escapeAtom(id)}', _Type, _Props))`);
@@ -33,6 +35,92 @@ async function previewContradictions(prolog, input, entity, relationships) {
         throw new Error(formatUpsertError(input.id, preview.error, preview.errorRecord));
     }
 }
+// implements REQ-model-what-if-planned-facts
+/**
+ * Validate the planned facts in order, each against the live store plus the
+ * facts before it, exactly as kb_apply_plan validates a plan's steps. The
+ * result is the staged state the payload's own validation reads: a planned
+ * fact counts as a live relationship target and its claim_key is read from
+ * the plan, so a requirement can be previewed before its facts are written.
+ */
+async function stagePlannedFacts(input, context) {
+    const planned = input.plannedFacts;
+    if (planned === undefined)
+        return null;
+    if (!Array.isArray(planned))
+        throw new Error("plannedFacts must be an array of fact upsert payloads");
+    const entities = new Map();
+    const relationships = [];
+    const steps = [];
+    for (const [index, fact] of planned.entries()) {
+        const id = typeof fact?.id === "string" ? fact.id : `#${index + 1}`;
+        if (fact?.type !== "fact")
+            throw new Error(`planned fact ${id} is invalid: plannedFacts stages fact entities only (got type '${String(fact?.type)}')`);
+        if (fact.id === input.id)
+            throw new Error(`planned fact ${id} is invalid: it has the same id as the payload`);
+        try {
+            const { validated } = await validateUpsertForCommit(plannedFactUpsert(fact), context, { staged: { entities, relationships: [...relationships] } });
+            entities.set(fact.id, validated.entity);
+            relationships.push(...validated.relationships);
+            steps.push({
+                entity: validated.entity,
+                relationships: validated.relationships,
+            });
+        }
+        catch (error) {
+            throw new Error(`planned fact ${id} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { staged: { entities, relationships }, steps };
+}
+function plannedFactUpsert(fact) {
+    return {
+        type: fact.type,
+        id: fact.id,
+        properties: fact.properties,
+        ...(fact.relationships !== undefined
+            ? { relationships: fact.relationships }
+            : {}),
+    };
+}
+// implements REQ-model-what-if-planned-facts, REQ-kibi-truthful-consistency
+/**
+ * The contradiction preview for a payload with planned facts: the facts and
+ * the payload are staged together in a rolled-back transaction and the
+ * witnesses the KB would then hold are compared with the current KB's. A
+ * blocking witness the batch introduces refuses the dry run the way the
+ * commit would refuse the last write of the batch; the full split is
+ * returned so an agent sees the conflict before any fact exists.
+ */
+async function previewStagedContradictions(prolog, input, entity, relationships, facts) {
+    const result = await prolog.query(buildWhatIfAnalysisGoal([
+        ...facts.steps.map((step) => ({
+            entity: step.entity,
+            relationships: step.relationships,
+            skipContradictionCheck: true,
+        })),
+        { entity, relationships, skipContradictionCheck: true },
+    ]));
+    if (!result.success)
+        throw new Error(formatUpsertError(input.id, result.error, result.errorRecord));
+    const analysis = parseWhatIfAnalysis(result.bindings.JsonString);
+    if (analysis === null)
+        throw new Error(`Failed to preview ${input.id} with planned facts: the staged contradiction analysis could not be read`);
+    const skip = input.type !== "req" || input._skipContradictionCheck === true;
+    const blocking = skip ? [] : analysis.introduced.filter(isBlockingWitness);
+    if (blocking.length > 0) {
+        const conflicts = blocking.map((witness) => {
+            const others = witness.requirements.filter((id) => id !== input.id);
+            return `  - Conflicts with ${others.join(", ") || witness.requirements.join(", ")}: ${witness.reason}`;
+        });
+        throw new Error(`Contradiction detected for requirement ${input.id} once its planned facts are written:\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. (stage=contradiction_check, plannedFacts staged)`);
+    }
+    return {
+        introduced: analysis.introduced,
+        removed: analysis.removed,
+        unchanged: analysis.unchanged,
+    };
+}
 /**
  * The validation chain for a runtime without a store: everything that does
  * not need to read the KB.
@@ -58,12 +146,25 @@ async function validateWithoutStore(input, context) {
  */
 export async function executeValidateUpsert(input, context) {
     try {
+        if (input.plannedFacts !== undefined && context.prolog === undefined)
+            throw new Error("plannedFacts needs a KB store: the planned facts are staged against the current KB");
+        let whatIf;
+        let stagedFacts;
+        let relationships = input.relationships ?? [];
         const { entity, semantic } = context.prolog !== undefined
-            ? await validateUpsertForCommit(input, context).then(async (result) => {
+            ? await stagePlannedFacts(input, context).then(async (facts) => {
+                const result = await validateUpsertForCommit(input, context, facts === null ? {} : { staged: facts.staged });
                 // The commit goal checks requirement contradictions after the
                 // validations above; a dry run previews that stage as well, so
                 // "valid" means the commit would not refuse the write.
-                await previewContradictions(context.prolog, input, result.validated.entity, result.validated.relationships);
+                if (facts === null) {
+                    await previewContradictions(context.prolog, input, result.validated.entity, result.validated.relationships);
+                }
+                else {
+                    stagedFacts = [...facts.staged.entities.keys()];
+                    whatIf = await previewStagedContradictions(context.prolog, input, result.validated.entity, result.validated.relationships, facts);
+                }
+                relationships = result.validated.relationships;
                 return {
                     entity: result.validated.entity,
                     semantic: result.semantic,
@@ -81,22 +182,33 @@ export async function executeValidateUpsert(input, context) {
             !(await entityExists(context.prolog, input.id))
             ? candidateIdStyleWarnings
             : [];
+        // The same symbol-coverage warning the write returns, so the dry run
+        // tells the agent before the write that kb_check will flag it.
+        const coverageWarnings = context.prolog
+            ? await symbolCoverageWarnings(context.prolog, relationships, input.type, input.id)
+            : [];
         const payload = {
             valid: true,
             errors: [],
             warnings: [
                 ...semantic.warnings,
+                ...coverageWarnings,
                 ...idStyleWarnings,
                 ...entityContextWarnings(input, entity, context.workspaceRoot),
             ],
             semanticAdvisor: semantic.receipt,
             normalizedPreview: entity,
+            ...(stagedFacts !== undefined ? { stagedFacts } : {}),
+            ...(whatIf !== undefined ? { whatIf } : {}),
         };
+        const stagedNote = stagedFacts === undefined
+            ? ""
+            : ` ${stagedFacts.length} planned fact(s) were staged ahead of it (${stagedFacts.join(", ")}); the batch introduces ${whatIf?.introduced.length ?? 0} witness(es).`;
         return {
             content: [
                 {
                     type: "text",
-                    text: "kb_validate_upsert: payload is valid for kb_upsert preflight checks. No mutation was performed.",
+                    text: `kb_validate_upsert: payload is valid for kb_upsert preflight checks. No mutation was performed.${stagedNote}`,
                 },
             ],
             structuredContent: payload,

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

@@ -2,4 +2,14 @@ import type { PrologPort } from "../../public/operations/runtime-types.js";
 import type { RelationshipInput } from "./types.js";
 export declare function scenarioCoverageWarning(entityId: string): readonly string[];
 export declare function scenarioCoverageWarnings(prolog: PrologPort, relationships: readonly RelationshipInput[], entityType: string, entityId: string): Promise<readonly string[]>;
+export declare function symbolCoverageWarning(entityId: string): readonly string[];
+/**
+ * A production symbol (one that implements a requirement) needs a covered_by
+ * edge to a test that covers that requirement, or kb_check reports
+ * symbol-coverage once it is written. Warn before and after the write so the
+ * agent learns it from the upsert, not from the next check. An executable
+ * test symbol (executable_for) is not production code, and a symbol that
+ * already has a stored covered_by edge is left for kb_check to judge.
+ */
+export declare function symbolCoverageWarnings(prolog: PrologPort, relationships: readonly RelationshipInput[], entityType: string, entityId: string): Promise<readonly string[]>;
 //# sourceMappingURL=warnings.d.ts.map

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

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

package/dist/operations/mutation/warnings.js

@@ -17,3 +17,29 @@ export async function scenarioCoverageWarnings(prolog, relationships, entityType
     }
     return [];
 }
+// implements REQ-kibi-operation-interface-parity
+export function symbolCoverageWarning(entityId) {
+    return [
+        `Production symbol ${entityId} has implements but no covered_by: kb_check will report symbol-coverage. Add covered_by: TEST-<area>-<behavior> to a test that validates the requirement's scenario (or verified_by(req,test) when the requirement has no scenario).`,
+    ];
+}
+// implements REQ-kibi-operation-interface-parity
+/**
+ * A production symbol (one that implements a requirement) needs a covered_by
+ * edge to a test that covers that requirement, or kb_check reports
+ * symbol-coverage once it is written. Warn before and after the write so the
+ * agent learns it from the upsert, not from the next check. An executable
+ * test symbol (executable_for) is not production code, and a symbol that
+ * already has a stored covered_by edge is left for kb_check to judge.
+ */
+export async function symbolCoverageWarnings(prolog, relationships, entityType, entityId) {
+    if (entityType !== "symbol")
+        return [];
+    const own = relationships.filter((relationship) => relationship.from === undefined || relationship.from === entityId);
+    const has = (type) => own.some((relationship) => relationship.type === type);
+    if (!has("implements") || has("covered_by") || has("executable_for"))
+        return [];
+    const id = escapeAtom(entityId);
+    const stored = await prolog.query(`once((kb_relationship(covered_by, '${id}', _) ; kb_relationship(executable_for, '${id}', _)))`);
+    return stored.success ? [] : symbolCoverageWarning(entityId);
+}

package/dist/operations/mutation/what-if.d.ts

@@ -0,0 +1,25 @@
+/** A contradiction or scenario-infeasibility witness the checker reports. */
+export type ContradictionWitness = Readonly<{
+    requirements: readonly string[];
+    reason: string;
+    status?: string;
+    /** property | predicate | rule | scenario_feasibility */
+    kind?: string;
+} & Record<string, unknown>>;
+export type WhatIfAnalysis = Readonly<{
+    after: readonly ContradictionWitness[];
+    introduced: readonly ContradictionWitness[];
+    removed: readonly ContradictionWitness[];
+    unchanged: readonly ContradictionWitness[];
+}>;
+/**
+ * Parse checks:what_if_analysis_json/2 output. The binding is a quoted Prolog
+ * string, so the JSON may arrive encoded once more as a JSON string. A bare
+ * witness array (the what_if_contradiction_witnesses_json/2 shape) carries no
+ * current-KB baseline, so every witness in it is treated as introduced.
+ * Returns null when the output cannot be read.
+ */
+export declare function parseWhatIfAnalysis(raw: unknown): WhatIfAnalysis | null;
+/** Blocking: a proven contradiction or an infeasible success scenario. */
+export declare function isBlockingWitness(witness: ContradictionWitness): boolean;
+//# sourceMappingURL=what-if.d.ts.map

package/dist/operations/mutation/what-if.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"what-if.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/what-if.ts"],"names":[],"mappings":"AAGA,6EAA6E;AAC7E,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CACzC;IACE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC5B,CAAC;AAGF,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC5C,CAAC,CAAC;AA6BH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAoBvE;AAGD,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAExE"}

package/dist/operations/mutation/what-if.js

@@ -0,0 +1,59 @@
+import { normalizeEntityId } from "../../prolog/codec.js";
+function text(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function whatIfWitness(witness) {
+    return {
+        ...witness,
+        requirements: Array.isArray(witness.requirements)
+            ? witness.requirements.map((id) => normalizeEntityId(String(id)))
+            : [],
+        reason: text(witness.reason),
+        status: text(witness.status) || "contradiction",
+        ...(typeof witness.kind === "string" ? { kind: witness.kind } : {}),
+    };
+}
+function whatIfWitnesses(value) {
+    return (Array.isArray(value) ? value.filter(isRecord) : []).map(whatIfWitness);
+}
+// implements REQ-kibi-truthful-consistency
+/**
+ * Parse checks:what_if_analysis_json/2 output. The binding is a quoted Prolog
+ * string, so the JSON may arrive encoded once more as a JSON string. A bare
+ * witness array (the what_if_contradiction_witnesses_json/2 shape) carries no
+ * current-KB baseline, so every witness in it is treated as introduced.
+ * Returns null when the output cannot be read.
+ */
+export function parseWhatIfAnalysis(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+        if (typeof parsed === "string")
+            parsed = JSON.parse(parsed);
+    }
+    catch {
+        return null;
+    }
+    if (Array.isArray(parsed)) {
+        const after = whatIfWitnesses(parsed);
+        return { after, introduced: after, removed: [], unchanged: [] };
+    }
+    if (!isRecord(parsed))
+        return null;
+    return {
+        after: whatIfWitnesses(parsed.after),
+        introduced: whatIfWitnesses(parsed.introduced),
+        removed: whatIfWitnesses(parsed.removed),
+        unchanged: whatIfWitnesses(parsed.unchanged),
+    };
+}
+// implements REQ-kibi-truthful-consistency
+/** Blocking: a proven contradiction or an infeasible success scenario. */
+export function isBlockingWitness(witness) {
+    return witness.status === "contradiction" || witness.status === "infeasible";
+}

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

@@ -1,5 +1,6 @@
 import { type IntentSearchFacets, type IntentSearchMatch, type SourceLocation } from "../../intent-search.js";
 import type { OperationContext } from "../../public/operations/runtime-types.js";
+import { type ContradictionWitness } from "../mutation/what-if.js";
 import type { SemanticInterpretationInput } from "../semantic-advisor/types.js";
 export declare const COMPILE_PLAN_VERSION: "kibi.compile-plan.v1";
 export type CompileIntentArgs = Readonly<{
@@ -47,13 +48,8 @@ export type ProposalDecision = Readonly<{
  * (sides, facts, scenario, comparison) is kept alongside these normalized
  * fields so callers can act on more than requirement ids.
  */
-export type ContradictionWitness = Readonly<{
-    requirements: readonly string[];
-    reason: string;
-    status?: string;
-    /** property | predicate | rule | scenario_feasibility */
-    kind?: string;
-} & Record<string, unknown>>;
+export type { ContradictionWitness, WhatIfAnalysis, } from "../mutation/what-if.js";
+export { isBlockingWitness, parseWhatIfAnalysis } from "../mutation/what-if.js";
 export type TraceabilityProposal = Readonly<{
     proposalId: string;
     candidateId: string;
@@ -173,22 +169,21 @@ export type SourceWritePlan = Readonly<{
 }>;
 /** Rolled-back staging goal for a plan's steps (see what_if_analysis/2). */
 export declare function planWhatIfGoal(steps: readonly PlanStep[], now: Date): string;
-export type WhatIfAnalysis = Readonly<{
-    after: readonly ContradictionWitness[];
-    introduced: readonly ContradictionWitness[];
-    removed: readonly ContradictionWitness[];
-    unchanged: readonly ContradictionWitness[];
+export type GroundingPlanInput = Readonly<{
+    requirementId: string;
+    claimKey: string;
+    text: string;
+    /** The fact write(s), then the requirement upsert that links them. */
+    steps: readonly PlanStep[];
 }>;
 /**
- * Parse checks:what_if_analysis_json/2 output. The binding is a quoted Prolog
- * string, so the JSON may arrive encoded once more as a JSON string. A bare
- * witness array (the what_if_contradiction_witnesses_json/2 shape) carries no
- * current-KB baseline, so every witness in it is treated as introduced.
- * Returns null when the output cannot be read.
+ * A hash-bound compile plan for a grounding kb_model planned: the predicate
+ * fact and the requirement upsert that links it, validated and applied
+ * together by kb_apply_plan. Its contradiction analysis is the what-if over
+ * the current KB plus these steps, so a decision conflict with a fact that is
+ * already stored is reported here, before any write, and blocks the plan.
  */
-export declare function parseWhatIfAnalysis(raw: unknown): WhatIfAnalysis | null;
-/** Blocking: a proven contradiction or an infeasible success scenario. */
-export declare function isBlockingWitness(witness: ContradictionWitness): boolean;
+export declare function compileGroundingPlan(context: OperationContext, prolog: NonNullable<OperationContext["prolog"]>, input: GroundingPlanInput): Promise<CompilePlanV1>;
 export declare function executeCompileIntent(args: CompileIntentArgs, context: OperationContext): Promise<{
     content: Array<{
         type: "text";