kibi-cli 2.10.0 → 2.12.0

package/dist/operations/bootstrap/requirement-claims.js

@@ -1,4 +1,5 @@
-import { isConventionalSubjectKey, normalizeSubjectKey, } from "../../utils/strict-modeling.js";
+import { createHash } from "node:crypto";
+import { isConventionalSubjectKey, normalizeSourceKey, normalizeSubjectKey, } from "../../utils/strict-modeling.js";
 // implements REQ-KIBI-BOOTSTRAP-PLAN
 export function normalizeClaimStatement(statement) {
     return statement
@@ -67,16 +68,164 @@ function snakeSegment(value) {
         .replace(/[^a-z0-9]+/g, "_")
         .replace(/^_+|_+$/g, "");
 }
+/** The longest aspect a bootstrap key keeps as derived. */
+export const MAX_ASPECT_WORDS = 4;
+export const MAX_ASPECT_CHARS = 40;
+/** Words that start a dependent clause or a second item: the aspect ends before them. */
+const ASPECT_BOUNDARY_WORDS = new Set([
+    "when",
+    "whenever",
+    "while",
+    "if",
+    "unless",
+    "without",
+    "after",
+    "before",
+    "until",
+    "because",
+    "once",
+    "as",
+    "by",
+    "via",
+    "during",
+    "except",
+    "so",
+    "that",
+    "which",
+    "who",
+    "where",
+    "since",
+    "for",
+    "and",
+    "or",
+]);
+/** Words that carry no meaning in a key on their own. */
+const ASPECT_STOP_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "be",
+    "is",
+    "are",
+    "was",
+    "were",
+    "been",
+    "being",
+    "to",
+    "of",
+    "in",
+    "on",
+    "at",
+    "with",
+    "from",
+    "into",
+    "its",
+    "it",
+    "their",
+    "they",
+    "them",
+    "this",
+    "these",
+    "those",
+    "can",
+    "could",
+    "will",
+    "would",
+    "may",
+    "might",
+    "must",
+    "shall",
+    "should",
+    "do",
+    "does",
+    "has",
+    "have",
+    "had",
+    "any",
+    "all",
+    "each",
+    "every",
+    "some",
+    "only",
+    "also",
+    "then",
+    "than",
+    "not",
+    "no",
+]);
+function fitsAspect(words) {
+    return (words.length > 0 &&
+        words.length <= MAX_ASPECT_WORDS &&
+        words.join("_").length <= MAX_ASPECT_CHARS);
+}
+function trimStopWords(words) {
+    let start = 0;
+    let end = words.length;
+    while (start < end && ASPECT_STOP_WORDS.has(words[start] ?? ""))
+        start += 1;
+    while (end > start && ASPECT_STOP_WORDS.has(words[end - 1] ?? ""))
+        end -= 1;
+    return words.slice(start, end);
+}
+/**
+ * A short noun-phrase aspect for a long one, deterministically: the words
+ * before the first clause boundary (when, while, for, and, ...), without
+ * leading or trailing stop words; if that is still longer than four words or
+ * forty characters, its content words (no stop words or -ly adverbs); if
+ * those are still too long, the first content word and the last two, where a
+ * noun phrase keeps its head noun. An aspect that already fits is returned
+ * unchanged.
+ */
+// implements REQ-bootstrap-claim-name-length
+export function shortenSubjectAspect(aspect) {
+    const words = aspect.split("_").filter(Boolean);
+    if (fitsAspect(words))
+        return aspect;
+    const boundary = words.findIndex((word, index) => index > 0 &&
+        ASPECT_BOUNDARY_WORDS.has(word) &&
+        trimStopWords(words.slice(0, index)).length > 0);
+    const head = trimStopWords(boundary < 0 ? words : words.slice(0, boundary));
+    if (fitsAspect(head))
+        return head.join("_");
+    // Content words only: no stop words, no -ly adverbs.
+    const content = head.filter((word) => !ASPECT_STOP_WORDS.has(word) && !(word.length > 4 && word.endsWith("ly")));
+    if (fitsAspect(content))
+        return content.join("_");
+    // The leading word (the action or state) and the closing words, where an
+    // English noun phrase keeps its head noun.
+    const picked = Array.from(new Set([content[0], ...content.slice(-(MAX_ASPECT_WORDS - 2))])).filter((word) => typeof word === "string");
+    while (picked.length > 1 && picked.join("_").length > MAX_ASPECT_CHARS)
+        picked.splice(1, 1);
+    const short = picked.join("_");
+    return short.length > 0
+        ? short.slice(0, MAX_ASPECT_CHARS).replace(/_+$/, "")
+        : (words[0] ?? aspect).slice(0, MAX_ASPECT_CHARS);
+}
+function withShortAspect(component, aspect) {
+    const full = `${component}.${aspect}`;
+    const short = shortenSubjectAspect(aspect);
+    const candidate = `${component}.${short}`;
+    if (!isConventionalSubjectKey(candidate))
+        return {
+            ok: false,
+            reason: `subject key "${candidate}" does not follow component.aspect[.sub]`,
+        };
+    return short === aspect
+        ? { ok: true, subjectKey: candidate }
+        : { ok: true, subjectKey: candidate, shortenedFrom: full };
+}
 /**
  * The bootstrap subject key in the component.aspect[.sub] shape that
  * subject-key-shape checks. A subject that already has that shape is kept.
  * Otherwise the component comes from the declared `component` (claim or
  * knowledge source) and the aspect from the claim's subject; a one-word
  * subject is itself the component and the constrained property becomes the
- * aspect. When no component can be named the claim is not resolved, so the
- * caller reports it instead of writing a malformed key.
+ * aspect. An aspect longer than four words or forty characters is shortened
+ * to a noun phrase and the original key is returned in `shortenedFrom`. When
+ * no component can be named the claim is not resolved, so the caller reports
+ * it instead of writing a malformed key.
  */
