kibi-mcp 0.3.3 → 0.5.0

package/dist/tools/query.js

@@ -1,14 +1,5 @@
-import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
-export const VALID_ENTITY_TYPES = [
-    "req",
-    "scenario",
-    "test",
-    "adr",
-    "flag",
-    "event",
-    "symbol",
-    "fact",
-];
+import { loadEntities, paginateResults, } from "./entity-query.js";
+export { VALID_ENTITY_TYPES } from "./entity-query.js";
 /**
  * Handle kb.query tool calls
  * Reuses query logic from CLI command
@@ -16,73 +7,8 @@ export const VALID_ENTITY_TYPES = [
 export async function handleKbQuery(prolog, args) {
     const { type, id, tags, sourceFile, limit = 100, offset = 0 } = args;
     try {
-        let results = [];
-        // Validate type if provided
-        if (type) {
-            if (!VALID_ENTITY_TYPES.includes(type)) {
-                throw new Error(`Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`);
-            }
-        }
-        // Build Prolog query
-        let goal;
-        if (sourceFile) {
-            const safeSource = escapeAtomContent(sourceFile);
-            if (type) {
-                const safeType = escapeAtomContent(type);
-                goal = `findall([Id,'${safeType}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${safeType}', Props)), Results)`;
-            }
-            else {
-                goal = `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
-            }
-        }
-        else if (id && type) {
-            const safeId = escapeAtomContent(id);
-            const safeType = escapeAtomContent(type);
-            goal = `findall(['${safeId}','${safeType}',Props], kb_entity('${safeId}', '${safeType}', Props), Results)`;
-        }
-        else if (id) {
-            const safeId = escapeAtomContent(id);
-            goal = `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
-        }
-        else if (tags && tags.length > 0) {
-            // JS-side fallback until REQ-mcp-tag-filtering-server-side is implemented.
-            if (type) {
-                const safeType = escapeAtomContent(type);
-                goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
-            }
-            else {
-                goal = "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
-            }
-        }
-        else if (type) {
-            const safeType = escapeAtomContent(type);
-            goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
-        }
-        else {
-            goal = "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
-        }
-        const queryResult = await prolog.query(goal);
-        if (queryResult.success) {
-            if (queryResult.bindings.Results) {
-                const entitiesData = parseListOfLists(queryResult.bindings.Results);
-                for (const data of entitiesData) {
-                    const entity = parseEntityFromList(data);
-                    results.push(entity);
-                }
-            }
-            else if (queryResult.bindings.Result) {
-                const entity = parseEntityFromBinding(queryResult.bindings.Result);
-                results = [entity];
-            }
-        }
-        else {
-            throw new Error(queryResult.error || "Query failed with unknown error");
-        }
-        if (tags && tags.length > 0) {
-            results = dedupeEntities(results.filter((entity) => hasAnyTag(entity, tags)));
-        }
-        // Apply pagination
-        const paginated = results.slice(offset, offset + limit);
+        const results = await loadEntities(prolog, { type, id, tags, sourceFile });
+        const paginated = paginateResults(results, limit, offset);
         // Build human-readable text with entity IDs and titles
         let text;
         if (results.length === 0) {
@@ -118,34 +44,3 @@ export async function handleKbQuery(prolog, args) {
         throw new Error(`Query execution failed: ${message}`);
     }
 }
-function hasAnyTag(entity, requestedTags) {
-    const expected = new Set(requestedTags.map(normalizeTagValue));
-    const rawTags = entity.tags;
-    if (!Array.isArray(rawTags) || rawTags.length === 0) {
-        return false;
-    }
-    for (const tag of rawTags) {
-        if (expected.has(normalizeTagValue(tag))) {
-            return true;
-        }
-    }
-    return false;
-}
-function normalizeTagValue(tag) {
-    return String(tag).trim();
-}
-function dedupeEntities(entities) {
-    const seen = new Set();
-    const deduped = [];
-    for (const entity of entities) {
-        const id = String(entity.id ?? "");
-        const type = String(entity.type ?? "");
-        const key = `${type}::${id}`;
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        deduped.push(entity);
-    }
-    return deduped;
-}

package/dist/tools/search.js

@@ -0,0 +1,37 @@
+import { rankEntities } from "kibi-cli/search-ranking";
+import { resolveWorkspaceRoot } from "../workspace.js";
+import { loadEntities, paginateResults, validateEntityType, } from "./entity-query.js";
+// implements REQ-mcp-search-discovery, REQ-002
+export async function handleKbSearch(prolog, args) {
+    const { query, type, limit = 20, offset = 0 } = args;
+    const trimmedQuery = query.trim();
+    if (!trimmedQuery) {
+        throw new Error("Search execution failed: query must be a non-empty string");
+    }
+    validateEntityType(type);
+    try {
+        const workspaceRoot = resolveWorkspaceRoot();
+        const entities = await loadEntities(prolog, { type });
+        const matches = await rankEntities(entities, trimmedQuery, workspaceRoot);
+        const paginated = paginateResults(matches, limit, offset);
+        const text = matches.length === 0
+            ? `No search results for '${trimmedQuery}'.`
+            : `Found ${matches.length} search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
+                .map((match) => `${match.entity.id} [${match.reasons.join(", ")}]`)
+                .join(", ")}`;
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: {
+                results: paginated,
+                count: matches.length,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("Search execution failed:")) {
+            throw error;
+        }
+        throw new Error(`Search execution failed: ${message}`);
+    }
+}

package/dist/tools/status.js

@@ -0,0 +1,20 @@
+import { runJsonModuleQuery } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleKbStatus(prolog, _args) {
+    try {
+        const payload = await runJsonModuleQuery(prolog, "status.pl", "status:kb_status_json(JsonString)", "Status execution");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Branch ${payload.branch} is ${payload.syncState} (snapshot ${payload.snapshotId}, dirty=${payload.dirty})`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Status execution failed: ${message}`);
+    }
+}

package/dist/tools/symbols.js

@@ -151,6 +151,7 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
     return { refreshed, found: true };
 }
 export function resolveManifestPath(workspaceRoot) {
+    // implements REQ-002, REQ-013
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
     if (existsSync(configPath)) {
         try {
@@ -168,7 +169,9 @@ export function resolveManifestPath(workspaceRoot) {
                     : path.resolve(workspaceRoot, config.symbolsManifest);
             }
         }
-        catch { }
+        catch {
+            // config file missing or malformed; fall through to defaults
+        }
     }
     const candidates = [
         path.join(workspaceRoot, "symbols.yaml"),

package/dist/tools/upsert.js

@@ -16,7 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import Ajv from "ajv";
-import { escapeAtom, toPrologAtom } from "kibi-cli/prolog/codec";
+import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
@@ -73,6 +73,10 @@ export async function handleKbUpsert(prolog, args) {
             throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
         }
     }
+    validateRelationshipSources(id, relationships);
+    // Validate strict-lane fact_kind pairing for constrains/requires_property
+    // implements REQ-011
+    await validateStrictLanePairing(prolog, relationships);
     let created = 0;
     let updated = 0;
     let relationshipsCreated = 0;
@@ -94,26 +98,44 @@ export async function handleKbUpsert(prolog, args) {
                 const from = rel.from;
                 const to = rel.to;
                 const metadata = buildRelationshipMetadata(rel);
-                relationshipGoals.push(`kb_assert_relationship(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
+                relationshipGoals.push(`kb_assert_relationship_no_audit(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
             }
             // Build atomic transaction goal wrapping entity + all relationships
+            // For requirements, also include contradiction check within the transaction
             // implements REQ-002, REQ-011
             let transactionGoal;
+            const needsContradictionCheck = type === "req" && !args._skipContradictionCheck;
             if (relationshipGoals.length === 0) {
                 // Simple case: just entity
-                transactionGoal = `rdf_transaction((kb_assert_entity(${type}, ${props})))`;
+                if (needsContradictionCheck) {
+                    transactionGoal = `rdf_transaction((kb_assert_entity_no_audit(${type}, ${props}), check_req_contradiction('${escapeAtom(id)}')))`;
+                }
+                else {
+                    transactionGoal = `rdf_transaction((kb_assert_entity_no_audit(${type}, ${props})))`;
+                }
             }
             else {
                 // Entity + relationships in one transaction
                 const goals = [
-                    `kb_assert_entity(${type}, ${props})`,
+                    `kb_assert_entity_no_audit(${type}, ${props})`,
                     ...relationshipGoals,
                 ].join(", ");
-                transactionGoal = `rdf_transaction((${goals}))`;
+                if (needsContradictionCheck) {
+                    transactionGoal = `rdf_transaction((${goals}, check_req_contradiction('${escapeAtom(id)}')))`;
+                }
+                else {
+                    transactionGoal = `rdf_transaction((${goals}))`;
+                }
             }
             const txResult = await prolog.query(transactionGoal);
             if (!txResult.success) {
-                throw new Error(`Failed to upsert entity ${id}: ${txResult.error || "Unknown error"} (goal: ${transactionGoal})`);
+                // Format error message without exposing raw transaction goal
+                const formattedError = formatUpsertError(id, txResult.error);
+                throw new Error(formattedError);
+            }
+            await recordEntityAudit(prolog, type, entity);
+            for (const rel of relationships) {
+                await recordRelationshipAudit(prolog, rel);
             }
             // Update counters
             if (isUpdate) {
@@ -131,10 +153,6 @@ export async function handleKbUpsert(prolog, args) {
         if (!saveResult.success) {
             throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
         }
-        let contradictionPairsDetected;
-        if (type === "req" && !args._skipContradictionCheck) {
-            contradictionPairsDetected = await detectContradictionPairs(prolog, id);
-        }
         if (type === "symbol") {
             try {
                 await refreshCoordinatesForSymbolId(id);
@@ -150,16 +168,13 @@ export async function handleKbUpsert(prolog, args) {
             content: [
                 {
                     type: "text",
-                    text: contradictionPairsDetected && contradictionPairsDetected > 0
-                        ? `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s). Contradiction probe detected ${contradictionPairsDetected} potential conflict pair(s).`
-                        : `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
+                    text: `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
                 },
             ],
             structuredContent: {
                 created,
                 updated,
                 relationships_created: relationshipsCreated,
-                contradiction_pairs_detected: contradictionPairsDetected,
             },
         };
     }
@@ -168,27 +183,28 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
-async function detectContradictionPairs(prolog, reqId) {
-    const escaped = escapeAtom(reqId);
-    const goal = `aggregate_all(count, (contradicting_reqs(A, B, _), (A = '${escaped}' ; B = '${escaped}' ; A = 'file:///${escaped}' ; B = 'file:///${escaped}')), Count)`;
-    const result = await prolog.query(goal);
-    if (!result.success) {
-        return 0;
-    }
-    const raw = result.bindings.Count;
-    const count = Number(raw);
-    return Number.isFinite(count) ? count : 0;
-}
 /**
  * Build Prolog property list from entity object
  * Returns simple Key=Value format without typed literals
  * Example output: "[id='test-1', title=\"Test\", status=active]"
+ * implements REQ-002
  */
 function buildPropertyList(entity) {
     const pairs = [];
     // Defined internally to ensure thread safety and avoid initialization order issues.
     // Using simple arrays instead of Sets is performant enough for small lists and avoids Set allocation overhead.
-    const ATOM_FIELDS = ["status", "owner", "priority", "severity"];
+    // implements REQ-002
+    const ATOM_FIELDS = [
+        "status",
+        "owner",
+        "priority",
+        "severity",
+        // Typed fact enum fields must be atoms for Prolog validation
+        "fact_kind",
+        "operator",
+        "value_type",
+        "polarity",
+    ];
     const STRING_FIELDS = [
         "id",
         "title",
@@ -211,10 +227,10 @@ function buildPropertyList(entity) {
             prologValue = toPrologAtom(value);
         }
         else if (STRING_FIELDS.includes(key) && typeof value === "string") {
-            prologValue = `"${escapeQuotes(value)}"`;
+            prologValue = `${toPrologString(value)}`;
         }
         else if (typeof value === "string") {
-            prologValue = `"${escapeQuotes(value)}"`;
+            prologValue = `${toPrologString(value)}`;
         }
         else if (typeof value === "number") {
             prologValue = String(value);
@@ -223,7 +239,7 @@ function buildPropertyList(entity) {
             prologValue = value ? "true" : "false";
         }
         else {
-            prologValue = `"${escapeQuotes(String(value))}"`;
+            prologValue = `${toPrologString(String(value))}`;
         }
         pairs.push(`${key}=${prologValue}`);
     }
@@ -240,21 +256,122 @@ function buildRelationshipMetadata(rel) {
             continue;
         let prologValue;
         if (typeof value === "string") {
-            prologValue = `"${escapeQuotes(value)}"`;
+            prologValue = `${toPrologString(value)}`;
         }
         else if (typeof value === "number") {
             prologValue = String(value);
         }
         else {
-            prologValue = `"${escapeQuotes(String(value))}"`;
+            prologValue = `${toPrologString(String(value))}`;
         }
         pairs.push(`${key}=${prologValue}`);
     }
     return `[${pairs.join(", ")}]`;
 }
 /**
- * Escape double quotes in strings for Prolog
+ * Ensure all relationship rows belong to the entity being upserted.
+ * Rejects foreign-source relationship writes in the same request.
+ * implements REQ-002, REQ-011
+ */
+function validateRelationshipSources(entityId, relationships) {
+    for (const rel of relationships) {
+        if (rel.from !== entityId) {
+            throw new Error(`Relationship source must match the upserted entity ${entityId}; received from=${String(rel.from)}`);
+        }
+    }
+}
+/**
+ * Validate strict-lane fact_kind pairing for constrains/requires_property relationships.
+ * constrains targets must be subject, observation, or meta facts (or legacy without fact_kind).
+ * requires_property targets must be property_value, observation, or meta facts (or legacy without fact_kind).
+ * implements REQ-011
+ */
+async function validateStrictLanePairing(prolog, relationships) {
+    // implements REQ-011
+    for (const rel of relationships) {
+        if (rel.type === "constrains") {
+            const targetId = rel.to;
+            // Reject if target is a fact with fact_kind=property_value.
+            // Allow: legacy (no fact_kind), subject, observation, meta, or non-existent
+            // (non-existent targets are caught by relationship type validation elsewhere).
+            const rejectResult = await prolog.query(`once((kb_entity('${escapeAtom(targetId)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, property_value)))`);
+            if (rejectResult.success) {
+                throw new Error(`Relationship 'constrains' requires target '${targetId}' to be a subject, observation, or meta fact. Property_value facts cannot be direct targets of constrains relationships.`);
+            }
+        }
+        else if (rel.type === "requires_property") {
+            const targetId = rel.to;
+            // Reject if target is a fact with fact_kind=subject.
+            // Allow: legacy (no fact_kind), property_value, observation, meta, or non-existent.
+            const rejectResult = await prolog.query(`once((kb_entity('${escapeAtom(targetId)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, subject)))`);
+            if (rejectResult.success) {
+                throw new Error(`Relationship 'requires_property' requires target '${targetId}' to be a property_value, observation, or meta fact. Subject facts cannot be direct targets of requires_property relationships.`);
+            }
+        }
+    }
+}
+/**
+ * Record audit entry for a successfully committed entity mutation.
+ * Called only after the RDF transaction succeeds.
+ * implements REQ-011
+ */
+async function recordEntityAudit(prolog, type, entity) {
+    const props = buildPropertyList(entity);
+    const result = await prolog.query(`kb_log_entity_upsert(${type}, ${props})`);
+    if (!result.success) {
+        throw new Error(`Failed to record audit entry for ${String(entity.id)}: ${result.error || "Unknown error"}`);
+    }
+}
+/**
+ * Record audit entry for a successfully committed relationship mutation.
+ * Called only after the RDF transaction succeeds.
+ * implements REQ-011
  */
-function escapeQuotes(str) {
-    return str.replace(/"/g, '\\"');
+async function recordRelationshipAudit(prolog, rel) {
+    const relType = rel.type;
+    const from = rel.from;
+    const to = rel.to;
+    const metadata = buildRelationshipMetadata(rel);
+    const result = await prolog.query(`kb_log_relationship_upsert(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
+    if (!result.success) {
+        throw new Error(`Failed to record relationship audit entry ${from}->${to}: ${result.error || "Unknown error"}`);
+    }
+}
+/**
+ * Format upsert error message for user-facing display.
+ * Removes raw transaction goals and extracts meaningful contradiction details.
+ * implements REQ-011
+ */
+function formatUpsertError(entityId, rawError) {
+    if (!rawError) {
+        return `Failed to upsert entity ${entityId}: Unknown error`;
+    }
+    // Check for contradiction error - Prolog returns kb_contradiction([...]) term
+    // Try to extract readable details from the term
+    const contradictionMatch = rawError.match(/kb_contradiction\(\s*\[([^\]]+)\]\s*\)/);
+    if (contradictionMatch) {
+        // Extract individual conflict details from the list
+        const details = contradictionMatch[1];
+        // Parse out readable parts - each entry is like 'Reason'-'ReqId'
+        const conflicts = [];
+        const conflictRegex = /'([^']+)'-'([^']+)'/g;
+        let execResult = conflictRegex.exec(details);
+        while (execResult !== null) {
+            const reason = execResult[1];
+            const otherReq = execResult[2];
+            conflicts.push(`  - Conflicts with ${otherReq}: ${reason}`);
+            execResult = conflictRegex.exec(details);
+        }
+        if (conflicts.length > 0) {
+            const uniqueConflicts = [...new Set(conflicts)];
+            return `Contradiction detected for requirement ${entityId}:\n${uniqueConflicts.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.`;
+    }
+    // Check for RDF transaction error
+    if (rawError.includes("rdf_transaction")) {
+        return `Failed to upsert entity ${entityId}: Transaction failed`;
+    }
+    // Default: return cleaned error without raw goal
+    return `Failed to upsert entity ${entityId}: ${rawError}`;
 }