kibi-cli 0.16.1 → 0.18.1

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

@@ -1,14 +1,16 @@
+import { utf8Span, validateLogicIr, } from "../../logic/ir.js";
+import { logicRuleFactId } from "../modeling/logic-modeling.js";
 import { buildAdvisorResult } from "./analysis-receipt.js";
-import { extractSemanticClauses } from "./clauses.js";
+import { extractSemanticClauses, semanticClaimKey, } from "./clauses.js";
 import { observationPlan } from "./observation-plan.js";
 import { detectPredicateRules } from "./predicate-rule.js";
 import { CORE_PREDICATE_RULES } from "./predicate-rules-core.js";
 import { POLICY_PREDICATE_RULES } from "./predicate-rules-policy.js";
 import { PRODUCT_TAIL_PREDICATE_RULES } from "./predicate-rules-product-tail.js";
 import { PRODUCT_PREDICATE_RULES } from "./predicate-rules-product.js";
-import { isRecord, propertiesOf, statementOf, stringValue, } from "./shared.js";
+import { isRecord, payloadHash, propertiesOf, relationship, semanticClausesOf, semanticSourceHash, semanticSourceOf, sourceOf, statementOf, stringValue, } from "./shared.js";
 import { detectStrictSuggestion } from "./strict-rules.js";
