kibi-cli 0.19.0 → 2.0.0

package/dist/operations/modeling/suggest-predicates.js

@@ -1,68 +1,238 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
-import { buildGapApplyPlan, buildPredicateApplyPlan, buildRelationshipPlan, buildSuggestion, } from "./predicate-applyplan.js";
+import { STRONG_APPLICABILITY_SCORE, WEAK_CANDIDATE_MARGIN, evaluateSemanticApplicability, } from "./predicate-applicability.js";
+import { buildGapApplyPlan, buildPredicateApplyPlan, buildPredicateSchemaDraft, buildRelationshipPlan, buildSuggestion, } from "./predicate-applyplan.js";
 import { BUILT_IN_PREDICATE_SCHEMAS } from "./predicate-catalog.js";
 import { inferSubject } from "./predicate-inference.js";
 import { loadExistingPredicateSchemas } from "./predicate-loader.js";
-import { scoreSchema } from "./predicate-ranker.js";
+import { rankSchema } from "./predicate-ranker.js";
 import { clampInteger, clampScore, normalizeText } from "./predicate-utils.js";
 const DEFAULT_MAX_CANDIDATES = 5;
+const DEFAULT_MIN_SCORE = 0.35;
+const NON_ASSERTIVE_PROPOSITION_ROLES = new Set([
+    "rationale",
+    "example",
+    "subjective",
+]);
+function analyzeInputPropositions(text) {
+    return analyzeSemanticAdvisorInput({
+        payload: {
+            type: "req",
+            id: "REQ-KIBI-PREDICATE-SUGGESTION-INPUT",
+            properties: { semantic_text: text },
+        },
+    }).receipt.propositions;
+}
+function compoundInputAbstention(args, text, subject, propositionCount) {
+    const claimKey = semanticClaimKey(text);
+    const warning = `kb_suggest_predicates requires one atomic assertive proposition; semantic advisor detected ${propositionCount}. Split the input into atomic propositions and retry each one. No candidate, ontology-gap draft, or write plan was generated.`;
+    const applyPlan = [];
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Predicate suggestion abstained because the input contains multiple assertive propositions. Split the prose into atomic propositions and retry each one.",
+            },
+        ],
+        structuredContent: {
+            text,
+            claimKey,
+            logicClaims: Array.from(new Set(args.existingLogicClaims ?? [])),
+            source: args.source ?? null,
+            requirementId: args.requirementId ?? null,
+            subject,
+            candidates: [],
+            recommendedAction: "record_ontology_gap",
+            recommendedPredicateSchema: null,
+            applyPlan,
+            relationshipPlan: null,
+            warnings: [warning],
+        },
+        applyPlan,
+    };
+}
+function nonlogicalInputRouting(args, text, subject) {
+    const claimKey = semanticClaimKey(text);
+    const warning = "The semantic advisor classifies this prose as nonlogical (rationale, example, or subjective context); it does not assert a verifiable domain proposition. Advisor routing wins: no predicate candidates, schema draft, or write plan were generated, and the claim was not added to logic_claims.";
+    const applyPlan = [];
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Predicate suggestion abstained because the semantic advisor classifies this prose as nonlogical (rationale, example, or subjective context). Keep it outside logic_claims; no candidate, ontology-gap observation, or schema draft was generated.",
+            },
+        ],
+        structuredContent: {
+            text,
+            claimKey,
+            logicClaims: Array.from(new Set(args.existingLogicClaims ?? [])),
+            source: args.source ?? null,
+            requirementId: args.requirementId ?? null,
+            subject,
+            candidates: [],
+            recommendedAction: "review_nonlogical",
+            recommendedPredicateSchema: null,
+            applyPlan,
+            relationshipPlan: null,
+            warnings: [warning],
+        },
+        applyPlan,
+    };
+}
+function uniqueSchemas(schemas) {
+    const seen = new Set();
+    return schemas.filter((schema) => {
+        const key = `${schema.predicate_name}:${schema.id}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function compareEligibleByApplicabilityThenName(left, right) {
+    if (right.applicability_score !== left.applicability_score)
+        return right.applicability_score - left.applicability_score;
+    return left.predicate_name.localeCompare(right.predicate_name);
+}
+export function compareEligibleByApplicabilityScoreThenName(left, right) {
+    if (right.applicability_score !== left.applicability_score)
+        return right.applicability_score - left.applicability_score;
+    if (right.score !== left.score)
+        return right.score - left.score;
+    return left.predicate_name.localeCompare(right.predicate_name);
+}
+function withMarginRejection(candidates) {
+    const eligible = candidates
+        .filter((candidate) => candidate.eligibility === "eligible")
+        .sort(compareEligibleByApplicabilityThenName);
+    const top = eligible[0];
+    const second = eligible[1];
+    if (!top ||
+        !second ||
+        top.applicability_score >= STRONG_APPLICABILITY_SCORE ||
+        top.applicability_score - second.applicability_score >=
+            WEAK_CANDIDATE_MARGIN)
+        return [...candidates];
+    const weakNames = `${top.predicate_name} and ${second.predicate_name}`;
+    return candidates.map((candidate) => {
+        if (candidate.predicate_name !== top.predicate_name &&
+            candidate.predicate_name !== second.predicate_name)
+            return candidate;
+        return {
+            ...candidate,
+            eligibility: "rejected",
+            rejection_reasons: [
+                ...candidate.rejection_reasons,
+                `weak-candidate margin abstention: ${weakNames} are within ${WEAK_CANDIDATE_MARGIN.toFixed(2)} applicability points`,
+            ],
+        };
+    });
+}
 // implements REQ-mcp-suggest-predicates
 export async function handleKbSuggestPredicates(prolog, args) {
     const text = normalizeText(args.text);
+    const subject = inferSubject(text, args.subjectHint);
+    const propositions = analyzeInputPropositions(text);
+    const assertivePropositionCount = propositions.filter((proposition) => !NON_ASSERTIVE_PROPOSITION_ROLES.has(proposition.role)).length;
+    if (propositions.length > 0 && assertivePropositionCount === 0) {
+        return nonlogicalInputRouting(args, text, subject);
+    }
+    if (assertivePropositionCount > 1) {
+        return compoundInputAbstention(args, text, subject, assertivePropositionCount);
+    }
     const maxCandidates = clampInteger(args.maxCandidates, DEFAULT_MAX_CANDIDATES, 1, 20);
-    const minScore = clampScore(args.minScore);
+    const minScore = clampScore(args.minScore ?? DEFAULT_MIN_SCORE);
     const warnings = [];
-    const subject = inferSubject(text, args.subjectHint);
     const existingSchemas = await loadExistingPredicateSchemas(prolog, args.includeExistingSchemas ?? true, warnings);
-    const schemas = [...existingSchemas, ...BUILT_IN_PREDICATE_SCHEMAS];
+    const schemas = uniqueSchemas([
+        ...existingSchemas,
+        ...BUILT_IN_PREDICATE_SCHEMAS,
+    ]);
     const selectedSchemas = args.schemaId
         ? schemas.filter((schema) => schema.id === args.schemaId)
         : schemas;
     if (args.schemaId && selectedSchemas.length === 0) {
         warnings.push(`Requested predicate schema ${args.schemaId} is not available. Refresh the KB or correct schemaId before retrying; no ontology-gap or predicate write plan was generated.`);
     }
-    const candidates = selectedSchemas
-        .map((schema) => ({ schema, score: scoreSchema(schema, text) }))
-        .filter((scored) => args.schemaId || scored.score >= minScore)
+    // Stage 1: retrieval/ranking only. No argument values influence this list.
+    const retrieved = selectedSchemas
+        .map((schema) => rankSchema(schema, text))
+        .filter((ranked) => args.schemaId || ranked.score >= minScore)
         .sort((left, right) => {
         if (right.score !== left.score)
             return right.score - left.score;
+        if (right.components.specificity_bonus !== left.components.specificity_bonus)
+            return (right.components.specificity_bonus - left.components.specificity_bonus);
         return left.schema.predicate_name.localeCompare(right.schema.predicate_name);
     })
-        .slice(0, maxCandidates)
-        .map((scored) => buildSuggestion(scored.schema, text, subject, scored.score, args.argumentBindings, args.polarityHint));
+        // Keep a wider bounded pool for semantic review so a lexical false
+        // positive cannot crowd out a lower-ranked but fitting domain schema.
+        .slice(0, Math.min(50, Math.max(maxCandidates, maxCandidates * 3)));
+    // Stage 2: semantic eligibility. A complete binding list cannot bypass this
+    // gate, and every rejected candidate remains inspectable when retrieved.
+    const initialCandidates = retrieved.map((ranked) => {
+        const applicability = evaluateSemanticApplicability(ranked, text);
+        return buildSuggestion(ranked.schema, text, subject, ranked.score, args.argumentBindings, args.polarityHint, {
+            eligibility: applicability.eligible ? "eligible" : "rejected",
+            rejectionReasons: applicability.reasons,
+            applicabilityScore: applicability.applicabilityScore,
+            scoreComponents: ranked.components,
+            explicitSubject: Boolean(args.subjectHint?.trim()),
+        });
+    });
+    const evaluatedCandidates = withMarginRejection(initialCandidates)
+        .sort((left, right) => {
+        const leftEligible = left.eligibility === "eligible" ? 1 : 0;
+        const rightEligible = right.eligibility === "eligible" ? 1 : 0;
+        if (rightEligible !== leftEligible)
+            return rightEligible - leftEligible;
+        if (right.applicability_score !== left.applicability_score)
+            return right.applicability_score - left.applicability_score;
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return left.predicate_name.localeCompare(right.predicate_name);
+    })
+        .slice(0, maxCandidates);
+    // Preserve the established empty-candidate response when general discovery
+    // finds no applicable schema. Rejected diagnostics remain available beside
+    // an eligible match and for an explicitly requested schema.
+    const candidates = args.schemaId ||
+        evaluatedCandidates.some((candidate) => candidate.eligibility === "eligible")
+        ? evaluatedCandidates
+        : [];
+    const recommendedCandidate = candidates
+        .filter((candidate) => candidate.eligibility === "eligible")
+        .sort(compareEligibleByApplicabilityScoreThenName)[0];
     if (candidates.length === 0 && !args.schemaId) {
         warnings.push("No predicate candidate met minScore. If this is recurring domain language, create a fact_kind=predicate_schema fact; otherwise keep the generated review:ontology-gap observation. Do not invent unsupported predicate names without a predicate_schema.");
     }
-    const firstCandidate = candidates[0];
-    const bindingsComplete = firstCandidate?.binding_status === "complete";
-    if (firstCandidate && !bindingsComplete) {
-        warnings.push(`Top predicate candidate ${firstCandidate.predicate_name} has unbound arguments: ${firstCandidate.unbound_arguments.join(", ")}. Supply exact argumentBindings keyed by the schema's argument_names before applying it.`);
-    }
-    const recommendedAction = !firstCandidate
-        ? args.schemaId
+    // Stage 3/4: bind only after eligibility, then decide conservatively.
+    const unavailableSchema = Boolean(args.schemaId && selectedSchemas.length === 0);
+    const recommendedAction = !recommendedCandidate
+        ? unavailableSchema
             ? "resolve_schema_reference"
             : "record_ontology_gap"
-        : bindingsComplete
+        : recommendedCandidate.binding_status === "complete"
             ? "apply_requires_predicate"
             : "provide_argument_bindings";
-    const applyPlan = !firstCandidate
-        ? args.schemaId
-            ? []
-            : buildGapApplyPlan(text, args)
-        : bindingsComplete
-            ? buildPredicateApplyPlan(firstCandidate, args)
+    const applyPlan = recommendedCandidate && recommendedCandidate.binding_status === "complete"
+        ? buildPredicateApplyPlan(recommendedCandidate, args)
+        : !recommendedCandidate && !unavailableSchema
+            ? buildGapApplyPlan(text, args)
             : [];
-    const relationshipPlan = firstCandidate && bindingsComplete
+    const relationshipPlan = recommendedCandidate && recommendedCandidate.binding_status === "complete"
         ? buildRelationshipPlan(String(applyPlan[0]?.id ?? ""), args.requirementId, text, args.existingLogicClaims)
         : null;
-    const textSummary = firstCandidate && bindingsComplete
-        ? `Suggested ${candidates.length} predicate candidate(s). Top match: ${candidates[0]?.predicate_name}. Apply structured predicate facts before falling back to prose.`
-        : firstCandidate
-            ? `Matched ${firstCandidate.predicate_name}, but exact values are still required for: ${firstCandidate.unbound_arguments.join(", ")}. No apply plan was generated.`
-            : args.schemaId
-                ? `Requested predicate schema ${args.schemaId} is unavailable. No apply plan was generated.`
-                : "No predicate candidate met the confidence threshold; record an ontology gap instead of silently writing prose.";
+    const recommendedPredicateSchema = !recommendedCandidate && !unavailableSchema
+        ? buildPredicateSchemaDraft(text, subject)
+        : null;
+    const textSummary = recommendedCandidate && recommendedCandidate.binding_status === "complete"
+        ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${recommendedCandidate.predicate_name}. Apply structured predicate facts before falling back to prose.`
+        : recommendedCandidate
+            ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. No apply plan was generated.`
+            : unavailableSchema
+                ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
+                : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.";
     const claimKey = semanticClaimKey(text);
     const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
     return {
@@ -76,6 +246,7 @@ export async function handleKbSuggestPredicates(prolog, args) {
             subject,
             candidates,
             recommendedAction,
+            recommendedPredicateSchema,
             applyPlan,
             relationshipPlan,
             warnings,

package/dist/operations/mutation/contradictions.d.ts

@@ -1,3 +1,4 @@
+import type { PrologErrorRecord } from "../../prolog/error-terms.js";
 import type { RelationshipInput } from "./types.js";
 type TransactionInput = {
     readonly entity: Readonly<Record<string, unknown>>;
@@ -5,6 +6,6 @@ type TransactionInput = {
     readonly skipContradictionCheck: boolean;
 };
 export declare function buildUpsertCommitGoal(input: TransactionInput): string;
-export declare function formatUpsertError(entityId: string, raw?: string): string;
+export declare function formatUpsertError(entityId: string, raw?: string, record?: PrologErrorRecord): string;
 export {};
 //# sourceMappingURL=contradictions.d.ts.map

package/dist/operations/mutation/contradictions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/contradictions.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C,CAAC;AAGF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAGD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA6CxE"}
+{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/contradictions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AASrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C,CAAC;AAGF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAGD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAOR"}

package/dist/operations/mutation/contradictions.js

@@ -1,5 +1,5 @@
 import { escapeAtom } from "../../prolog/codec.js";
-import { formatInvalidRelationshipError } from "./relationships.js";
+import { formatInvalidRelationshipError, formatInvalidRelationshipTuple, } from "./relationships.js";
 import { buildPropertyList, buildRelationshipMetadata, } from "./serialization.js";
 // implements REQ-kibi-operation-interface-parity
 export function buildUpsertCommitGoal(input) {
@@ -8,12 +8,33 @@ export function buildUpsertCommitGoal(input) {
     return `kb_commit_upsert(${type}, ${buildPropertyList(input.entity)}, [${relationships.join(", ")}], ${input.skipContradictionCheck ? "true" : "false"}, ChangeKind)`;
 }
 // implements REQ-kibi-operation-interface-parity
-export function formatUpsertError(entityId, raw) {
+export function formatUpsertError(entityId, raw, record) {
+    const stage = raw?.match(/\(stage=([^)]+)\)/)?.[1];
+    const stageSuffix = stage === undefined ? "" : ` (stage=${stage})`;
+    if (record) {
+        return formatStructuredUpsertError(entityId, record, stageSuffix);
+    }
+    return formatTextUpsertError(entityId, raw, stageSuffix);
+}
+function formatStructuredUpsertError(entityId, record, stageSuffix) {
+    if (record.code === "contradiction") {
+        const conflicts = [
+            ...new Set((record.conflicts ?? []).map((conflict) => `  - Conflicts with ${conflict.otherId}: ${conflict.reason}`)),
+        ];
+        if (conflicts.length > 0) {
+            return `Contradiction detected for requirement ${entityId}:\n${conflicts.join("\n")}\n\nTo resolve:\n  1. Add a supersedes relationship from the new requirement to the conflicting one, OR\n  2. Deprecate the conflicting requirement before creating the new one.${stageSuffix}`;
+        }
+        return `Contradiction detected for entity ${entityId}: This requirement conflicts with existing requirements. Add a supersedes relationship to the conflicting requirement, or deprecate the old requirement before creating the new one.${stageSuffix}`;
+    }
+    if (record.code === "invalid_relationship" && record.relationship) {
+        return `Failed to upsert entity ${entityId}: ${formatInvalidRelationshipTuple(record.relationship)}${stageSuffix}`;
+    }
+    return `Failed to upsert entity ${entityId}: ${record.message}${stageSuffix}`;
+}
+function formatTextUpsertError(entityId, raw, stageSuffix) {
     if (!raw)
         return `Failed to upsert entity ${entityId}: Unknown error`;
-    const stage = raw.match(/\(stage=([^)]+)\)/)?.[1];
-    const stageSuffix = stage === undefined ? "" : ` (stage=${stage})`;
-    const diagnosticFree = raw.replace(/^__KIBI_(?:STAGE|RUNTIME)__:[^\r\n]*\r?\n?/gm, "");
+    const diagnosticFree = raw.replace(/^__KIBI_(?:STAGE|RUNTIME|ERROR)__:[^\r\n]*\r?\n?/gm, "");
     if (diagnosticFree.includes("stale_snapshot")) {
         return `Failed to upsert entity ${entityId}: KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)${stageSuffix}`;
     }

package/dist/operations/mutation/delete.d.ts

@@ -1,5 +1,8 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
+import { type RelationshipSelector } from "../../relationships/shards.js";
 import type { DeleteInput, DeletePayload } from "./types.js";
+export declare function assertFilesystemCapableRuntime(fs: OperationContext["fs"]): asserts fs is NonNullable<OperationContext["fs"]>;
+export declare function executeRelationshipDelete(selectors: readonly RelationshipSelector[], context: OperationContext, onCommitted?: () => void): Promise<DeletePayload>;
 export declare function executeDelete(input: DeleteInput, context: OperationContext): Promise<OperationResult<DeletePayload>>;
 //# sourceMappingURL=delete.d.ts.map

package/dist/operations/mutation/delete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/delete.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAIxE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+B7D,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA6CzC"}
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/delete.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EACL,KAAK,oBAAoB,EAI1B,MAAM,+BAA+B,CAAC;AAgBvC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAc7D,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,gBAAgB,CAAC,IAAI,CAAC,GACzB,OAAO,CAAC,EAAE,IAAI,WAAW,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAMnD;AAuWD,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,OAAO,EAAE,gBAAgB,EACzB,WAAW,GAAE,MAAM,IAAsB,GACxC,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA6OzC"}