kibi-cli 0.14.0 → 0.16.1

package/dist/operations/modeling/requirement-modeler.js

@@ -0,0 +1,70 @@
+import { buildFallbackClaim, extractHeuristicClaim, } from "./requirement-heuristics.js";
+import { clampConfidence, normalizeClaimValue, normalizeOptionalString, normalizeSourceFiles, normalizeText, stripListPrefix, } from "./requirement-utils.js";
+const NORMATIVE_SECTION_PATTERN = /\b(requirements?|polic(?:y|ies)|rules?)\b/i;
+function hasExplicitClaimFields(args) {
+    return (args.subjectKey !== undefined ||
+        args.propertyKey !== undefined ||
+        args.operator !== undefined ||
+        args.value !== undefined);
+}
+// implements REQ-002
+export function estimateNormativeSignalConfidence(statement, heading) {
+    const normalizedStatement = stripListPrefix(statement).toLowerCase();
+    if (!/\b(must|shall|should)\b/.test(normalizedStatement))
+        return 0;
+    let confidence = normalizedStatement.includes(" shall ")
+        ? 0.86
+        : normalizedStatement.includes(" must ")
+            ? 0.84
+            : 0.78;
+    if (heading && NORMATIVE_SECTION_PATTERN.test(heading))
+        confidence += 0.08;
+    return Math.round(Math.min(0.95, confidence) * 100) / 100;
+}
+// implements REQ-002
+export function extractRequirementClaim(args) {
+    const statement = normalizeText(args.text);
+    const sourceFiles = normalizeSourceFiles(args.sourceFiles);
+    const source = normalizeOptionalString(args.source) ?? sourceFiles[0];
+    if (!source) {
+        throw new Error("Requirement modeling failed: provide source or at least one sourceFiles entry");
+    }
+    const provenance = normalizeOptionalString(args.provenance);
+    const confidence = clampConfidence(args.confidence);
+    if (hasExplicitClaimFields(args)) {
+        const subjectKey = normalizeOptionalString(args.subjectKey);
+        const propertyKey = normalizeOptionalString(args.propertyKey);
+        if (!subjectKey ||
+            !propertyKey ||
+            args.operator === undefined ||
+            args.value === undefined) {
+            throw new Error("Requirement modeling failed: subjectKey, propertyKey, operator, and value must all be provided when any extracted claim field is supplied");
+        }
+        const claim = {
+            source,
+            subjectKey,
+            propertyKey,
+            operator: args.operator,
+            value: normalizeClaimValue(args.value),
+            confidence,
+            ...(provenance ? { provenance } : {}),
+        };
+        return {
+            statement,
+            source,
+            sourceFiles,
+            claim,
+            extractionMode: "provided",
+            extractionWarnings: [],
+        };
+    }
+    const heuristic = extractHeuristicClaim(statement, source, confidence, provenance);
+    if (heuristic)
+        return { statement, source, sourceFiles, ...heuristic };
+    return {
+        statement,
+        source,
+        sourceFiles,
+        ...buildFallbackClaim(statement, source, confidence, provenance),
+    };
+}

package/dist/operations/modeling/requirement-types.d.ts

@@ -0,0 +1,49 @@
+import type { SemanticClaim, StrictWriteSet } from "../../public/check-types.js";
+export type ModelRequirementArgs = Readonly<Record<string, unknown>> & {
+    readonly text: string;
+    readonly source?: string;
+    readonly sourceFiles?: string[];
+    readonly confidence?: number;
+    readonly subjectKey?: string;
+    readonly propertyKey?: string;
+    readonly operator?: SemanticClaim["operator"];
+    readonly value?: string | number | boolean;
+    readonly provenance?: string;
+    /** Existing requirement claim manifest. Returned req updates merge this list. */
+    readonly existingLogicClaims?: readonly string[];
+};
+export interface ExtractedRequirementClaim {
+    claim: SemanticClaim;
+    extractionMode: "provided" | "heuristic" | "fallback";
+    extractionWarnings: string[];
+}
+export interface ModelRequirementResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: {
+        statement: string;
+        claimKey: string;
+        logicClaims: string[];
+        source: string;
+        sourceFiles: string[];
+        claim: SemanticClaim;
+        writeSet: StrictWriteSet;
+        applyPlan: Array<Record<string, unknown>>;
+        isStrict: boolean;
+        confidence: number;
+        extractionMode: "provided" | "heuristic" | "fallback";
+        extractionWarnings: string[];
+        warnings: Array<{
+            kind: string;
+            message: string;
+            nextAction: string;
+        }>;
+        migrationWarning: string | null;
+    };
+    applyPlan: Array<Record<string, unknown>>;
+    writeSet: StrictWriteSet;
+    migrationWarning: string | null;
+}
+//# sourceMappingURL=requirement-types.d.ts.map