-// implements REQ-bootstrap-subject-key-shape
+// implements REQ-bootstrap-subject-key-shape, REQ-bootstrap-claim-name-length
 export function resolveBootstrapSubjectKey(subject, propertyKey, component) {
     const stripped = subject.trim().replace(/^(?:the|a|an)\s+/i, "");
     let key;
@@ -91,28 +240,183 @@ export function resolveBootstrapSubjectKey(subject, propertyKey, component) {
     const flat = key.replace(/\./g, "_");
     const comp = component === undefined ? "" : snakeSegment(component);
     const property = snakeSegment(propertyKey);
-    let candidate;
     if (comp) {
         const aspect = flat === comp
             ? property
             : flat.startsWith(`${comp}_`)
                 ? flat.slice(comp.length + 1)
                 : flat;
-        candidate = `${comp}.${aspect}`;
-    }
-    else if (/^[a-z][a-z0-9]*$/.test(flat) && property) {
-        candidate = `${flat}.${property}`;
+        return withShortAspect(comp, aspect);
     }
-    else {
-        return {
-            ok: false,
-            reason: `subject key "${flat}" names no component, so it would violate component.aspect[.sub]`,
-        };
+    if (/^[a-z][a-z0-9]*$/.test(flat) && property)
+        return withShortAspect(flat, property);
+    return {
+        ok: false,
+        reason: `subject key "${flat}" names no component, so it would violate component.aspect[.sub]`,
+    };
+}
+/**
+ * Keeps the subject keys of one bootstrap plan distinct. Claims about the
+ * same subject (the same full key) share a key; when shortening collapses two
+ * different subjects onto one key, the later one gets a third segment from
+ * its own wording (or a short digest) instead of colliding.
+ */
+// implements REQ-bootstrap-claim-name-length
+export class SubjectKeyRegistry {
+    owners = new Map();
+    assigned = new Map();
+    /** The plan-wide key for a resolution, and the key it collided with, if any. */
+    assign(resolution) {
+        const identity = resolution.shortenedFrom ?? resolution.subjectKey;
+        const known = this.assigned.get(identity);
+        if (known !== undefined)
+            return { subjectKey: known };
+        const owner = this.owners.get(resolution.subjectKey);
+        if (owner === undefined || owner === identity) {
+            this.owners.set(resolution.subjectKey, identity);
+            this.assigned.set(identity, resolution.subjectKey);
+            return { subjectKey: resolution.subjectKey };
+        }
+        const used = new Set(resolution.subjectKey.split(/[._]/));
+        const fullWords = identity.split(".").slice(1).join("_").split("_");
+        const qualifier = fullWords.find((word) => /^[a-z][a-z0-9]*$/.test(word) &&
+            !used.has(word) &&
+            !ASPECT_STOP_WORDS.has(word) &&
+            !ASPECT_BOUNDARY_WORDS.has(word) &&
+            !this.owners.has(`${resolution.subjectKey}.${word}`));
+        const subjectKey = `${resolution.subjectKey}.${qualifier ?? `k${digest(identity)}`}`;
+        this.owners.set(subjectKey, identity);
+        this.assigned.set(identity, subjectKey);
+        return { subjectKey, collidedWith: resolution.subjectKey };
     }
-    return isConventionalSubjectKey(candidate)
-        ? { ok: true, subjectKey: candidate }
-        : {
-            ok: false,
-            reason: `subject key "${candidate}" does not follow component.aspect[.sub]`,
-        };
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 6);
+}
+/**
+ * Resolve a claim's subject key for a plan and describe any renaming as a
+ * plan diagnostic, so the operator can pick a better name before applying.
+ */
+// implements REQ-bootstrap-claim-name-length
+export function planSubjectKey(subject, propertyKey, component, registry, location) {
+    const resolved = resolveBootstrapSubjectKey(subject, propertyKey, component);
+    if (!resolved.ok)
+        return { resolution: resolved, diagnostics: [] };
+    const diagnostics = [];
+    const assigned = registry?.assign(resolved) ?? {
+        subjectKey: resolved.subjectKey,
+    };
+    if (resolved.shortenedFrom)
+        diagnostics.push(`subject-key-shortened: claim at ${location} would have the subject key ${resolved.shortenedFrom}; its aspect is longer than ${MAX_ASPECT_WORDS} words or ${MAX_ASPECT_CHARS} characters, so the plan uses ${assigned.subjectKey}. Rename the subject after apply if another noun phrase fits better.`);
+    if (assigned.collidedWith)
+        diagnostics.push(`subject-key-disambiguated: claim at ${location} names a different subject than an earlier claim keyed ${assigned.collidedWith}, so the plan uses ${assigned.subjectKey} instead of reusing that key.`);
+    return {
+        resolution: {
+            ok: true,
+            subjectKey: assigned.subjectKey,
+            ...(resolved.shortenedFrom
+                ? { shortenedFrom: resolved.shortenedFrom }
+                : {}),
+        },
+        diagnostics,
+    };
+}
+function stepProperties(step) {
+    return step.properties !== null && typeof step.properties === "object"
+        ? step.properties
+        : {};
+}
+function subjectStepKey(step) {
+    const properties = stepProperties(step);
+    return step.type === "fact" &&
+        properties.fact_kind === "subject" &&
+        typeof properties.subject_key === "string" &&
+        typeof step.id === "string"
+        ? properties.subject_key
+        : null;
+}
+function retarget(relationships, renamed) {
+    return relationships.map((relationship) => {
+        const to = renamed.get(relationship.to);
+        return to === undefined ? relationship : { ...relationship, to };
+    });
+}
+function retargetStep(step, renamed) {
+    if (!Array.isArray(step.relationships))
+        return step;
+    const relationships = step.relationships;
+    return { ...step, relationships: retarget(relationships, renamed) };
+}
+/**
+ * One subject fact per subject_key in a bootstrap plan. The registry keeps
+ * different subjects on different keys, so claims that share a key name the
+ * same subject: the first selected claim's subject fact is kept, every later
+ * requirement links to it through constrains instead of minting another
+ * subject fact (which subject-key-identity would report), and the later
+ * sources' provenance is added to the kept fact's tags and body. Each shared
+ * key is reported as a subject-key-shared diagnostic. The result depends only
+ * on the candidate order, so the plan hash stays deterministic.
+ */
+// implements REQ-bootstrap-subject-fact-shared
+export function shareSubjectFacts(candidates) {
+    const owners = new Map();
+    const renamed = new Map();
+    candidates.forEach((candidate, candidateIndex) => {
+        for (const step of candidate.applyPlan) {
+            const key = subjectStepKey(step);
+            if (key === null)
+                continue;
+            const factId = String(step.id);
+            const source = String(stepProperties(step).text_ref ?? candidate.sourcePath);
+            const owner = owners.get(key);
+            if (owner === undefined) {
+                owners.set(key, { factId, candidateIndex, sources: [source] });
+                continue;
+            }
+            if (owner.factId === factId)
+                continue;
+            renamed.set(factId, owner.factId);
+            if (!owner.sources.includes(source))
+                owner.sources.push(source);
+        }
+    });
+    if (renamed.size === 0)
+        return { candidates: [...candidates], diagnostics: [] };
+    const shared = [...owners.entries()].filter(([, owner]) => owner.sources.length > 1);
+    const sharedFacts = new Map(shared.map(([key, owner]) => [owner.factId, { key, owner }]));
+    const result = candidates.map((candidate) => ({
+        ...candidate,
+        relationships: retarget(candidate.relationships, renamed),
+        applyPlan: candidate.applyPlan
+            .filter((step) => !renamed.has(String(step.id)))
+            .map((step) => {
+            const sharing = sharedFacts.get(String(step.id));
+            const retargeted = retargetStep(step, renamed);
+            if (sharing === undefined || subjectStepKey(step) === null)
+                return retargeted;
+            const properties = stepProperties(step);
+            const tags = Array.isArray(properties.tags)
+                ? properties.tags.map(String)
+                : [];
+            return {
+                ...retargeted,
+                properties: {
+                    ...properties,
+                    tags: [
+                        ...new Set([
+                            ...tags,
+                            ...sharing.owner.sources.map((source) => `provenance:${normalizeSourceKey(source)}`),
+                        ]),
+                    ],
+                },
+                document: {
+                    body: `Subject ${sharing.key}, shared by the requirements bootstrap planned from ${sharing.owner.sources.join(", ")}. Each of them links to this fact through constrains.\n`,
+                },
+            };
+        }),
+    }));
+    return {
+        candidates: result,
+        diagnostics: shared.map(([key, owner]) => `subject-key-shared: claims at ${owner.sources.join(", ")} name the same subject ${key}, so the plan writes one subject fact ${owner.factId} and links every requirement to it through constrains.`),
+    };
 }

package/dist/operations/modeling/predicate-applyplan.d.ts

@@ -5,9 +5,22 @@ export declare function buildSuggestion(schema: PredicateSchemaCandidate, text:
     applicabilityScore?: number;
     scoreComponents?: PredicateScoreComponents;
     explicitSubject?: boolean;
+    /**
+     * The subject_key of the subject fact the requirement constrains. It
+     * binds the schema's `subject` argument (provenance `requirement`) unless
+     * the caller bound that argument or passed subjectHint.
+     */
+    requirementSubject?: string;
 }): PredicateSuggestion;
 export declare function buildPredicateApplyPlan(suggestion: PredicateSuggestion, args: SuggestPredicatesArgs): Array<Record<string, unknown>>;
 export declare function buildRelationshipPlan(factId: string | undefined, requirementId: string | undefined, claimText?: string, existingLogicClaims?: readonly string[]): Record<string, unknown> | null;
