kibi-cli 2.5.2 → 2.6.1

package/dist/operations/mutation/context-warning.js

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { contextFinding } from "../../entity-body-context.js";
+import { requirementSemanticText } from "../../extractors/markdown.js";
+import { readAuthoredEntity } from "../../public/operations/entity-context.js";
+import { readKbManifest } from "../../utils/kb-manifest.js";
+function readBody(workspaceRoot, source) {
+    if (typeof source !== "string" || !source.endsWith(".md"))
+        return undefined;
+    try {
+        return (readAuthoredEntity(readFileSync(path.resolve(workspaceRoot, source), "utf8"), source)?.body ?? undefined);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The body the authored document has, or will have, after this upsert: the
+ * written file when there is one, the supplied body, the preserved body of
+ * the entity's existing document, or the default a new requirement gets.
+ */
+// implements REQ-kb-entity-body-context
+export function upsertDocumentBody(input, entity, workspaceRoot, writtenPath) {
+    if (writtenPath !== undefined) {
+        const written = readBody(workspaceRoot, writtenPath);
+        if (written !== undefined)
+            return written;
+    }
+    if (input.document?.body !== undefined)
+        return input.document.body;
+    const existing = readBody(workspaceRoot, input.document?.path ?? entity.source);
+    if (existing !== undefined)
+        return existing;
+    return input.type === "req" ? `${String(entity.semantic_text ?? "")}\n` : "";
+}
+/**
+ * kb_upsert warning for a written entity whose body lacks context. The same
+ * finding blocks `kb_check` as entity-context-missing, so agents see it first.
+ */
+// implements REQ-kb-entity-body-context
+export function entityContextWarnings(input, entity, workspaceRoot, writtenPath) {
+    const body = upsertDocumentBody(input, entity, workspaceRoot, writtenPath);
+    const semanticText = typeof entity.semantic_text === "string" && entity.semantic_text.trim()
+        ? entity.semantic_text
+        : input.type === "req"
+            ? requirementSemanticText(body)
+            : undefined;
+    const acknowledged = (readKbManifest(workspaceRoot)?.contextAcknowledged ?? []).includes(input.id);
+    const finding = contextFinding(input.type, input.id, body, {
+        title: entity.title,
+        semantic_text: semanticText,
+        fact_kind: entity.fact_kind,
+    }, acknowledged);
+    return finding === null
+        ? []
+        : [
+            `${finding.description}. kb_check blocks it under entity-context-missing. ${finding.suggestion}`,
+        ];
+}

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

@@ -1,4 +1,5 @@
 import type { PrologPort } from "../../public/operations/runtime-types.js";
+import { type StoredEntityLookup } from "./stored-entity.js";
 import type { StagedUpsertState, UpsertInput } from "./types.js";
 /**
  * Resolve the provenance an upsert writes. kb_upsert never overwrites who
@@ -17,5 +18,5 @@ import type { StagedUpsertState, UpsertInput } from "./types.js";
  * Without a Prolog runtime the existing entity cannot be read, so only rule 1
  * applies.
  */
-export declare function resolveUpsertOrigin(input: UpsertInput, prolog: Pick<PrologPort, "query"> | undefined, now: Date, staged?: StagedUpsertState): Promise<UpsertInput>;
+export declare function resolveUpsertOrigin(input: UpsertInput, prolog: Pick<PrologPort, "query"> | undefined, now: Date, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<UpsertInput>;
 //# sourceMappingURL=origin.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/origin.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAUjE;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAiCtB"}
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/origin.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAUjE;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAwBtB"}

package/dist/operations/mutation/origin.js

@@ -15,9 +15,8 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { escapeAtom } from "../../prolog/codec.js";
 import { readEntityOrigin } from "../../public/entity-origin.js";
-import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { storedEntityLookup, } from "./stored-entity.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -42,7 +41,7 @@ function withOrigin(input, origin) {
  * applies.
  */
 // implements REQ-kibi-entity-origin
-export async function resolveUpsertOrigin(input, prolog, now, staged) {
+export async function resolveUpsertOrigin(input, prolog, now, staged, lookup) {
     const supplied = input.properties.origin;
     if (supplied !== undefined) {
         return isRecord(supplied) && supplied.recorded_at === undefined
@@ -57,22 +56,12 @@ export async function resolveUpsertOrigin(input, prolog, now, staged) {
         const stored = readEntityOrigin(planned.origin);
         return stored === null ? input : withOrigin(input, stored);
     }
-    // The same existence probe the rest of the upsert uses.
-    const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
-    if (!exists.success) {
+    const existing = await (lookup ?? storedEntityLookup(prolog, input.id, input.type)).entity();
+    if (existing === undefined) {
         return withOrigin(input, { kind: "agent", recorded_at: now.toISOString() });
     }
-    let stored = null;
-    try {
-        const [existing] = await loadEntities(prolog, {
-            id: input.id,
-            type: input.type,
-        });
-        stored = readEntityOrigin(existing?.origin);
-    }
-    catch {
-        // Unreadable: leave origin out. The source-first write merges the
-        // authored frontmatter, so a stored origin there survives either way.
-    }
+    // Unreadable (null): leave origin out. The source-first write merges the
+    // authored frontmatter, so a stored origin there survives either way.
+    const stored = readEntityOrigin(existing?.origin);
     return stored === null ? input : withOrigin(input, stored);
 }

package/dist/operations/mutation/requirement-semantics.d.ts

@@ -0,0 +1,16 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import { type StoredEntityLookup } from "./stored-entity.js";
+import type { StagedUpsertState, UpsertInput } from "./types.js";
+/**
+ * kb_upsert on an existing requirement that changes neither its prose nor its
+ * proposition ledger keeps the stored ledger. A payload that adds a
+ * relationship (for example `specified_by`) and carries no `semantic_*` or
+ * `logic_claims` field, and no `title` or `text_ref` that differs from the
+ * stored value, is merged over the stored semantic contract (and the stored
+ * `text_ref` it omits) before validation. The
+ * proposition-complete check then runs against the merged requirement, which
+ * is also what the write records. A payload that supplies any ledger field or
+ * changes the prose is validated exactly as given.
+ */
+export declare function withStoredRequirementSemantics(input: UpsertInput, prolog: Pick<PrologPort, "query">, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<UpsertInput>;
+//# sourceMappingURL=requirement-semantics.d.ts.map

package/dist/operations/mutation/requirement-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-semantics.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/requirement-semantics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwCjE;;;;;;;;;;GAUG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,GAAE,kBAAqE,GAC5E,OAAO,CAAC,WAAW,CAAC,CA6BtB"}

package/dist/operations/mutation/requirement-semantics.js

@@ -0,0 +1,64 @@
+import { storedEntityLookup, } from "./stored-entity.js";
+/** The fields that make up a requirement's proposition ledger. */
+const SEMANTIC_CONTRACT_FIELDS = [
+    "semantic_text",
+    "semantic_clauses",
+    "semantic_inventory",
+    "semantic_inventory_version",
+    "semantic_source_field",
+    "semantic_source_hash",
+    "logic_claims",
+];
+/** Prose a requirement's semantic source can be read from besides semantic_text. */
+const PROSE_FIELDS = ["title", "text_ref"];
+/** Stored prose a relationship-only update may leave out. */
+const PRESERVED_PROSE_FIELDS = ["text_ref"];
+function suppliesSemanticContract(properties) {
+    return Object.keys(properties).some((key) => key.startsWith("semantic_") || key === "logic_claims");
+}
+async function storedRequirement(id, lookup, staged) {
+    // An earlier step of the same plan that writes this entity is its history.
+    const planned = staged?.entities.get(id);
+    if (planned !== undefined)
+        return planned.type === "req" ? planned : undefined;
+    return (await lookup.entity()) ?? undefined;
+}
+// implements REQ-kibi-upsert-preserves-requirement-semantics
+/**
+ * kb_upsert on an existing requirement that changes neither its prose nor its
+ * proposition ledger keeps the stored ledger. A payload that adds a
+ * relationship (for example `specified_by`) and carries no `semantic_*` or
+ * `logic_claims` field, and no `title` or `text_ref` that differs from the
+ * stored value, is merged over the stored semantic contract (and the stored
+ * `text_ref` it omits) before validation. The
+ * proposition-complete check then runs against the merged requirement, which
+ * is also what the write records. A payload that supplies any ledger field or
+ * changes the prose is validated exactly as given.
+ */
+export async function withStoredRequirementSemantics(input, prolog, staged, lookup = storedEntityLookup(prolog, input.id, input.type)) {
+    if (input.type !== "req")
+        return input;
+    const properties = input.properties ?? {};
+    if (suppliesSemanticContract(properties))
+        return input;
+    const stored = await storedRequirement(input.id, lookup, staged);
+    if (stored === undefined)
+        return input;
+    if (PROSE_FIELDS.some((field) => properties[field] !== undefined && properties[field] !== stored[field]))
+        return input;
+    const preserved = {};
+    for (const field of [
+        ...SEMANTIC_CONTRACT_FIELDS,
+        ...PRESERVED_PROSE_FIELDS,
+    ]) {
+        if (stored[field] !== undefined)
+            preserved[field] = stored[field];
+    }
+    // Only a recorded ledger is kept. A stored `semantic_text` alone (derived
+    // from the body at sync) is not one, and merging it would turn a payload
+    // that is valid as sent into one the ingestion boundary rejects.
+    if (stored.semantic_inventory_version === undefined ||
+        !Array.isArray(stored.semantic_inventory))
+        return input;
+    return { ...input, properties: { ...preserved, ...properties } };
+}

package/dist/operations/mutation/source-authoring.d.ts.map

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

package/dist/operations/mutation/source-authoring.js

@@ -6,6 +6,7 @@ import { isDeepStrictEqual } from "node:util";
 import { dump as dumpYaml, load as loadYaml } from "js-yaml";
 import { parseDocument, stringify } from "yaml";
 import { OperationError } from "../../cli-errors.js";
+import { requirementSemanticText } from "../../extractors/markdown.js";
 import { canonicalFilesystemPath } from "../../utils/canonical-path.js";
 import { CANONICAL_ENTITY_PATHS, isDerivedKbPath, } from "../../utils/kb-paths.js";
 function digest(value) {
@@ -192,6 +193,15 @@ function renderEntityDocument(input, entity, existingContent) {
     frontmatter.id = entity.id;
     frontmatter.title ??= entity.id;
     frontmatter.type = entity.type;
+    // The checked meaning is always stated, never derived from a body that now
+    // also carries context sections.
+    if (entity.type === "req" &&
+        (typeof frontmatter.semantic_text !== "string" ||
+            frontmatter.semantic_text.trim() === "")) {
+        const derived = requirementSemanticText(body);
+        if (derived !== "")
+            frontmatter.semantic_text = derived;
+    }
     return `---\n${dumpYaml(frontmatter, { noRefs: true, lineWidth: -1, sortKeys: false })}---${body.startsWith("\n") ? "" : "\n"}${body}`;
 }
 /** Generated coordinate fields belong exclusively to `.kb/symbol-coordinates.yaml`. */

package/dist/operations/mutation/stored-entity.d.ts

@@ -0,0 +1,20 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+/**
+ * The stored entity an upsert replaces: `undefined` when no entity has the
+ * id, `null` when one exists but cannot be read.
+ */
+export type StoredEntity = Readonly<Record<string, unknown>> | null | undefined;
+export type StoredEntityLookup = {
+    /** Whether an entity with the id is stored. */
+    readonly exists: () => Promise<boolean>;
+    /** The stored entity, loaded only when one exists. */
+    readonly entity: () => Promise<StoredEntity>;
+};
+/**
+ * One read of the entity an upsert replaces, shared by every step of the
+ * upsert that needs it (the requirement ledger merge, the stored
+ * relationships and the stored origin), so the store is probed and loaded at
+ * most once per upsert.
+ */
+export declare function storedEntityLookup(prolog: Pick<PrologPort, "query">, id: string, type: string): StoredEntityLookup;
+//# sourceMappingURL=stored-entity.d.ts.map

package/dist/operations/mutation/stored-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-entity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/stored-entity.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAEhF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9C,CAAC;AAGF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,kBAAkB,CAsBpB"}

package/dist/operations/mutation/stored-entity.js

@@ -0,0 +1,51 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { escapeAtom } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+// implements REQ-kibi-upsert-preserves-requirement-semantics, REQ-kibi-entity-origin
+/**
+ * One read of the entity an upsert replaces, shared by every step of the
+ * upsert that needs it (the requirement ledger merge, the stored
+ * relationships and the stored origin), so the store is probed and loaded at
+ * most once per upsert.
+ */
+export function storedEntityLookup(prolog, id, type) {
+    let probe;
+    let read;
+    const exists = () => {
+        probe ??= prolog
+            .query(`once(kb_entity('${escapeAtom(id)}', _, _))`)
+            .then((result) => result.success);
+        return probe;
+    };
+    const entity = () => {
+        read ??= (async () => {
+            if (!(await exists()))
+                return undefined;
+            try {
+                const [existing] = await loadEntities(prolog, { id, type });
+                return existing ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        return read;
+    };
+    return { exists, entity };
+}

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

@@ -1,10 +1,11 @@
 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 StoredEntityLookup } from "./stored-entity.js";
 import type { RelationshipInput, StagedUpsertState, UpsertInput, UpsertPayload, ValidatedUpsert } from "./types.js";
 export declare function assertRelationshipShardContained(workspaceRoot: string, shardPath: string): void;
 export declare function validateAppendOnlyProofReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext, staged?: StagedUpsertState): Promise<void>;
-export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext, staged?: StagedUpsertState): Promise<readonly RelationshipInput[]>;
+export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<readonly RelationshipInput[]>;
 export type UpsertValidationOptions = Readonly<{
     /** Skip the append-only receipt check (kibi proof prune only). */
     readonly allowReceiptsPrune?: boolean;
@@ -29,7 +30,7 @@ export type UpsertValidation = Readonly<{
  * kb_apply_plan runs it for every plan step before the plan's first write,
  * passing the earlier steps' writes as `staged`.
  */
-export declare function validateUpsertForCommit(input: UpsertInput, context: OperationContext, options?: UpsertValidationOptions): Promise<UpsertValidation>;
+export declare function validateUpsertForCommit(payload: UpsertInput, context: OperationContext, options?: UpsertValidationOptions): Promise<UpsertValidation>;
 export type UpsertExecutionOptions = Readonly<{
     /**
      * Internal escape hatch for proof-receipt ingest: when provided, the

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

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAiCnF,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAmCD,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,GACzB,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,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAkE3B;AAGD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAggBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA4BnF,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAmCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAgF3B;AAGD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAsgBzC"}

package/dist/operations/mutation/upsert.js

@@ -4,7 +4,6 @@ import path from "node:path";
 import { OperationError } from "../../cli-errors.js";
 import { readManifestWithCoordinateOverlay } from "../../extractors/manifest.js";
 import { extractManifestSymbolRecords } from "../../extractors/manifest.js";
-import { escapeAtom } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
 import { appendRelationship, computeShardPath, } from "../../relationships/shards.js";
@@ -13,13 +12,16 @@ import { canonicalFilesystemPath } from "../../utils/canonical-path.js";
 import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
+import { entityContextWarnings } from "./context-warning.js";
 import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
 import { resolveUpsertOrigin } from "./origin.js";
 import { planRecoveryNotes, settlePendingPlanApplyJournals, withPlanRecoveryNotes, } from "./plan-apply-journal.js";
 import { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.js";
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
+import { withStoredRequirementSemantics } from "./requirement-semantics.js";
 import { MutationRollbackFailureError, MutationSaga } from "./saga.js";
 import { writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
+import { storedEntityLookup, } from "./stored-entity.js";
 import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "./symbol-compiler-lock.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { refreshSymbolCoordinatesForManifest } from "./symbol-refresh.js";
@@ -118,16 +120,16 @@ export async function validateAppendOnlyProofReceipts(entity, context, staged) {
         throw new Error(`Entity validation failed: ${errors.join("; ")}`);
     }
 }
-export async function effectiveRelationships(input, entity, relationships, context, staged) {
+export async function effectiveRelationships(input, entity, relationships, context, staged, lookup) {
     const prolog = requireProlog(context);
     // Relationships an earlier plan step adds from this entity will exist when
     // this upsert runs.
     const plannedOwn = (staged?.relationships ?? []).filter((relationship) => relationship.from === input.id);
-    const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
-    if (!exists.success && plannedOwn.length === 0)
+    const exists = await (lookup ?? storedEntityLookup(prolog, input.id, input.type)).exists();
+    if (!exists && plannedOwn.length === 0)
         return relationships;
     try {
-        const current = exists.success
+        const current = exists
             ? (await existingRelationships(prolog, String(entity.id)))
                 // An upsert owns only relationships whose source is the upserted
                 // entity. Incoming relationships must not be copied into its
@@ -186,16 +188,22 @@ function reextractCanonicalSymbolEntity(symbolId, authoredRelativePath, workspac
  * kb_apply_plan runs it for every plan step before the plan's first write,
  * passing the earlier steps' writes as `staged`.
  */
-export async function validateUpsertForCommit(input, context, options = {}) {
+export async function validateUpsertForCommit(payload, context, options = {}) {
     const prolog = requireProlog(context);
     const staged = options.staged;
-    const validated = validateUpsertInput(input, context.clock());
+    // The payload must be valid on its own before the store is read.
+    const checked = validateUpsertInput(payload, context.clock());
+    validateRelationshipSources(payload.id, checked.relationships);
+    // One read of the entity this upsert replaces, shared by the ledger merge
+    // and the stored origin below.
+    const lookup = storedEntityLookup(prolog, payload.id, payload.type);
+    const input = await withStoredRequirementSemantics(payload, prolog, staged, lookup);
+    const validated = input === payload ? checked : validateUpsertInput(input, context.clock());
     if (options.allowReceiptsPrune !== true) {
         await validateAppendOnlyProofReceipts(validated.entity, context, staged);
     }
-    validateRelationshipSources(input.id, validated.relationships);
     await validateSymbolGranularity(validated.entity, validated.relationships, context);
-    const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context, staged);
+    const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context, staged, lookup);
     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);
@@ -207,7 +215,7 @@ export async function validateUpsertForCommit(input, context, options = {}) {
     await assertPredicateArgumentVocabulary(prolog, validated.entity, staged);
     // The origin the write records is added last: none of the checks above
     // reads it, and a rejected payload never pays for the stored-origin read.
-    const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged);
+    const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged, lookup);
     return {
         validated: recorded === input
             ? validated
@@ -516,6 +524,7 @@ export async function executeUpsert(input, context, options = {}) {
                 ...semantic.warnings,
                 ...coverage,
                 ...idStyleWarnings,
+                ...entityContextWarnings(input, commitEntity ?? validated.entity, context.workspaceRoot, sourceWrite?.receipt.path),
                 ...shardWarnings,
             ],
             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":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+CrE;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAwDjD"}
+{"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;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+CrE;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CA4DjD"}

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

@@ -3,6 +3,7 @@ import { escapeAtom } from "../../prolog/codec.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 { validateRelationshipSources } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
@@ -57,7 +58,11 @@ export async function executeValidateUpsert(input, context) {
         const payload = {
             valid: true,
             errors: [],
-            warnings: [...semantic.warnings, ...idStyleWarnings],
+            warnings: [
+                ...semantic.warnings,
+                ...idStyleWarnings,
+                ...entityContextWarnings(input, entity, context.workspaceRoot),
+            ],
             semanticAdvisor: semantic.receipt,
             normalizedPreview: entity,
         };

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

@@ -14,6 +14,15 @@ export type CompileIntentArgs = Readonly<{
     scenarioDrafts?: readonly ScenarioDraft[];
     testDrafts?: readonly TestDraft[];
     proposalDecisions?: readonly ProposalDecision[];
+    /**
+     * Why the requirement exists, who asked and what does not fit its checked
+     * meaning. Required when mode is create; rendered as `## Context`.
+     */
+    context?: string;
+    /** Verbatim text the intent came from; rendered as a blockquote in `## Source`. */
+    sourceExcerpt?: string;
+    /** Locator of that text (ticket, URL, path); rendered in `## Source`. */
+    sourceReference?: string;
 }>;
 export type ScenarioDraft = Readonly<{
     id?: string;

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

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

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

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
 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";
@@ -48,6 +50,13 @@ function requiredIntent(args) {
         !text(args.requirementId)) {
         throw new Error("Compile intent failed: requirementId must be non-empty when supplied");
     }
+    if (args.mode === "create" && !text(args.context)) {
+        throw new Error("Compile intent failed: context must be non-empty when mode is create; state why the requirement exists, who asked and the source, or write 'Reason not stated' when the requester gave no reason");
+    }
+    if (!text(args.context) &&
+        (text(args.sourceExcerpt) !== "" || text(args.sourceReference) !== "")) {
+        throw new Error("Compile intent failed: sourceExcerpt and sourceReference need context; supply context or drop them");
+    }
     return intent;
 }
 function validateLocation(location) {
@@ -251,7 +260,9 @@ async function withDocumentTargets(context, prolog, steps, requirement, now) {
         const stepDocument = isRecord(step.document) ? step.document : {};
         const document = type === "req" && id === requirement.id
             ? {
-                body: requirement.body,
+                ...(requirement.body !== undefined
+                    ? { body: requirement.body }
+                    : {}),
                 ...(requirement.path !== undefined
                     ? { path: requirement.path }
                     : {}),
@@ -283,6 +294,18 @@ async function withDocumentTargets(context, prolog, steps, requirement, now) {
     }
     return targeted;
 }
+/** Body of the requirement's existing authored document, when readable. */
+async function existingRequirementBody(context, source) {
+    if (!context.fs || !source.endsWith(".md"))
+        return undefined;
+    try {
+        const raw = await context.fs.readFile(path.join(context.workspaceRoot, source));
+        return readAuthoredEntity(String(raw), source)?.body ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function generatedRequirementId(intent) {
     return `REQ-${slug(intent)}-${shortHash(intent).toUpperCase()}`;
 }
@@ -841,11 +864,35 @@ export async function executeCompileIntent(args, context) {
     // A step whose entity or document cannot be rendered would fail the apply,
     // so it makes the plan need resolution instead of reporting it ready.
     let planSteps = stepsWithAcceptedProposals;
+    // A create always carries context. An update replaces the non-context part
+    // of the existing body with the new intent and keeps its context sections
+    // byte for byte; supplied context or source replaces those sections too.
+    const sourceInput = {
+        excerpt: args.sourceExcerpt,
+        reference: args.sourceReference,
+    };
+    const existingBody = args.mode === "update"
+        ? await existingRequirementBody(context, requirementDocument ?? text(existingEntity.source))
+        : undefined;
+    const requirementBody = existingBody !== undefined
+        ? reviseRequirementBody({
+            existingBody,
+            statement: intent,
+            context: args.context,
+            source: sourceInput,
+        })
+        : text(args.context) !== ""
+            ? renderRequirementBody({
+                statement: intent,
+                context: args.context,
+                source: sourceInput,
+            })
+            : undefined;
     if (statusValue === "ready") {
         try {
             planSteps = await withDocumentTargets(context, prolog, stepsWithAcceptedProposals, {
                 id: requirementId,
-                body: `${intent.trim()}\n`,
+                ...(requirementBody !== undefined ? { body: requirementBody } : {}),
                 ...(requirementDocument !== undefined
                     ? { path: requirementDocument }
                     : {}),