kibi-cli 2.3.0 → 2.5.0

package/dist/operations/proof/receipt-compaction.js

@@ -0,0 +1,121 @@
+/*
+ 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 { canonicalJson } from "../../public/proof-fingerprint.js";
+// implements REQ-kibi-fresh-verification-receipts-v2
+export const PROOF_RECEIPT_COMPACTION_POLICY = "kibi.proof-receipt-compaction.v1";
+function finishedStamp(receipt) {
+    const value = receipt.finished_at;
+    const parsed = typeof value === "string" ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
+}
+/** Newest by finished_at; equal stamps resolve to the later history entry. */
+function newest(receipts, indices) {
+    let best;
+    for (const index of indices) {
+        const receipt = receipts[index];
+        if (best === undefined ||
+            finishedStamp(receipt) >= finishedStamp(receipts[best])) {
+            best = index;
+        }
+    }
+    return best;
+}
+/**
+ * Deterministic, decision-preserving compaction of one test's proof-receipt
+ * history (policy kibi.proof-receipt-compaction.v1).
+ *
+ * Coverage decides a test from one selector group: receipts whose
+ * `binding_hash` equals the test's current binding, or, when there are none,
+ * receipts whose `code_snapshot` equals the live snapshot. Within that group
+ * it reads the newest receipt per (scope, contract_hash) and the set of
+ * contract hashes present. Compaction keeps exactly what those reads can
+ * observe, plus two history anchors:
+ *
+ * - per selector group, the newest receipt for each (scope, contract_hash);
+ * - the newest receipt overall (what the last run reported);
+ * - the newest passing receipt (last known good, so reverting a change
+ *   finds its proof again without a re-run).
+ *
+ * Everything else is superseded evidence: it can never be the deciding
+ * receipt again for the current snapshot or binding. The result is an
+ * ordered subsequence of the input, so it stays a valid history, and the
+ * function is idempotent for a fixed anchor. Inputs that are not structurally
+ * valid histories must not be compacted (callers validate first): an invalid
+ * history decides `invalid`, and dropping the offending entry would change
+ * that decision.
+ */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export function compactProofReceipts(receipts, anchor) {
+    if (receipts.length === 0)
+        return { kept: [], removed: 0 };
+    const all = receipts.map((_, index) => index);
+    const keep = new Set();
+    const add = (index) => {
+        if (index !== undefined)
+            keep.add(index);
+    };
+    add(newest(receipts, all));
+    add(newest(receipts, all.filter((index) => receipts[index]?.outcome === "passed")));
+    const selectors = [];
+    if (anchor.bindingHash !== undefined && anchor.bindingHash !== "") {
+        const bindingHash = anchor.bindingHash;
+        selectors.push((receipt) => receipt.binding_hash === bindingHash);
+    }
+    if (anchor.codeSnapshot !== undefined && anchor.codeSnapshot !== "") {
+        const codeSnapshot = anchor.codeSnapshot;
+        selectors.push((receipt) => receipt.code_snapshot === codeSnapshot);
+    }
+    for (const selector of selectors) {
+        const groups = new Map();
+        for (const index of all) {
+            const receipt = receipts[index];
+            if (!selector(receipt))
+                continue;
+            const key = `${String(receipt.scope)}\0${String(receipt.contract_hash)}`;
+            const group = groups.get(key) ?? [];
+            group.push(index);
+            groups.set(key, group);
+        }
+        for (const group of groups.values())
+            add(newest(receipts, group));
+    }
+    const kept = all
+        .filter((index) => keep.has(index))
+        .map((index) => receipts[index]);
+    return { kept, removed: receipts.length - kept.length };
+}
+/**
+ * True when `subset` is `superset` with entries removed and nothing changed or
+ * reordered. Compaction may only drop receipts; this guard keeps every other
+ * rewrite of a receipt history fail-closed.
+ */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export function isOrderedReceiptSubsequence(subset, superset) {
+    let cursor = 0;
+    for (const receipt of subset) {
+        const wanted = canonicalJson(receipt);
+        while (cursor < superset.length &&
+            canonicalJson(superset[cursor]) !== wanted) {
+            cursor += 1;
+        }
+        if (cursor === superset.length)
+            return false;
+        cursor += 1;
+    }
+    return true;
+}

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

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

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

