kibi-cli 0.17.0 → 0.19.0

package/dist/operations/mutation/contradictions.js

@@ -2,39 +2,44 @@ import { escapeAtom } from "../../prolog/codec.js";
 import { formatInvalidRelationshipError } from "./relationships.js";
 import { buildPropertyList, buildRelationshipMetadata, } from "./serialization.js";
 // implements REQ-kibi-operation-interface-parity
-export function buildUpsertTransaction(input) {
-    const id = String(input.entity.id);
+export function buildUpsertCommitGoal(input) {
     const type = String(input.entity.type);
-    const goals = [
-        `kb_assert_entity_no_audit(${type}, ${buildPropertyList(input.entity)})`,
-        ...input.relationships.map((relationship) => `kb_assert_relationship_no_audit(${String(relationship.type)}, '${escapeAtom(String(relationship.from))}', '${escapeAtom(String(relationship.to))}', ${buildRelationshipMetadata(relationship)})`),
-    ];
-    if (type === "req" && !input.skipContradictionCheck) {
-        goals.push(`check_req_contradiction('${escapeAtom(id)}')`);
-    }
-    return `rdf_transaction((${goals.join(", ")}))`;
+    const relationships = input.relationships.map((relationship) => `rel(${String(relationship.type)}, '${escapeAtom(String(relationship.from))}', '${escapeAtom(String(relationship.to))}', ${buildRelationshipMetadata(relationship)})`);
+    return `kb_commit_upsert(${type}, ${buildPropertyList(input.entity)}, [${relationships.join(", ")}], ${input.skipContradictionCheck ? "true" : "false"}, ChangeKind)`;
 }
 // implements REQ-kibi-operation-interface-parity
 export function formatUpsertError(entityId, raw) {
     if (!raw)
         return `Failed to upsert entity ${entityId}: Unknown error`;
-    const invalidRelationship = formatInvalidRelationshipError(raw);
+    const stage = raw.match(/\(stage=([^)]+)\)/)?.[1];
+    const stageSuffix = stage === undefined ? "" : ` (stage=${stage})`;
+    const diagnosticFree = raw.replace(/^__KIBI_(?:STAGE|RUNTIME)__:[^\r\n]*\r?\n?/gm, "");
+    if (diagnosticFree.includes("stale_snapshot")) {
+        return `Failed to upsert entity ${entityId}: KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)${stageSuffix}`;
+    }
+    if (diagnosticFree.includes("Audit journal is locked") ||
+        diagnosticFree.includes("audit_log") ||
+        diagnosticFree.includes("audit.log") ||
+        diagnosticFree.includes("Resource temporarily unavailable")) {
+        return `Failed to upsert entity ${entityId}: Audit journal is locked by another Kibi runtime; restart the stale MCP/CLI session before retrying${stageSuffix}`;
+    }
+    const invalidRelationship = formatInvalidRelationshipError(diagnosticFree);
     if (invalidRelationship !== null) {
-        return `Failed to upsert entity ${entityId}: ${invalidRelationship}`;
+        return `Failed to upsert entity ${entityId}: ${invalidRelationship}${stageSuffix}`;
     }
-    const contradiction = raw.match(/kb_contradiction\(\s*\[([^\]]+)\]\s*\)/);
+    const contradiction = diagnosticFree.match(/kb_contradiction\(\s*\[([^\]]+)\]\s*\)/);
     if (contradiction) {
         const details = contradiction[1] ?? "";
         const conflicts = [
             ...details.matchAll(/(?:'([^']+)'|"([^"\\]*(?:\\.[^"\\]*)*)")-'([^']+)'/g),
         ].map((match) => `  - Conflicts with ${String(match[3])}: ${String(match[1] ?? match[2])}`);
         if (conflicts.length > 0) {
-            return `Contradiction detected for requirement ${entityId}:\n${[...new Set(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.`;
+            return `Contradiction detected for requirement ${entityId}:\n${[...new Set(conflicts)].join("\n")}\n\nTo resolve:\n  1. Add a supersedes relationship from the new requirement to the conflicting one, OR\n  2. Deprecate the conflicting requirement before creating the new one.${stageSuffix}`;
         }
-        return `Contradiction detected for entity ${entityId}: This requirement conflicts with existing requirements. Add a supersedes relationship to the conflicting requirement, or deprecate the old requirement before creating the new one.`;
+        return `Contradiction detected for entity ${entityId}: This requirement conflicts with existing requirements. Add a supersedes relationship to the conflicting requirement, or deprecate the old requirement before creating the new one.${stageSuffix}`;
     }
-    if (raw.includes("rdf_transaction")) {
-        return `Failed to upsert entity ${entityId}: Transaction failed`;
+    if (diagnosticFree.includes("rdf_transaction")) {
+        return `Failed to upsert entity ${entityId}: Transaction failed${stageSuffix}`;
     }
-    return `Failed to upsert entity ${entityId}: ${raw}`;
+    return `Failed to upsert entity ${entityId}: ${diagnosticFree || raw}`;
 }

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

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

package/dist/operations/mutation/serialization.js

@@ -20,16 +20,19 @@ const STRING_FIELDS = [
     "updated_at",
     "source",
     "text_ref",
+    "semantic_text",
 ];
 function serializeValue(key, value) {
     if (key === "id" && typeof value === "string") {
         return `'${value.replaceAll("'", "''")}'`;
     }
-    if (Array.isArray(value))
-        return JSON.stringify(value);
-    if (key === "rule_ir" || key === "semantic_inventory") {
+    if (key === "rule_ir" ||
+        key === "semantic_inventory" ||
+        key === "verification_receipts") {
         return toPrologString(JSON.stringify(value));
     }
+    if (Array.isArray(value))
+        return JSON.stringify(value);
     if (typeof value === "string") {
         return ATOM_FIELDS.includes(key)
             ? toPrologAtom(value)

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

@@ -1,5 +1,7 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
-import type { UpsertInput, UpsertPayload } from "./types.js";
+import type { RelationshipInput, UpsertInput, UpsertPayload } from "./types.js";
+export declare function validateAppendOnlyVerificationReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext): Promise<void>;
+export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext): Promise<readonly RelationshipInput[]>;
 export declare function executeUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<UpsertPayload>>;
 //# sourceMappingURL=upsert.d.ts.map

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":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAaxE,OAAO,KAAK,EAAqB,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkChF,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA0FzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAgBxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA8BhF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;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,GACxB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAgBvC;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAuGzC"}

package/dist/operations/mutation/upsert.js

@@ -1,9 +1,10 @@
 import { escapeAtom } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { appendOnlyVerificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
-import { recordEntityAudit, recordRelationshipAudits } from "./audit.js";
-import { buildUpsertTransaction, formatUpsertError } from "./contradictions.js";
+import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
+import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, } from "./relationships.js";
-import { saveMutation } from "./save.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { refreshSymbolCoordinates } from "./symbol-refresh.js";
 import { validateUpsertInput } from "./validation.js";
@@ -14,7 +15,36 @@ function requireProlog(context) {
     }
     return context.prolog;
 }