package/dist/operations/modeling/requirement-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/requirement-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACf,MAAM,6BAA6B,CAAC;AAGrC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD,CAAC;AAGF,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,aAAa,CAAC;IACrB,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;IACtD,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAGD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;QACrB,QAAQ,EAAE,cAAc,CAAC;QACzB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1C,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;QACtD,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC,CAAC;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,CAAC;IACF,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,QAAQ,EAAE,cAAc,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC"}

package/dist/operations/modeling/requirement-types.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/modeling/requirement-utils.d.ts

@@ -0,0 +1,10 @@
+export declare function normalizeText(text: string): string;
+export declare function normalizeOptionalString(value: string | undefined): string | undefined;
+export declare function normalizeSourceFiles(sourceFiles: string[] | undefined): string[];
+export declare function clampConfidence(confidence: number | undefined): number;
+export declare function normalizeClaimValue(value: unknown): string | number | boolean;
+export declare function stripListPrefix(value: string): string;
+export declare function trimSentenceTail(value: string): string;
+export declare function cleanSubject(value: string): string;
+export declare function cleanPredicate(value: string): string;
+//# sourceMappingURL=requirement-utils.d.ts.map

package/dist/operations/modeling/requirement-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-utils.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/requirement-utils.ts"],"names":[],"mappings":"AACA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD;AAGD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAGpB;AAGD,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,GAChC,MAAM,EAAE,CAUV;AAGD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMtE;AAGD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAgB7E;AAGD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKrD;AAGD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlD;AAGD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/operations/modeling/requirement-utils.js

@@ -0,0 +1,65 @@
+// implements REQ-002
+export function normalizeText(text) {
+    const normalized = String(text ?? "").trim();
+    if (!normalized) {
+        throw new Error("Requirement modeling failed: text must be a non-empty string");
+    }
+    return normalized;
+}
+// implements REQ-002
+export function normalizeOptionalString(value) {
+    const normalized = String(value ?? "").trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+// implements REQ-002
+export function normalizeSourceFiles(sourceFiles) {
+    const seen = new Set();
+    const normalized = [];
+    for (const sourceFile of sourceFiles ?? []) {
+        const trimmed = String(sourceFile ?? "").trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+// implements REQ-002
+export function clampConfidence(confidence) {
+    const numeric = typeof confidence === "number" && Number.isFinite(confidence)
+        ? confidence
+        : 0.8;
+    return Math.round(Math.min(1, Math.max(0, numeric)) * 100) / 100;
+}
+// implements REQ-002
+export function normalizeClaimValue(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            throw new Error("Requirement modeling failed: value must be a finite number");
+        }
+        return value;
+    }
+    throw new Error("Requirement modeling failed: value must be a string, number, or boolean");
+}
+// implements REQ-002
+export function stripListPrefix(value) {
+    return value
+        .replace(/^\s*[-*+]\s+/, "")
+        .replace(/^\s*\d+[.)]\s+/, "")
+        .trim();
+}
+// implements REQ-002
+export function trimSentenceTail(value) {
+    return value.replace(/[\s.?!:;]+$/g, "").trim();
+}
+// implements REQ-002
+export function cleanSubject(value) {
+    const cleaned = trimSentenceTail(stripListPrefix(value));
+    return cleaned.replace(/^(?:the|a|an)\s+/i, "").trim() || cleaned;
+}
+// implements REQ-002
+export function cleanPredicate(value) {
+    return trimSentenceTail(stripListPrefix(value)) || "statement";
+}

