kibi-cli 2.26.3 → 2.27.0

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

@@ -12,6 +12,7 @@ import { validateUpsertInput } from "../mutation/validation.js";
 import { isBlockingWitness, parseWhatIfAnalysis, } from "../mutation/what-if.js";
 import { analyzeSemanticAdvisorInputWithPlugins } from "../semantic-advisor/plugin-orchestration.js";
 import { canonicalize } from "../semantic-advisor/shared.js";
+import { MAX_REVIEW_CANDIDATES, REVIEW_CANDIDATE_MIN_SCORE, loadReviewRequirements, reviewCandidate, reviewNextAction, } from "./conflict-review.js";
 // implements REQ-kibi-change-to-proof-plan-compiler-v2
 export const COMPILE_PLAN_VERSION = "kibi.compile-plan.v1";
 export { isBlockingWitness, parseWhatIfAnalysis } from "../mutation/what-if.js";
@@ -358,6 +359,7 @@ async function contradictionAnalysis(prolog, requirementId, steps, now) {
         introduced: [],
         removed: [],
         unchanged: [],
+        reasons: [{ reason: "analysis_unavailable", ids: [] }],
     };
     let goal;
     try {
@@ -389,6 +391,108 @@ async function contradictionAnalysis(prolog, requirementId, steps, now) {
         unchanged: analysis.unchanged,
     };
 }