-async function effectiveRelationships(input, entity, relationships, context) {
+function receiptRecords(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((receipt) => receipt !== null &&
+        typeof receipt === "object" &&
+        !Array.isArray(receipt));
+}
+function parseChangeKind(value) {
+    const normalized = value?.trim().replace(/^['"]|['"]$/g, "");
+    return normalized === "created" || normalized === "updated"
+        ? normalized
+        : null;
+}
+export async function validateAppendOnlyVerificationReceipts(entity, context) {
+    if (entity.type !== "test")
+        return;
+    const existing = await loadEntities(requireProlog(context), {
+        id: String(entity.id),
+        type: "test",
+    });
+    const previous = receiptRecords(existing[0]?.verification_receipts);
+    if (!previous || previous.length === 0)
+        return;
+    const next = receiptRecords(entity.verification_receipts);
+    const errors = appendOnlyVerificationReceiptHistoryErrors(previous, next);
+    if (errors.length > 0) {
+        throw new Error(`Entity validation failed: ${errors.join("; ")}`);
+    }
+}
+export async function effectiveRelationships(input, entity, relationships, context) {
     if (input.relationships !== undefined && input.relationships.length > 0) {
         return relationships;
     }
@@ -36,13 +66,18 @@ export async function executeUpsert(input, context) {
     const prolog = requireProlog(context);
     try {
         const validated = validateUpsertInput(input, context.clock());
+        await validateAppendOnlyVerificationReceipts(validated.entity, context);
         validateRelationshipSources(input.id, validated.relationships);
         await validateSymbolGranularity(validated.entity, validated.relationships, context);
         const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context);
         await validateStrictLanePairing(prolog, relationships);
         await validateLiveRelationshipTargets(prolog, validated.entity, relationships);
-        const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
-        const transaction = buildUpsertTransaction({
+        const semantic = analyzeSemanticAdvisorInput({
+            payload: { ...input, relationships },
+        });
+        assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
+        await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships);
+        const transaction = buildUpsertCommitGoal({
             entity: validated.entity,
             relationships,
             skipContradictionCheck: input._skipContradictionCheck === true,
@@ -51,9 +86,14 @@ export async function executeUpsert(input, context) {
         if (!written.success) {
             throw new Error(formatUpsertError(input.id, written.error));
         }
-        await recordEntityAudit(prolog, exists.success ? "updated" : "created", validated.entity);
-        await recordRelationshipAudits(prolog, relationships);
-        await saveMutation(prolog);
+        // The combined commit is the sole mutation boundary. Invalidate reads only
+        // after Prolog reports success so a failed/rolled-back commit does not
+        // disturb callers' view of the current snapshot.
+        prolog.invalidateCache?.();
+        const changeKind = parseChangeKind(written.bindings.ChangeKind);
+        if (changeKind === null) {
+            throw new Error(`Upsert commit completed without a created/updated result for ${input.id}`);
+        }
         if (input.type === "symbol") {
             try {
                 await refreshSymbolCoordinates(input.id, context);
@@ -63,12 +103,11 @@ export async function executeUpsert(input, context) {
                     throw error;
             }
         }
-        const semantic = analyzeSemanticAdvisorInput({ payload: { ...input } });
         const coverage = await scenarioCoverageWarnings(prolog, validated.relationships, input.type, input.id);
-        const created = exists.success ? 0 : 1;
+        const created = changeKind === "created" ? 1 : 0;
         const payload = {
             created,
-            updated: exists.success ? 1 : 0,
+            updated: changeKind === "updated" ? 1 : 0,
             relationships_created: relationships.length,
             warnings: [...semantic.warnings, ...coverage],
             semanticAdvisor: semantic.receipt,

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;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGrE,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAoDjD"}
+{"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"}

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

@@ -1,16 +1,32 @@
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, validateSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { validateLiveRelationshipTargets, validateRelationshipSources, } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
+import { effectiveRelationships, validateAppendOnlyVerificationReceipts, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
 export async function executeValidateUpsert(input, context) {
     try {
         const validated = validateUpsertInput(input, context.clock());
+        await validateAppendOnlyVerificationReceipts(validated.entity, context);
         validateRelationshipSources(input.id, validated.relationships);
         await validateSymbolGranularity(validated.entity, validated.relationships, context);
+        const previewSemantic = analyzeSemanticAdvisorInput({
+            payload: { ...input, relationships: validated.relationships },
+        });
+        const previewBoundary = validateSemanticInventoryBoundary({ ...input, relationships: validated.relationships }, validated.relationships, previewSemantic.receipt);
+        const relationships = context.prolog === undefined || !previewBoundary.applicable
+            ? validated.relationships
+            : await effectiveRelationships(input, validated.entity, validated.relationships, context);
         if (context.prolog !== undefined) {
-            await validateLiveRelationshipTargets(context.prolog, validated.entity, validated.relationships);
+            await validateLiveRelationshipTargets(context.prolog, validated.entity, relationships);
+        }
+        const semantic = analyzeSemanticAdvisorInput({
+            payload: { ...input, relationships },
+        });
+        assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
+        if (context.prolog !== undefined) {
+            await assertLogicalGroundingClaimKeys(context.prolog, { ...input, relationships }, relationships);
         }
-        const semantic = analyzeSemanticAdvisorInput({ payload: { ...input } });
         const payload = {
             valid: true,
             errors: [],

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":"AAIA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA0CjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAQ5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CAwDjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -3,6 +3,7 @@ import entitySchema from "../../public/schemas/entity.js";
 import relationshipSchema from "../../public/schemas/relationship.js";
 // implements REQ-kibi-operation-interface-parity
 import { SYMBOL_ROLES, isAllowedGranularityReason, } from "../../public/symbol-granularity.js";
+import { verificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { factKindShapeHints, validateFactModelingShape, valueFieldHint, } from "./strict-fact.js";
 const ajv = new Ajv({ strict: false });
@@ -84,6 +85,13 @@ export function validateUpsertInput(input, now) {
     if (!validateEntity(entity)) {
         throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
     }
+    if (entity.type === "test" && Array.isArray(entity.verification_receipts)) {
+        const receipts = entity.verification_receipts.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value));
+        const receiptErrors = verificationReceiptHistoryErrors(input.id, entity.verification_scope, receipts);
+        if (receiptErrors.length > 0) {
+            throw new Error(`Entity validation failed: ${receiptErrors.join("; ")}`);
+        }
+    }
     validateFactModelingShape(entity);
     if (entity.type === "fact" &&
         typeof entity.claim_key === "string" &&

package/dist/operations/semantic-advisor/analysis-receipt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-receipt.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analysis-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,OAAO,EAA6B,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EACV,6BAA6B,EAI7B,4BAA4B,EAC5B,0BAA0B,EAC1B,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AA0CpB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,0BAA0B,EAAE,EAClD,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,YAAY,EAAE,SAAS,mBAAmB,EAAE,EAC5C,eAAe,EAAE,SAAS,4BAA4B,EAAE,EACxD,cAAc,EAAE,SAAS,iBAAiB,EAAE,GAC3C,6BAA6B,CA4G/B"}
+{"version":3,"file":"analysis-receipt.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analysis-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,KAAK,OAAO,EAMb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,6BAA6B,EAI7B,4BAA4B,EAC5B,0BAA0B,EAC1B,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AA0CpB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,0BAA0B,EAAE,EAClD,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,YAAY,EAAE,SAAS,mBAAmB,EAAE,EAC5C,eAAe,EAAE,SAAS,4BAA4B,EAAE,EACxD,cAAc,EAAE,SAAS,iBAAiB,EAAE,GAC3C,6BAA6B,CAkH/B"}

package/dist/operations/semantic-advisor/analysis-receipt.js

@@ -1,4 +1,4 @@
-import { payloadHash, propertiesOf } from "./shared.js";
+import { SEMANTIC_INVENTORY_VERSION, payloadHash, propertiesOf, semanticSourceHash, semanticSourceOf, } from "./shared.js";
 function chooseLane(signals) {
     if (signals.some(({ kind }) => kind === "numeric_cardinality" || kind === "numeric_threshold"))
         return "strict_property";
@@ -25,6 +25,7 @@ function summary(readiness, lane) {
 }
 // implements REQ-mcp-semantic-advisor-preflight
 export function buildAdvisorResult(payload, signals, modeled, suggestions, clauses, propositions, interpretations, shadowAnalysis) {
+    const semanticSource = semanticSourceOf(payload);
     const suggestionLane = suggestions.some(({ kind }) => kind === "strict_property")
         ? "strict_property"
         : suggestions.some(({ kind }) => kind === "rule")
@@ -72,6 +73,11 @@ export function buildAdvisorResult(payload, signals, modeled, suggestions, claus
     const receipt = {
         version: "semantic-advisor-v2",
         payload_hash: payloadHash(payload),
+        inventory_contract: {
+            version: SEMANTIC_INVENTORY_VERSION,
+            source_field: semanticSource.field,
+            source_hash: semanticSourceHash(semanticSource.text),
+        },
         logic_readiness: readiness,
         candidate_lane: candidateLane,
         signals,

package/dist/operations/semantic-advisor/analyze-prose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA6zBhD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CAuD/B"}
+{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA01BhD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CA+D/B"}

package/dist/operations/semantic-advisor/analyze-prose.js

@@ -8,7 +8,7 @@ import { CORE_PREDICATE_RULES } from "./predicate-rules-core.js";
 import { POLICY_PREDICATE_RULES } from "./predicate-rules-policy.js";
 import { PRODUCT_TAIL_PREDICATE_RULES } from "./predicate-rules-product-tail.js";
 import { PRODUCT_PREDICATE_RULES } from "./predicate-rules-product.js";
-import { isRecord, payloadHash, propertiesOf, relationship, sourceOf, statementOf, stringValue, } from "./shared.js";
+import { isRecord, payloadHash, propertiesOf, relationship, semanticClausesOf, semanticSourceHash, semanticSourceOf, sourceOf, statementOf, stringValue, } from "./shared.js";
 import { detectStrictSuggestion } from "./strict-rules.js";
 export const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v2";
 export { semanticClaimKey } from "./clauses.js";
@@ -52,7 +52,12 @@ const SIGNAL_PATTERNS = [
 ];
 function proseOf(payload) {
     const properties = propertiesOf(payload);
-    return [properties.title, properties.text_ref, properties.description]
+    return [
+        properties.title,
+        properties.semantic_text,
+        properties.text_ref,
+        properties.description,
+    ]
         .map(stringValue)
         .filter(Boolean)
         .join("\n");
@@ -69,8 +74,8 @@ function logicalGroundingSlots(payload) {
     return relationships.filter((relationship) => isRecord(relationship) &&
         ["requires_property", "requires_predicate", "requires_rule"].includes(stringValue(relationship.type))).length;
 }
-function isModeled(payload, expectedClaimCount) {
-    if (expectedClaimCount === 0)
+function isModeled(payload, expectedClaimKeys) {
+    if (expectedClaimKeys.length === 0)
         return false;
     const relationships = Array.isArray(payload.relationships)
         ? payload.relationships
@@ -79,7 +84,16 @@ function isModeled(payload, expectedClaimCount) {
         .filter(isRecord)
         .map((relationship) => stringValue(relationship.type))
         .filter(Boolean));
-    return (logicalGroundingSlots(payload) >= expectedClaimCount &&
+    const rawInventory = propertiesOf(payload).semantic_inventory;
+    const inventory = Array.isArray(rawInventory)
+        ? rawInventory.filter(isRecord)
+        : [];
+    const modeledClaimKeys = inventory
+        .filter(({ status }) => status === "modeled")
+        .map(({ claim_key }) => stringValue(claim_key));
+    return (logicalGroundingSlots(payload) === expectedClaimKeys.length &&
+        modeledClaimKeys.length === expectedClaimKeys.length &&
+        expectedClaimKeys.every((claimKey) => modeledClaimKeys.includes(claimKey)) &&
         ((types.has("constrains") && types.has("requires_property")) ||
             types.has("requires_predicate") ||
             types.has("requires_rule")));
@@ -231,13 +245,8 @@ function modelingSuggestions(payload, modeled, clauses, interpretations) {
     const suggestions = [];
     const seen = new Set();
     const expectedClaimKeys = clauses
-        .filter((clause) => clause.normative)
+        .filter((clause) => !["rationale", "example", "subjective"].includes(propositionRole(clause.text, clause.normative)))
         .map((clause) => clause.claim_key);
-    const rawDeclaredClaimKeys = propertiesOf(payload).logic_claims;
-    const declaredClaimKeys = Array.isArray(rawDeclaredClaimKeys)
-        ? rawDeclaredClaimKeys.filter((value) => typeof value === "string")
-        : [];
-    const mergedClaimKeys = Array.from(new Set([...declaredClaimKeys, ...expectedClaimKeys]));
     for (const clause of clauses) {
         const candidate = clause.text;
         const rawSuggestion = predicateSuggestion(payload, candidate) ??
@@ -245,9 +254,9 @@ function modelingSuggestions(payload, modeled, clauses, interpretations) {
             ambiguitySuggestion(payload, candidate) ??
             detectStrictSuggestion(payload, candidate);
         const suggestion = rawSuggestion
-            ? withClauseProvenance(rawSuggestion, clause, mergedClaimKeys, statementOf(payload))
+            ? withClauseProvenance(rawSuggestion, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field)
             : clause.normative
-                ? unmatchedClauseSuggestion(payload, clause, mergedClaimKeys)
+                ? unmatchedClauseSuggestion(payload, clause, clauses, expectedClaimKeys)
                 : null;
         if (!suggestion)
             continue;
@@ -264,7 +273,7 @@ function modelingSuggestions(payload, modeled, clauses, interpretations) {
         const suggestion = ruleSuggestion(payload, interpretation);
         if (!suggestion)
             continue;
-        const withProvenance = withClauseProvenance(suggestion, clause, mergedClaimKeys, statementOf(payload));
+        const withProvenance = withClauseProvenance(suggestion, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field);
         const key = withProvenance.kind === "rule"
             ? `${withProvenance.claim_key}:rule:${withProvenance.semantic_key}`
             : `${withProvenance.claim_key}:${withProvenance.kind}`;
@@ -275,9 +284,45 @@ function modelingSuggestions(payload, modeled, clauses, interpretations) {
     }
     return suggestions;
 }
-function withClauseProvenance(suggestion, clause, expectedClaimKeys, statement) {
+function withClauseProvenance(suggestion, clause, clauses, expectedClaimKeys, statement, sourceField) {
     const clauseOffset = statement.indexOf(clause.text);
     const clauseSpan = utf8Span(statement || clause.text, clauseOffset >= 0 ? clauseOffset : 0, clauseOffset >= 0 ? clauseOffset + clause.text.length : clause.text.length);
+    const status = suggestion.kind === "ambiguity_observation"
+        ? "ambiguous"
+        : suggestion.kind === "ontology_gap"
+            ? "ontology_gap"
+            : "modeled";
+    let inventoryCursor = 0;
+    const semanticInventory = clauses.map((entry) => {
+        const located = propositionSpan(statement, entry, inventoryCursor);
+        inventoryCursor = located.next;
+        const role = propositionRole(entry.text, entry.normative);
+        const context = ["rationale", "example", "subjective"].includes(role);
+        const entryStatus = entry.index === clause.index
+            ? status
+            : context
+                ? "nonlogical"
+                : "missing";
+        return {
+            claim_key: entry.claim_key,
+            claim_text: entry.text,
+            role,
+            status: entryStatus,
+            span: located.span,
+            reason: entry.index === clause.index
+                ? status === "modeled"
+                    ? "Draft apply plan contains a typed grounding for this proposition."
+                    : suggestion.rationale
+                : context
+                    ? "Prose is retained for human context and is not a verifiable domain proposition."
+                    : "No typed grounding is included for this proposition in the current draft plan.",
+        };
+    });
+    const inventoryContract = {
+        version: "kibi.semantic-inventory.v1",
+        source_field: sourceField,
+        source_hash: semanticSourceHash(statement),
+    };
     const applyPlan = suggestion.applyPlan.map((step) => {
         if (!isRecord(step))
             return step;
@@ -288,32 +333,16 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys, statement)
             const existing = Array.isArray(properties.logic_claims)
                 ? properties.logic_claims.filter((value) => typeof value === "string")
                 : [];
-            const inventory = Array.isArray(properties.semantic_inventory)
-                ? properties.semantic_inventory.filter(isRecord)
-                : [];
-            const status = suggestion.kind === "ambiguity_observation"
-                ? "ambiguous"
-                : suggestion.kind === "ontology_gap"
-                    ? "ontology_gap"
-                    : "modeled";
             return {
                 ...step,
                 properties: {
                     ...properties,
                     logic_claims: Array.from(new Set([...existing, ...expectedClaimKeys])),
-                    semantic_inventory: [
-                        ...inventory.filter((entry) => entry.claim_key !== clause.claim_key),
-                        {
-                            claim_key: clause.claim_key,
-                            claim_text: clause.text,
-                            role: clause.normative ? "normative" : "descriptive",
-                            status,
-                            span: clauseSpan,
-                            reason: status === "modeled"
-                                ? "Draft apply plan contains a typed grounding for this proposition."
-                                : suggestion.rationale,
-                        },
-                    ],
+                    semantic_clauses: clauses.map(({ text }) => text),
+                    semantic_inventory_version: inventoryContract.version,
+                    semantic_source_field: inventoryContract.source_field,
+                    semantic_source_hash: inventoryContract.source_hash,
+                    semantic_inventory: semanticInventory,
                 },
             };
         }
@@ -342,16 +371,9 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys, statement)
                     claimKey: clause.claim_key,
                     claimText: clause.text,
                     logicClaims: expectedClaimKeys,
-                    semanticInventory: [
-                        {
-                            claim_key: clause.claim_key,
-                            claim_text: clause.text,
-                            role: clause.normative ? "normative" : "descriptive",
-                            status: "modeled",
-                            span: clauseSpan,
-                            reason: "The returned typed fact grounds this proposition.",
-                        },
-                    ],
+                    semanticClauses: clauses.map(({ text }) => text),
+                    semanticInventory,
+                    inventoryContract,
                     instructions: "Create the predicate fact, merge the returned logicClaims into the requirement logic_claims manifest, then add requires_predicate without overwriting other requirement metadata.",
                 },
             }
@@ -363,23 +385,16 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys, statement)
                     claimKey: clause.claim_key,
                     claimText: clause.text,
                     logicClaims: expectedClaimKeys,
-                    semanticInventory: [
-                        {
-                            claim_key: clause.claim_key,
-                            claim_text: clause.text,
-                            role: clause.normative ? "normative" : "descriptive",
-                            status: "modeled",
-                            span: clauseSpan,
-                            reason: "The returned typed rule grounds this proposition.",
-                        },
-                    ],
+                    semanticClauses: clauses.map(({ text }) => text),
+                    semanticInventory,
+                    inventoryContract,
                     instructions: "Create the rule_schema and rule facts, merge the returned logicClaims into the requirement logic_claims manifest, then add requires_rule without overwriting other requirement metadata.",
                 },
             }
             : {}),
     };
 }
-function unmatchedClauseSuggestion(payload, clause, expectedClaimKeys) {
+function unmatchedClauseSuggestion(payload, clause, clauses, expectedClaimKeys) {
     return withClauseProvenance({
         kind: "ontology_gap",
         claim_key: clause.claim_key,
@@ -394,7 +409,7 @@ function unmatchedClauseSuggestion(payload, clause, expectedClaimKeys) {
             "review:ontology-gap",
             "needs_schema_extension",
         ]),
-    }, clause, expectedClaimKeys, statementOf(payload));
+    }, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field);
 }
 function propositionRole(statement, normative) {
     if (/\b(?:for example|e\.g\.|such as|illustrative)\b/i.test(statement))
@@ -668,17 +683,17 @@ export function analyzeSemanticAdvisorInput(input) {
     const statement = statementOf(payload) || proseOf(payload);
     const signals = requirement ? detectSignals(proseOf(payload)) : [];
     const clauses = statement
-        ? extractSemanticClauses(statement, input.clauses)
+        ? extractSemanticClauses(statement, input.clauses ?? semanticClausesOf(payload))
         : [];
     const rawDeclaredClaims = propertiesOf(payload).logic_claims;
     const declaredClaims = Array.isArray(rawDeclaredClaims)
         ? rawDeclaredClaims.filter((value) => typeof value === "string")
         : [];
     const expectedClaims = clauses
-        .filter((clause) => clause.normative)
+        .filter((clause) => !["rationale", "example", "subjective"].includes(propositionRole(clause.text, clause.normative)))
         .map((clause) => clause.claim_key);
     const modeled = requirement &&
-        isModeled(payload, expectedClaims.length) &&
+        isModeled(payload, expectedClaims) &&
         expectedClaims.length > 0 &&
         expectedClaims.every((claimKey) => declaredClaims.includes(claimKey));
     const suggestions = modelingSuggestions(payload, modeled, clauses, input.interpretations);

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

@@ -5,6 +5,7 @@ export type SemanticClause = Readonly<{
     normative: boolean;
     source: "detected" | "supplied";
 }>;
+export declare function normalizeSemanticClause(value: string): string;
 export declare function semanticClaimKey(text: string): string;
 export declare function extractSemanticClauses(text: string, suppliedClauses?: readonly string[]): readonly SemanticClause[];
 //# sourceMappingURL=clauses.d.ts.map

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,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAeD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CAgB3B"}
+{"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;AAKH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAeD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CAgB3B"}

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

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 const NORMATIVE_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|forbidden|denied|defaults?\s+to|before|unless|when|if)\b/i;
-function normalizeClause(value) {
+export function normalizeSemanticClause(value) {
     return (value
         .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "")
         .replace(/\s+/g, " ")
@@ -11,7 +11,7 @@ function normalizeClause(value) {
         .trim());
 }
 export function semanticClaimKey(text) {
-    const normalized = normalizeClause(text).toLowerCase();
+    const normalized = normalizeSemanticClause(text).toLowerCase();
     const digest = createHash("sha256").update(normalized).digest("hex");
     return `CLAIM-${digest.slice(0, 16).toUpperCase()}`;
 }
@@ -23,21 +23,21 @@ function detectedClauses(text) {
             return [sentence];
         return sentence.split(/\s+(?:,\s*)?and\s+(?=(?:the\s+)?[a-z][^.!?]{0,100}\b(?:must|shall|should|requires?|cannot|can't|expire|default|transition|states?\s+are)\b)/i);
     })
-        .map(normalizeClause)
+        .map(normalizeSemanticClause)
         .filter(Boolean);
 }
 export function extractSemanticClauses(text, suppliedClauses) {
     const source = suppliedClauses === undefined ? "detected" : "supplied";
     const raw = suppliedClauses ?? detectedClauses(text);
-    const unique = Array.from(new Set(raw.map(normalizeClause).filter(Boolean)));
-    if (suppliedClauses !== undefined && unique.length === 0) {
+    const normalized = raw.map(normalizeSemanticClause).filter(Boolean);
+    if (suppliedClauses !== undefined && normalized.length === 0) {
         throw new Error("Semantic advisor clauses must contain at least one non-empty atomic claim");
     }
-    return unique.map((clause, index) => ({
+    return normalized.map((clause, index) => ({
         claim_key: semanticClaimKey(clause),
         text: clause,
         index,
-        normative: source === "supplied" || NORMATIVE_PATTERN.test(clause),
+        normative: NORMATIVE_PATTERN.test(clause),
         source,
     }));
 }