+/**
+ * The ontology-gap observation plan. It is a review note, not a semantic
+ * claim: it quotes the claim in claim_text without a claim_key, carries the
+ * review tags in `tags` only (a tag is not an entity, so no relationship
+ * targets it) and explains itself in `document.body`, so kb_upsert accepts
+ * it unchanged.
+ */
 export declare function buildGapApplyPlan(text: string, args: SuggestPredicatesArgs): Array<Record<string, unknown>>;
 /**
  * Build a review-only schema draft when retrieval found no eligible schema.

package/dist/operations/modeling/predicate-applyplan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,mBAAmB,CA8FrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuBhC;AAGD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+BhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}
+{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,GACA,mBAAmB,CAsHrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuBhC;AAoBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwBhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}

package/dist/operations/modeling/predicate-applyplan.js

@@ -9,8 +9,17 @@ import { applyArgumentRewrites, predicateArgumentConformance, } from "./predicat
 export function buildSuggestion(schema, text, subject, score, argumentBindings = {}, polarityHint, diagnostics) {
     const inferredArgs = inferArgs(schema, text, subject);
     const canonicalLauncherArgs = exactLauncherPredicateArgs(schema.predicate_name, text);
+    const hasExactBinding = (name) => typeof argumentBindings[name] === "string" &&
+        argumentBindings[name].trim().length > 0;
+    const requirementSubjectArgument = diagnostics?.requirementSubject &&
+        diagnostics.explicitSubject !== true &&
+        !hasExactBinding("subject")
+        ? schema.argument_names.indexOf("subject")
+        : -1;
     const boundArgs = schema.argument_names.map((name, index) => {
         const exactBinding = argumentBindings[name];
+        if (index === requirementSubjectArgument)
+            return diagnostics?.requirementSubject ?? "unknown";
         return typeof exactBinding === "string" && exactBinding.trim().length > 0
             ? exactBinding.trim()
             : (inferredArgs[index] ?? "unknown");
@@ -27,13 +36,26 @@ export function buildSuggestion(schema, text, subject, score, argumentBindings =
     const undeclaredArguments = new Set(conformance.undeclared.map((value) => value.argumentName));
     const bindingProvenanceByArgument = Object.fromEntries(schema.argument_names.map((name, index) => [
         name,
-        classifyBinding(predicateArgs[index] ?? "unknown", text, (typeof argumentBindings[name] === "string" &&
-            argumentBindings[name].trim().length > 0) ||
-            (diagnostics?.explicitSubject === true && index === 0), canonicalLauncherArgs?.[index] === predicateArgs[index] &&
-            !(index === 0 &&
-                predicateArgs[index] === "launcher" &&
-                diagnostics?.explicitSubject !== true &&
-                typeof argumentBindings[name] !== "string")),
+        index === requirementSubjectArgument && !undeclaredArguments.has(name)
+            ? "requirement"
+            : classifyBinding(predicateArgs[index] ?? "unknown", text, (typeof argumentBindings[name] === "string" &&
+                argumentBindings[name].trim().length > 0) ||
+                (diagnostics?.explicitSubject === true && index === 0), canonicalLauncherArgs?.[index] === predicateArgs[index] &&
+                !(index === 0 &&
+                    predicateArgs[index] === "launcher" &&
+                    diagnostics?.explicitSubject !== true &&
+                    typeof argumentBindings[name] !== "string"), 
+            // A subject named through subjectHint is the agent's reviewed
+            // subject, even when the schema names its first argument after it.
+            index === 0 &&
+                diagnostics?.explicitSubject === true &&
+                typeof argumentBindings[name] !== "string"
+                ? { constants: schema.argument_constants?.[name] }
+                : {
+                    argumentName: name,
+                    argumentNames: schema.argument_names,
+                    constants: schema.argument_constants?.[name],
+                }),
     ]));
     const bindingProvenance = aggregateBindingProvenance(Object.values(bindingProvenanceByArgument));
     const unboundArguments = schema.argument_names.filter((name) => undeclaredArguments.has(name) ||
@@ -136,9 +158,31 @@ export function buildRelationshipPlan(factId, requirementId, claimText, existing
         instructions: `Apply the predicate fact ${factId} first, update the requirement with the returned merged logicClaims manifest, then attach this relationship without overwriting other requirement metadata. The relationship target is the planned fact id ${factId}, never a candidates[].id (SUGGEST-...).`,
     };
 }
-// implements REQ-mcp-suggest-predicates
+/**
+ * The prose an ontology-gap observation carries in `document.body`. Schema 8
+ * blocks an observation without body context (entity-context-missing), so the
+ * body says why the note exists and quotes the claim it is about.
+ */
+function gapObservationBody(text, args) {
+    const origin = [
+        args.requirementId ? `requirement ${args.requirementId}` : null,
+        args.source ? `source ${args.source}` : null,
+    ].filter((value) => value !== null);
+    return [
+        "No available predicate schema fits this claim, so kb_model mode predicates recorded it as an open ontology gap. The observation does not ground the claim; it stays visible for review until a reviewed predicate_schema covers this kind of statement.",
+        ...(origin.length > 0 ? [`Claim from ${origin.join(", ")}:`] : ["Claim:"]),
+        `> ${text.trim().replace(/\n/g, "\n> ")}`,
+    ].join("\n\n");
+}
+// implements REQ-mcp-suggest-predicates, REQ-model-predicates-plan-roundtrip
+/**
+ * The ontology-gap observation plan. It is a review note, not a semantic
+ * claim: it quotes the claim in claim_text without a claim_key, carries the
+ * review tags in `tags` only (a tag is not an entity, so no relationship
+ * targets it) and explains itself in `document.body`, so kb_upsert accepts
+ * it unchanged.
+ */
 export function buildGapApplyPlan(text, args) {
-    const claimKey = semanticClaimKey(text);
     const factId = hashId("FACT-ONTOLOGY-GAP", [
         args.requirementId ?? "",
         args.source ?? "",
@@ -152,20 +196,14 @@ export function buildGapApplyPlan(text, args) {
                 title: "Ontology gap: predicate schema needed",
                 status: "active",
                 source: args.source ?? "mcp://kibi/suggest-predicates",
-                text_ref: args.source,
+                ...(args.source ? { text_ref: args.source } : {}),
                 tags: ["review:ontology-gap", "needs_schema_extension"],
                 fact_kind: "observation",
                 value_string: text,
-                claim_key: claimKey,
                 claim_text: text,
             },
-            relationships: [
-                {
-                    type: "relates_to",
-                    from: factId,
-                    to: "review:ontology-gap",
-                },
-            ],
+            document: { body: gapObservationBody(text, args) },
+            relationships: [],
         },
     ];
 }

