kibi-cli 2.21.2 → 2.22.1

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

@@ -1,6 +1,6 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
-import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import type { SemanticAdvisorReceipt } from "../semantic-advisor/types.js";
 import { type StoredEntityLookup } from "./stored-entity.js";
 import type { RelationshipInput, StagedUpsertState, UpsertInput, UpsertPayload, ValidatedUpsert } from "./types.js";
 export declare function assertRelationshipShardContained(workspaceRoot: string, shardPath: string): void;
@@ -15,11 +15,26 @@ export type UpsertValidationOptions = Readonly<{
      */
     readonly staged?: StagedUpsertState;
 }>;
+/** The semantic advisor result an upsert reports; no receipt for a non-requirement. */
+export type UpsertSemanticAnalysis = Readonly<{
+    readonly receipt: SemanticAdvisorReceipt | null;
+    readonly warnings: readonly string[];
+}>;
+/**
+ * The semantic advisor analyses requirement prose: its propositions, claim
+ * keys and inventory contract describe a requirement. Any other entity has no
+ * prose inventory, so analysing its title (the fallback prose) would report
+ * claim keys nothing declares, for example a fact whose claim_key derives
+ * from claim_text. Its upsert carries no receipt.
+ */
+export declare function analyzeUpsertSemantics(payload: UpsertInput & {
+    readonly relationships: readonly RelationshipInput[];
+}): UpsertSemanticAnalysis;
 export type UpsertValidation = Readonly<{
     readonly validated: ValidatedUpsert;
     /** The upsert's relationships merged with the entity's existing ones. */
     readonly relationships: readonly RelationshipInput[];
-    readonly semantic: ReturnType<typeof analyzeSemanticAdvisorInput>;
+    readonly semantic: UpsertSemanticAnalysis;
 }>;
 /**
  * The complete validation an upsert passes before its first write: schema,

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;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA8BnF,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA8DpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAiF3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}
+{"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;AAexE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAyB3E,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;AAsEpB,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,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG;IACrB,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,GACA,sBAAsB,CASxB;AAGD,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,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA0E3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}

package/dist/operations/mutation/upsert.js

@@ -59,6 +59,11 @@ function storedClaimKey(entity) {
         ? { claimKey: entity.claim_key }
         : {};
 }
+// implements REQ-mcp-semantic-advisor-preflight
+/** The written result's semantic advisor receipt, omitted for a non-requirement. */
+function advisorReceipt(receipt) {
+    return receipt === null ? {} : { semanticAdvisor: receipt };
+}
 function fileHash(pathname) {
     if (!existsSync(pathname))
         return null;
@@ -194,6 +199,21 @@ function reextractCanonicalSymbolEntity(symbolId, authoredRelativePath, workspac
             : { sourceFile: result.sourceFile }),
     };
 }
