kibi-cli 2.18.0 → 2.20.0

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";

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

@@ -3,17 +3,18 @@ import path from "node:path";
 import { renderRequirementBody, reviseRequirementBody, } from "../../entity-body-context.js";
 import { executeIntentSearch, } from "../../intent-search.js";
 import { publicCapabilityStamp } from "../../plugins/compose-semantic-classifier.js";
-import { normalizeEntityId } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { executeStatus } from "../../public/operations/discovery-executors.js";
 import { readAuthoredEntity } from "../../public/operations/entity-context.js";
 import { buildWhatIfAnalysisGoal } from "../mutation/contradictions.js";
 import { canonicalSourcePath } from "../mutation/source-authoring.js";
 import { validateUpsertInput } from "../mutation/validation.js";
+import { isBlockingWitness, parseWhatIfAnalysis, } from "../mutation/what-if.js";
 import { analyzeSemanticAdvisorInputWithPlugins } from "../semantic-advisor/plugin-orchestration.js";
 import { canonicalize } from "../semantic-advisor/shared.js";
 // implements REQ-kibi-change-to-proof-plan-compiler-v2
 export const COMPILE_PLAN_VERSION = "kibi.compile-plan.v1";
+export { isBlockingWitness, parseWhatIfAnalysis } from "../mutation/what-if.js";
 // implements REQ-kibi-change-to-proof-plan-compiler-v2
 export function compilePlanHash(plan) {
     const { planHash: _ignored, ...body } = plan;
@@ -342,58 +343,6 @@ export function planWhatIfGoal(steps, now) {
         };
     }));
 }
-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";
-}
 // implements REQ-kibi-truthful-consistency
 // Check the KB as it would be after this plan, not the KB as it is: stage every
 // planned step in a rolled-back transaction and compare its contradiction and
@@ -608,6 +557,68 @@ function draftSteps(requirementId, scenarios, tests) {
     }
     return { steps, diagnostics };
 }
+// implements REQ-model-what-if-planned-facts
+/**
+ * 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 async function compileGroundingPlan(context, prolog, input) {
+    const now = context.clock();
+    const statusResult = await executeStatus({}, context);
+    const status = statusResult.structuredContent;
+    if (!status)
+        throw new Error("Grounding plan failed: status query returned no payload");
+    const contradictions = await contradictionAnalysis(prolog, input.requirementId, input.steps, now);
+    const diagnostics = [];
+    let statusValue = contradictions.outcome === "conflict" ? "blocked" : "ready";
+    let planSteps = [...input.steps];
+    if (statusValue === "ready") {
+        try {
+            planSteps = await withDocumentTargets(context, prolog, input.steps, { id: input.requirementId }, now);
+        }
+        catch (error) {
+            statusValue = "needs_resolution";
+            diagnostics.push(`A plan step cannot be applied as written: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // The hash binds the plan as it travels: a step field left undefined
+    // (kb_model's optional source) is absent on the wire, so it is absent here.
+    const planBody = JSON.parse(JSON.stringify({
+        version: COMPILE_PLAN_VERSION,
+        status: statusValue,
+        expected: {
+            branch: status.branch,
+            kbSnapshotId: status.snapshotId,
+            workspaceSnapshot: status.proofSnapshot ?? "unknown",
+            sourceHashes: {},
+        },
+        target: {
+            mode: "update",
+            requirementId: input.requirementId,
+            selectionReason: `kb_model mode predicates grounds claim ${input.claimKey} of the supplied requirementId.`,
+        },
+        discovery: { candidates: [], abstained: true },
+        propositions: [
+            {
+                claimKey: input.claimKey,
+                text: input.text,
+                span: { start: 0, end: Buffer.byteLength(input.text, "utf8") },
+                disposition: "predicate",
+                status: "modeled",
+                origin: "deterministic",
+            },
+        ],
+        contradictionAnalysis: contradictions,
+        proposals: [],
+        steps: planSteps,
+        sourceWrites: [],
+        diagnostics,
+    }));
+    return { ...planBody, planHash: compilePlanHash(planBody) };
+}
 // implements REQ-kibi-change-to-proof-plan-compiler-v2
 export async function executeCompileIntent(args, context) {
     const intent = requiredIntent(args);

package/dist/operations/semantic-advisor/clauses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAkBH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAQD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,GAAG,aAAa,CAG7B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4BD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CA4B3B"}
+{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAmBH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAQD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,GAAG,aAAa,CAG7B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4BD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CA4B3B"}

package/dist/operations/semantic-advisor/clauses.js

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
-// An explicit grant ("are allowed to", "is permitted to") asserts a
-// permission just as "denied"/"forbidden" assert a prohibition. Bare "can" and
-// "may" are accepted by the predicate applicability gate but not here: stored
-// clause roles are derived from this pattern, and "it can be restricted to …"
-// style capability prose would turn existing descriptive inventories into
-// unmodeled normative clauses.
-const NORMATIVE_ASSERTION_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|(?:is|are)\s+(?:not\s+)?(?:allowed|permitted)\s+to|permitted|may\s+(?:not\s+)?(?:be\s+)?\w+\s+only\b|may\s+(?:have\s+)?(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to)|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|denied|forbidden|prohibited|(?:is|are|be|become|becomes|remain|remains)\s+(?:invalid|rejected|prohibited|forbidden)|(?:reject|rejects|rejected|rejection)\s+(?:invalid|unresolved|ambiguous)|fail(?:s|ed)?\s+(?:clearly|explicitly|with)|expires?\s+(?:after|within|in)|failure\s+(?:behavior|policy|outcome)|error\s+(?:handling|behavior|policy|outcome)|required\s+outcome|defaults?\s+to)\b/i;
+// An explicit grant ("are allowed to", "is permitted to", "have permission
+// to", "are entitled to") asserts a permission just as "denied"/"forbidden"
+// assert a prohibition. Bare "can", "may" and "are able to" are accepted by
+// the predicate applicability gate but not here: stored clause roles are
+// derived from this pattern, and "it can be restricted to …" style capability
+// prose would turn existing descriptive inventories into unmodeled normative
+// clauses ("must be able to" is already normative through "must").
+const NORMATIVE_ASSERTION_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|(?:is|are)\s+(?:not\s+)?(?:allowed|permitted|entitled)\s+to|ha(?:s|ve)\s+(?:no\s+)?permission\s+to|permitted|may\s+(?:not\s+)?(?:be\s+)?\w+\s+only\b|may\s+(?:have\s+)?(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to)|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|denied|forbidden|prohibited|(?:is|are|be|become|becomes|remain|remains)\s+(?:invalid|rejected|prohibited|forbidden)|(?:reject|rejects|rejected|rejection)\s+(?:invalid|unresolved|ambiguous)|fail(?:s|ed)?\s+(?:clearly|explicitly|with)|expires?\s+(?:after|within|in)|failure\s+(?:behavior|policy|outcome)|error\s+(?:handling|behavior|policy|outcome)|required\s+outcome|defaults?\s+to)\b/i;
 // Conditional/temporal cues help discover clauses but do not by themselves
 // turn explanatory or subjective context into an asserted obligation.
 const NORMATIVE_PATTERN = new RegExp(`${NORMATIVE_ASSERTION_PATTERN.source}|\\b(?:before|unless|when|if)\\b`, "i");