package/dist/operations/modeling/predicate-binding-hints.d.ts

@@ -0,0 +1,11 @@
+import type { BindingHint, PredicateSuggestion } from "./predicate-types.js";
+/**
+ * For each unbound argument of a candidate: its type, its declared constants
+ * when the vocabulary is closed, example values from the schema, and why the
+ * current value was not accepted, so the agent binds from the claim text
+ * instead of guessing.
+ */
+export declare function buildBindingHints(candidate: PredicateSuggestion, text: string, requirementSubjects?: readonly string[]): BindingHint[];
+/** One line per hint for the text summary: `name (type, e.g. a, b)`. */
+export declare function describeBindingHints(hints: readonly BindingHint[]): string;
+//# sourceMappingURL=predicate-binding-hints.d.ts.map

package/dist/operations/modeling/predicate-binding-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate-binding-hints.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-binding-hints.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAoD7E;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE,MAAM,EACZ,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,WAAW,EAAE,CAiCf;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAW1E"}

package/dist/operations/modeling/predicate-binding-hints.js

@@ -0,0 +1,97 @@
+import { isGenericPlaceholder, nameOrStopWordReason, } from "./predicate-bindings.js";
+const MAX_EXAMPLES = 5;
+/** Split `name(a, b(c), d)` into its top-level arguments, or [] when it is not a call. */
+function exampleArguments(example) {
+    const open = example.indexOf("(");
+    const close = example.lastIndexOf(")");
+    if (open < 0 || close <= open)
+        return [];
+    const inner = example.slice(open + 1, close);
+    const args = [];
+    let depth = 0;
+    let current = "";
+    for (const char of inner) {
+        if (char === "(" || char === "[")
+            depth += 1;
+        if (char === ")" || char === "]")
+            depth -= 1;
+        if (char === "," && depth === 0) {
+            args.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    args.push(current.trim());
+    return args.filter(Boolean);
+}
+function unboundReason(candidate, name, value, text) {
+    const schema = candidate.schema;
+    const provenance = candidate.binding_provenance_by_argument[name];
+    const nameReason = nameOrStopWordReason(value, {
+        argumentName: name,
+        argumentNames: schema.argument_names,
+        constants: schema.argument_constants?.[name],
+        text,
+    });
+    if (nameReason !== null)
+        return `The value "${value}" is not a binding: ${nameReason}.`;
+    if (!value.trim() || isGenericPlaceholder(value))
+        return "The claim text names no value for this argument.";
+    if (provenance === "inferred")
+        return `The value "${value}" was inferred and does not appear in the claim text; confirm it or pass the exact value.`;
+    if (schema.argument_constants?.[name])
+        return `The value "${value}" is not one of this argument's declared constants.`;
+    return `The value "${value}" needs review.`;
+}
+/**
+ * For each unbound argument of a candidate: its type, its declared constants
+ * when the vocabulary is closed, example values from the schema, and why the
+ * current value was not accepted, so the agent binds from the claim text
+ * instead of guessing.
+ */
+// implements REQ-model-predicates-binding-placeholders, REQ-model-predicates-requirement-subject
+export function buildBindingHints(candidate, text, requirementSubjects = []) {
+    const schema = candidate.schema;
+    const parsedExamples = schema.examples.map(exampleArguments);
+    return candidate.unbound_arguments.map((name) => {
+        const position = schema.argument_names.indexOf(name);
+        const constants = schema.argument_constants?.[name];
+        const exampleValues = parsedExamples
+            .map((args) => args[position])
+            .filter((value) => typeof value === "string");
+        // The subject keys the requirement already constrains come first, so
+        // the predicate and the subject fact use one identifier for the subject.
+        const examples = Array.from(new Set([
+            ...(name === "subject" ? requirementSubjects : []),
+            ...(constants ?? []),
+            ...exampleValues,
+        ])).slice(0, MAX_EXAMPLES);
+        const current = candidate.predicate_args[position] ?? "";
+        const description = schema.argument_descriptions?.[position];
+        return {
+            argument: name,
+            position,
+            type: schema.argument_types[position] ?? "unknown",
+            ...(description ? { description } : {}),
+            ...(constants ? { allowedValues: [...constants] } : {}),
+            examples,
+            currentValue: current,
+            provenance: candidate.binding_provenance_by_argument[name] ?? "placeholder",
+            reason: unboundReason(candidate, name, current, text),
+        };
+    });
+}
+/** One line per hint for the text summary: `name (type, e.g. a, b)`. */
+export function describeBindingHints(hints) {
+    return hints
+        .map((hint) => {
+        const values = hint.allowedValues
+            ? `one of ${hint.allowedValues.join(", ")}`
+            : hint.examples.length > 0
+                ? `e.g. ${hint.examples.join(", ")}`
+                : "no example in the schema";
+        return `${hint.argument} (${hint.type}, ${values})`;
+    })
+        .join("; ");
+}

package/dist/operations/modeling/predicate-bindings.d.ts

@@ -1,6 +1,29 @@
 import type { BindingProvenance } from "./predicate-types.js";
 export declare function isGenericPlaceholder(value: string): boolean;
-export declare function classifyBinding(value: string, text: string, explicit: boolean, canonical?: boolean): BindingProvenance;
+/** A binding value in the snake_case form argument names use. */
+export declare function bindingToken(value: string): string;
+/** The schema context a binding is judged against. */
+export type BindingContext = Readonly<{
+    /** The argument this value binds. */
+    argumentName?: string;
+    /** Every argument name of the schema. */
+    argumentNames?: readonly string[];
+    /** Declared constants of this argument: always valid when matched. */
+    constants?: readonly string[] | undefined;
+    /**
+     * The claim text. A value that repeats an argument name is still a real
+     * binding when the claim itself names it (a `launcher` argument bound to
+     * "launcher" in "The launcher must ...").
+     */
+    text?: string | undefined;
+}>;
+/**
+ * Why a value only stands in for a binding, or null when it can be a reviewed
+ * value: it repeats its own or another argument's name, or it is a bare stop
+ * word. Declared constants and the booleans `true`/`false` always pass.
+ */
+export declare function nameOrStopWordReason(value: string, context?: BindingContext): string | null;
+export declare function classifyBinding(value: string, text: string, explicit: boolean, canonical?: boolean, context?: BindingContext): BindingProvenance;
 export declare function aggregateBindingProvenance(values: readonly BindingProvenance[]): BindingProvenance;
 export declare function bindingCanBeApplied(value: BindingProvenance): boolean;
 //# sourceMappingURL=predicate-bindings.d.ts.map