@@ -17,6 +17,17 @@ function summary(readiness, lane) {
         return "Requirement prose has a typed interpretation candidate; validate and persist it as a safe kibi.logic.v1 rule.";
     return "Requirement prose appears normative but needs review before it can participate in logic checks.";
 }
+/**
+ * How an agent reaches a catalog operation: MCP serves the modeling
+ * operations as modes of kb_model.
+ */
+function hostToolName(operation) {
+    if (operation === "kb_model_requirement")
+        return "kb_model (mode requirement)";
+    if (operation === "kb_suggest_predicates")
+        return "kb_model (mode predicates)";
+    return operation;
+}
 // implements REQ-mcp-semantic-advisor-preflight
 export function buildAdvisorResult(payload, signals, modeled, suggestions, clauses, propositions, interpretations, shadowAnalysis) {
     const semanticSource = semanticSourceOf(payload);
@@ -119,7 +130,7 @@ export function buildAdvisorResult(payload, signals, modeled, suggestions, claus
         receipt,
         warnings: readiness === "needs_modeling"
             ? [
-                `Semantic advisor: ${receipt.summary} Next action: call ${tools.join(" or ")} before treating this requirement as Prolog-checkable.`,
+                `Semantic advisor: ${receipt.summary} Next action: call ${tools.map(hostToolName).join(" or ")} before treating this requirement as Prolog-checkable.`,
             ]
             : [],
     };

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

@@ -1,6 +1,7 @@
-import type { SemanticAdvisorAnalysisResult, SemanticAdvisorInput } from "./types.js";
+import type { SemanticAdvisorAnalysisResult, SemanticAdvisorInput, SemanticPropositionRole } from "./types.js";
 export declare const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v2";
 export { semanticClaimKey } from "./clauses.js";
 export declare function stringLogicClaims(value: unknown): string[];
+export declare function propositionRole(statement: string, normative: boolean): SemanticPropositionRole;
 export declare function analyzeSemanticAdvisorInput(input: SemanticAdvisorInput): SemanticAdvisorAnalysisResult;
 //# sourceMappingURL=analyze-prose.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI1D;AAk2BD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CA+D/B"}
+{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAKpB,uBAAuB,EAMxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI1D;AAwgBD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,GACjB,uBAAuB,CAuDzB;AA4VD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CA+D/B"}

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

@@ -3,6 +3,7 @@ import { utf8Span, validateLogicIr, } from "../../logic/ir.js";
 import { logicRuleFactId } from "../modeling/logic-modeling.js";
 import { buildAdvisorResult } from "./analysis-receipt.js";
 import { extractSemanticClauses, hasNormativeAssertion, semanticClaimKey, } from "./clauses.js";
+import { detectConditionalRule, } from "./conditional-rules.js";
 import { observationPlan } from "./observation-plan.js";
 import { predicateSuggestion as buildPredicateSuggestion, isRecord, payloadHash, propertiesOf, relationship, semanticClausesOf, semanticSourceHash, semanticSourceOf, sourceOf, statementOf, stringValue, } from "./shared.js";
 import { detectStrictSuggestion } from "./strict-rules.js";
@@ -126,7 +127,8 @@ function predicateSuggestion(payload, statement) {
         return null;
     return buildPredicateSuggestion(payload, hit.evidence, hit.predicateName, hit.arguments, hit.rationale ?? "", hit.polarity);
 }
-function ruleSuggestion(payload, candidate) {
+const HOST_RULE_RATIONALE = "The host supplied a typed kibi.logic.v1 interpretation. Kibi validated its safety, canonicalized it, and will persist it as data-backed rule evidence.";
+function ruleSuggestion(payload, candidate, rationale = HOST_RULE_RATIONALE) {
     const validation = validateLogicIr(candidate.ir);
     if (!validation.valid ||
         !validation.normalized ||
@@ -163,7 +165,7 @@ function ruleSuggestion(payload, candidate) {
         claim_text: candidate.claim_text,
         confidence: candidate.confidence ?? 0.75,
         evidence: candidate.claim_text,
-        rationale: "The host supplied a typed kibi.logic.v1 interpretation. Kibi validated its safety, canonicalized it, and will persist it as data-backed rule evidence.",
+        rationale,
         suggested_next_tool: "kb_model_requirement",
         rule: validation.normalized,
         semantic_key: semanticKey,
@@ -175,7 +177,7 @@ function ruleSuggestion(payload, candidate) {
                 type: "fact",
                 id: factId,
                 properties: {
-                    title: `${candidate.ir.kind} rule ${semanticKey}`,
+                    title: `Rule: ${candidate.claim_text}`,
                     status: "active",
                     source: sourceOf(payload),
                     fact_kind: "rule",
@@ -199,6 +201,46 @@ function ruleSuggestion(payload, candidate) {
             : null,
     };
 }
+// implements REQ-kibi-truthful-consistency
+// "X may happen only when C" and "X must not happen unless C" are conditional
+// requirements: they restrict an action, not a property of every situation.
+// Route them to the rule lane as a typed forbid-unless rule, so scenario
+// feasibility and contradiction checks see the action and its condition.
+function conditionalRuleSuggestion(payload, clause, match) {
+    if (match?.kind !== "rule")
+        return null;
+    return ruleSuggestion(payload, {
+        claim_key: clause.claim_key,
+        claim_text: clause.text,
+        ir: match.ir,
+        confidence: 0.8,
+    }, `Conditional requirement (${match.shape === "only_when" ? "only when" : "must not ... unless"}): ${match.action} is forbidden unless ${match.subjectKey}.${match.propertyKey} meets the stated condition${match.scope ? ` in scope ${match.scope}` : ""}. Kibi modeled it as a typed forbid-unless rule; assume ${match.subjectKey}.${match.propertyKey} property values in scenarios to check them against it.`);
+}
+// implements REQ-kibi-truthful-consistency
+// A conditional clause that is neither a translatable rule nor a catalog
+// predicate stays an ontology gap (unresolved), never a strict property or an
+// observation that looks modeled: the strict lane would drop the condition.
+function unresolvedConditionalSuggestion(payload, clause, match) {
+    if (match === null)
+        return null;
+    return {
+        kind: "ontology_gap",
+        claim_key: clause.claim_key,
+        claim_text: clause.text,
+        confidence: 0.6,
+        evidence: match.evidence,
+        rationale: match.kind === "unparsed"
+            ? `${match.reason} Supply a typed kibi.logic.v1 interpretation (forbid the action unless the condition holds) instead of an observation.`
+            : "The conditional clause did not produce a valid kibi.logic.v1 rule; supply a typed interpretation instead of an observation.",
+        suggested_next_tool: "kb_suggest_predicates",
+        recommendedPredicateSchema: null,
+        applyPlan: observationPlan(payload, "Ontology gap: conditional clause", [
+            "semantic-advisor-suggestion",
+            "review:ontology-gap",
+            "needs_rule_interpretation",
+        ]),
+    };
+}
 function modelingSuggestions(payload, modeled, clauses, interpretations) {
     if (!isRequirement(payload) || modeled)
         return [];
@@ -209,7 +251,10 @@ function modelingSuggestions(payload, modeled, clauses, interpretations) {
         .map((clause) => clause.claim_key);
     for (const clause of clauses) {
         const candidate = clause.text;
-        const rawSuggestion = predicateSuggestion(payload, candidate) ??
+        const conditional = detectConditionalRule(candidate);
+        const rawSuggestion = conditionalRuleSuggestion(payload, clause, conditional) ??
+            predicateSuggestion(payload, candidate) ??
+            unresolvedConditionalSuggestion(payload, clause, conditional) ??
             ontologyGapSuggestion(payload, candidate) ??
             ambiguitySuggestion(payload, candidate) ??
             detectStrictSuggestion(payload, candidate);
@@ -370,7 +415,8 @@ function unmatchedClauseSuggestion(payload, clause, clauses, expectedClaimKeys)
         ]),
     }, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field);
 }
-function propositionRole(statement, normative) {
+// implements REQ-kibi-conditional-requirement-authoring
+export function propositionRole(statement, normative) {
     // Explicit context labels may quote obligations. Incidental explanatory
     // words within an asserted obligation must not exempt it from grounding.
     const assertedNormative = normative && hasNormativeAssertion(statement);

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

@@ -6,6 +6,7 @@ export type SemanticClause = Readonly<{
     source: "detected" | "supplied";
 }>;
 export declare function hasNormativeAssertion(text: string): boolean;
+export declare function modeledClaimRole(text: string, modality?: string): "normative" | "descriptive";
 export declare function normalizeSemanticClause(value: string): string;
 export declare function semanticClaimKey(text: string): string;
 export declare function extractSemanticClauses(text: string, suppliedClauses?: readonly string[]): readonly SemanticClause[];

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

@@ -1 +1 @@
-{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAYH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4BD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CA4B3B"}
+{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAYH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAQD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,GAAG,aAAa,CAG7B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4BD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CA4B3B"}

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

@@ -1,11 +1,21 @@
 import { createHash } from "node:crypto";
-const NORMATIVE_ASSERTION_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|may\s+(?:have\s+)?(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to)|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|denied|forbidden|prohibited|(?:is|are|be|become|becomes|remain|remains)\s+(?:invalid|rejected|prohibited|forbidden)|(?:reject|rejects|rejected|rejection)\s+(?:invalid|unresolved|ambiguous)|fail(?:s|ed)?\s+(?:clearly|explicitly|with)|expires?\s+(?:after|within|in)|failure\s+(?:behavior|policy|outcome)|error\s+(?:handling|behavior|policy|outcome)|required\s+outcome|defaults?\s+to)\b/i;
+const NORMATIVE_ASSERTION_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|may\s+(?:not\s+)?(?:be\s+)?\w+\s+only\b|may\s+(?:have\s+)?(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to)|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|denied|forbidden|prohibited|(?:is|are|be|become|becomes|remain|remains)\s+(?:invalid|rejected|prohibited|forbidden)|(?:reject|rejects|rejected|rejection)\s+(?:invalid|unresolved|ambiguous)|fail(?:s|ed)?\s+(?:clearly|explicitly|with)|expires?\s+(?:after|within|in)|failure\s+(?:behavior|policy|outcome)|error\s+(?:handling|behavior|policy|outcome)|required\s+outcome|defaults?\s+to)\b/i;
 // Conditional/temporal cues help discover clauses but do not by themselves
 // turn explanatory or subjective context into an asserted obligation.
 const NORMATIVE_PATTERN = new RegExp(`${NORMATIVE_ASSERTION_PATTERN.source}|\\b(?:before|unless|when|if)\\b`, "i");
 export function hasNormativeAssertion(text) {
     return NORMATIVE_ASSERTION_PATTERN.test(text);
 }
+const NORMATIVE_MODALITIES = new Set(["oblige", "forbid", "permit"]);
+// implements REQ-kibi-truthful-consistency
+// Role for a clause that was just modeled. A deontic rule modality is decisive;
+// otherwise the same assertion pattern the semantic advisor uses decides, so a
+// modeled inventory entry never disagrees with the advisor's own analysis.
+export function modeledClaimRole(text, modality) {
+    if (modality && NORMATIVE_MODALITIES.has(modality))
+        return "normative";
+    return hasNormativeAssertion(text) ? "normative" : "descriptive";
+}
 export function normalizeSemanticClause(value) {
     return (value
         .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "")

package/dist/operations/semantic-advisor/conditional-rules.d.ts

@@ -0,0 +1,33 @@
+import type { LogicRuleIR } from "../../logic/ir.js";
+/**
+ * Conditional requirement shapes routed to the rule lane.
+ *
+ *   "<Action> may|can|must|shall happen only when|if <condition>"
+ *   "<Action> may|can only happen when|if <condition>"
+ *   "<Action> must|shall|may|can not (or cannot) happen unless <condition>"
+ *
+ * Both say the action is forbidden unless the condition holds, so both become
+ * one typed kibi.logic.v1 rule: forbid <action>(X) :- <subject>:<property>(X,
+ * V) unless V <op> <value>.  A leading "In the EU," or "For EU orders," scopes
+ * the rule.  A clause with one of these shapes whose action or condition this
+ * reader cannot translate is reported as `unparsed`, so the caller keeps it
+ * unresolved instead of downgrading it to an observation that looks modeled.
+ */
+export type ConditionalRuleShape = "only_when" | "unless";
+export type ConditionalRuleMatch = Readonly<{
+    kind: "rule";
+    shape: ConditionalRuleShape;
+    evidence: string;
+    action: string;
+    subjectKey: string;
+    propertyKey: string;
+    scope: string | null;
+    ir: LogicRuleIR;
+}> | Readonly<{
+    kind: "unparsed";
+    shape: ConditionalRuleShape;
+    evidence: string;
+    reason: string;
+}>;
+export declare function detectConditionalRule(statement: string): ConditionalRuleMatch | null;
+//# sourceMappingURL=conditional-rules.d.ts.map

package/dist/operations/semantic-advisor/conditional-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional-rules.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/conditional-rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,mBAAmB,CAAC;AAGhE;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAG1D,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,CAAC;IACP,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,EAAE,EAAE,WAAW,CAAC;CACjB,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAuMP,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAChB,oBAAoB,GAAG,IAAI,CA0F7B"}

package/dist/operations/semantic-advisor/conditional-rules.js

@@ -0,0 +1,262 @@
+import { normalizeKey } from "./shared.js";
+const ONLY_WHEN = /^(?<action>.+?)\s+(?:may|can|must|shall|should)\s+(?:only\s+(?<verbBefore>.+?)|(?<verbAfter>.+?)\s+only)\s+(?:when|if)\s+(?<condition>.+)$/i;
+const ONLY_WHEN_ANYWHERE = /\bonly\s+(?:when|if)\b|\b(?:may|can|must|shall|should)\s+only\s+[^.;]*?\b(?:when|if)\b/i;
+const UNLESS = /^(?<action>.+?)\s+(?:(?:may|can|must|shall|should)\s+not|cannot|can't|must\s+never|shall\s+never)\s+(?<verb>.+?)\s+unless\s+(?<condition>.+)$/i;
+const NEGATED_UNLESS_ANYWHERE = /\b(?:not|cannot|can't|never)\b[^.;]*\bunless\b/i;
+const SCOPE_PREFIX = /^(?:[Ii]n|[Ff]or|[Ww]ithin)\s+(?:[Tt]he\s+)?(?<scope>[A-Z]{2,})(?:\s+[a-z]+)?\s*,\s*/;
+// Verbs that only say the action takes place: the action is the subject.
+const OCCURRENCE_VERB = /^(?:happen|occur|proceed|start|begin|run|complete|take\s+place|be\s+(?:performed|placed|submitted|started|completed|processed|executed))$/i;
+const NUMBER_WORDS = {
+    zero: 0,
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+    seven: 7,
+    eight: 8,
+    nine: 9,
+    ten: 10,
+};
+const DURATION_UNITS = {
+    ms: "ms",
+    millisecond: "ms",
+    milliseconds: "ms",
+    s: "s",
+    sec: "s",
+    second: "s",
+    seconds: "s",
+    min: "m",
+    minute: "m",
+    minutes: "m",
+    h: "h",
+    hour: "h",
+    hours: "h",
+    d: "d",
+    day: "d",
+    days: "d",
+    w: "w",
+    week: "w",
+    weeks: "w",
+};
+function identifier(text) {
+    return normalizeKey(text.replace(/\b(?:a|an|the)\b/gi, " "));
+}
+function numberValue(text) {
+    const trimmed = text.trim().toLowerCase();
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    return NUMBER_WORDS[trimmed] ?? null;
+}
+// "5", "five", "30 minutes", "2.5"
+function quantity(text) {
+    const match = text
+        .trim()
+        .match(/^(?<amount>-?\d+(?:\.\d+)?|[a-z]+)(?:\s+(?<unit>[a-z]+))?$/i);
+    if (!match?.groups?.amount)
+        return null;
+    const amount = numberValue(match.groups.amount);
+    if (amount === null)
+        return null;
+    const unitText = match.groups.unit?.toLowerCase();
+    if (unitText === undefined)
+        return { value: { kind: "number", value: amount }, valueType: "number" };
+    const unit = DURATION_UNITS[unitText];
+    if (unit === undefined || amount < 0)
+        return null;
+    return {
+        value: { kind: "duration", value: amount, unit },
+        valueType: "duration",
+    };
+}
+const ZERO = { kind: "number", value: 0 };
+function comparison(predicate) {
+    const text = predicate
+        .trim()
+        .replace(/[.!?]+$/, "")
+        .toLowerCase();
+    const fixed = {
+        positive: { operator: "gt", value: ZERO, valueType: "number" },
+        "greater than zero": { operator: "gt", value: ZERO, valueType: "number" },
+        "above zero": { operator: "gt", value: ZERO, valueType: "number" },
+        "more than zero": { operator: "gt", value: ZERO, valueType: "number" },
+        negative: { operator: "lt", value: ZERO, valueType: "number" },
+        "below zero": { operator: "lt", value: ZERO, valueType: "number" },
+        "less than zero": { operator: "lt", value: ZERO, valueType: "number" },
+        zero: { operator: "eq", value: ZERO, valueType: "number" },
+        "non-negative": { operator: "gte", value: ZERO, valueType: "number" },
+        nonnegative: { operator: "gte", value: ZERO, valueType: "number" },
+        "not negative": { operator: "gte", value: ZERO, valueType: "number" },
+        "non-zero": { operator: "neq", value: ZERO, valueType: "number" },
+        "not zero": { operator: "neq", value: ZERO, valueType: "number" },
+    };
+    const known = fixed[text];
+    if (known)
+        return known;
+    const comparators = [
+        [/^(?:greater|more|higher)\s+than\s+(?<q>.+)$/, "gt"],
+        [/^(?:above|over|exceeds?)\s+(?<q>.+)$/, "gt"],
+        [/^(?:at\s+least|no\s+less\s+than|not\s+less\s+than)\s+(?<q>.+)$/, "gte"],
+        [/^(?<q>.+?)\s+or\s+more$/, "gte"],
+        [/^(?:less|fewer|lower)\s+than\s+(?<q>.+)$/, "lt"],
+        [/^(?:below|under)\s+(?<q>.+)$/, "lt"],
+        [
+            /^(?:at\s+most|no\s+more\s+than|not\s+more\s+than|up\s+to)\s+(?<q>.+)$/,
+            "lte",
+        ],
+        [/^(?<q>.+?)\s+or\s+(?:less|fewer)$/, "lte"],
+        [/^(?:not\s+equal\s+to|different\s+from|not)\s+(?<q>.+)$/, "neq"],
+        [/^(?:equal\s+to|exactly)\s+(?<q>.+)$/, "eq"],
+    ];
+    for (const [pattern, operator] of comparators) {
+        const match = text.match(pattern);
+        const parsed = match?.groups?.q ? quantity(match.groups.q) : null;
+        if (parsed)
+            return { operator, ...parsed };
+    }
+    const bare = quantity(text);
+    if (bare)
+        return { operator: "eq", ...bare };
+    // A single word state ("active", "verified") is a symbolic value.
+    if (/^[a-z][a-z_-]*$/.test(text) && !/^(?:not|no|any|some)$/.test(text))
+        return {
+            operator: "eq",
+            value: { kind: "const", value: text.replace(/-/g, "_"), type: "string" },
+            valueType: "string",
+        };
+    return null;
+}
+// "the cart total is positive", "the cart's total is at least 5"
+function condition(text) {
+    if (/\b(?:and|or|but)\b|,/i.test(text))
+        return null;
+    const match = text
+        .trim()
+        .replace(/[.!?]+$/, "")
+        .match(/^(?<subject>.+?)\s+(?<verb>is|are|stays|remains|equals)\s+(?<predicate>.+)$/i);
+    if (!match?.groups?.subject || !match.groups.verb || !match.groups.predicate)
+        return null;
+    const parsed = comparison(match.groups.verb.toLowerCase() === "equals"
+        ? `equal to ${match.groups.predicate}`
+        : match.groups.predicate);
+    if (!parsed)
+        return null;
+    const subjectText = match.groups.subject.replace(/\b(?:a|an|the)\b/gi, " ");
+    let subjectPart;
+    let propertyPart;
+    const possessive = subjectText.match(/^(?<owner>.+?)['’]s\s+(?<prop>.+)$/);
+    const ofForm = subjectText.match(/^(?<prop>.+?)\s+of\s+(?<owner>.+)$/i);
+    if (possessive?.groups?.owner && possessive.groups.prop) {
+        subjectPart = possessive.groups.owner;
+        propertyPart = possessive.groups.prop;
+    }
+    else if (ofForm?.groups?.owner && ofForm.groups.prop) {
+        subjectPart = ofForm.groups.owner;
+        propertyPart = ofForm.groups.prop;
+    }
+    else {
+        const words = subjectText.trim().split(/\s+/);
+        if (words.length < 2)
+            return null;
+        propertyPart = words.slice(-1).join(" ");
+        subjectPart = words.slice(0, -1).join(" ");
+    }
+    const subjectKey = identifier(subjectPart);
+    const propertyKey = identifier(propertyPart);
+    if (!/^[a-z]/.test(subjectKey) || !/^[a-z]/.test(propertyKey))
+        return null;
+    return { subjectKey, propertyKey, comparison: parsed };
+}
+function actionName(subject, verb) {
+    const verbText = verb.trim();
+    return OCCURRENCE_VERB.test(verbText)
+        ? identifier(subject)
+        : identifier(`${subject} ${verbText.replace(/^be\s+/i, "")}`);
+}
+// implements REQ-kibi-conditional-requirement-authoring
+export function detectConditionalRule(statement) {
+    const text = statement.trim().replace(/[.!?]+$/, "");
+    const shape = ONLY_WHEN_ANYWHERE.test(text)
+        ? "only_when"
+        : NEGATED_UNLESS_ANYWHERE.test(text)
+            ? "unless"
+            : null;
+    if (shape === null)
+        return null;
+    const scopeMatch = text.match(SCOPE_PREFIX);
+    const scope = scopeMatch?.groups?.scope
+        ? scopeMatch.groups.scope.toLowerCase()
+        : null;
+    const body = scopeMatch ? text.slice(scopeMatch[0].length) : text;
+    const unparsed = (reason) => ({
+        kind: "unparsed",
+        shape,
+        evidence: text,
+        reason,
+    });
+    let action;
+    let conditionText;
+    if (shape === "only_when") {
+        const match = body.match(ONLY_WHEN);
+        const verb = match?.groups?.verbBefore ?? match?.groups?.verbAfter;
+        if (!match?.groups?.action || !verb || !match.groups.condition)
+            return unparsed("The clause says an action happens only under a condition, but its action could not be read.");
+        action = actionName(match.groups.action, verb);
+        conditionText = match.groups.condition;
+    }
+    else {
+        const match = body.match(UNLESS);
+        if (!match?.groups?.action || !match.groups.verb || !match.groups.condition)
+            return unparsed("The clause forbids an action unless a condition holds, but its action could not be read.");
+        action = actionName(match.groups.action, match.groups.verb);
+        conditionText = match.groups.condition;
+    }
+    if (!/^[a-z]/.test(action))
+        return unparsed("The conditional clause names no action that can become a rule head.");
+    const parsed = condition(conditionText);
+    if (!parsed)
+        return unparsed("The condition is not a single comparison of one subject property (for example 'the cart total is positive'); define its terms before grounding it.");
+    const instanceType = parsed.subjectKey;
+    const instance = { kind: "var", name: "X", type: instanceType };
+    const value = {
+        kind: "var",
+        name: "V",
+        type: parsed.comparison.valueType,
+    };
+    const ir = {
+        version: "kibi.logic.v1",
+        kind: "rule",
+        modality: "forbid",
+        head: { kind: "atom", name: action, args: [instance] },
+        body: {
+            kind: "atom",
+            namespace: parsed.subjectKey,
+            name: parsed.propertyKey,
+            args: [instance, value],
+        },
+        exceptions: [
+            {
+                kind: "compare",
+                operator: parsed.comparison.operator,
+                left: value,
+                right: parsed.comparison.value,
+            },
+        ],
+        variables: [
+            { name: "X", type: instanceType },
+            { name: "V", type: parsed.comparison.valueType },
+        ],
+        ...(scope ? { scope: { name: scope } } : {}),
+    };
+    return {
+        kind: "rule",
+        shape,
+        evidence: text,
+        action,
+        subjectKey: parsed.subjectKey,
+        propertyKey: parsed.propertyKey,
+        scope,
+        ir,
+    };
+}

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

@@ -13,6 +13,8 @@ type SemanticRelationship = Readonly<{
 }>;
 export declare function validateSemanticInventoryBoundary(payload: Payload, relationships: readonly SemanticRelationship[], receipt: SemanticAdvisorReceipt): SemanticInventoryBoundaryResult;
 export declare function assertSemanticInventoryBoundary(payload: Payload, relationships: readonly SemanticRelationship[], receipt: SemanticAdvisorReceipt): void;
-export declare function assertLogicalGroundingClaimKeys(prolog: PrologPort, payload: Payload, relationships: readonly SemanticRelationship[]): Promise<void>;
+export declare function assertLogicalGroundingClaimKeys(prolog: PrologPort, payload: Payload, relationships: readonly SemanticRelationship[], staged?: Readonly<{
+    entities: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+}>): Promise<void>;
 export {};
 //# sourceMappingURL=ingestion-boundary.d.ts.map

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;AAE3E,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,KAAK,oBAAoB,GAAG,QAAQ,CAAC;IACnC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAgCH,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;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CA+Cf"}
+{"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;AAE3E,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,KAAK,oBAAoB,GAAG,QAAQ,CAAC;IACnC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAgCH,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;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,CAsDf"}