+// implements REQ-mcp-semantic-advisor-preflight
+/**
+ * The semantic advisor analyses requirement prose: its propositions, claim
+ * keys and inventory contract describe a requirement. Any other entity has no
+ * prose inventory, so analysing its title (the fallback prose) would report
+ * claim keys nothing declares, for example a fact whose claim_key derives
+ * from claim_text. Its upsert carries no receipt.
+ */
+export function analyzeUpsertSemantics(payload) {
+    if (payload.type !== "req")
+        return { receipt: null, warnings: [] };
+    const semantic = analyzeSemanticAdvisorInput({ payload });
+    assertSemanticInventoryBoundary(payload, payload.relationships, semantic.receipt);
+    return semantic;
+}
 // implements REQ-kibi-truthful-consistency
 /**
  * The complete validation an upsert passes before its first write: schema,
@@ -223,10 +243,7 @@ export async function validateUpsertForCommit(payload, context, options = {}) {
     await validateStrictLanePairing(prolog, validated.relationships, staged);
     await validateLiveRelationshipTargets(prolog, validated.entity, validated.relationships, staged);
     await validateSupersedesSourceHistory(prolog, validated.entity, validated.relationships, context.workspaceRoot, undefined, staged);
-    const semantic = analyzeSemanticAdvisorInput({
-        payload: { ...input, relationships },
-    });
-    assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
+    const semantic = analyzeUpsertSemantics({ ...input, relationships });
     await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships, staged);
     await assertPredicateArgumentVocabulary(prolog, validated.entity, staged);
     // The origin the write records is added last: none of the checks above
@@ -321,7 +338,7 @@ export async function executeUpsert(input, context, options = {}) {
     let commitEntity;
     let relationshipCount = 0;
     let changeKind = null;
-    let semanticAdvisor;
+    let semanticAdvisor = null;
     let compilerLock;
     let sourceMutationLock;
     let operationFailure;
@@ -510,7 +527,7 @@ export async function executeUpsert(input, context, options = {}) {
                     updated: 0,
                     relationships_created: validated.relationships.length,
                     warnings: [...planRecoveryWarnings, ...semantic.warnings],
-                    semanticAdvisor: semantic.receipt,
+                    ...advisorReceipt(semantic.receipt),
                     ...storedClaimKey(commitEntity ?? validated.entity),
                     deferredCommit,
                     ...(sourceWrite ? { sourceWrites: [sourceWrite.receipt] } : {}),
@@ -587,10 +604,10 @@ export async function executeUpsert(input, context, options = {}) {
                 ...semantic.warnings,
                 ...coverage,
                 ...idStyleWarnings,
-                ...entityContextWarnings(input, commitEntity ?? validated.entity, context.workspaceRoot, sourceWrite?.receipt.path),
+                ...entityContextWarnings(input, commitEntity ?? validated.entity, context.workspaceRoot, { writtenPath: sourceWrite?.receipt.path }),
                 ...shardWarnings,
             ],
-            semanticAdvisor: semantic.receipt,
+            ...advisorReceipt(semantic.receipt),
             ...storedClaimKey(commitEntity ?? validated.entity),
             ...(shardWarnings.length > 0
                 ? {
@@ -625,9 +642,9 @@ export async function executeUpsert(input, context, options = {}) {
                             ? "skipped"
                             : "no-conflict",
                         checked_req_id: input.id,
-                        strict_readiness: semantic.receipt.logic_readiness === "modeled"
+                        strict_readiness: semantic.receipt?.logic_readiness === "modeled"
                             ? "modeled"
-                            : semantic.receipt.candidate_lane,
+                            : (semantic.receipt?.candidate_lane ?? "none"),
                     },
                 }
                 : {}),
@@ -662,7 +679,7 @@ export async function executeUpsert(input, context, options = {}) {
                     updated: changeKind === "updated" ? 1 : 0,
                     relationships_created: relationshipCount,
                     warnings: [...planRecoveryWarnings, detail],
-                    semanticAdvisor: semanticAdvisor,
+                    ...advisorReceipt(semanticAdvisor),
                     status: "committed_with_repairs",
                     effectFailures: [
                         {

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;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"}
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAWxE,OAAO,KAAK,EAIV,WAAW,EACX,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAiPpB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAkHjD"}

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

@@ -1,13 +1,13 @@
 // implements REQ-kibi-operation-interface-parity
 import { escapeAtom } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
 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, buildWhatIfAnalysisGoal, formatUpsertError, } from "./contradictions.js";
 import { validateRelationshipSources } from "./relationships.js";
+import { canonicalSourcePath } from "./source-authoring.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
-import { validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
+import { analyzeUpsertSemantics, validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
 import { symbolCoverageWarnings } from "./warnings.js";
 import { isBlockingWitness, parseWhatIfAnalysis } from "./what-if.js";
@@ -16,6 +16,37 @@ async function entityExists(prolog, id) {
     const result = await prolog.query(`once(kb_entity('${escapeAtom(id)}', _Type, _Props))`);
     return result.success;
 }
+// implements REQ-kibi-operation-interface-parity, REQ-kb-entity-body-context
+/**
+ * The authored document a real kb_upsert would update, resolved with the
+ * write's own rules (stored authored source, else the canonical lane path).
+ * The preview entity's `source` is the runtime marker, so without this the
+ * context warning would judge the statement instead of the existing body the
+ * write preserves. Undefined when the write would not touch a document.
+ */
+async function previewDocumentPath(input, entity, context) {
+    if (context.fs === undefined || context.sourceFirst === false) {
+        return undefined;
+    }
+    try {
+        const existing = context.prolog === undefined
+            ? undefined
+            : (await loadEntities(context.prolog, {
+                id: input.id,
+                type: input.type,
+            }))[0];
+        const existingSource = typeof existing?.source === "string" ? existing.source : undefined;
+        if (input.document === undefined &&
+            existing !== undefined &&
+            !existingSource?.match(/\.(?:md|mdx|ya?ml|json)$/i)) {
+            return undefined;
+        }
+        return canonicalSourcePath(context, input, entity, existing);
+    }
+    catch {
+        return undefined;
+    }
+}
 // implements REQ-kibi-operation-interface-parity, REQ-kibi-truthful-consistency
 /**
  * The commit-time contradiction check, run against a staged and rolled-back
@@ -130,11 +161,10 @@ async function validateWithoutStore(input, context) {
     await validateAppendOnlyProofReceipts(validated.entity, context);
     validateRelationshipSources(input.id, validated.relationships);
     await validateSymbolGranularity(validated.entity, validated.relationships, context);
-    const relationships = validated.relationships;
-    const semantic = analyzeSemanticAdvisorInput({
-        payload: { ...input, relationships },
+    const semantic = analyzeUpsertSemantics({
+        ...input,
+        relationships: validated.relationships,
     });
-    assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
     return { entity: validated.entity, semantic };
 }
 // implements REQ-kibi-operation-interface-parity, REQ-kibi-truthful-consistency
@@ -194,7 +224,9 @@ export async function executeValidateUpsert(input, context) {
                 ...semantic.warnings,
                 ...coverageWarnings,
                 ...idStyleWarnings,
-                ...entityContextWarnings(input, entity, context.workspaceRoot),
+                ...entityContextWarnings(input, entity, context.workspaceRoot, {
+                    targetPath: await previewDocumentPath(input, entity, context),
+                }),
             ],
             semanticAdvisor: semantic.receipt,
             normalizedPreview: entity,

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqI/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA8L/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -64,9 +64,51 @@ function unknownEntityProperties(entity) {
     const known = upsertEntitySchema.properties;
     return Object.keys(entity).filter((key) => !Object.hasOwn(known, key));
 }
+/**
+ * The fields a type-conditional `else: { not: ... }` branch of the entity
+ * schema forbids, and the types that may carry them; null for any other
+ * schema path.
+ */
+function typeRestrictedFields(schemaPath) {
+    const match = /^#\/allOf\/(\d+)\/else\/not$/.exec(schemaPath);
+    if (match === null)
+        return null;
+    const allOf = upsertEntitySchema.allOf;
+    const branch = Array.isArray(allOf) ? allOf[Number(match[1])] : undefined;
+    if (branch === null || typeof branch !== "object")
+        return null;
+    const record = branch;
+    const typeRule = record.if?.properties?.type;
+    const types = Array.isArray(typeRule?.enum)
+        ? typeRule.enum.map(String)
+        : typeof typeRule?.const === "string"
+            ? [typeRule.const]
+            : [];
+    const not = record.else?.not;
+    const requiredLists = [
+        not?.required,
+        ...(Array.isArray(not?.anyOf)
+            ? not.anyOf.map((entry) => entry?.required)
+            : []),
+    ];
+    const fields = requiredLists.flatMap((list) => Array.isArray(list) ? list.map(String) : []);
+    return types.length > 0 && fields.length > 0 ? { fields, types } : null;
+}
 // implements REQ-upsert-unknown-field-guidance
 function formatEntityErrors(entity, errors) {
-    const messages = errors.map((error) => {
+    // A field only some entity types carry fails a type-conditional `not`
+    // branch; AJV then reports "must NOT be valid" plus the "else" it chose.
+    const restricted = new Set(errors.flatMap((error) => error.keyword === "not" && typeRestrictedFields(error.schemaPath)
+        ? [error.schemaPath.replace(/\/else\/not$/, "/if")]
+        : []));
+    const visible = errors.filter((error) => !(error.keyword === "if" && restricted.has(error.schemaPath)));
+    const messages = visible.map((error) => {
+        const restriction = error.keyword === "not" ? typeRestrictedFields(error.schemaPath) : null;
+        if (restriction !== null) {
+            const present = restriction.fields.filter((field) => Object.hasOwn(entity, field));
+            const named = present.length > 0 ? present : restriction.fields;
+            return `${named.join(", ")} ${named.length === 1 ? "is" : "are"} only valid on ${restriction.types.join(" and ")} entities; remove ${named.length === 1 ? "it" : "them"} from this ${String(entity.type ?? "entity")}`;
+        }
         const params = error.params;
         const path = error.instancePath || "root";
         if (error.keyword === "additionalProperties" && params.additionalProperty) {

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

@@ -1 +1 @@
-{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AASlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAgE/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AA8zBD;;;;;;GAMG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAyqDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB;AACzB;;;GAGG;AACH,WAAW,GAAE,MAAM,IAAsB,GACxC,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAmDD"}
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AASlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAiE/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AAi1BD;;;;;;GAMG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAyqDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB;AACzB;;;GAGG;AACH,WAAW,GAAE,MAAM,IAAsB,GACxC,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAmDD"}

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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { OperationError } from "../../cli-errors.js";
 import { branchEnsureCommand, branchMigrateCommand, branchRecoverCommand, } from "../../commands/branch.js";
-import { migrateCommand } from "../../commands/migrate.js";
+import { describeMigrationRun, migrateCommand, } from "../../commands/migrate.js";
 import { syncCommand } from "../../commands/sync.js";
 import { PROOF_INTEGRATION_CONFIGURE, applyProofIntegrationAction, } from "../../proof/integration-plan.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
@@ -16,7 +16,7 @@ import { canonicalFilesystemPath } from "../../utils/canonical-path.js";
 import { isDerivedKbPath } from "../../utils/kb-paths.js";
 import { bootstrapEmptyKbSnapshotId, bootstrapPlanHash, } from "../bootstrap/types.js";
 import { validateBootstrapPayload } from "../bootstrap/validation.js";
-import { SCHEMA6_AUTOMATIC_CODES, applySchema6MigrationAction, } from "../migration/schema6.js";
+import { SCHEMA6_APPROVABLE_REVIEW_CODES, SCHEMA6_AUTOMATIC_CODES, applySchema6MigrationAction, } from "../migration/schema6.js";
 import { buildUpsertBatchCommitGoal, formatUpsertError, } from "../mutation/contradictions.js";
 import { executeDelete } from "../mutation/delete.js";
 import { PLAN_APPLY_JOURNAL_VERSION, contentHash, createPlanApplyJournal, isPlanApplyJournalId, openPlanApplyJournal, openPlanApplyJournalById, planRecoveryNotes, publishJournaledFiles, reconcilePendingSourceReceipts, recordPlanApplyJournal, recoverPlanApplyJournal, restoreJournaledFiles, settlePendingPlanApplyJournals, storeFingerprint, withPlanRecoveryNotes, } from "../mutation/plan-apply-journal.js";
@@ -273,7 +273,8 @@ function validateMigrationPlanShape(args) {
     for (const action of actions) {
         if (action.state !== "ready")
             throw new Error(`Migration apply failed: action '${action.id}' is blocked`);
-        if (action.safety !== "automatic" || action.autoApplicable !== true)
+        if (!(action.safety === "automatic" && action.autoApplicable === true) &&
+            !isApprovableReviewAction(action))
             throw new Error(`Migration apply failed: action '${action.id}' is not automatic`);
         for (const dependency of action.dependsOn) {
             if (!selected.has(dependency))
@@ -282,6 +283,19 @@ function validateMigrationPlanShape(args) {
     }
     return actions;
 }
+/**
+ * A review action Kibi can execute once a person approves it by id. Callers
+ * pass the approved ids explicitly; `kibi migrate --apply-safe` without
+ * `--approved-action` selects only automatic actions, so these never run on
+ * their own.
+ */
+// implements REQ-agent-guided-migration-orchestration, REQ-cli-schema-migration
+function isApprovableReviewAction(action) {
+    return (action.safety === "review" &&
+        action.autoApplicable === false &&
+        action.invocation.kind === "cli" &&
+        SCHEMA6_APPROVABLE_REVIEW_CODES.has(action.code));
+}
 function topologicalActions(actions) {
     const byId = new Map(actions.map((action) => [action.id, action]));
     const result = [];
@@ -2141,12 +2155,12 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
             continue;
         }
         try {
-            await applyMigrationAction(action, context);
+            const detail = await applyMigrationAction(action, context);
             onCommitted();
             results.push({
                 actionId: action.id,
                 outcome: "applied",
-                detail: `Applied ${action.code}.`,
+                detail: detail ?? `Applied ${action.code}.`,
             });
         }
         catch (error) {
@@ -2278,6 +2292,10 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
         structuredContent: payload,
     };
 }
+/**
+ * Run one approved migration action. Returns a detail line for the action
+ * result when the executor reports what it changed.
+ */
 async function applyMigrationAction(action, context) {
     switch (action.code) {
         case "legacy_branch_storage":
@@ -2328,14 +2346,19 @@ async function applyMigrationAction(action, context) {
             return;
         case "schema_version_upgrade":
         case "invalid_schema_version":
-        case "legacy_storage_migration":
-            if ((await migrateCommand({
+        case "legacy_storage_migration": {
+            // implements REQ-agent-guided-migration-orchestration
+            const run = await migrateCommand({
                 yes: true,
                 workspaceRoot: context.workspaceRoot,
                 initializeMissingConfig: true,
-            })).exitCode !== 0)
+            });
+            if (run.exitCode !== 0)
                 throw new Error("Schema migration did not complete successfully.");
-            return;
+            return run.summary !== undefined
+                ? describeMigrationRun(run.summary)
+                : undefined;
+        }
         case "symbol_refresh_coordinates":
         case "coverage_source_coordinates": {
             const result = await syncCommand({
@@ -2354,7 +2377,8 @@ async function applyMigrationAction(action, context) {
             applyProofIntegrationAction(action, context.workspaceRoot);
             return;
         default:
-            if (SCHEMA6_AUTOMATIC_CODES.has(action.code)) {
+            if (SCHEMA6_AUTOMATIC_CODES.has(action.code) ||
+                SCHEMA6_APPROVABLE_REVIEW_CODES.has(action.code)) {
                 await applySchema6MigrationAction(action, context);
                 return;
             }

package/dist/operations/semantic-advisor/ingestion-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingestion-boundary.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/ingestion-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG3E,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,YAAY,CAAC;AAgB9E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAuEH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,+BAA+B,CA0IjC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAoDD;;;;GAIG;AAEH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9D,MAAM,GAAG,IAAI,CAUf;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"ingestion-boundary.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/ingestion-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG3E,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,YAAY,CAAC;AAgB9E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAuEH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,+BAA+B,CA0IjC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAoFD;;;;GAIG;AAEH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9D,MAAM,GAAG,IAAI,CAUf;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/operations/semantic-advisor/ingestion-boundary.js

@@ -192,9 +192,33 @@ function groundingClaimKeyError(modeledClaimKeys, grounded) {
         return `Proposition-complete ingestion failed: claim '${duplicate}' has more than one logical grounding relationship.`;
     if (groundedClaimKeys.length !== modeledClaimKeys.length ||
         modeledClaimKeys.some((claimKey) => !groundedClaimKeys.includes(claimKey)))
-        return "Proposition-complete ingestion failed: modeled proposition claim_keys must match logical grounding target claim_keys exactly.";
+        return `Proposition-complete ingestion failed: modeled proposition claim_keys must match logical grounding target claim_keys exactly. ${claimKeyMismatchDetail(modeledClaimKeys, grounded)}`;
     return null;
 }
+/**
+ * Why the mismatch names both sides: a claim_key is derived from the clause
+ * text, so a requirement whose prose was reworded (or analyzed from another
+ * field than the stored semantic_text) carries keys none of its grounding
+ * facts declare. Listing the unmatched modeled keys and the facts with the
+ * keys they still declare lets the agent see the drift and pick the remedy
+ * without diffing the KB by hand.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+function claimKeyMismatchDetail(modeledClaimKeys, grounded) {
+    const groundedClaimKeys = grounded.map(([, claimKey]) => claimKey);
+    const ungrounded = modeledClaimKeys.filter((claimKey) => !groundedClaimKeys.includes(claimKey));
+    const stale = grounded.filter(([, claimKey]) => !modeledClaimKeys.includes(claimKey));
+    const parts = [
+        ungrounded.length > 0
+            ? `Modeled claims with no grounding fact declaring their claim_key: ${ungrounded.map((claimKey) => `'${claimKey}'`).join(", ")}.`
+            : "",
+        stale.length > 0
+            ? `Grounding facts whose claim_key the inventory no longer models: ${stale.map(([target, claimKey]) => `${target} ('${claimKey}')`).join(", ")}.`
+            : "",
+        "A claim_key is derived from the clause text, so reworded prose (or prose analyzed from a field other than the stored semantic_text) yields new keys. Keep the stored semantic_text wording, or kb_upsert each grounding fact with the new claim_key and claim_text (same fact id) before this write; for a change of meaning, supersede the requirement instead.",
+    ];
+    return parts.filter(Boolean).join(" ");
+}
 /**
  * The write-time claim_key check, run against planned writes only. Returns
  * null when it passes or when a target is outside the plan (the write-time

package/dist/operations/semantic-advisor/stored-ledger-drift.d.ts

@@ -0,0 +1,19 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { SemanticAdvisorReceipt } from "./types.js";
+/**
+ * Why `kb_model mode: analyze` with the `id` of a stored requirement compares
+ * its ledger with the stored one: a claim_key is derived from the clause
+ * text, so analyzing reworded prose, or the title instead of the stored
+ * `semantic_text`, yields keys that none of the requirement's grounding
+ * facts declare. The write that follows such a receipt is refused by the
+ * proposition-complete check, long after the agent picked the wording. The
+ * receipt therefore warns at analysis time, naming the stored modeled
+ * clauses the analysis no longer states, the facts that ground them, and the
+ * clauses the analysis adds, so the agent can keep the stored wording or
+ * re-ground the facts before writing.
+ *
+ * Returns null when the requirement is not stored, carries no recorded
+ * ledger, or every stored modeled clause is still among the analyzed ones.
+ */
+export declare function storedLedgerDriftWarning(prolog: Pick<PrologPort, "query">, id: string, text: string, receipt: SemanticAdvisorReceipt): Promise<string | null>;
+//# sourceMappingURL=stored-ledger-drift.d.ts.map

package/dist/operations/semantic-advisor/stored-ledger-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-ledger-drift.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/stored-ledger-drift.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAwCzD;;;;;;;;;;;;;;GAcG;AAEH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkDxB"}

package/dist/operations/semantic-advisor/stored-ledger-drift.js

@@ -0,0 +1,78 @@
+import { escapeAtom, parseListOfLists, parsePrologValue, } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { SEMANTIC_INVENTORY_VERSION, isRecord, stringValue } from "./shared.js";
+const LOGICAL_RELATIONSHIPS = [
+    "requires_property",
+    "requires_predicate",
+    "requires_rule",
+];
+function atom(value) {
+    return stringValue(parsePrologValue(value ?? "")).replace(/^['"]|['"]$/g, "");
+}
+function quoted(text) {
+    return text ? ` ("${text}")` : "";
+}
+async function groundingFactsOf(prolog, id) {
+    const result = await prolog.query(`findall([Type,To,ClaimKey], (member(Type, [${LOGICAL_RELATIONSHIPS.join(",")}]), kb_relationship(Type, '${escapeAtom(id)}', To), ((kb_entity(To, fact, _DriftProps), memberchk(claim_key=_DriftRaw, _DriftProps), normalize_term_atom(_DriftRaw, ClaimKey)) -> true ; ClaimKey = '')), Rows)`);
+    if (!result.success)
+        return [];
+    return parseListOfLists(result.bindings.Rows ?? "[]").map(([type, target, claimKey]) => ({
+        type: atom(type),
+        target: atom(target),
+        claimKey: atom(claimKey),
+    }));
+}
+/**
+ * Why `kb_model mode: analyze` with the `id` of a stored requirement compares
+ * its ledger with the stored one: a claim_key is derived from the clause
+ * text, so analyzing reworded prose, or the title instead of the stored
+ * `semantic_text`, yields keys that none of the requirement's grounding
+ * facts declare. The write that follows such a receipt is refused by the
+ * proposition-complete check, long after the agent picked the wording. The
+ * receipt therefore warns at analysis time, naming the stored modeled
+ * clauses the analysis no longer states, the facts that ground them, and the
+ * clauses the analysis adds, so the agent can keep the stored wording or
+ * re-ground the facts before writing.
+ *
+ * Returns null when the requirement is not stored, carries no recorded
+ * ledger, or every stored modeled clause is still among the analyzed ones.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+export async function storedLedgerDriftWarning(prolog, id, text, receipt) {
+    const [stored] = await loadEntities(prolog, { id, type: "req" });
+    if (!stored ||
+        stored.semantic_inventory_version !== SEMANTIC_INVENTORY_VERSION ||
+        !Array.isArray(stored.semantic_inventory))
+        return null;
+    const storedInventory = stored.semantic_inventory.filter(isRecord);
+    const storedKeys = new Set(storedInventory.map((entry) => stringValue(entry.claim_key)));
+    const analyzedKeys = new Set(receipt.propositions.map(({ claim_key }) => claim_key));
+    const drifted = storedInventory
+        .filter((entry) => stringValue(entry.status) === "modeled" &&
+        !analyzedKeys.has(stringValue(entry.claim_key)))
+        .map((entry) => ({
+        claimKey: stringValue(entry.claim_key),
+        claimText: stringValue(entry.claim_text),
+    }));
+    if (drifted.length === 0)
+        return null;
+    const facts = await groundingFactsOf(prolog, id);
+    const groundedBy = (claimKey) => {
+        const matches = facts.filter((fact) => fact.claimKey === claimKey);
+        return matches.length > 0
+            ? `, grounded by ${matches.map((fact) => `${fact.target} via ${fact.type}`).join(" and ")}`
+            : "";
+    };
+    const missing = drifted
+        .map(({ claimKey, claimText }) => `'${claimKey}'${quoted(claimText)}${groundedBy(claimKey)}`)
+        .join("; ");
+    const added = receipt.propositions
+        .filter(({ claim_key }) => !storedKeys.has(claim_key))
+        .map(({ claim_key, claim_text }) => `'${claim_key}'${quoted(claim_text)}`)
+        .join("; ");
+    const storedText = stringValue(stored.semantic_text);
+    const cause = storedText && storedText !== text
+        ? `The analyzed prose differs from the stored semantic_text of ${id}.`
+        : "The stored clause keys were derived from different prose.";
+    return `Claim-key drift against the stored ledger of ${id}: stored modeled clause(s) not stated by this analysis: ${missing}.${added ? ` Clause(s) this analysis adds without a stored grounding: ${added}.` : ""} ${cause} A kb_upsert of ${id} with this ledger fails the proposition-complete claim_key check unless each affected grounding fact is first re-written with the new claim_key and claim_text (same fact id). Keep the stored semantic_text wording to keep the keys, or supersede the requirement for a change of meaning.`;
+}

package/dist/public/impact/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/public/impact/diagnostics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAYrF,OAAO,KAAK,EACV,iBAAiB,EACjB,gCAAgC,EAChC,mCAAmC,EACpC,MAAM,YAAY,CAAC;AA6FpB,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,oBAAoB,EAAE,CA+CxB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,EAAE,CAsBxB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAET;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAIT"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/public/impact/diagnostics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAarF,OAAO,KAAK,EACV,iBAAiB,EACjB,gCAAgC,EAChC,mCAAmC,EACpC,MAAM,YAAY,CAAC;AAoFpB,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,oBAAoB,EAAE,CAmExB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,EAAE,CAsBxB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAET;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAIT"}

package/dist/public/impact/diagnostics.js

@@ -1,14 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 import { extractSymbolsFromStagedFile, } from "../../traceability/symbol-extract.js";
-import { ALLOWED_GRANULARITY_REASONS_PROSE, getBehavioralSymbolNames, getNonBehavioralSymbolNames, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../symbol-granularity.js";
-function isNarrowerSymbol(manifestSymbolName, candidate, sourceSymbols) {
-    if (candidate.name === manifestSymbolName)
-        return false;
-    if (candidate.name.startsWith(`${manifestSymbolName}.`))
-        return true;
-    return !sourceSymbols.some((symbol) => symbol.name === manifestSymbolName);
-}
+import { ALLOWED_GRANULARITY_REASONS_PROSE, getBehavioralSymbolNames, getNonBehavioralSymbolNames, isAllowedGranularityReason, isTraceabilityRelationshipType, narrowerSymbols, } from "../symbol-granularity.js";
 function hasTraceabilityRelationship(result) {
     return result.relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type));
 }
@@ -62,6 +55,7 @@ function isChangedBehavioralReviewCandidate(symbol) {
         return false;
     return symbol.hunkRanges.length > 0;
 }
+// implements REQ-cli-staged-impact-enforcement, REQ-cli-check
 export function createSymbolGranularityDiagnostics(options) {
     const diagnostics = [];
     for (const result of options.manifestResults) {
@@ -76,25 +70,41 @@ export function createSymbolGranularityDiagnostics(options) {
         if (hasValidGranularityReason(result))
             continue;
         const { candidateSymbols, sourceSymbols } = getGranularSymbolsForSourceFile(result.sourceFile, options);
-        const narrowerSymbols = candidateSymbols.filter((symbol) => isNarrowerSymbol(result.entity.title, symbol, sourceSymbols));
-        if (narrowerSymbols.length === 0)
+        const narrower = narrowerSymbols(result.entity.title, candidateSymbols, sourceSymbols);
+        if (narrower.length === 0)
             continue;
-        const behavioralNames = getBehavioralSymbolNames(narrowerSymbols);
+        const behavioralNames = getBehavioralSymbolNames(narrower);
         if (behavioralNames.length === 0)
             continue;
-        const nonBehavioralNames = getNonBehavioralSymbolNames(narrowerSymbols);
+        const nonBehavioralNames = getNonBehavioralSymbolNames(narrower);
         const ignoredSymbolsSuggestion = nonBehavioralNames.length > 0
             ? ` Non-behavioral symbols ignored for this decision: ${nonBehavioralNames.join(", ")}.`
             : "";
+        // A title the extractor does not produce (a private class member, a
+        // renamed or removed declaration) can never become granular by refresh:
+        // say so instead of only calling the link coarse.
+        const titleExtracted = sourceSymbols.some((symbol) => symbol.name === result.entity.title);
         diagnostics.push({
             id: "symbol_granularity_violation",
             severity: "error",
             blocking: true,
             category: "symbol",
+            entityId: result.entity.id,
+            ...(result.entity.source ? { source: result.entity.source } : {}),
             files: [result.entity.source, result.sourceFile],
             docs: ["docs/symbol-traceability-taxonomy.md"],
-            message: `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`,
-            suggestion: `Move ownership/coverage/test relationships to the narrow behavioral symbol, add a manifest behavioral anchor, or add granularity_reason with ${ALLOWED_GRANULARITY_REASONS_PROSE} when the coarse symbol is intentional.${ignoredSymbolsSuggestion}`,
+            message: titleExtracted
+                ? `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`
+                : `Symbol ${result.entity.id} names '${result.entity.title}', which the source extractor does not produce for ${result.sourceFile} (private class members and removed or renamed declarations are not tracked), so it links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`,
+            suggestion: titleExtracted
+                ? `Move ownership/coverage/test relationships to the narrow behavioral symbol, add a manifest behavioral anchor, or add granularity_reason with ${ALLOWED_GRANULARITY_REASONS_PROSE} when the coarse symbol is intentional.${ignoredSymbolsSuggestion}`
+                : `Re-point this symbol's relationships to the public declaration that owns the behavior (one of: ${behavioralNames.join(", ")}) or remove the symbol; add granularity_reason with ${ALLOWED_GRANULARITY_REASONS_PROSE} only when coarse ownership is intentional.${ignoredSymbolsSuggestion}`,
+            evidence: {
+                sourceFile: result.sourceFile,
+                title: result.entity.title,
+                titleExtracted,
+                granularSymbols: behavioralNames,
+            },
         });
     }
     return diagnostics;