kibi-cli 0.14.0 → 0.17.0

package/dist/operations/mutation/validate-upsert.d.ts

@@ -0,0 +1,5 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import type { OperationResult } from "../../public/operations/types.js";
+import type { UpsertInput, ValidateUpsertPayload } from "./types.js";
+export declare function executeValidateUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<ValidateUpsertPayload>>;
+//# sourceMappingURL=validate-upsert.d.ts.map

package/dist/operations/mutation/validate-upsert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGrE,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAoDjD"}

package/dist/operations/mutation/validate-upsert.js

@@ -0,0 +1,50 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { validateLiveRelationshipTargets, validateRelationshipSources, } from "./relationships.js";
+import { validateSymbolGranularity } from "./symbol-granularity.js";
+import { validateUpsertInput } from "./validation.js";
+export async function executeValidateUpsert(input, context) {
+    try {
+        const validated = validateUpsertInput(input, context.clock());
+        validateRelationshipSources(input.id, validated.relationships);
+        await validateSymbolGranularity(validated.entity, validated.relationships, context);
+        if (context.prolog !== undefined) {
+            await validateLiveRelationshipTargets(context.prolog, validated.entity, validated.relationships);
+        }
+        const semantic = analyzeSemanticAdvisorInput({ payload: { ...input } });
+        const payload = {
+            valid: true,
+            errors: [],
+            warnings: semantic.warnings,
+            semanticAdvisor: semantic.receipt,
+            normalizedPreview: validated.entity,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "kb_validate_upsert: payload is valid for kb_upsert preflight checks. No mutation was performed.",
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const payload = {
+            valid: false,
+            errors: [message],
+            warnings: [],
+            semanticAdvisor: null,
+            normalizedPreview: null,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `kb_validate_upsert: payload is invalid. ${message}`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+}

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

@@ -0,0 +1,5 @@
+import { isAllowedGranularityReason } from "../../public/symbol-granularity.js";
+import type { UpsertInput, ValidatedUpsert } from "./types.js";
+export declare function validateUpsertInput(input: UpsertInput, now: Date): ValidatedUpsert;
+export { isAllowedGranularityReason };
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA0CjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -0,0 +1,107 @@
+import Ajv from "ajv";
+import entitySchema from "../../public/schemas/entity.js";
+import relationshipSchema from "../../public/schemas/relationship.js";
+// implements REQ-kibi-operation-interface-parity
+import { SYMBOL_ROLES, isAllowedGranularityReason, } from "../../public/symbol-granularity.js";
+import { semanticClaimKey } from "../semantic-advisor/clauses.js";
+import { factKindShapeHints, validateFactModelingShape, valueFieldHint, } from "./strict-fact.js";
+const ajv = new Ajv({ strict: false });
+const schema = entitySchema;
+const properties = schema.properties !== null && typeof schema.properties === "object"
+    ? schema.properties
+    : {};
+const validateEntity = ajv.compile({
+    ...schema,
+    properties: {
+        ...properties,
+        granularity_reason: {
+            type: "string",
+            enum: [
+                "config-artifact",
+                "module-level-behavior",
+                "extractor-miss",
+                "legacy-link",
+            ],
+        },
+        symbol_role: { type: "string", enum: [...SYMBOL_ROLES] },
+    },
+});
+const validateRelationship = ajv.compile(relationshipSchema);
+const ALIASES = new Map([
+    ["subjectKey", "subject_key"],
+    ["propertyKey", "property_key"],
+    ["predicateName", "predicate_name"],
+    ["predicateArgs", "predicate_args"],
+    ["canonicalKey", "canonical_key"],
+    ["closedWorld", "closed_world"],
+]);
+function formatEntityErrors(entity, errors) {
+    const messages = errors.map((error) => {
+        const params = error.params;
+        const path = error.instancePath || "root";
+        if (error.keyword === "additionalProperties" && params.additionalProperty) {
+            const property = params.additionalProperty;
+            if (property === "value") {
+                return `${path}: unknown property 'value'. ${valueFieldHint(entity.value)} Do not use generic value in kb_upsert.properties.`;
+            }
+            const canonical = ALIASES.get(property);
+            if (canonical) {
+                return `${path}: unknown property '${property}'. Did you mean '${canonical}'? kb_upsert.properties uses snake_case typed fact fields.`;
+            }
+        }
+        if (error.keyword === "enum" && params.allowedValues) {
+            return `${path}: ${error.message}. Allowed values: ${params.allowedValues.map(String).join(", ")}`;
+        }
+        return `${path}: ${error.message}`;
+    });
+    const hints = factKindShapeHints(entity);
+    for (const [alias, canonical] of ALIASES) {
+        if (Object.hasOwn(entity, alias)) {
+            hints.push(`Unknown property '${alias}'. Use '${canonical}' in kb_upsert.properties.`);
+        }
+    }
+    if (Object.hasOwn(entity, "value"))
+        hints.push(valueFieldHint(entity.value));
+    if (hints.length > 0 &&
+        (Object.hasOwn(entity, "value") ||
+            [...ALIASES.keys()].some((key) => Object.hasOwn(entity, key)))) {
+        hints.push("Next action: if starting from prose, call kb_model_requirement and apply its sequential applyPlan instead of guessing field names.");
+    }
+    return [...messages, ...hints].join("; ");
+}
+export function validateUpsertInput(input, now) {
+    if (!input.type || !input.id) {
+        throw new Error("'type' and 'id' are required for upsert");
+    }
+    const entity = {
+        id: input.id,
+        type: input.type,
+        ...input.properties,
+    };
+    entity.created_at ??= now.toISOString();
+    entity.updated_at ??= now.toISOString();
+    entity.source ??= "mcp://kibi/upsert";
+    if (!validateEntity(entity)) {
+        throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
+    }
+    validateFactModelingShape(entity);
+    if (entity.type === "fact" &&
+        typeof entity.claim_key === "string" &&
+        typeof entity.claim_text === "string") {
+        const expectedClaimKey = semanticClaimKey(entity.claim_text);
+        if (entity.claim_key !== expectedClaimKey) {
+            throw new Error(`Entity validation failed: claim_key must equal the stable key derived from claim_text (expected '${expectedClaimKey}')`);
+        }
+    }
+    const relationships = input.relationships ?? [];
+    relationships.forEach((relationship, index) => {
+        if (!validateRelationship(relationship)) {
+            const details = (validateRelationship.errors ?? [])
+                .map((error) => `${error.instancePath || "root"}: ${error.message}`)
+                .join("; ");
+            throw new Error(`Relationship validation failed at index ${index}: ${details}`);
+        }
+    });
+    return { entity, relationships };
+}
+export { isAllowedGranularityReason };

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

@@ -0,0 +1,4 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { RelationshipInput } from "./types.js";
+export declare function scenarioCoverageWarnings(prolog: PrologPort, relationships: readonly RelationshipInput[], entityType: string, entityId: string): Promise<readonly string[]>;
+//# sourceMappingURL=warnings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/warnings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAc5B"}

package/dist/operations/mutation/warnings.js

@@ -0,0 +1,17 @@
+import { escapeAtom } from "../../prolog/codec.js";
+// implements REQ-kibi-operation-interface-parity
+export async function scenarioCoverageWarnings(prolog, relationships, entityType, entityId) {
+    if (entityType !== "req")
+        return [];
+    for (const relationship of relationships) {
+        if (relationship.type !== "verified_by")
+            continue;
+        const result = await prolog.query(`once(kb_relationship(specified_by, '${escapeAtom(entityId)}', ScenarioId))`);
+        if (result.success) {
+            return [
+                `Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`,
+            ];
+        }
+    }
+    return [];
+}

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

@@ -0,0 +1,5 @@
+import type { SemanticClause } from "./clauses.js";
+import { type Payload } from "./shared.js";
+import type { SemanticAdvisorAnalysisResult, SemanticInterpretationResult, SemanticModelingSuggestion, SemanticProposition, SemanticShadowCue, SemanticSignal } from "./types.js";
+export declare function buildAdvisorResult(payload: Payload, signals: readonly SemanticSignal[], modeled: boolean, suggestions: readonly SemanticModelingSuggestion[], clauses: readonly SemanticClause[], propositions: readonly SemanticProposition[], interpretations: readonly SemanticInterpretationResult[], shadowAnalysis: readonly SemanticShadowCue[]): SemanticAdvisorAnalysisResult;
+//# sourceMappingURL=analysis-receipt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-receipt.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analysis-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,OAAO,EAA6B,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EACV,6BAA6B,EAI7B,4BAA4B,EAC5B,0BAA0B,EAC1B,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AA0CpB,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,CA4G/B"}

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

@@ -0,0 +1,120 @@
+import { payloadHash, propertiesOf } from "./shared.js";
+function chooseLane(signals) {
+    if (signals.some(({ kind }) => kind === "numeric_cardinality" || kind === "numeric_threshold"))
+        return "strict_property";
+    if (signals.some(({ kind }) => kind === "conditional" ||
+        kind === "permission" ||
+        kind === "state_or_default"))
+        return "predicate";
+    return signals.some(({ kind }) => kind === "normative_modal")
+        ? "observation_review"
+        : "none";
+}
+function summary(readiness, lane) {
+    if (readiness === "modeled")
+        return "Requirement declares every detected atomic claim and has logical fact links; run kb_check logic-coverage to verify each manifest entry is grounded.";
+    if (readiness === "not_applicable")
+        return "No strong machine-checkable requirement signals were detected.";
+    if (lane === "strict_property")
+        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, propositions, interpretations, shadowAnalysis) {
+    const suggestionLane = suggestions.some(({ kind }) => kind === "strict_property")
+        ? "strict_property"
+        : suggestions.some(({ kind }) => kind === "rule")
+            ? "rule"
+            : suggestions.some(({ kind }) => kind === "predicate")
+                ? "predicate"
+                : null;
+    const candidateLane = modeled
+        ? "none"
+        : (suggestionLane ?? chooseLane(signals));
+    const readiness = modeled
+        ? "modeled"
+        : candidateLane === "none"
+            ? "not_applicable"
+            : "needs_modeling";
+    const tools = modeled
+        ? []
+        : candidateLane === "strict_property"
+            ? ["kb_model_requirement"]
+            : candidateLane === "predicate"
+                ? ["kb_suggest_predicates"]
+                : 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 = propositions
+        .filter(({ status }) => ["ambiguous", "ontology_gap", "missing"].includes(status))
+        .map(({ claim_key }) => claim_key);
+    const coverageStatus = expectedClaimKeys.length === 0
+        ? "not_applicable"
+        : modeled
+            ? "complete"
+            : declaredClaimKeys.length === 0
+                ? "unverified"
+                : "partial";
+    const receipt = {
+        version: "semantic-advisor-v2",
+        payload_hash: payloadHash(payload),
+        logic_readiness: readiness,
+        candidate_lane: candidateLane,
+        signals,
+        ambiguity_witnesses: modeled
+            ? []
+            : signals
+                .filter(({ kind }) => kind === "numeric_cardinality")
+                .map((signal) => ({
+                signal_kind: signal.kind,
+                evidence: signal.evidence,
+                interpretations: [
+                    "exactly",
+                    "at_most",
+                    "at_least",
+                    "named_membership",
+                    "illustrative_example",
+                ],
+                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,
+            suggestion_indexes: suggestions.flatMap((suggestion, index) => suggestion.claim_key === clause.claim_key ? [index] : []),
+        })),
+        logic_coverage: {
+            status: coverageStatus,
+            expected_claim_keys: expectedClaimKeys,
+            declared_claim_keys: declaredClaimKeys,
+            missing_claim_keys: missingClaimKeys,
+            unresolved_claim_keys: unresolvedClaimKeys,
+        },
+        suggested_next_tools: tools,
+        summary: summary(readiness, candidateLane),
+    };
+    return {
+        receipt,
+        warnings: readiness === "needs_modeling"
+            ? [
+                `Semantic advisor: ${receipt.summary} Next action: call ${tools.join(" or ")} before treating this requirement as Prolog-checkable.`,
+            ]
+            : [],
+    };
+}

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

@@ -0,0 +1,5 @@
+import type { SemanticAdvisorAnalysisResult, SemanticAdvisorInput } from "./types.js";
+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

@@ -0,0 +1 @@
+{"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"}