kibi-mcp 0.19.0 → 0.19.2

package/dist/tools/graph.js

@@ -1,27 +1,14 @@
-import { runJsonModuleQuery, toPrologList } from "./core-module.js";
+import { executeGraph } from "kibi-cli/operations";
 // implements REQ-002, REQ-013
 export async function handleKbGraph(prolog, args) {
-    const direction = args.direction ?? "outgoing";
-    const depth = args.depth ?? 1;
-    const maxNodes = args.maxNodes ?? 200;
-    const maxEdges = args.maxEdges ?? 500;
-    try {
-        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:graph_expand_json(${toPrologList(args.seedIds)}, ${toPrologList(args.relationships)}, '${direction}', ${depth}, ${toPrologList(args.entityTypes)}, ${maxNodes}, ${maxEdges}, JsonString)`, "Graph execution");
-        const nodes = payload?.nodes ?? [];
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: nodes.length === 0
-                        ? "Graph traversal returned no nodes."
-                        : `Graph traversal returned ${nodes.length} nodes and ${(payload?.edges ?? []).length} edges from ${args.seedIds.join(", ")}.`,
-                },
-            ],
-            ...(payload !== undefined ? { structuredContent: payload } : {}),
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Graph execution failed: ${message}`);
-    }
+    return executeGraph({ ...args }, {
+        workspaceRoot: process.cwd(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
+        prolog: {
+            query: (goal) => prolog.query(goal),
+            nextSolution: async () => null,
+            save: () => prolog.query("kb_save"),
+        },
+    });
 }

package/dist/tools/model-requirement.js