package/dist/operations/modeling/suggest-predicates.d.ts

@@ -0,0 +1,6 @@
+import type { OperationContext, PrologPort } from "../../public/operations/runtime-types.js";
+import type { SuggestPredicatesArgs, SuggestPredicatesResult } from "./predicate-types.js";
+export type { SuggestPredicatesArgs, SuggestPredicatesResult, } from "./predicate-types.js";
+export declare function handleKbSuggestPredicates(prolog: PrologPort | null, args: SuggestPredicatesArgs): Promise<SuggestPredicatesResult>;
+export declare function executeSuggestPredicates(args: SuggestPredicatesArgs, context: OperationContext): Promise<SuggestPredicatesResult>;
+//# sourceMappingURL=suggest-predicates.d.ts.map

package/dist/operations/modeling/suggest-predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-predicates.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/suggest-predicates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACX,MAAM,0CAA0C,CAAC;AAYlD,OAAO,KAAK,EACV,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAK9B,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CA4ElC;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}

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

@@ -0,0 +1,64 @@
+import { semanticClaimKey } from "../semantic-advisor/clauses.js";
+import { buildGapApplyPlan, buildPredicateApplyPlan, 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 { clampInteger, clampScore, normalizeText } from "./predicate-utils.js";
+const DEFAULT_MAX_CANDIDATES = 5;
+// implements REQ-mcp-suggest-predicates
+export async function handleKbSuggestPredicates(prolog, args) {
+    const text = normalizeText(args.text);
+    const maxCandidates = clampInteger(args.maxCandidates, DEFAULT_MAX_CANDIDATES, 1, 20);
+    const minScore = clampScore(args.minScore);
+    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 candidates = schemas
+        .map((schema) => ({ schema, score: scoreSchema(schema, text) }))
+        .filter((scored) => scored.score >= minScore)
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return left.schema.predicate_name.localeCompare(right.schema.predicate_name);
+    })
+        .slice(0, maxCandidates)
+        .map((scored) => buildSuggestion(scored.schema, text, subject, scored.score));
+    if (candidates.length === 0) {
+        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 recommendedAction = candidates.length > 0 ? "apply_requires_predicate" : "record_ontology_gap";
+    const firstCandidate = candidates[0];
+    const applyPlan = firstCandidate
+        ? buildPredicateApplyPlan(firstCandidate, args)
+        : buildGapApplyPlan(text, args);
+    const relationshipPlan = firstCandidate
+        ? buildRelationshipPlan(String(applyPlan[0]?.id ?? ""), args.requirementId, text, args.existingLogicClaims)
+        : null;
+    const textSummary = candidates.length > 0
+        ? `Suggested ${candidates.length} predicate candidate(s). Top match: ${candidates[0]?.predicate_name}. Apply structured predicate facts before falling back to prose.`
+        : "No predicate candidate met the confidence threshold; record an ontology gap instead of silently writing prose.";
+    const claimKey = semanticClaimKey(text);
+    const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
+    return {
+        content: [{ type: "text", text: textSummary }],
+        structuredContent: {
+            text,
+            claimKey,
+            logicClaims,
+            source: args.source ?? null,
+            requirementId: args.requirementId ?? null,
+            subject,
+            candidates,
+            recommendedAction,
+            applyPlan,
+            relationshipPlan,
+            warnings,
+        },
+        applyPlan,
+    };
+}
+export async function executeSuggestPredicates(args, context) {
+    return handleKbSuggestPredicates(context.prolog ?? null, args);
+}

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

@@ -0,0 +1,6 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { RelationshipInput } from "./types.js";
+export declare function recordEntityAudit(prolog: PrologPort, change: "created" | "updated", entity: Readonly<Record<string, unknown>>): Promise<void>;
+export declare function recordRelationshipAudits(prolog: PrologPort, relationships: readonly RelationshipInput[]): Promise<void>;
+export declare function buildEntityDeleteAuditGoal(entity: Readonly<Record<string, unknown>>): string;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/audit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAK3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAOR"}