+// implements REQ-kibi-contradiction-review-candidates
+// No witness is not the same as no conflict: the checker compares only what
+// has a logical model. When a target proposition is unmodeled, or a related
+// current requirement from discovery has no logic of its own, the outcome
+// stays unresolved with the reason, and the related requirements become
+// review candidates the agent compares and judges. The verdicts come back
+// through conflictReviews: a conflict blocks the plan, a no_conflict clears
+// that candidate. A pending review leaves a ready plan ready; the outcome and
+// nextAction say what was not checked.
+async function withConflictReview(prolog, analysis, input) {
+    const diagnostics = [];
+    const decisions = new Map();
+    for (const decision of input.decisions) {
+        const id = text(decision.requirementId);
+        if (id)
+            decisions.set(id, decision);
+    }
+    const unmodeledClaims = input.propositions
+        .filter((proposition) => proposition.status === "ontology_gap" ||
+        proposition.status === "ambiguous")
+        .map((proposition) => proposition.claimKey);
+    // Matches arrive best first, so the first score seen is the highest.
+    const scores = new Map();
+    for (const match of input.matches) {
+        const id = text(match.entity.id);
+        if (text(match.entity.type) !== "req" ||
+            !id ||
+            id === input.requirementId ||
+            match.score < REVIEW_CANDIDATE_MIN_SCORE ||
+            scores.has(id))
+            continue;
+        scores.set(id, match.score);
+    }
+    const requirements = await loadReviewRequirements(prolog, [
+        ...scores.keys(),
+        ...[...decisions.keys()].filter((id) => id !== input.requirementId),
+    ]);
+    for (const id of decisions.keys()) {
+        if (id === input.requirementId || !requirements.has(id))
+            diagnostics.push(`conflictReviews names ${id}, which is not a current requirement other than the target; its verdict was ignored.`);
+    }
+    const candidates = [];
+    let pendingCount = 0;
+    for (const [id, score] of scores) {
+        const requirement = requirements.get(id);
+        if (!requirement)
+            continue;
+        const decision = decisions.get(id);
+        if (!decision) {
+            // A modeled target is compared logically with every modeled
+            // requirement; only prose-only ones need the agent. An unmodeled
+            // target cannot be compared with anything.
+            if (unmodeledClaims.length === 0 && requirement.modeled)
+                continue;
+            if (pendingCount >= MAX_REVIEW_CANDIDATES)
+                continue;
+            pendingCount += 1;
+        }
+        candidates.push(reviewCandidate(input.intent, requirement, score, decision));
+    }
+    // A verdict on a requirement discovery did not rank still counts: the
+    // agent may know a conflict the search missed.
+    for (const [id, decision] of decisions) {
+        const requirement = requirements.get(id);
+        if (!requirement || scores.has(id) || id === input.requirementId)
+            continue;
+        candidates.push(reviewCandidate(input.intent, requirement, 0, decision));
+    }
+    const pending = candidates.filter((candidate) => candidate.review === "pending");
+    const declaredConflicts = candidates.filter((candidate) => candidate.review === "conflict");
+    const reasons = [...(analysis.reasons ?? [])];
+    if (unmodeledClaims.length > 0)
+        reasons.push({ reason: "unmodeled_target", ids: unmodeledClaims });
+    const pendingUnmodeled = pending.filter((candidate) => !candidate.modeled);
+    if (unmodeledClaims.length === 0 && pendingUnmodeled.length > 0)
+        reasons.push({
+            reason: "unmodeled_related",
+            ids: pendingUnmodeled.map((candidate) => candidate.requirementId),
+        });
+    const outcome = analysis.outcome === "conflict" || declaredConflicts.length > 0
+        ? "conflict"
+        : analysis.outcome === "unresolved" || reasons.length > 0
+            ? "unresolved"
+            : "no_conflict";
+    if (declaredConflicts.length > 0)
+        diagnostics.push(`By your review the intent contradicts current requirement ${declaredConflicts.map((candidate) => candidate.requirementId).join(", ")}: ask the human which rule holds, then supersede or change the conflicting requirement, or change the intent, before applying this plan.`);
+    if (pending.length > 0)
+        diagnostics.push(`Contradiction check incomplete: Kibi could not compare this intent logically with current requirement ${pending.map((candidate) => candidate.requirementId).join(", ")}. Compare them (contradictionAnalysis.reviewCandidates) and send your verdicts in conflictReviews.`);
+    const nextAction = outcome === "no_conflict"
+        ? undefined
+        : reviewNextAction(candidates, unmodeledClaims);
+    return {
+        analysis: {
+            ...analysis,
+            outcome,
+            reasons,
+            reviewCandidates: candidates,
+            ...(nextAction !== undefined ? { nextAction } : {}),
+        },
+        diagnostics,
+    };
+}
 function proposalFor(requirementId, match) {
     const candidateId = text(match.entity.id);
     const candidateType = text(match.entity.type);
@@ -847,15 +951,24 @@ export async function executeCompileIntent(args, context) {
     // specified_by links) into the requirement step, which an upsert needs:
     // a step without properties fails entity validation.
     const stepsWithAcceptedProposals = applyAcceptedProposals(mergeSteps([...stepsWithInventory, ...drafts.steps]), proposals);
-    const contradictions = await contradictionAnalysis(prolog, requirementId, stepsWithAcceptedProposals, context.clock());
-    if (contradictions.outcome === "conflict")
-        diagnostics.push(contradictions.witnesses.some((witness) => witness.kind === "scenario_feasibility")
+    const checked = await contradictionAnalysis(prolog, requirementId, stepsWithAcceptedProposals, context.clock());
+    if (checked.outcome === "conflict")
+        diagnostics.push(checked.witnesses.some((witness) => witness.kind === "scenario_feasibility")
             ? "The plan leaves a success scenario infeasible or conflicts with a current requirement: set expects: rejection, correct the assumption, record an approved exception, or supersede the conflicting requirement before applying this plan."
             : "Current requirement conflicts must be resolved with an explicit supersedes relationship before applying this plan.");
-    if (contradictions.outcome === "unresolved")
-        diagnostics.push(contradictions.witnesses.length > 0
+    if (checked.outcome === "unresolved")
+        diagnostics.push(checked.witnesses.length > 0
             ? "Contradiction analysis is unresolved: the planned rules may overlap with current requirements and the checker can neither prove nor exclude a conflict."
             : "Contradiction analysis could not run against the attached KB snapshot with this plan staged.");
+    const reviewed = await withConflictReview(prolog, checked, {
+        intent,
+        requirementId,
+        propositions,
+        matches: search.matches,
+        decisions: args.conflictReviews ?? [],
+    });
+    const contradictions = reviewed.analysis;
+    diagnostics.push(...reviewed.diagnostics);
     if (args.mode === "create" &&
         existing.length > 0 &&
         diagnostics.some((entry) => entry.includes("already exists with different content")))

package/dist/operations/planning/conflict-review.d.ts

@@ -0,0 +1,69 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+/**
+ * Relevance floor for a related requirement, below the kb_search default
+ * (0.18): a missed contradiction costs more than one extra comparison, and a
+ * requirement sharing half the intent's terms in other words ("label length
+ * is limited" against "label length must be at most 200") scores about 0.13.
+ * The candidate cap bounds the noise.
+ */
+export declare const REVIEW_CANDIDATE_MIN_SCORE = 0.1;
+/** At most this many related requirements are put up for review. */
+export declare const MAX_REVIEW_CANDIDATES = 5;
+export type ConflictReviewVerdict = "conflict" | "no_conflict";
+/** The agent's judgement of one review candidate, sent back on recompile. */
+export type ConflictReviewDecision = Readonly<{
+    requirementId: string;
+    verdict: ConflictReviewVerdict;
+    note?: string;
+}>;
+/**
+ * A current requirement the contradiction checker could not compare with the
+ * intent, which the agent must compare itself.
+ */
+export type ConflictReviewCandidate = Readonly<{
+    requirementId: string;
+    title: string;
+    /** The sentence of the requirement that shares the most terms with the intent. */
+    sentence: string;
+    /** The requirement's checked statement (semantic text, else title), bounded. */
+    statement: string;
+    /** Discovery score; 0 for a requirement only the agent's review named. */
+    score: number;
+    /** Whether the requirement has a logical representation of its own. */
+    modeled: boolean;
+    review: "pending" | ConflictReviewVerdict;
+    note?: string;
+}>;
+/** Why the contradiction check could not decide, with the ids involved. */
+export type UncheckedReason = Readonly<{
+    reason: "unmodeled_target" | "unmodeled_related" | "analysis_unavailable";
+    /** Claim keys for unmodeled_target, requirement ids for unmodeled_related. */
+    ids: readonly string[];
+}>;
+/** One current requirement as review reads it. */
+export type ReviewRequirement = Readonly<{
+    id: string;
+    title: string;
+    semanticText: string;
+    modeled: boolean;
+}>;
+/**
+ * The current requirements among `ids`, each with whether it has a logical
+ * representation. Ids that are not current requirements (superseded,
+ * deprecated or unknown) are left out.
+ */
+export declare function loadReviewRequirements(prolog: Pick<PrologPort, "query">, ids: readonly string[]): Promise<Map<string, ReviewRequirement>>;
+/**
+ * The sentence of a requirement most likely to bear on the intent: the one
+ * sharing the most intent terms, the first on a tie, the title when the
+ * requirement has no prose.
+ */
+export declare function reviewSentence(intent: string, requirement: Pick<ReviewRequirement, "title" | "semanticText">): string;
+export declare function reviewCandidate(intent: string, requirement: ReviewRequirement, score: number, decision: ConflictReviewDecision | undefined): ConflictReviewCandidate;
+/**
+ * What the agent does next while the contradiction outcome is not decided:
+ * resolve a conflict it found, compare the candidates still pending, or model
+ * the claims Kibi could not check.
+ */
+export declare function reviewNextAction(candidates: readonly ConflictReviewCandidate[], unmodeledClaims: readonly string[]): string | undefined;
+//# sourceMappingURL=conflict-review.d.ts.map

package/dist/operations/planning/conflict-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-review.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/conflict-review.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAc3E;;;;;;GAMG;AAEH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,oEAAoE;AAEpE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAMvC,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,aAAa,CAAC;AAE/D,6EAA6E;AAE7E,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH;;;GAGG;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,qBAAqB,CAAC;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,2EAA2E;AAE3E,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,MAAM,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;IAC1E,8EAA8E;IAC9E,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACxB,CAAC,CAAC;AAEH,kDAAkD;AAElD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAMH;;;;GAIG;AAEH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CA+BzC;AAaD;;;;GAIG;AAEH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,cAAc,CAAC,GAC7D,MAAM,CAgBR;AASD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,iBAAiB,EAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,sBAAsB,GAAG,SAAS,GAC3C,uBAAuB,CAWzB;AAED;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,uBAAuB,EAAE,EAC9C,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,MAAM,GAAG,SAAS,CAcpB"}

package/dist/operations/planning/conflict-review.js

@@ -0,0 +1,133 @@
+import { intentTokens } from "../../intent-search.js";
+import { escapeAtomContent, parseListOfLists, parsePrologValue, } from "../../prolog/codec.js";
+import { loadEntityRows } from "../../public/operations/discovery-entities.js";
+/**
+ * Relationships that give a requirement a logical representation the
+ * contradiction checker can compare. A requirement with none of them is prose
+ * only: no witness can ever name it.
+ */
+const LOGICAL_RELATIONSHIPS = [
+    "constrains",
+    "requires_property",
+    "requires_predicate",
+    "requires_rule",
+];
+/**
+ * Relevance floor for a related requirement, below the kb_search default
+ * (0.18): a missed contradiction costs more than one extra comparison, and a
+ * requirement sharing half the intent's terms in other words ("label length
+ * is limited" against "label length must be at most 200") scores about 0.13.
+ * The candidate cap bounds the noise.
+ */
+// implements REQ-kibi-contradiction-review-candidates
+export const REVIEW_CANDIDATE_MIN_SCORE = 0.1;
+/** At most this many related requirements are put up for review. */
+// implements REQ-kibi-contradiction-review-candidates
+export const MAX_REVIEW_CANDIDATES = 5;
+/** The longest requirement statement a review candidate quotes. */
+const MAX_STATEMENT_LENGTH = 600;
+function text(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+/**
+ * The current requirements among `ids`, each with whether it has a logical
+ * representation. Ids that are not current requirements (superseded,
+ * deprecated or unknown) are left out.
+ */
+// implements REQ-kibi-contradiction-review-candidates
+export async function loadReviewRequirements(prolog, ids) {
+    const unique = [...new Set(ids.filter(Boolean))];
+    const found = new Map();
+    if (unique.length === 0)
+        return found;
+    const idList = unique.map((id) => `'${escapeAtomContent(id)}'`).join(",");
+    const result = await prolog.query(`findall([R,M], (member(R, [${idList}]), kb:current_req(R), (once((member(T, [${LOGICAL_RELATIONSHIPS.join(",")}]), kb_relationship(T, R, _))) -> M = modeled ; M = unmodeled)), Rows)`);
+    if (!result.success)
+        return found;
+    const modeled = new Map(parseListOfLists(result.bindings.Rows ?? "[]").map(([id, flag]) => [
+        atom(id),
+        atom(flag) === "modeled",
+    ]));
+    const rows = await loadEntityRows(prolog, [...modeled.keys()], ["id", "title", "semantic_text"]);
+    for (const row of rows) {
+        const id = text(row.id);
+        if (!modeled.has(id))
+            continue;
+        found.set(id, {
+            id,
+            title: text(row.title),
+            semanticText: text(row.semantic_text),
+            modeled: modeled.get(id) === true,
+        });
+    }
+    return found;
+}
+function atom(value) {
+    return String(parsePrologValue(value ?? "")).replace(/^['"]|['"]$/g, "");
+}
+function sentences(value) {
+    return value
+        .split(/(?<=[.!?])\s+|\n+/)
+        .map((sentence) => sentence.trim())
+        .filter(Boolean);
+}
+/**
+ * The sentence of a requirement most likely to bear on the intent: the one
+ * sharing the most intent terms, the first on a tie, the title when the
+ * requirement has no prose.
+ */
+// implements REQ-kibi-contradiction-review-candidates
+export function reviewSentence(intent, requirement) {
+    const units = sentences(requirement.semanticText);
+    if (units.length === 0)
+        return requirement.title;
+    const wanted = new Set(intentTokens(intent));
+    let best = units[0] ?? requirement.title;
+    let bestShared = -1;
+    for (const unit of units) {
+        const shared = intentTokens(unit).filter((token) => wanted.has(token)).length;
+        if (shared > bestShared) {
+            best = unit;
+            bestShared = shared;
+        }
+    }
+    return best;
+}
+function bounded(value) {
+    return value.length > MAX_STATEMENT_LENGTH
+        ? `${value.slice(0, MAX_STATEMENT_LENGTH - 1).trimEnd()}…`
+        : value;
+}
+// implements REQ-kibi-contradiction-review-candidates
+export function reviewCandidate(intent, requirement, score, decision) {
+    return {
+        requirementId: requirement.id,
+        title: requirement.title,
+        sentence: reviewSentence(intent, requirement),
+        statement: bounded(requirement.semanticText || requirement.title),
+        score: Math.round(score * 1000) / 1000,
+        modeled: requirement.modeled,
+        review: decision?.verdict ?? "pending",
+        ...(decision?.note ? { note: decision.note } : {}),
+    };
+}
+/**
+ * What the agent does next while the contradiction outcome is not decided:
+ * resolve a conflict it found, compare the candidates still pending, or model
+ * the claims Kibi could not check.
+ */
+// implements REQ-kibi-contradiction-review-candidates
+export function reviewNextAction(candidates, unmodeledClaims) {
+    const ids = (review) => candidates
+        .filter((candidate) => candidate.review === review)
+        .map((candidate) => candidate.requirementId);
+    const conflicts = ids("conflict");
+    if (conflicts.length > 0)
+        return `You judged that the intent contradicts ${conflicts.join(", ")}. Ask the human which rule holds, then supersede or change the conflicting requirement, or change the intent, and compile again. Record a conflict the human has not decided yet as a review:conflict observation fact.`;
+    const pending = ids("pending");
+    if (pending.length > 0)
+        return `Kibi could not compare this intent with ${pending.join(", ")} logically. Read each reviewCandidates entry (its statement and sentence) and decide whether the intent contradicts it, then call kb_compile_intent again with the same arguments plus conflictReviews: [{requirementId, verdict: "conflict" | "no_conflict", note}] for each.`;
+    if (unmodeledClaims.length > 0)
+        return `Kibi could not check claim ${unmodeledClaims.join(", ")} for contradictions because it has no logical model: model it with kb_model (mode requirement or predicates) and compile again. Until then no conflict is confirmed, only reviewed.`;
+    return undefined;
+}

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

@@ -12,6 +12,14 @@ export type SemanticRelationship = Readonly<{
     to?: unknown;
 }>;
 export declare function validateSemanticInventoryBoundary(payload: Payload, relationships: readonly SemanticRelationship[], receipt: SemanticAdvisorReceipt): SemanticInventoryBoundaryResult;
+/**
+ * The inventory contract the advisor derives for this payload's prose, as
+ * the properties to resend: the version, source field and hash, one ledger
+ * entry per proposition and the assertive claim keys. An entry keeps the
+ * status the payload already gave the same claim key; otherwise it carries
+ * the advisor's status (an ambiguity or ontology gap stays explicit).
+ */
+export declare function semanticInventoryContract(payload: Payload, receipt: SemanticAdvisorReceipt): Record<string, unknown>;
 export declare function assertSemanticInventoryBoundary(payload: Payload, relationships: readonly SemanticRelationship[], receipt: SemanticAdvisorReceipt): void;
 /**
  * The write-time claim_key check, run against planned writes only. Returns

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;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"}
+{"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;;;;;;GAMG;AAEH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,sBAAsB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB;AAGD,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAwFD;;;;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,CAiCf"}

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

@@ -157,10 +157,41 @@ export function validateSemanticInventoryBoundary(payload, relationships, receip
     }
     return { applicable, errors, sourceHash };
 }
+/**
+ * The inventory contract the advisor derives for this payload's prose, as
+ * the properties to resend: the version, source field and hash, one ledger
+ * entry per proposition and the assertive claim keys. An entry keeps the
+ * status the payload already gave the same claim key; otherwise it carries
+ * the advisor's status (an ambiguity or ontology gap stays explicit).
+ */
+// implements REQ-kb-upsert-ledger-contract-in-error
+export function semanticInventoryContract(payload, receipt) {
+    const semanticSource = semanticSourceOf(payload);
+    const sent = new Map(inventoryOf(payload).map((entry) => [
+        stringValue(entry.claim_key),
+        stringValue(entry.status),
+    ]));
+    return {
+        semantic_inventory_version: SEMANTIC_INVENTORY_VERSION,
+        semantic_source_field: semanticSource.field,
+        semantic_source_hash: semanticSourceHash(semanticSource.text),
+        semantic_inventory: receipt.propositions.map((proposition) => ({
+            claim_key: proposition.claim_key,
+            claim_text: proposition.claim_text,
+            role: proposition.role,
+            status: sent.get(proposition.claim_key) || proposition.status,
+            span: { start: proposition.span.start, end: proposition.span.end },
+        })),
+        logic_claims: receipt.propositions
+            .filter(propositionIsAssertive)
+            .map(({ claim_key }) => claim_key),
+    };
+}
+// implements REQ-kibi-proposition-complete-ingestion, REQ-kb-upsert-ledger-contract-in-error
 export function assertSemanticInventoryBoundary(payload, relationships, receipt) {
     const result = validateSemanticInventoryBoundary(payload, relationships, receipt);
     if (result.errors.length > 0) {
-        throw new Error(`Proposition-complete ingestion failed: ${result.errors.join("; ")}. Run kb_model mode analyze (CLI: semantic-advisor) with the complete prose and preserve its inventory contract before retrying.`);
+        throw new Error(`Proposition-complete ingestion failed: ${result.errors.join("; ")}. The contract kb_model mode analyze returns for this prose, to merge into properties and resend (a claim marked modeled needs one requires_property, requires_predicate or requires_rule link to a fact with its claim_key; otherwise keep the advisor's status): ${JSON.stringify(semanticInventoryContract(payload, receipt))}`);
     }
 }
 function modeledClaimKeysOf(payload) {
@@ -182,10 +213,13 @@ function groundingTargets(payload, relationships) {
 function plannedClaimKey(planned) {
     return planned.type === "fact" ? stringValue(planned.claim_key) : "";
 }
+function missingGroundingFactError(target) {
+    return `Proposition-complete ingestion failed: logical grounding target '${target}' does not exist yet. Write the fact first: the kb_compile_intent plan has an earlier fact step for '${target}' that carries its claim_key; run that step before this one, or apply the whole plan with kb_apply_plan.`;
+}
 function groundingClaimKeyError(modeledClaimKeys, grounded) {
     const missing = grounded.find(([, claimKey]) => !claimKey);
     if (missing)
-        return `Proposition-complete ingestion failed: logical grounding target '${missing[0]}' must declare a claim_key.`;
+        return `Proposition-complete ingestion failed: logical grounding target '${missing[0]}' must declare a claim_key: it is a fact without the claim_key of the claim it grounds. Set the claim_key the kb_compile_intent plan's fact step gives it.`;
     const groundedClaimKeys = grounded.map(([, claimKey]) => claimKey);
     const duplicate = groundedClaimKeys.find((claimKey, index) => groundedClaimKeys.indexOf(claimKey) !== index);
     if (duplicate)
@@ -256,6 +290,13 @@ export async function assertLogicalGroundingClaimKeys(prolog, payload, relations
             claimKey = result.success
                 ? stringValue(result.bindings.ClaimKey).replace(/^['"]|['"]$/g, "")
                 : "";
+            // implements REQ-kibi-symbol-link-guidance
+            // A target that is not stored yet is a skipped plan step, not a fact
+            // missing its key: say which step to run first.
+            if (!claimKey &&
+                !(await prolog.query(`once(kb_entity('${escapeAtom(target)}', _, _))`))
+                    .success)
+                throw new Error(missingGroundingFactError(target));
         }
         grounded.push([target, claimKey]);
         // The first target without a claim_key is reported; later reads are moot.

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

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/public/impact/analyzer.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAGpB,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAmKlC"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/public/impact/analyzer.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAWpB,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA0LlC"}

package/dist/public/impact/analyzer.js

@@ -7,11 +7,19 @@ import { extractSymbolsFromStagedFileAsync } from "../../traceability/symbol-ext
 import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
 import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, } from "./diagnostics.js";
 import { createImpactManifestLookup, readImpactManifestResults, } from "./manifest.js";
+import { createRequirementStatementDiagnostics, readWorkspaceRequirement, workspaceFileChanged, } from "./requirement-statements.js";
 import { normalizeSourceFile } from "./source-changes.js";
 import { collectSourceChanges, uniqueSorted } from "./source-changes.js";
 import { buildNextActions, collectLinkedEntities, formatExtractedSymbols, } from "./summaries.js";
 import { createSymbolQualityDiagnostics } from "./symbol-quality.js";
 import { createUnownedFileDiagnostics } from "./unowned-files.js";
+/** The workspace-relative document a requirement was read from. */
+function requirementSourcePath(requirement) {
+    const source = requirement.source;
+    return source && !source.includes("://")
+        ? source.replace(/^\.\//, "")
+        : `.kb/requirements/${requirement.id}.md`;
+}
 export async function analyzeChangedFileImpact(options) {
     const workspaceRoot = path.resolve(options.workspaceRoot);
     const snapshot = options.staged
@@ -47,8 +55,11 @@ export async function analyzeChangedFileImpact(options) {
             (filter.size === 0 || filter.has(file.path)))
             .map((file) => file.path)
         : sourceChanges.map((change) => change.file));
-    const manifestResults = snapshot
-        ? readSnapshotKnowledge(snapshot.readGit, snapshot.headTree, snapshot.readBlobs).filter((result) => result.entity.type === "symbol")
+    const snapshotKnowledge = snapshot
+        ? readSnapshotKnowledge(snapshot.readGit, snapshot.headTree, snapshot.readBlobs)
+        : undefined;
+    const manifestResults = snapshotKnowledge
+        ? snapshotKnowledge.filter((result) => result.entity.type === "symbol")
         : readImpactManifestResults(workspaceRoot);
     const manifestLookup = createImpactManifestLookup(manifestResults);
     const symbolsByFile = new Map();
@@ -92,6 +103,19 @@ export async function analyzeChangedFileImpact(options) {
                 requestedFiles: [...filter],
                 linkedSourceFiles,
             }),
+            // What the changed code is meant to do, quoted, before the
+            // structural findings: "no violations" never compared it.
+            ...createRequirementStatementDiagnostics({
+                workspaceRoot,
+                symbolsByFile,
+                readRequirement: (id) => snapshotKnowledge
+                    ? snapshotKnowledge.find((result) => result.entity.id === id)
+                        ?.entity
+                    : readWorkspaceRequirement(workspaceRoot, id),
+                requirementChanged: (requirement) => snapshot
+                    ? snapshot.inventory.some((file) => file.path === requirementSourcePath(requirement))
+                    : workspaceFileChanged(workspaceRoot, requirementSourcePath(requirement)),
+            }),
             ...createSymbolGranularityDiagnostics({
                 manifestResults: activeManifestResults,
                 symbolsByFile,

package/dist/public/impact/requirement-statements.d.ts

@@ -0,0 +1,29 @@
+import { type ExtractedEntity } from "../../extractors/markdown.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
+export type RequirementStatementDiagnosticsOptions = {
+    readonly workspaceRoot: string;
+    readonly symbolsByFile: ReadonlyMap<string, readonly ExtractedSymbol[]>;
+    /** The requirement entity for an id, or undefined when it is unknown. */
+    readonly readRequirement: (id: string) => ExtractedEntity | undefined;
+    /** Whether the requirement's document changed in this change. */
+    readonly requirementChanged: (requirement: ExtractedEntity) => boolean;
+};
+/**
+ * One `requirement_statement_unverified` warning per current requirement that
+ * a changed behavioral symbol implements, quoting the requirement's statement
+ * and firmness. A requirement whose own document changed in the same change
+ * is left to the firmness and supersede checks.
+ */
+export declare function createRequirementStatementDiagnostics(options: RequirementStatementDiagnosticsOptions): KibiImpactDiagnostic[];
+/**
+ * Whether Git reports any change (staged, unstaged or untracked) to a
+ * workspace file against HEAD. Outside a repository nothing counts as changed.
+ */
+export declare function workspaceFileChanged(workspaceRoot: string, relativePath: string): boolean;
+/**
+ * Read a requirement from its canonical document in the working tree
+ * (`.kb/requirements/<id>.md`).
+ */
+export declare function readWorkspaceRequirement(workspaceRoot: string, id: string): ExtractedEntity | undefined;
+//# sourceMappingURL=requirement-statements.d.ts.map

package/dist/public/impact/requirement-statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-statements.d.ts","sourceRoot":"","sources":["../../../src/public/impact/requirement-statements.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAgB5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC,CAAC;IACxE,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,CAAC;IACtE,iEAAiE;IACjE,QAAQ,CAAC,kBAAkB,EAAE,CAAC,WAAW,EAAE,eAAe,KAAK,OAAO,CAAC;CACxE,CAAC;AAiBF;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,sCAAsC,GAC9C,oBAAoB,EAAE,CAsExB;AAGD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,OAAO,CAeT;AAGD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,EAAE,EAAE,MAAM,GACT,eAAe,GAAG,SAAS,CAS7B"}