kibi-cli 0.16.1 → 0.17.0

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

@@ -19,15 +19,19 @@ function summary(readiness, lane) {
         return "Requirement prose appears to contain scalar, threshold, or cardinality logic that should be modeled with strict facts.";
     if (lane === "predicate")
         return "Requirement prose appears to contain relational or behavioral logic that should be modeled with ontology predicates.";
+    if (lane === "rule")
+        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.";
 }
 // implements REQ-mcp-semantic-advisor-preflight
-export function buildAdvisorResult(payload, signals, modeled, suggestions, clauses) {
+export function buildAdvisorResult(payload, signals, modeled, suggestions, clauses, propositions, interpretations, shadowAnalysis) {
     const suggestionLane = suggestions.some(({ kind }) => kind === "strict_property")
         ? "strict_property"
-        : suggestions.some(({ kind }) => kind === "predicate")
-            ? "predicate"
-            : null;
+        : suggestions.some(({ kind }) => kind === "rule")
+            ? "rule"
+            : suggestions.some(({ kind }) => kind === "predicate")
+                ? "predicate"
+                : null;
     const candidateLane = modeled
         ? "none"
         : (suggestionLane ?? chooseLane(signals));
@@ -42,21 +46,22 @@ export function buildAdvisorResult(payload, signals, modeled, suggestions, claus
             ? ["kb_model_requirement"]
             : candidateLane === "predicate"
                 ? ["kb_suggest_predicates"]
-                : candidateLane === "observation_review"
-                    ? ["kb_model_requirement", "kb_suggest_predicates"]
-                    : [];
-    const expectedClaimKeys = clauses
-        .filter((clause) => clause.normative)
-        .map((clause) => clause.claim_key);
+                : candidateLane === "rule"
+                    ? ["kb_model_requirement"]
+                    : candidateLane === "observation_review"
+                        ? ["kb_model_requirement", "kb_suggest_predicates"]
+                        : [];
+    const expectedClaimKeys = propositions
+        .filter(({ role }) => !["rationale", "example", "subjective"].includes(role))
+        .map(({ claim_key }) => claim_key);
     const rawDeclaredClaimKeys = propertiesOf(payload).logic_claims;
     const declaredClaimKeys = Array.isArray(rawDeclaredClaimKeys)
         ? rawDeclaredClaimKeys.filter((value) => typeof value === "string")
         : [];
     const missingClaimKeys = expectedClaimKeys.filter((claimKey) => !declaredClaimKeys.includes(claimKey));
-    const unresolvedClaimKeys = suggestions
-        .filter((suggestion) => suggestion.kind === "ambiguity_observation" ||
-        suggestion.kind === "ontology_gap")
-        .map((suggestion) => suggestion.claim_key);
+    const unresolvedClaimKeys = propositions
+        .filter(({ status }) => ["ambiguous", "ontology_gap", "missing"].includes(status))
+        .map(({ claim_key }) => claim_key);
     const coverageStatus = expectedClaimKeys.length === 0
         ? "not_applicable"
         : modeled
@@ -65,7 +70,7 @@ export function buildAdvisorResult(payload, signals, modeled, suggestions, claus
                 ? "unverified"
                 : "partial";
     const receipt = {
-        version: "semantic-advisor-v1",
+        version: "semantic-advisor-v2",
         payload_hash: payloadHash(payload),
         logic_readiness: readiness,
         candidate_lane: candidateLane,
@@ -86,6 +91,9 @@ export function buildAdvisorResult(payload, signals, modeled, suggestions, claus
                 ],
                 message: "Numeric cardinality prose can mean an exact count, an upper/lower bound, named membership, or an example; model it explicitly before relying on contradiction checks.",
             })),
+        propositions,
+        interpretations,
+        shadow_analysis: shadowAnalysis,
         suggestions,
         clauses: clauses.map((clause) => ({
             ...clause,

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

@@ -1,5 +1,5 @@
 import type { SemanticAdvisorAnalysisResult, SemanticAdvisorInput } from "./types.js";
-export declare const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v1";
+export declare const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v2";
 export { semanticClaimKey } from "./clauses.js";
 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":"AAgBA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAsThD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CAuB/B"}
+{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA6zBhD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CAuD/B"}

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, 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 = [
     {
@@ -65,7 +67,7 @@ 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)
@@ -79,7 +81,8 @@ function isModeled(payload, expectedClaimCount) {
         .filter(Boolean));
     return (logicalGroundingSlots(payload) >= expectedClaimCount &&
         ((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,7 +152,80 @@ 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 = [];
@@ -169,7 +245,7 @@ function modelingSuggestions(payload, modeled, clauses) {
             ambiguitySuggestion(payload, candidate) ??
             detectStrictSuggestion(payload, candidate);
         const suggestion = rawSuggestion
-            ? withClauseProvenance(rawSuggestion, clause, mergedClaimKeys)
+            ? withClauseProvenance(rawSuggestion, clause, mergedClaimKeys, statementOf(payload))
             : clause.normative
                 ? unmatchedClauseSuggestion(payload, clause, mergedClaimKeys)
                 : null;
@@ -181,9 +257,27 @@ 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, mergedClaimKeys, statementOf(payload));
+        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, expectedClaimKeys, statement) {
+    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 applyPlan = suggestion.applyPlan.map((step) => {
         if (!isRecord(step))
             return step;
@@ -194,11 +288,32 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
             const existing = Array.isArray(properties.logic_claims)
                 ? properties.logic_claims.filter((value) => typeof value === "string")
                 : [];
+            const inventory = Array.isArray(properties.semantic_inventory)
+                ? properties.semantic_inventory.filter(isRecord)
+                : [];
+            const status = suggestion.kind === "ambiguity_observation"
+                ? "ambiguous"
+                : suggestion.kind === "ontology_gap"
+                    ? "ontology_gap"
+                    : "modeled";
             return {
                 ...step,
                 properties: {
                     ...properties,
                     logic_claims: Array.from(new Set([...existing, ...expectedClaimKeys])),
+                    semantic_inventory: [
+                        ...inventory.filter((entry) => entry.claim_key !== clause.claim_key),
+                        {
+                            claim_key: clause.claim_key,
+                            claim_text: clause.text,
+                            role: clause.normative ? "normative" : "descriptive",
+                            status,
+                            span: clauseSpan,
+                            reason: status === "modeled"
+                                ? "Draft apply plan contains a typed grounding for this proposition."
+                                : suggestion.rationale,
+                        },
+                    ],
                 },
             };
         }
@@ -210,6 +325,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,10 +342,41 @@ function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
                     claimKey: clause.claim_key,
                     claimText: clause.text,
                     logicClaims: expectedClaimKeys,
+                    semanticInventory: [
+                        {
+                            claim_key: clause.claim_key,
+                            claim_text: clause.text,
+                            role: clause.normative ? "normative" : "descriptive",
+                            status: "modeled",
+                            span: clauseSpan,
+                            reason: "The returned typed fact grounds this proposition.",
+                        },
+                    ],
                     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,
+                    semanticInventory: [
+                        {
+                            claim_key: clause.claim_key,
+                            claim_text: clause.text,
+                            role: clause.normative ? "normative" : "descriptive",
+                            status: "modeled",
+                            span: clauseSpan,
+                            reason: "The returned typed rule grounds this proposition.",
+                        },
+                    ],
+                    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) {
@@ -246,14 +394,281 @@ function unmatchedClauseSuggestion(payload, clause, expectedClaimKeys) {
             "review:ontology-gap",
             "needs_schema_extension",
         ]),
-    }, clause, expectedClaimKeys);
+    }, clause, expectedClaimKeys, statementOf(payload));
+}
+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)
         : [];
     const rawDeclaredClaims = propertiesOf(payload).logic_claims;
     const declaredClaims = Array.isArray(rawDeclaredClaims)
@@ -266,6 +681,13 @@ export function analyzeSemanticAdvisorInput(input) {
         isModeled(payload, expectedClaims.length) &&
         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/observation-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/observation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,aAAa,CAAC;AAGrB,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAgB9C"}
+{"version":3,"file":"observation-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/observation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAMb,MAAM,aAAa,CAAC;AAGrB,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CA6B9C"}

package/dist/operations/semantic-advisor/observation-plan.js

@@ -1,10 +1,20 @@
-import { shortHash, sourceOf, statementOf, stringValue, } from "./shared.js";
+import { relationship, shortHash, sourceOf, statementOf, stringValue, } from "./shared.js";
 // implements REQ-mcp-semantic-advisor-preflight
 export function observationPlan(payload, title, tags) {
+    const factId = `FACT-OBS-${shortHash(`${stringValue(payload.id)}.${title}.${statementOf(payload)}`)}`;
+    const target = tags.includes("review:ambiguity")
+        ? "review:ambiguous-claim"
+        : tags.includes("review:keyword-false-positive")
+            ? "review:keyword-false-positive"
+            : tags.includes("review:ontology-gap")
+                ? "review:ontology-gap"
+                : tags.includes("review:nonlogical")
+                    ? "review:nonlogical"
+                    : undefined;
     return [
         {
             type: "fact",
-            id: `FACT-OBS-${shortHash(`${stringValue(payload.id)}.${title}.${statementOf(payload)}`)}`,
+            id: factId,
             properties: {
                 title,
                 status: "active",
@@ -13,7 +23,9 @@ export function observationPlan(payload, title, tags) {
                 text_ref: statementOf(payload),
                 tags,
             },
-            relationships: [],
+            relationships: target === undefined
+                ? []
+                : [relationship(factId, target, "relates_to")],
         },
     ];
 }