package/dist/operations/mutation/audit.js

@@ -0,0 +1,22 @@
+import { escapeAtom } from "../../prolog/codec.js";
+import { buildPropertyList, buildRelationshipMetadata, } from "./serialization.js";
+export async function recordEntityAudit(prolog, change, entity) {
+    const result = await prolog.query(`kb_log_entity_upsert(${change}, ${String(entity.type)}, ${buildPropertyList(entity)})`);
+    if (!result.success) {
+        throw new Error(`Failed to record audit entry for ${String(entity.id)}: ${result.error ?? "Unknown error"}`);
+    }
+}
+export async function recordRelationshipAudits(prolog, relationships) {
+    for (const relationship of relationships) {
+        const from = String(relationship.from);
+        const to = String(relationship.to);
+        const result = await prolog.query(`kb_log_relationship_upsert(${String(relationship.type)}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${buildRelationshipMetadata(relationship)})`);
+        if (!result.success) {
+            throw new Error(`Failed to record relationship audit entry ${from}->${to}: ${result.error ?? "Unknown error"}`);
+        }
+    }
+}
+export function buildEntityDeleteAuditGoal(entity) {
+    const auditEntity = Object.fromEntries(["id", "title", "source", "text_ref"].flatMap((key) => typeof entity[key] === "string" ? [[key, entity[key]]] : []));
+    return `kb_retract_entity('${escapeAtom(String(entity.id))}', ${String(entity.type)}, ${buildPropertyList(auditEntity)})`;
+}

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

@@ -0,0 +1,10 @@
+import type { RelationshipInput } from "./types.js";
+type TransactionInput = {
+    readonly entity: Readonly<Record<string, unknown>>;
+    readonly relationships: readonly RelationshipInput[];
+    readonly skipContradictionCheck: boolean;
+};
+export declare function buildUpsertTransaction(input: TransactionInput): string;
+export declare function formatUpsertError(entityId: string, raw?: string): string;
+export {};
+//# sourceMappingURL=contradictions.d.ts.map

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

@@ -0,0 +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,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CActE;AAGD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA0BxE"}

package/dist/operations/mutation/contradictions.js