@@ -1,351 +1,12 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { buildStrictWriteSet, } from "kibi-cli/public/check-types";
-import { getSchemaVersionStatus } from "kibi-cli/schema-version";
+import { modelRequirementSpec, } from "kibi-cli/operations";
+import { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "kibi-cli/operations/modeling/model-requirement";
 import { resolveWorkspaceRoot } from "../workspace.js";
-const STRICT_FALLBACK_CONFIDENCE = 0.69;
-const NORMATIVE_SECTION_PATTERN = /\b(requirements?|polic(?:y|ies)|rules?)\b/i;
-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;
-}
-function normalizeOptionalString(value) {
-    const normalized = String(value ?? "").trim();
-    return normalized.length > 0 ? normalized : undefined;
-}
-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;
-}
-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;
-}
-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");
-}
-function stripListPrefix(value) {
-    return value
-        .replace(/^\s*[-*+]\s+/, "")
-        .replace(/^\s*\d+[.)]\s+/, "")
-        .trim();
-}
-function trimSentenceTail(value) {
-    return value.replace(/[\s.?!:;]+$/g, "").trim();
-}
-function cleanSubject(value) {
-    const cleaned = trimSentenceTail(stripListPrefix(value));
-    return cleaned.replace(/^(?:the|a|an)\s+/i, "").trim() || cleaned;
-}
-function cleanPredicate(value) {
-    return trimSentenceTail(stripListPrefix(value)) || "statement";
-}
-function fallbackSubjectFromSource(source) {
-    const basename = path
-        .basename(source, path.extname(source))
-        .replace(/[-_]+/g, " ")
-        .trim();
-    return basename || "Requirement";
-}
-function hasExplicitClaimFields(args) {
-    return (args.subjectKey !== undefined ||
-        args.propertyKey !== undefined ||
-        args.operator !== undefined ||
-        args.value !== undefined);
-}
-function buildFallbackClaim(statement, source, confidence, provenance) {
-    return {
-        claim: {
-            source,
-            subjectKey: fallbackSubjectFromSource(source),
-            propertyKey: "statement",
-            operator: "eq",
-            value: statement,
-            confidence: Math.min(confidence, STRICT_FALLBACK_CONFIDENCE),
-            ...(provenance ? { provenance } : {}),
-        },
-        extractionMode: "fallback",
-        extractionWarnings: [
-            "Deterministic claim extraction could not infer a strict semantic claim; emitted a review artifact instead.",
-        ],
-    };
-}
-function extractHeuristicClaim(statement, source, confidence, provenance) {
-    const normalized = stripListPrefix(statement);
-    const retentionMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+be\s+retained\s+for\s+(?<value>\d+)\s+(?<unit>day|days|month|months|year|years)\.?$/i);
-    if (retentionMatch?.groups) {
-        const { unit, subject, value } = retentionMatch.groups;
-        if (!unit || !subject || !value)
-            return null;
-        const normalizedUnit = unit.toLowerCase().startsWith("day")
-            ? "Days"
-            : unit.toLowerCase().startsWith("month")
-                ? "Months"
-                : "Years";
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: `Retention ${normalizedUnit}`,
-                operator: "eq",
-                value: Number(value),
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    const enabledMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+be\s+(?<state>enabled|disabled)\.?$/i);
-    if (enabledMatch?.groups) {
-        const { subject, state } = enabledMatch.groups;
-        if (!subject || !state)
-            return null;
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: "enabled",
-                operator: "bool",
-                value: state.toLowerCase() === "enabled",
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    const forbiddenMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+not\s+(?<predicate>.+?)\.?$/i);
-    if (forbiddenMatch?.groups) {
-        const { subject, predicate } = forbiddenMatch.groups;
-        if (!subject || !predicate)
-            return null;
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: cleanPredicate(predicate),
-                operator: "polarity",
-                value: "forbid",
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    const requiredMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+(?<predicate>.+?)\.?$/i);
-    if (requiredMatch?.groups) {
-        const { subject, predicate } = requiredMatch.groups;
-        if (!subject || !predicate)
-            return null;
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: cleanPredicate(predicate),
-                operator: "polarity",
-                value: "require",
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    return null;
-}
-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;
-}
-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)) {
-        if (!normalizeOptionalString(args.subjectKey) ||
-            !normalizeOptionalString(args.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");
-        }
-        return {
-            statement,
-            source,
-            sourceFiles,
-            claim: {
-                source,
-                subjectKey: normalizeOptionalString(args.subjectKey),
-                propertyKey: normalizeOptionalString(args.propertyKey),
-                operator: args.operator,
-                value: normalizeClaimValue(args.value),
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            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),
-    };
-}
-function toRelationshipPlanRows(relationships) {
-    return relationships.map((relationship) => ({
-        type: relationship.type,
-        from: relationship.from,
-        to: relationship.to,
-    }));
-}
-export function strictWriteSetToApplyPlan(writeSet) {
-    if (!writeSet.isStrict) {
-        return [
-            {
-                type: writeSet.observationFact.type,
-                id: writeSet.observationFact.id,
-                properties: writeSet.observationFact.properties,
-                relationships: [],
-            },
-        ];
-    }
-    return [
-        {
-            type: writeSet.subjectFact.type,
-            id: writeSet.subjectFact.id,
-            properties: writeSet.subjectFact.properties,
-            relationships: [],
-        },
-        {
-            type: writeSet.propertyFact.type,
-            id: writeSet.propertyFact.id,
-            properties: writeSet.propertyFact.properties,
-            relationships: [],
-        },
-        {
-            type: writeSet.req.type,
-            id: writeSet.req.id,
-            properties: writeSet.req.properties,
-            relationships: toRelationshipPlanRows(writeSet.relationships),
-        },
-    ];
-}
-export function writeSetPrimaryEntityId(writeSet) {
-    return writeSet.isStrict ? writeSet.req.id : writeSet.observationFact.id;
-}
-export async function getWorkspaceMigrationWarning(workspaceRoot = resolveWorkspaceRoot()) {
-    const configPath = path.join(workspaceRoot, ".kb", "config.json");
-    let rawConfig;
-    try {
-        rawConfig = await readFile(configPath, "utf8");
-    }
-    catch {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(rawConfig);
-        const status = getSchemaVersionStatus(parsed ?? undefined);
-        return status.warning;
-    }
-    catch {
-        return "KB config schemaVersion could not be read and should be checked before applying automated modeling.";
-    }
-}
+export { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, };
 export async function handleKbModelRequirement(_prolog, args) {
-    const extracted = extractRequirementClaim(args);
-    const writeSet = buildStrictWriteSet({
-        claim: extracted.claim,
-        statement: extracted.statement,
-    });
-    const applyPlan = strictWriteSetToApplyPlan(writeSet);
-    const migrationWarning = await getWorkspaceMigrationWarning();
-    const warnings = writeSet.isStrict
-        ? []
-        : [
-            {
-                kind: "low_confidence_observation_downgrade",
-                message: `Claim confidence ${writeSet.confidence.toFixed(2)} is below the strict threshold 0.70, so Kibi emitted an observation fact instead of strict subject/property facts.`,
-                nextAction: "If this is normative, provide subjectKey, propertyKey, operator, and value explicitly, then apply the returned strict write-set sequentially.",
-            },
-        ];
-    const strictSummary = writeSet.isStrict
-        ? `Modeled strict requirement into ${applyPlan.length} sequential applyPlan step(s).`
-        : "Modeled a non-blocking observation review artifact; deterministic claim extraction stayed below the strict threshold.";
-    const structuredContent = {
-        statement: extracted.statement,
-        source: extracted.source,
-        sourceFiles: extracted.sourceFiles,
-        claim: extracted.claim,
-        writeSet,
-        applyPlan,
-        isStrict: writeSet.isStrict,
-        confidence: writeSet.confidence,
-        extractionMode: extracted.extractionMode,
-        extractionWarnings: extracted.extractionWarnings,
-        warnings,
-        migrationWarning,
-    };
-    return {
-        content: [
-            {
-                type: "text",
-                text: migrationWarning
-                    ? `${strictSummary} Migration warning included.`
-                    : strictSummary,
-            },
-        ],
-        structuredContent,
-        applyPlan,
-        writeSet,
-        migrationWarning,
+    const context = {
+        workspaceRoot: resolveWorkspaceRoot(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
     };
+    return modelRequirementSpec.execute(args, context);
 }

package/dist/tools/mutation-context.js

@@ -0,0 +1,28 @@
+import * as fs from "node:fs/promises";
+import { resolveWorkspaceRoot } from "../workspace.js";
+const filesystem = {
+    readFile: (filePath) => fs.readFile(filePath, "utf8"),
+    writeFile: (filePath, data) => fs.writeFile(filePath, data, "utf8"),
+    mkdir: async (directoryPath) => {
+        await fs.mkdir(directoryPath, { recursive: true });
+    },
+    stat: (filePath) => fs.stat(filePath),
+};
+// implements REQ-kibi-operation-interface-parity
+export function createMutationContext(prolog) {
+    const port = prolog === undefined
+        ? undefined
+        : {
+            query: (goal) => prolog.query(goal),
+            nextSolution: async () => null,
+            invalidateCache: () => prolog.invalidateCache(),
+            save: () => prolog.query("kb_save"),
+        };
+    return {
+        workspaceRoot: resolveWorkspaceRoot(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
+        fs: filesystem,
+        ...(port === undefined ? {} : { prolog: port }),
+    };
+}

package/dist/tools/query.js

@@ -1,52 +1,7 @@
-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
- */
+import { VALID_ENTITY_TYPES, querySpec } from "kibi-cli/operations";
+import { createDiscoveryContext } from "./discovery-adapter.js";
+export { VALID_ENTITY_TYPES };
 export async function handleKbQuery(prolog, args) {
-    const { type, id, tags, sourceFile, limit = 100, offset = 0 } = args;
-    try {
-        const queryArgs = {
-            ...(type !== undefined ? { type } : {}),
-            ...(id !== undefined ? { id } : {}),
-            ...(tags !== undefined ? { tags } : {}),
-            ...(sourceFile !== undefined ? { sourceFile } : {}),
-        };
-        const results = await loadEntities(prolog, queryArgs);
-        const paginated = paginateResults(results, limit, offset);
-        // Build human-readable text with entity IDs and titles
-        let text;
-        if (results.length === 0) {
-            text = `No entities found${type ? ` of type '${type}'` : ""}.`;
-        }
-        else {
-            const details = paginated
-                .map((e) => {
-                const id = e.id.replace(/^file:\/\/.*\//, "");
-                const title = e.title;
-                const status = e.status;
-                return `${id} (${title}, status=${status})`;
-            })
-                .join(", ");
-            text = `Found ${results.length} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${details}`;
-        }
-        // Return MCP structured response
-        return {
-            content: [
-                {
-                    type: "text",
-                    text,
-                },
-            ],
-            structuredContent: {
-                entities: paginated,
-                count: results.length,
-            },
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Query execution failed: ${message}`);
-    }
+    // implements REQ-kibi-operation-interface-parity
+    return querySpec.execute(args, createDiscoveryContext(prolog));
 }

package/dist/tools/relationship-validation.js

@@ -1,118 +1,11 @@
-import { escapeAtom, toPrologAtom } from "kibi-cli/prolog/codec";
-function getStringField(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 normalizePrologAtom(value) {
-    return value.replace(/^['"]|['"]$/g, "");
-}
-async function resolveEndpointType(input) {
-    if (input.endpointId === input.entity.id) {
-        const type = input.entity.type;
-        if (typeof type === "string" && type.trim() !== "") {
-            return type;
-        }
-    }
-    let result;
-    try {
-        result = await input.prolog.query(`kb_entity('${escapeAtom(input.endpointId)}', Type, _)`);
-    }
-    catch (error) {
-        if (error instanceof Error) {
-            return null;
-        }
-        throw error;
-    }
-    if (!result.success) {
-        return null;
-    }
-    const rawType = result.bindings?.Type;
-    if (typeof rawType !== "string" || rawType.trim() === "") {
-        return null;
-    }
-    return normalizePrologAtom(rawType);
-}
-function relationshipRecipe(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.",
-        ].join(" ");
-    }
-    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.",
-        ].join(" ");
-    }
-    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}. ${relationshipRecipe(tuple)}`;
-}
-export function formatInvalidRelationshipError(rawError) {
-    const placeholderMatch = rawError.match(/Invalid relationship:\s*~w from ~w to ~w-\[([^,\]]+),([^,\]]+),([^\]]+)\]/);
-    if (placeholderMatch) {
-        const [, relType, fromType, toType] = placeholderMatch;
-        if (relType && fromType && toType) {
-            return formatInvalidRelationshipTuple({ relType, fromType, toType });
-        }
-    }
-    const readableMatch = rawError.match(/Invalid relationship:\s*([^\s]+) from ([^\s]+) to ([^\s.]+)/);
-    if (readableMatch) {
-        const [, relType, fromType, toType] = readableMatch;
-        if (relType && fromType && toType) {
-            return formatInvalidRelationshipTuple({ relType, fromType, toType });
-        }
-    }
-    return null;
-}
-export function formatRelationshipSourceMismatch(entityId, relationship) {
-    const from = getStringField(relationship, "from");
-    const to = getStringField(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.`,
-    ].join(" ");
-}
+import { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, validateLiveRelationshipTargets as validateSharedTargets, } from "kibi-cli/operations/mutation/relationships";
+export { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, };
 export async function validateLiveRelationshipTargets(prolog, entity, relationships) {
-    for (const relationship of relationships) {
-        const fromType = await resolveEndpointType({
-            prolog,
-            entity,
-            endpointId: getStringField(relationship, "from"),
-        });
-        const toType = await resolveEndpointType({
-            prolog,
-            entity,
-            endpointId: getStringField(relationship, "to"),
-        });
-        if (fromType === null || toType === null) {
-            continue;
-        }
-        const tuple = {
-            relType: getStringField(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));
-        }
-    }
+    const port = {
+        query: (goal) => prolog.query(goal),
+        nextSolution: async () => null,
+        invalidateCache: () => prolog.invalidateCache(),
+        save: () => prolog.query("kb_save"),
+    };
+    await validateSharedTargets(port, entity, relationships);
 }

package/dist/tools/search.js

@@ -1,39 +1,6 @@
-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
+import { searchSpec } from "kibi-cli/operations";
+import { createDiscoveryContext } from "./discovery-adapter.js";
 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 !== undefined ? { 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}`);
-    }
+    // implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+    return searchSpec.execute(args, createDiscoveryContext(prolog));
 }