-export const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v1";
+export const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v2";
 export { semanticClaimKey } from "./clauses.js";
 const SIGNAL_PATTERNS = [
     {
@@ -50,7 +52,12 @@ const SIGNAL_PATTERNS = [
 ];
 function proseOf(payload) {
     const properties = propertiesOf(payload);
-    return [properties.title, properties.text_ref, properties.description]
+    return [
+        properties.title,
+        properties.semantic_text,
+        properties.text_ref,
+        properties.description,
+    ]
         .map(stringValue)
         .filter(Boolean)
         .join("\n");
@@ -65,10 +72,10 @@ function logicalGroundingSlots(payload) {
         ? payload.relationships
         : [];
     return relationships.filter((relationship) => isRecord(relationship) &&
-        ["requires_property", "requires_predicate"].includes(stringValue(relationship.type))).length;
+        ["requires_property", "requires_predicate", "requires_rule"].includes(stringValue(relationship.type))).length;
 }
-function isModeled(payload, expectedClaimCount) {
-    if (expectedClaimCount === 0)
+function isModeled(payload, expectedClaimKeys) {
+    if (expectedClaimKeys.length === 0)
         return false;
     const relationships = Array.isArray(payload.relationships)
         ? payload.relationships
@@ -77,9 +84,19 @@ function isModeled(payload, expectedClaimCount) {
         .filter(isRecord)
         .map((relationship) => stringValue(relationship.type))
         .filter(Boolean));
-    return (logicalGroundingSlots(payload) >= expectedClaimCount &&
+    const rawInventory = propertiesOf(payload).semantic_inventory;
+    const inventory = Array.isArray(rawInventory)
+        ? rawInventory.filter(isRecord)
+        : [];
+    const modeledClaimKeys = inventory
+        .filter(({ status }) => status === "modeled")
+        .map(({ claim_key }) => stringValue(claim_key));
+    return (logicalGroundingSlots(payload) === expectedClaimKeys.length &&
+        modeledClaimKeys.length === expectedClaimKeys.length &&
+        expectedClaimKeys.every((claimKey) => modeledClaimKeys.includes(claimKey)) &&
         ((types.has("constrains") && types.has("requires_property")) ||
-            types.has("requires_predicate")));
+            types.has("requires_predicate") ||
+            types.has("requires_rule")));
 }
 function detectSignals(prose) {
     const seen = new Set();
@@ -149,19 +166,87 @@ function predicateSuggestion(payload, statement) {
         detectPredicateRules(payload, statement, PRODUCT_PREDICATE_RULES) ??
         detectPredicateRules(payload, statement, PRODUCT_TAIL_PREDICATE_RULES));
 }
-function modelingSuggestions(payload, modeled, clauses) {
+function ruleSuggestion(payload, candidate) {
+    const validation = validateLogicIr(candidate.ir);
+    if (!validation.valid ||
+        !validation.normalized ||
+        !validation.semanticKey ||
+        !validation.renderedProlog)
+        return null;
+    const reqId = stringValue(payload.id);
+    const semanticKey = validation.semanticKey;
+    const schemaId = candidate.ir.ruleSchemaId ?? "FACT-RULE-SCHEMA-LOGIC-V1";
+    const factId = logicRuleFactId(semanticKey);
+    const schemaPlan = candidate.ir.ruleSchemaId
+        ? []
+        : [
+            {
+                type: "fact",
+                id: schemaId,
+                properties: {
+                    title: "kibi.logic.v1 rule schema",
+                    status: "active",
+                    source: sourceOf(payload),
+                    fact_kind: "rule_schema",
+                    rule_name: "kibi.logic.v1",
+                    argument_names: ["rule_ir"],
+                    argument_types: ["logic_ir"],
+                    aliases: ["conditional rule", "constraint", "policy rule"],
+                    examples: [validation.renderedProlog],
+                },
+                relationships: [],
+            },
+        ];
+    return {
+        kind: "rule",
+        claim_key: candidate.claim_key,
+        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.",
+        suggested_next_tool: "kb_model_requirement",
+        rule: validation.normalized,
+        semantic_key: semanticKey,
+        rendered_prolog: validation.renderedProlog,
+        rejected_alternatives: ["raw_prolog", "observation_review"],
+        applyPlan: [
+            ...schemaPlan,
+            {
+                type: "fact",
+                id: factId,
+                properties: {
+                    title: `${candidate.ir.kind} rule ${semanticKey}`,
+                    status: "active",
+                    source: sourceOf(payload),
+                    fact_kind: "rule",
+                    rule_ir: validation.normalized,
+                    rule_hash: validation.ruleHash,
+                    semantic_key: semanticKey,
+                    rule_schema_id: schemaId,
+                    rule_name: validation.normalized.ruleSchemaId ?? "kibi.logic.v1",
+                    canonical_key: semanticKey,
+                    tags: ["lane:logic", "semantic-advisor-suggestion"],
+                },
+                relationships: [],
+            },
+        ],
+        relationshipPlan: reqId
+            ? {
+                applyAfter: factId,
+                requiresExistingReq: reqId,
+                relationship: relationship(reqId, factId, "requires_rule"),
+            }
+            : null,
+    };
+}
+function modelingSuggestions(payload, modeled, clauses, interpretations) {
     if (!isRequirement(payload) || modeled)
         return [];
     const suggestions = [];
     const seen = new Set();
     const expectedClaimKeys = clauses
-        .filter((clause) => clause.normative)
+        .filter((clause) => !["rationale", "example", "subjective"].includes(propositionRole(clause.text, clause.normative)))
         .map((clause) => clause.claim_key);
-    const rawDeclaredClaimKeys = propertiesOf(payload).logic_claims;
-    const declaredClaimKeys = Array.isArray(rawDeclaredClaimKeys)
-        ? rawDeclaredClaimKeys.filter((value) => typeof value === "string")
-        : [];
-    const mergedClaimKeys = Array.from(new Set([...declaredClaimKeys, ...expectedClaimKeys]));
     for (const clause of clauses) {
         const candidate = clause.text;
         const rawSuggestion = predicateSuggestion(payload, candidate) ??
@@ -169,9 +254,9 @@ function modelingSuggestions(payload, modeled, clauses) {
             ambiguitySuggestion(payload, candidate) ??
             detectStrictSuggestion(payload, candidate);
         const suggestion = rawSuggestion
-            ? withClauseProvenance(rawSuggestion, clause, mergedClaimKeys)
+            ? withClauseProvenance(rawSuggestion, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field)
             : clause.normative
-                ? unmatchedClauseSuggestion(payload, clause, mergedClaimKeys)
+                ? unmatchedClauseSuggestion(payload, clause, clauses, expectedClaimKeys)
                 : null;
         if (!suggestion)
             continue;
@@ -181,9 +266,63 @@ function modelingSuggestions(payload, modeled, clauses) {
             suggestions.push(suggestion);
         }
     }
+    for (const interpretation of interpretations ?? []) {
+        const clause = clauses.find((entry) => entry.claim_key === interpretation.claim_key);
+        if (!clause)
+            continue;
+        const suggestion = ruleSuggestion(payload, interpretation);
+        if (!suggestion)
+            continue;
+        const withProvenance = withClauseProvenance(suggestion, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field);
+        const key = withProvenance.kind === "rule"
+            ? `${withProvenance.claim_key}:rule:${withProvenance.semantic_key}`
+            : `${withProvenance.claim_key}:${withProvenance.kind}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            suggestions.push(withProvenance);
+        }
+    }
     return suggestions;
 }
-function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
+function withClauseProvenance(suggestion, clause, clauses, expectedClaimKeys, statement, sourceField) {
+    const clauseOffset = statement.indexOf(clause.text);
+    const clauseSpan = utf8Span(statement || clause.text, clauseOffset >= 0 ? clauseOffset : 0, clauseOffset >= 0 ? clauseOffset + clause.text.length : clause.text.length);
+    const status = suggestion.kind === "ambiguity_observation"
+        ? "ambiguous"
+        : suggestion.kind === "ontology_gap"
+            ? "ontology_gap"
+            : "modeled";
+    let inventoryCursor = 0;
+    const semanticInventory = clauses.map((entry) => {
+        const located = propositionSpan(statement, entry, inventoryCursor);
+        inventoryCursor = located.next;
+        const role = propositionRole(entry.text, entry.normative);
+        const context = ["rationale", "example", "subjective"].includes(role);
+        const entryStatus = entry.index === clause.index
+            ? status
+            : context
+                ? "nonlogical"
+                : "missing";
+        return {
+            claim_key: entry.claim_key,
+            claim_text: entry.text,
+            role,
+            status: entryStatus,
+            span: located.span,
+            reason: entry.index === clause.index
+                ? status === "modeled"
+                    ? "Draft apply plan contains a typed grounding for this proposition."
+                    : suggestion.rationale
+                : context
+                    ? "Prose is retained for human context and is not a verifiable domain proposition."
+                    : "No typed grounding is included for this proposition in the current draft plan.",
+        };
+    });
+    const inventoryContract = {
+        version: "kibi.semantic-inventory.v1",
+        source_field: sourceField,
+        source_hash: semanticSourceHash(statement),
+    };
     const applyPlan = suggestion.applyPlan.map((step) => {
         if (!isRecord(step))
             return step;
@@ -199,6 +338,11 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
                 properties: {
                     ...properties,
                     logic_claims: Array.from(new Set([...existing, ...expectedClaimKeys])),
+                    semantic_clauses: clauses.map(({ text }) => text),
+                    semantic_inventory_version: inventoryContract.version,
+                    semantic_source_field: inventoryContract.source_field,
+                    semantic_source_hash: inventoryContract.source_hash,
+                    semantic_inventory: semanticInventory,
                 },
             };
         }
@@ -210,6 +354,8 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
                 ...properties,
                 claim_key: clause.claim_key,
                 claim_text: clause.text,
+                claim_span_start: clauseSpan.start,
+                claim_span_end: clauseSpan.end,
             },
         };
     });
@@ -225,13 +371,30 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
                     claimKey: clause.claim_key,
                     claimText: clause.text,
                     logicClaims: expectedClaimKeys,
+                    semanticClauses: clauses.map(({ text }) => text),
+                    semanticInventory,
+                    inventoryContract,
                     instructions: "Create the predicate fact, merge the returned logicClaims into the requirement logic_claims manifest, then add requires_predicate without overwriting other requirement metadata.",
                 },
             }
             : {}),
+        ...(suggestion.kind === "rule" && suggestion.relationshipPlan !== null
+            ? {
+                relationshipPlan: {
+                    ...suggestion.relationshipPlan,
+                    claimKey: clause.claim_key,
+                    claimText: clause.text,
+                    logicClaims: expectedClaimKeys,
+                    semanticClauses: clauses.map(({ text }) => text),
+                    semanticInventory,
+                    inventoryContract,
+                    instructions: "Create the rule_schema and rule facts, merge the returned logicClaims into the requirement logic_claims manifest, then add requires_rule without overwriting other requirement metadata.",
+                },
+            }
+            : {}),
     };
 }
-function unmatchedClauseSuggestion(payload, clause, expectedClaimKeys) {
+function unmatchedClauseSuggestion(payload, clause, clauses, expectedClaimKeys) {
     return withClauseProvenance({
         kind: "ontology_gap",
         claim_key: clause.claim_key,
@@ -246,26 +409,300 @@ function unmatchedClauseSuggestion(payload, clause, expectedClaimKeys) {
             "review:ontology-gap",
             "needs_schema_extension",
         ]),
-    }, clause, expectedClaimKeys);
+    }, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field);
+}
+function propositionRole(statement, normative) {
+    if (/\b(?:for example|e\.g\.|such as|illustrative)\b/i.test(statement))
+        return "example";
+    if (/\b(?:because|so that|in order to| rationale|therefore)\b/i.test(statement))
+        return "rationale";
+    if (/\b(?:feel|comfortable|looks complete|seems complete|subjective|prefer)\b/i.test(statement))
+        return "subjective";
+    if (/\b(?:means|defined as|refers to|is called)\b/i.test(statement))
+        return "definition";
+    if (/^\s*(?:if|when|whenever|provided that|only if)\b/i.test(statement))
+        return "condition";
+    if (/\b(?:unless|except|exempt|apart from)\b/i.test(statement))
+        return "exception";
+    if (normative)
+        return "normative";
+    return "descriptive";
+}
+function shadowAnalysis(text, interpretations) {
+    const valid = interpretations.filter((interpretation) => interpretation.valid);
+    const models = valid.flatMap(({ normalized_ir: ir }) => (ir ? [ir] : []));
+    const containsExpressionKind = (kind) => {
+        const visit = (value) => {
+            if (!isRecord(value))
+                return false;
+            if (value.kind === kind)
+                return true;
+            return Object.values(value).some((child) => Array.isArray(child) ? child.some(visit) : visit(child));
+        };
+        return models.some((model) => visit(model));
+    };
+    const hasModality = (modalities) => models.some((model) => modalities.includes(model.modality));
+    const hasNegativeAtom = (() => {
+        const visit = (value) => {
+            if (!isRecord(value))
+                return false;
+            if (value.kind === "not" || value.polarity === "negative")
+                return true;
+            return Object.values(value).some((child) => Array.isArray(child) ? child.some(visit) : visit(child));
+        };
+        return models.some((model) => visit(model));
+    })();
+    const cues = [
+        {
+            kind: "modal",
+            pattern: /\b(?:must|shall|should|may|can)\b/i,
+            evidence: "deontic modal",
+            represented: models.length > 0,
+        },
+        {
+            kind: "polarity",
+            pattern: /\b(?:assert|deny|forbid|allowed|permitted|prohibited)\b/i,
+            evidence: "polarity cue",
+            represented: hasModality(["deny", "forbid", "permit"]) || hasNegativeAtom,
+        },
+        {
+            kind: "passive_voice",
+            pattern: /\b(?:is|are|be|was|were)\s+[a-z]+ed\b/i,
+            evidence: "passive construction",
+            represented: false,
+        },
+        {
+            kind: "nominalization",
+            pattern: /\b[a-z]+(?:tion|ment|ity|ance|ence)\b/i,
+            evidence: "nominalized domain term",
+            represented: false,
+        },
+        {
+            kind: "conditional",
+            pattern: /\b(?:if|when|whenever|provided that)\b/i,
+            evidence: "conditional",
+            represented: models.some(({ kind, body }) => kind === "rule" && body !== undefined),
+        },
+        {
+            kind: "causal",
+            pattern: /\b(?:because|so that|therefore|as a result)\b/i,
+            evidence: "causal relation",
+            represented: false,
+        },
+        {
+            kind: "prerequisite",
+            pattern: /\b(?:before|only after|requires?\s+.+?\s+before)\b/i,
+            evidence: "prerequisite/order relation",
+            represented: containsExpressionKind("temporal"),
+        },
+        {
+            kind: "exception",
+            pattern: /\b(?:unless|except|exempt|apart from)\b/i,
+            evidence: "exception",
+            represented: models.some(({ exceptions }) => (exceptions?.length ?? 0) > 0) ||
+                containsExpressionKind("not"),
+        },
+        {
+            kind: "temporal",
+            pattern: /\b(?:before|after|during|until|within|expires?|retained for)\b/i,
+            evidence: "temporal qualifier",
+            represented: containsExpressionKind("temporal") ||
+                models.some(({ validFrom, validTo }) => validFrom !== undefined || validTo !== undefined) ||
+                containsExpressionKind("duration"),
+        },
+        {
+            kind: "quantifier",
+            pattern: /\b(?:each|every|all|any|some|only|at least|at most|exactly|no more than)\b/i,
+            evidence: "quantifier/cardinality",
+            represented: models.some(({ variables }) => (variables?.length ?? 0) > 0) ||
+                containsExpressionKind("count") ||
+                containsExpressionKind("compare") ||
+                containsExpressionKind("all") ||
+                containsExpressionKind("any"),
+        },
+        {
+            kind: "numeric",
+            pattern: /\b\d+(?:\.\d+)?\b|\b(?:zero|one|two|three|four|five|six|seven|eight|nine|ten)\b/i,
+            evidence: "numeric or cardinality value",
+            represented: containsExpressionKind("number") ||
+                containsExpressionKind("count") ||
+                containsExpressionKind("compare"),
+        },
+        {
+            kind: "negation_scope",
+            pattern: /\b(?:not|never|no|without|cannot|can't|must not)\b/i,
+            evidence: "negation scope",
+            represented: hasModality(["deny", "forbid"]) || hasNegativeAtom,
+        },
+        {
+            kind: "directionality",
+            pattern: /\b(?:only if|if and only if|unless|when)\b/i,
+            evidence: "condition direction",
+            represented: models.some(({ kind, body }) => kind === "rule" && body !== undefined),
+        },
+    ];
+    return cues
+        .filter((cue) => cue.pattern.test(text))
+        .map(({ kind, evidence, represented }) => ({
+        kind,
+        evidence,
+        represented,
+    }));
+}
+function propositionSpan(text, clause, cursor) {
+    const exact = text.indexOf(clause.text, cursor);
+    const start = exact >= 0 ? exact : cursor;
+    const end = exact >= 0
+        ? exact + clause.text.length
+        : Math.min(text.length, start + clause.text.length);
+    return { span: utf8Span(text, start, end), next: Math.max(cursor, end) };
+}
+function interpretationResults(interpretations, clauses, statement) {
+    if (interpretations === undefined)
+        return { results: [], warnings: [] };
+    const known = new Set(clauses.map((clause) => clause.claim_key));
+    const semanticKeys = new Map();
+    const warnings = [];
+    const results = interpretations.slice(0, 3).map((candidate) => {
+        const confidence = Math.max(0, Math.min(1, candidate.confidence ?? 0.5));
+        const validation = validateLogicIr(candidate.ir);
+        const errors = [...validation.errors];
+        const clause = clauses.find((entry) => entry.claim_key === candidate.claim_key);
+        if (!known.has(candidate.claim_key))
+            errors.push(`claim_key ${candidate.claim_key} is not present in the advisor proposition inventory`);
+        if (clause &&
+            candidate.claim_text !== clause.text &&
+            semanticClaimKey(candidate.claim_text) !== clause.claim_key)
+            errors.push(`claim_text for ${candidate.claim_key} must match the proposition text (apart from normalized punctuation)`);
+        if (candidate.span &&
+            (candidate.span.start < 0 || candidate.span.end < candidate.span.start))
+            errors.push("interpretation span is invalid");
+        if (clause && candidate.span) {
+            const candidateStart = statement.indexOf(candidate.claim_text);
+            const clauseStart = statement.indexOf(clause.text);
+            const sourceStart = candidateStart >= 0 ? candidateStart : clauseStart;
+            const sourceEnd = sourceStart >= 0
+                ? sourceStart +
+                    (candidateStart >= 0
+                        ? candidate.claim_text.length
+                        : clause.text.length)
+                : 0;
+            const expectedSpan = utf8Span(statement, Math.max(0, sourceStart), Math.max(0, sourceEnd));
+            if (candidate.span.start !== expectedSpan.start ||
+                candidate.span.end !== expectedSpan.end)
+                errors.push(`interpretation span for ${candidate.claim_key} does not match the exact UTF-8 proposition span`);
+        }
+        const semanticKey = validation.semanticKey;
+        if (semanticKey !== undefined) {
+            const prior = semanticKeys.get(candidate.claim_key);
+            if (prior !== undefined && prior !== semanticKey)
+                warnings.push(`Claim ${candidate.claim_key} has materially different interpretations; it remains unresolved until one is selected.`);
+            semanticKeys.set(candidate.claim_key, semanticKey);
+        }
+        return {
+            claim_key: candidate.claim_key,
+            ...(semanticKey ? { semantic_key: semanticKey } : {}),
+            ...(validation.normalized
+                ? { normalized_ir: validation.normalized }
+                : {}),
+            valid: errors.length === 0 && validation.valid,
+            confidence,
+            errors,
+            warnings: validation.warnings,
+            ...(validation.renderedProlog
+                ? { rendered_prolog: validation.renderedProlog }
+                : {}),
+        };
+    });
+    if (interpretations.length > 3)
+        warnings.push("Only the first three interpretations are considered; submit materially distinct alternatives explicitly and resolve them before writing.");
+    return { results, warnings };
+}
+function propositionInventory(statement, clauses, suggestions, interpretations, inputPayloadHash) {
+    const interpretationKeys = new Map();
+    for (const interpretation of interpretations) {
+        if (!interpretation.valid || !interpretation.semantic_key)
+            continue;
+        const keys = interpretationKeys.get(interpretation.claim_key) ?? new Set();
+        keys.add(interpretation.semantic_key);
+        interpretationKeys.set(interpretation.claim_key, keys);
+    }
+    let cursor = 0;
+    return clauses.map((clause) => {
+        const located = propositionSpan(statement, clause, cursor);
+        cursor = located.next;
+        const role = propositionRole(clause.text, clause.normative);
+        const suggestion = suggestions.find((candidate) => candidate.claim_key === clause.claim_key);
+        let status;
+        let reason;
+        const keys = interpretationKeys.get(clause.claim_key);
+        const semanticKey = keys?.size === 1 ? [...keys][0] : undefined;
+        if (keys && keys.size > 1) {
+            status = "ambiguous";
+            reason =
+                "Materially different valid interpretations were submitted; confidence cannot choose between them.";
+        }
+        else if (semanticKey) {
+            status = "modeled";
+        }
+        else if (role === "rationale" ||
+            role === "example" ||
+            role === "subjective") {
+            status = "nonlogical";
+            reason =
+                "Prose is retained for human context but does not assert a verifiable domain proposition.";
+        }
+        else if (suggestion?.kind === "ambiguity_observation") {
+            status = "ambiguous";
+            reason = suggestion.rationale;
+        }
+        else if (suggestion?.kind === "ontology_gap") {
+            status = "ontology_gap";
+            reason = suggestion.rationale;
+        }
+        else {
+            status = "missing";
+            reason =
+                "No accepted typed interpretation grounds this assertive proposition.";
+        }
+        return {
+            claim_key: clause.claim_key,
+            claim_text: clause.text,
+            role,
+            status,
+            span: located.span,
+            payload_hash: inputPayloadHash,
+            ...(semanticKey ? { semantic_key: semanticKey } : {}),
+            ...(reason ? { reason } : {}),
+        };
+    });
 }
 export function analyzeSemanticAdvisorInput(input) {
     const payload = input.payload;
     const requirement = isRequirement(payload);
+    const statement = statementOf(payload) || proseOf(payload);
     const signals = requirement ? detectSignals(proseOf(payload)) : [];
-    const clauses = requirement
-        ? extractSemanticClauses(statementOf(payload), input.clauses)
+    const clauses = statement
+        ? extractSemanticClauses(statement, input.clauses ?? semanticClausesOf(payload))
         : [];
     const rawDeclaredClaims = propertiesOf(payload).logic_claims;
     const declaredClaims = Array.isArray(rawDeclaredClaims)
         ? rawDeclaredClaims.filter((value) => typeof value === "string")
         : [];
     const expectedClaims = clauses
-        .filter((clause) => clause.normative)
+        .filter((clause) => !["rationale", "example", "subjective"].includes(propositionRole(clause.text, clause.normative)))
         .map((clause) => clause.claim_key);
     const modeled = requirement &&
-        isModeled(payload, expectedClaims.length) &&
+        isModeled(payload, expectedClaims) &&
         expectedClaims.length > 0 &&
         expectedClaims.every((claimKey) => declaredClaims.includes(claimKey));
-    const suggestions = modelingSuggestions(payload, modeled, clauses);
-    return buildAdvisorResult(payload, signals, modeled, suggestions, clauses);
+    const suggestions = modelingSuggestions(payload, modeled, clauses, input.interpretations);
+    const interpreted = interpretationResults(input.interpretations, clauses, statement);
+    const propositions = propositionInventory(statement, clauses, suggestions, interpreted.results, payloadHash(payload));
+    const shadow = shadowAnalysis(statement, interpreted.results);
+    const result = buildAdvisorResult(payload, signals, modeled, suggestions, clauses, propositions, interpreted.results, shadow);
+    return {
+        receipt: result.receipt,
+        warnings: [...result.warnings, ...interpreted.warnings],
+    };
 }

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

@@ -5,6 +5,7 @@ export type SemanticClause = Readonly<{
     normative: boolean;
     source: "detected" | "supplied";
 }>;
+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[];
 //# sourceMappingURL=clauses.d.ts.map

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;AAkBH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAeD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CAgB3B"}
+{"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;AAKH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAeD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CAgB3B"}

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

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 const NORMATIVE_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|forbidden|denied|defaults?\s+to|before|unless|when|if)\b/i;
-function normalizeClause(value) {
+export function normalizeSemanticClause(value) {
     return (value
         .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "")
         .replace(/\s+/g, " ")
@@ -11,7 +11,7 @@ function normalizeClause(value) {
         .trim());
 }
 export function semanticClaimKey(text) {
-    const normalized = normalizeClause(text).toLowerCase();
+    const normalized = normalizeSemanticClause(text).toLowerCase();
     const digest = createHash("sha256").update(normalized).digest("hex");
     return `CLAIM-${digest.slice(0, 16).toUpperCase()}`;
 }
@@ -23,21 +23,21 @@ function detectedClauses(text) {
             return [sentence];
         return sentence.split(/\s+(?:,\s*)?and\s+(?=(?:the\s+)?[a-z][^.!?]{0,100}\b(?:must|shall|should|requires?|cannot|can't|expire|default|transition|states?\s+are)\b)/i);
     })
-        .map(normalizeClause)
+        .map(normalizeSemanticClause)
         .filter(Boolean);
 }
 export function extractSemanticClauses(text, suppliedClauses) {
     const source = suppliedClauses === undefined ? "detected" : "supplied";
     const raw = suppliedClauses ?? detectedClauses(text);
-    const unique = Array.from(new Set(raw.map(normalizeClause).filter(Boolean)));
-    if (suppliedClauses !== undefined && unique.length === 0) {
+    const normalized = raw.map(normalizeSemanticClause).filter(Boolean);
+    if (suppliedClauses !== undefined && normalized.length === 0) {
         throw new Error("Semantic advisor clauses must contain at least one non-empty atomic claim");
     }
-    return unique.map((clause, index) => ({
+    return normalized.map((clause, index) => ({
         claim_key: semanticClaimKey(clause),
         text: clause,
         index,
-        normative: source === "supplied" || NORMATIVE_PATTERN.test(clause),
+        normative: NORMATIVE_PATTERN.test(clause),
         source,
     }));
 }

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

@@ -0,0 +1,18 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import { type Payload } from "./shared.js";
+import type { SemanticAdvisorReceipt } from "./types.js";
+export interface SemanticInventoryBoundaryResult {
+    readonly applicable: boolean;
+    readonly errors: readonly string[];
+    readonly sourceHash: string;
+}
+type SemanticRelationship = Readonly<{
+    type?: unknown;
+    from?: unknown;
+    to?: unknown;
+}>;
+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 {};
+//# sourceMappingURL=ingestion-boundary.d.ts.map