@@ -0,0 +1,40 @@
+import { escapeAtom } from "../../prolog/codec.js";
+import { formatInvalidRelationshipError } from "./relationships.js";
+import { buildPropertyList, buildRelationshipMetadata, } from "./serialization.js";
+// implements REQ-kibi-operation-interface-parity
+export function buildUpsertTransaction(input) {
+    const id = String(input.entity.id);
+    const type = String(input.entity.type);
+    const goals = [
+        `kb_assert_entity_no_audit(${type}, ${buildPropertyList(input.entity)})`,
+        ...input.relationships.map((relationship) => `kb_assert_relationship_no_audit(${String(relationship.type)}, '${escapeAtom(String(relationship.from))}', '${escapeAtom(String(relationship.to))}', ${buildRelationshipMetadata(relationship)})`),
+    ];
+    if (type === "req" && !input.skipContradictionCheck) {
+        goals.push(`check_req_contradiction('${escapeAtom(id)}')`);
+    }
+    return `rdf_transaction((${goals.join(", ")}))`;
+}
+// implements REQ-kibi-operation-interface-parity
+export function formatUpsertError(entityId, raw) {
+    if (!raw)
+        return `Failed to upsert entity ${entityId}: Unknown error`;
+    const invalidRelationship = formatInvalidRelationshipError(raw);
+    if (invalidRelationship !== null) {
+        return `Failed to upsert entity ${entityId}: ${invalidRelationship}`;
+    }
+    const contradiction = raw.match(/kb_contradiction\(\s*\[([^\]]+)\]\s*\)/);
+    if (contradiction) {
+        const details = contradiction[1] ?? "";
+        const conflicts = [
+            ...details.matchAll(/(?:'([^']+)'|"([^"\\]*(?:\\.[^"\\]*)*)")-'([^']+)'/g),
+        ].map((match) => `  - Conflicts with ${String(match[3])}: ${String(match[1] ?? match[2])}`);
+        if (conflicts.length > 0) {
+            return `Contradiction detected for requirement ${entityId}:\n${[...new Set(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.`;
+        }
+        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.`;
+    }
+    if (raw.includes("rdf_transaction")) {
+        return `Failed to upsert entity ${entityId}: Transaction failed`;
+    }
+    return `Failed to upsert entity ${entityId}: ${raw}`;
+}

package/dist/operations/mutation/delete.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 { DeleteInput, DeletePayload } from "./types.js";
+export declare function executeDelete(input: DeleteInput, context: OperationContext): Promise<OperationResult<DeletePayload>>;
+//# sourceMappingURL=delete.d.ts.map

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

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

package/dist/operations/mutation/delete.js

@@ -0,0 +1,67 @@
+import { parseEntityFromList, parseListOfLists } from "../../prolog/codec.js";
+import { buildEntityDeleteAuditGoal } from "./audit.js";
+import { dependentRelationshipsGoal } from "./relationships.js";
+import { saveAtomicMutation, saveMutation } from "./save.js";
+function requireProlog(context) {
+    if (context.prolog === undefined) {
+        throw new Error("Delete operation requires a Prolog runtime");
+    }
+    return context.prolog;
+}
+async function loadEntity(prolog, id) {
+    const safeId = id.replaceAll("'", "''");
+    const result = await prolog.query(`findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`);
+    if (!result.success) {
+        throw new Error(`Failed to load metadata for entity ${id}: ${result.error ?? "Unknown error"}`);
+    }
+    const rows = parseListOfLists(result.bindings.Results ?? "[]");
+    if (rows.length === 0) {
+        throw new Error(`Failed to load metadata for entity ${id}: Entity not found`);
+    }
+    return { ...parseEntityFromList(rows[0] ?? []), id };
+}
+export async function executeDelete(input, context) {
+    const prolog = requireProlog(context);
+    if (input.ids.length === 0)
+        throw new Error("At least one ID required for delete");
+    try {
+        const errors = [];
+        const goals = [];
+        for (const id of input.ids) {
+            const safeId = id.replaceAll("'", "''");
+            const exists = await prolog.query(`once(kb_entity('${safeId}', _, _))`);
+            if (!exists.success) {
+                errors.push(`Entity ${id} does not exist`);
+                continue;
+            }
+            const dependents = await prolog.query(dependentRelationshipsGoal(id));
+            if (!dependents.success) {
+                errors.push(`Failed to inspect dependents for entity ${id}: ${dependents.error ?? "Query failed"}`);
+                continue;
+            }
+            if ((dependents.bindings.Dependents ?? "[]") !== "[]") {
+                errors.push(`Cannot delete entity ${id}: has dependents (other entities reference it)`);
+                continue;
+            }
+            goals.push(buildEntityDeleteAuditGoal(await loadEntity(prolog, id)));
+        }
+        if (goals.length > 0)
+            await saveAtomicMutation(prolog, goals, "delete");
+        else
+            await saveMutation(prolog, "delete");
+        const payload = { deleted: goals.length, skipped: errors.length, errors };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Deleted ${payload.deleted} entities. Skipped ${payload.skipped}.${errors.length > 0 ? ` Errors: ${errors.join("; ")}` : ""}`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Delete execution failed: ${message}`);
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { RelationshipInput } from "./types.js";
+export declare function dependentRelationshipsGoal(entityId: string): string;
+type RelationshipTuple = {
+    readonly relType: string;
+    readonly fromType: string;
+    readonly toType: string;
+};
+export declare function formatInvalidRelationshipTuple(tuple: RelationshipTuple): string;
+export declare function formatInvalidRelationshipError(raw: string): string | null;
+export declare function validateRelationshipSources(entityId: string, relationships: readonly RelationshipInput[]): void;
+export declare function formatRelationshipSourceMismatch(entityId: string, relationship: RelationshipInput): string;
+export declare function validateLiveRelationshipTargets(prolog: PrologPort, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[]): Promise<void>;
+export declare function validateStrictLanePairing(prolog: PrologPort, relationships: readonly RelationshipInput[]): Promise<void>;
+export declare function existingRelationships(prolog: PrologPort, entityId: string): Promise<readonly RelationshipInput[]>;
+export {};
+//# sourceMappingURL=relationships.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/relationships.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAqBpD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,KAAK,iBAAiB,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAgCF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAER;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,IAAI,CAMN;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,iBAAiB,GAC9B,MAAM,CAIR;AAuBD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAevC"}

package/dist/operations/mutation/relationships.js

@@ -0,0 +1,134 @@
+import { escapeAtom, toPrologAtom } from "../../prolog/codec.js";
+import { parsePrologList } from "./serialization.js";
+const RELATIONSHIP_TYPES = [
+    "depends_on",
+    "specified_by",
+    "verified_by",
+    "validates",
+    "implements",
+    "covered_by",
+    "executable_for",
+    "constrained_by",
+    "constrains",
+    "requires_property",
+    "requires_predicate",
+    "guards",
+    "publishes",
+    "consumes",
+    "supersedes",
+    "relates_to",
+];
+export function dependentRelationshipsGoal(entityId) {
+    return `findall([RelType,From], (member(RelType, [${RELATIONSHIP_TYPES.join(", ")}]), kb_relationship(RelType, From, '${escapeAtom(entityId)}')), Dependents)`;
+}
+function stringField(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`Relationship ${field} must be a non-empty string`);
+    }
+    return value;
+}
+function recipe(tuple) {
+    if (tuple.relType === "verified_by" &&
+        tuple.fromType === "fact" &&
+        tuple.toType === "test") {
+        return "Facts are not directly verified by tests. Create or update a requirement and link REQ -> TEST with verified_by. Link the requirement to the fact with constrains or requires_property.";
+    }
+    if (tuple.relType === "validates" &&
+        tuple.fromType === "test" &&
+        tuple.toType === "fact") {
+        return "Tests validate requirements or scenarios, not facts directly. Create or update a requirement and link TEST -> REQ with validates. Link the requirement to the fact with constrains or requires_property.";
+    }
+    if (tuple.relType === "verified_by")
+        return "verified_by is only valid as req/scenario -> test.";
+    if (tuple.relType === "validates")
+        return "validates is only valid as test -> req/scenario.";
+    return "Use a typed relationship from docs/entity-schema.md, or relates_to only as a reviewed escape hatch.";
+}
+export function formatInvalidRelationshipTuple(tuple) {
+    return `Invalid relationship: ${tuple.relType} from ${tuple.fromType} to ${tuple.toType}. ${recipe(tuple)}`;
+}
+export function formatInvalidRelationshipError(raw) {
+    const match = raw.match(/Invalid relationship:\s*([^\s~]+) from ([^\s~]+) to ([^\s.\-]+)/) ??
+        raw.match(/Invalid relationship:\s*~w from ~w to ~w-\[([^,\]]+),([^,\]]+),([^\]]+)\]/);
+    const relType = match?.[1];
+    const fromType = match?.[2];
+    const toType = match?.[3];
+    return relType && fromType && toType
+        ? formatInvalidRelationshipTuple({ relType, fromType, toType })
+        : null;
+}
+export function validateRelationshipSources(entityId, relationships) {
+    for (const relationship of relationships) {
+        if (relationship.from !== entityId) {
+            throw new Error(formatRelationshipSourceMismatch(entityId, relationship));
+        }
+    }
+}
+export function formatRelationshipSourceMismatch(entityId, relationship) {
+    const from = stringField(relationship, "from");
+    const to = stringField(relationship, "to");
+    return `Relationship source must match the upserted entity ${entityId}; received from=${from}. To add ${from} -> ${to}, upsert ${from} instead and include the relationship in that call.`;
+}
+async function endpointType(prolog, entity, endpointId) {
+    if (endpointId === entity.id && typeof entity.type === "string")
+        return entity.type;
+    let result;
+    try {
+        result = await prolog.query(`kb_entity('${escapeAtom(endpointId)}', Type, _)`);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+    if (!result.success)
+        return null;
+    const type = result.bindings.Type;
+    return type ? type.replace(/^['"]|['"]$/g, "") : null;
+}
+export async function validateLiveRelationshipTargets(prolog, entity, relationships) {
+    for (const relationship of relationships) {
+        const fromType = await endpointType(prolog, entity, stringField(relationship, "from"));
+        const toType = await endpointType(prolog, entity, stringField(relationship, "to"));
+        if (fromType === null || toType === null)
+            continue;
+        const tuple = {
+            relType: stringField(relationship, "type"),
+            fromType,
+            toType,
+        };
+        const result = await prolog.query(`once(kb:validate_relationship(${toPrologAtom(tuple.relType)}, ${toPrologAtom(tuple.fromType)}, ${toPrologAtom(tuple.toType)}))`);
+        if (!result.success)
+            throw new Error(formatInvalidRelationshipTuple(tuple));
+    }
+}
+export async function validateStrictLanePairing(prolog, relationships) {
+    for (const relationship of relationships) {
+        const target = stringField(relationship, "to");
+        const wrongKind = relationship.type === "constrains"
+            ? "property_value"
+            : relationship.type === "requires_property"
+                ? "subject"
+                : null;
+        if (wrongKind === null)
+            continue;
+        const result = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, ${wrongKind})))`);
+        if (result.success) {
+            const expected = relationship.type === "constrains" ? "subject" : "property_value";
+            throw new Error(`Relationship '${String(relationship.type)}' requires target '${target}' to be a ${expected}, observation, or meta fact. ${wrongKind[0]?.toUpperCase()}${wrongKind.slice(1)} facts cannot be direct targets of ${String(relationship.type)} relationships.`);
+        }
+    }
+}
+export async function existingRelationships(prolog, entityId) {
+    const existing = [];
+    for (const type of RELATIONSHIP_TYPES) {
+        const forward = await prolog.query(`findall(To, kb_relationship(${type}, '${escapeAtom(entityId)}', To), Targets)`);
+        for (const to of parsePrologList(forward.bindings.Targets ?? "[]"))
+            existing.push({ type, from: entityId, to });
+        const reverse = await prolog.query(`findall(From, kb_relationship(${type}, From, '${escapeAtom(entityId)}'), Sources)`);
+        for (const from of parsePrologList(reverse.bindings.Sources ?? "[]"))
+            existing.push({ type, from, to: entityId });
+    }
+    return existing;
+}

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

@@ -0,0 +1,4 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+export declare function saveMutation(prolog: PrologPort, operation?: "upsert" | "delete"): Promise<void>;
+export declare function saveAtomicMutation(prolog: PrologPort, goals: readonly string[], operation: "delete"): Promise<void>;
+//# sourceMappingURL=save.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/save.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,wBAAsB,YAAY,CAChC,MAAM,EAAE,UAAU,EAClB,SAAS,GAAE,QAAQ,GAAG,QAAmB,GACxC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,QAAQ,GAClB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/operations/mutation/save.js

@@ -0,0 +1,14 @@
+export async function saveMutation(prolog, operation = "upsert") {
+    prolog.invalidateCache?.();
+    const result = await prolog.save();
+    if (!result.success) {
+        throw new Error(`Failed to save KB after ${operation}: ${result.error ?? "Unknown error"}`);
+    }
+}
+export async function saveAtomicMutation(prolog, goals, operation) {
+    const result = await prolog.query(`rdf_transaction((${[...goals, "kb_save"].join(", ")}))`);
+    if (!result.success) {
+        throw new Error(`Failed to save KB after ${operation}: ${result.error ?? "Unknown error"}`);
+    }
+    prolog.invalidateCache?.();
+}