kibi-mcp 0.22.0 → 2.0.0

package/dist/tools/symbols.js

@@ -15,11 +15,13 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { access, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { access, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
-import { enrichSymbolCoordinates, } from "kibi-cli/extractors/symbols-coordinator";
+import { enrichSymbolCoordinates, withSymbolCompilerLock, } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "../workspace.js";
+const SYMBOL_COORDINATES_FORMAT_VERSION = 2;
 const SYMBOL_COORDINATES_COMMENT_BLOCK = `# symbol-coordinates.yaml
 # GENERATED coordinate artifact — do not edit manually.
 # Run \`kibi sync --refresh-symbol-coordinates\` to refresh.
@@ -41,11 +43,24 @@ const SOURCE_EXTENSIONS = new Set([
     ".mjs",
     ".cjs",
 ]);
+const COARSE_GRANULARITY_REASONS = new Set([
+    "test-suite",
+    "extractor-miss",
+    "module-level-behavior",
+    "config-artifact",
+]);
 export async function handleKbSymbolsRefresh(args) {
+    const workspaceRoot = args.workspaceRoot ?? resolveWorkspaceRoot();
+    return withSymbolCompilerLock(workspaceRoot, () => handleKbSymbolsRefreshUnlocked(args, workspaceRoot));
+}
+async function handleKbSymbolsRefreshUnlocked(args, workspaceRoot) {
     // implements REQ-vscode-traceability
     const dryRun = args.dryRun === true;
-    const workspaceRoot = args.workspaceRoot ?? resolveWorkspaceRoot();
     const { coordinatesPath, manifestPath } = await resolveManifestPaths(workspaceRoot);
+    const currentCoordinates = await readOptionalTextFile(coordinatesPath);
+    if (currentCoordinates !== null) {
+        readCoordinateArtifact(currentCoordinates);
+    }
     const rawContent = await readFile(manifestPath, "utf8");
     const parsed = parseYAML(rawContent);
     if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
@@ -86,10 +101,9 @@ export async function handleKbSymbolsRefresh(args) {
             unchanged++;
         }
     }
-    const nextCoordinates = writeCoordinateArtifact(buildCoordinatesMap(finalized));
-    const currentCoordinates = await readOptionalTextFile(coordinatesPath);
+    const nextCoordinates = writeCoordinateArtifact(await buildCoordinatesMap(finalized, workspaceRoot));
     if (!dryRun && currentCoordinates !== nextCoordinates) {
-        await writeFile(coordinatesPath, nextCoordinates, "utf8");
+        await publishCoordinateArtifact(coordinatesPath, nextCoordinates);
     }
     return {
         content: [
@@ -107,6 +121,9 @@ export async function handleKbSymbolsRefresh(args) {
     };
 }
 export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = resolveWorkspaceRoot()) {
+    return withSymbolCompilerLock(workspaceRoot, () => refreshCoordinatesForSymbolIdUnlocked(symbolId, workspaceRoot));
+}
+async function refreshCoordinatesForSymbolIdUnlocked(symbolId, workspaceRoot) {
     // implements REQ-vscode-traceability
     const { coordinatesPath, manifestPath } = await resolveManifestPaths(workspaceRoot);
     const rawContent = await readFile(manifestPath, "utf8");
@@ -137,18 +154,45 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
     parsed.symbols = symbols;
     const refreshed = GENERATED_COORD_FIELDS.some((field) => original[field] !== finalized[field]);
     const artifact = await readCoordinateArtifactFromPath(coordinatesPath);
+    const currentContent = await readOptionalTextFile(coordinatesPath);
     const nextCoordinates = {
         ...artifact.coordinates,
     };
+    if (artifact.status === "legacy") {
+        for (const [existingId, existingRecord] of Object.entries(nextCoordinates)) {
+            const existingManifestEntry = symbols.find((entry) => entry.id === existingId);
+            if (!existingManifestEntry ||
+                !(await legacyRecordMatchesCurrentExtraction(existingManifestEntry, existingRecord, workspaceRoot))) {
+                delete nextCoordinates[existingId];
+            }
+        }
+    }
     const coordinatesRecord = toCoordinateRecord(finalized);
     if (coordinatesRecord) {
-        nextCoordinates[symbolId] = coordinatesRecord;
+        const sourceText = await readSourceText(coordinatesRecord.sourceFile, workspaceRoot);
+        if (sourceText !== null) {
+            nextCoordinates[symbolId] =
+                artifact.status === "legacy" && currentContent !== null
+                    ? coordinatesRecord
+                    : {
+                        ...coordinatesRecord,
+                        identityHash: coordinateIdentityHash(finalized),
+                        sourceHash: coordinateSourceHash(sourceText),
+                    };
+        }
+    }
+    else if (nextCoordinates[symbolId] !== undefined) {
+        delete nextCoordinates[symbolId];
     }
-    if (coordinatesRecord || Object.keys(nextCoordinates).length > 0) {
-        const nextContent = writeCoordinateArtifact(nextCoordinates);
-        const currentContent = await readOptionalTextFile(coordinatesPath);
+    const removedExistingRecord = coordinatesRecord === null && artifact.coordinates[symbolId] !== undefined;
+    if (coordinatesRecord ||
+        Object.keys(nextCoordinates).length > 0 ||
+        removedExistingRecord) {
+        const nextContent = artifact.status === "legacy" && currentContent !== null
+            ? writeLegacyCoordinateArtifact(nextCoordinates)
+            : writeCoordinateArtifact(nextCoordinates);
         if (currentContent !== nextContent) {
-            await writeFile(coordinatesPath, nextContent, "utf8");
+            await publishCoordinateArtifact(coordinatesPath, nextContent);
         }
     }
     return { refreshed, found: true };
@@ -161,42 +205,11 @@ async function resolveManifestPaths(workspaceRoot) {
     };
 }
 export async function resolveManifestPath(workspaceRoot) {
-    // implements REQ-002, REQ-013
-    const configPath = path.join(workspaceRoot, ".kb", "config.json");
-    try {
-        const config = JSON.parse(await readFile(configPath, "utf8"));
-        // Prefer paths.symbols (new standard) over symbolsManifest (legacy)
-        if (config.paths?.symbols) {
-            return path.isAbsolute(config.paths.symbols)
-                ? config.paths.symbols
-                : path.resolve(workspaceRoot, config.paths.symbols);
-        }
-        // Backward compatibility: check legacy symbolsManifest field
-        if (config.symbolsManifest) {
-            return path.isAbsolute(config.symbolsManifest)
-                ? config.symbolsManifest
-                : path.resolve(workspaceRoot, config.symbolsManifest);
-        }
-    }
-    catch {
-        // config file missing or malformed; fall through to defaults
-    }
-    const candidates = [
-        path.join(workspaceRoot, "symbols.yaml"),
-        path.join(workspaceRoot, "symbols.yml"),
-    ];
-    for (const candidate of candidates) {
-        if (await fileExists(candidate)) {
-            return candidate;
-        }
-    }
-    return candidates[0] ?? path.join(workspaceRoot, "symbols.yaml");
+    // implements REQ-cli-canonical-runtime, REQ-vscode-traceability
+    return path.join(workspaceRoot, ".kb", "symbols.yaml");
 }
 function hasGeneratedCoordinates(entry) {
-    return (typeof entry.sourceLine === "number" &&
-        typeof entry.sourceColumn === "number" &&
-        typeof entry.sourceEndLine === "number" &&
-        typeof entry.sourceEndColumn === "number");
+    return normalizeCoordinateRecord(entry) !== null;
 }
 async function isEligible(sourceFile, workspaceRoot) {
     if (!sourceFile)
@@ -219,7 +232,13 @@ async function fileExists(filePath) {
 }
 async function fillMissingCoordinates(before, after, workspaceRoot) {
     if (hasGeneratedCoordinates(after)) {
-        return after;
+        const coordinate = toCoordinateRecord(after);
+        if (coordinate &&
+            (isCoarseAnchor(after) ||
+                (await coordinateMatchesCurrentDeclaration(after, coordinate, workspaceRoot)))) {
+            return after;
+        }
+        return withoutGeneratedCoordinates(after);
     }
     const sourceFile = typeof after.sourceFile === "string"
         ? after.sourceFile
@@ -231,7 +250,7 @@ async function fillMissingCoordinates(before, after, workspaceRoot) {
         : typeof before.title === "string"
             ? before.title
             : undefined;
-    if (!sourceFile || !title) {
+    if (!sourceFile) {
         return after;
     }
     const absolutePath = path.isAbsolute(sourceFile)
@@ -239,6 +258,40 @@ async function fillMissingCoordinates(before, after, workspaceRoot) {
         : path.resolve(workspaceRoot, sourceFile);
     try {
         const content = await readFile(absolutePath, "utf8");
+        const lines = content.split(/\r?\n/);
+        if (isCoarseAnchor(after)) {
+            return {
+                ...after,
+                ...coarseCoordinateSpan(sourceFile, title ?? "", content),
+            };
+        }
+        if (title) {
+            const escapedTitle = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const pattern = new RegExp(`\\b${escapedTitle}\\b`);
+            for (let index = 0; index < lines.length; index++) {
+                const line = lines[index];
+                if (!line)
+                    continue;
+                const match = pattern.exec(line);
+                if (!match || match.index < 0)
+                    continue;
+                return {
+                    ...after,
+                    sourceLine: index + 1,
+                    sourceColumn: match.index,
+                    sourceEndLine: index + 1,
+                    sourceEndColumn: match.index + title.length,
+                };
+            }
+        }
+    }
+    catch {
+        return after;
+    }
+    return after;
+}
+function coarseCoordinateSpan(sourceFile, title, content) {
+    if (title.length > 0) {
         const escapedTitle = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
         const pattern = new RegExp(`\\b${escapedTitle}\\b`);
         const lines = content.split(/\r?\n/);
@@ -250,7 +303,7 @@ async function fillMissingCoordinates(before, after, workspaceRoot) {
             if (!match || match.index < 0)
                 continue;
             return {
-                ...after,
+                sourceFile,
                 sourceLine: index + 1,
                 sourceColumn: match.index,
                 sourceEndLine: index + 1,
@@ -258,10 +311,77 @@ async function fillMissingCoordinates(before, after, workspaceRoot) {
             };
         }
     }
+    const lines = content.split(/\r?\n/);
+    const lastLine = lines[lines.length - 1] ?? "";
+    return {
+        sourceFile,
+        sourceLine: 1,
+        sourceColumn: 0,
+        sourceEndLine: Math.max(1, lines.length),
+        sourceEndColumn: lastLine.length,
+    };
+}
+function isCoarseAnchor(entry) {
+    return (typeof entry.granularity_reason === "string" &&
+        COARSE_GRANULARITY_REASONS.has(entry.granularity_reason));
+}
+function withoutGeneratedCoordinates(entry) {
+    const next = { ...entry };
+    for (const field of [
+        "sourceLine",
+        "sourceColumn",
+        "sourceEndLine",
+        "sourceEndColumn",
+        "coordinatesGeneratedAt",
+    ]) {
+        delete next[field];
+    }
+    return next;
+}
+function coordinateIdentityKey(entry) {
+    return [
+        typeof entry.id === "string" ? entry.id : "",
+        typeof entry.title === "string" ? entry.title : "",
+        typeof entry.sourceFile === "string" ? entry.sourceFile : "",
+        typeof entry.granularity_reason === "string"
+            ? entry.granularity_reason
+            : "",
+    ].join("\u0000");
+}
+function coordinateIdentityHash(entry) {
+    return createHash("sha256")
+        .update(coordinateIdentityKey(entry))
+        .digest("hex");
+}
+function coordinateSourceHash(sourceText) {
+    return createHash("sha256").update(sourceText).digest("hex");
+}
+async function readSourceText(sourceFile, workspaceRoot) {
+    const absolutePath = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    try {
+        return await readFile(absolutePath, "utf8");
+    }
     catch {
-        return after;
+        return null;
     }
-    return after;
+}
+async function coordinateMatchesCurrentDeclaration(entry, coordinate, workspaceRoot) {
+    const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : undefined;
+    const title = typeof entry.title === "string" ? entry.title : "";
+    if (!sourceFile || sourceFile !== coordinate.sourceFile || !title) {
+        return false;
+    }
+    const content = await readSourceText(coordinate.sourceFile, workspaceRoot);
+    if (content === null)
+        return false;
+    const declarationName = title.slice(title.lastIndexOf(".") + 1);
+    const line = content.split(/\r?\n/)[coordinate.sourceLine - 1];
+    return (declarationName.length > 0 &&
+        line !== undefined &&
+        coordinate.sourceColumn <= line.length - declarationName.length &&
+        line.slice(coordinate.sourceColumn, coordinate.sourceColumn + declarationName.length) === declarationName);
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -272,10 +392,19 @@ function normalizeCoordinateRecord(value) {
     }
     const { sourceColumn, sourceEndColumn, sourceEndLine, sourceFile, sourceLine, } = value;
     if (typeof sourceFile !== "string" ||
+        sourceFile.length === 0 ||
         typeof sourceLine !== "number" ||
+        !Number.isInteger(sourceLine) ||
+        sourceLine < 1 ||
         typeof sourceColumn !== "number" ||
+        !Number.isInteger(sourceColumn) ||
+        sourceColumn < 0 ||
         typeof sourceEndLine !== "number" ||
-        typeof sourceEndColumn !== "number") {
+        !Number.isInteger(sourceEndLine) ||
+        sourceEndLine < sourceLine ||
+        typeof sourceEndColumn !== "number" ||
+        !Number.isInteger(sourceEndColumn) ||
+        sourceEndColumn < 0) {
         return null;
     }
     return {
@@ -286,43 +415,127 @@ function normalizeCoordinateRecord(value) {
         sourceEndColumn,
     };
 }
+function isSha256Hash(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function normalizeBoundCoordinateRecord(value) {
+    if (!isRecord(value))
+        return null;
+    const record = normalizeCoordinateRecord(value);
+    const { identityHash, sourceHash } = value;
+    if (record === null ||
+        !isSha256Hash(identityHash) ||
+        !isSha256Hash(sourceHash)) {
+        return null;
+    }
+    return { ...record, identityHash, sourceHash };
+}
 function sortCoordinates(coordinates) {
     const sortedCoordinates = {};
     for (const symbolId of Object.keys(coordinates).sort((left, right) => left.localeCompare(right))) {
-        const record = normalizeCoordinateRecord(coordinates[symbolId]);
+        const record = normalizeBoundCoordinateRecord(coordinates[symbolId]);
         if (!record) {
-            continue;
+            throw new Error(`Invalid bound coordinate record for ${symbolId}; refusing to publish`);
         }
         sortedCoordinates[symbolId] = record;
     }
     return sortedCoordinates;
 }
 function readCoordinateArtifact(content) {
-    const parsed = parseYAML(content);
-    if (!isRecord(parsed) || !isRecord(parsed.coordinates)) {
-        return { coordinates: {} };
+    let parsed;
+    try {
+        parsed = parseYAML(content);
     }
-    const coordinates = {};
+    catch (error) {
+        throw new Error(`Failed to parse coordinate artifact: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (parsed === null || parsed === undefined) {
+        return { status: "legacy", coordinates: {} };
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("Coordinate artifact root must be a mapping");
+    }
+    if (!isRecord(parsed.coordinates)) {
+        throw new Error("Coordinate artifact coordinates must be a mapping");
+    }
+    const declaredVersion = parsed.version;
+    if (declaredVersion === undefined) {
+        const coordinates = {};
+        for (const [symbolId, record] of Object.entries(parsed.coordinates)) {
+            const normalizedRecord = normalizeCoordinateRecord(record);
+            if (!normalizedRecord) {
+                throw new Error(`Coordinate artifact record '${symbolId}' has an invalid coordinate span`);
+            }
+            coordinates[symbolId] = normalizedRecord;
+        }
+        return { status: "legacy", coordinates };
+    }
+    if (declaredVersion !== SYMBOL_COORDINATES_FORMAT_VERSION) {
+        throw new Error(`Unsupported coordinate artifact version: ${String(declaredVersion)}`);
+    }
+    const boundCoordinates = {};
     for (const [symbolId, record] of Object.entries(parsed.coordinates)) {
-        const normalizedRecord = normalizeCoordinateRecord(record);
+        const normalizedRecord = normalizeBoundCoordinateRecord(record);
         if (!normalizedRecord) {
-            continue;
+            throw new Error(`Coordinate artifact record '${symbolId}' is missing a valid identity/source binding or span`);
         }
-        coordinates[symbolId] = normalizedRecord;
+        boundCoordinates[symbolId] = normalizedRecord;
     }
-    return { coordinates };
+    return { status: "parsed", coordinates: boundCoordinates };
 }
 function writeCoordinateArtifact(coordinates) {
-    return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML({ coordinates: sortCoordinates(coordinates) }, {
+    return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML({
+        version: SYMBOL_COORDINATES_FORMAT_VERSION,
+        coordinates: sortCoordinates(coordinates),
+    }, {
         lineWidth: -1,
         noRefs: true,
-        sortKeys: true,
     })}`;
 }
+function writeLegacyCoordinateArtifact(coordinates) {
+    const sortedCoordinates = {};
+    for (const symbolId of Object.keys(coordinates).sort((left, right) => left.localeCompare(right))) {
+        const record = normalizeCoordinateRecord(coordinates[symbolId]);
+        if (!record) {
+            throw new Error(`Invalid legacy coordinate record for ${symbolId}; refusing to publish`);
+        }
+        sortedCoordinates[symbolId] = record;
+    }
+    return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML({ coordinates: sortedCoordinates }, { lineWidth: -1, noRefs: true })}`;
+}
 function toCoordinateRecord(entry) {
     return normalizeCoordinateRecord(entry);
 }
-function buildCoordinatesMap(entries) {
+async function legacyRecordMatchesCurrentExtraction(record, coordinate, workspaceRoot) {
+    if (!normalizeCoordinateRecord(coordinate))
+        return false;
+    const sourceFile = typeof record.sourceFile === "string" ? record.sourceFile : undefined;
+    const title = typeof record.title === "string" ? record.title : "";
+    if (!sourceFile)
+        return false;
+    const content = await readSourceText(coordinate.sourceFile, workspaceRoot);
+    if (content === null || coordinate.sourceFile !== sourceFile)
+        return false;
+    if (isCoarseAnchor(record)) {
+        return coordinatesEqual(coordinate, coarseCoordinateSpan(sourceFile, title, content));
+    }
+    if (!title)
+        return false;
+    const declarationName = title.slice(title.lastIndexOf(".") + 1);
+    const line = content.split(/\r?\n/)[coordinate.sourceLine - 1];
+    return (declarationName.length > 0 &&
+        line !== undefined &&
+        coordinate.sourceColumn <= line.length - declarationName.length &&
+        line.slice(coordinate.sourceColumn, coordinate.sourceColumn + declarationName.length) === declarationName);
+}
+function coordinatesEqual(left, right) {
+    return (left.sourceFile === right.sourceFile &&
+        left.sourceLine === right.sourceLine &&
+        left.sourceColumn === right.sourceColumn &&
+        left.sourceEndLine === right.sourceEndLine &&
+        left.sourceEndColumn === right.sourceEndColumn);
+}
+async function buildCoordinatesMap(entries, workspaceRoot) {
     const coordinates = {};
     for (const entry of entries) {
         const id = typeof entry.id === "string" ? entry.id : undefined;
@@ -330,14 +543,21 @@ function buildCoordinatesMap(entries) {
         if (!id || !record) {
             continue;
         }
-        coordinates[id] = record;
+        const sourceText = await readSourceText(record.sourceFile, workspaceRoot);
+        if (sourceText === null)
+            continue;
+        coordinates[id] = {
+            ...record,
+            identityHash: coordinateIdentityHash(entry),
+            sourceHash: coordinateSourceHash(sourceText),
+        };
     }
     return coordinates;
 }
 async function readCoordinateArtifactFromPath(coordinatesPath) {
     const content = await readOptionalTextFile(coordinatesPath);
     if (content === null) {
-        return { coordinates: {} };
+        return { status: "legacy", coordinates: {} };
     }
     return readCoordinateArtifact(content);
 }
@@ -345,7 +565,29 @@ async function readOptionalTextFile(filePath) {
     try {
         return await readFile(filePath, "utf8");
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error !== null &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function publishCoordinateArtifact(targetPath, content) {
+    const temporary = `${targetPath}.kibi-tmp-${process.pid}`;
+    try {
+        await writeFile(temporary, content, "utf8");
+        await rename(temporary, targetPath);
+    }
+    catch (error) {
+        try {
+            await unlink(temporary);
+        }
+        catch {
+            // Preserve the publication failure; cleanup is best effort.
+        }
+        throw error;
     }
 }

package/dist/tools/upsert.js

@@ -1,6 +1,6 @@
-import { upsertSpec } from "kibi-cli/operations";
-import { setSymbolRefreshForTests } from "kibi-cli/operations/mutation/symbol-refresh";
-import { validateUpsertInput } from "kibi-cli/operations/mutation/validation";
+import { upsertSpec } from "kibi-runtime";
+import { setSymbolRefreshForTests } from "kibi-runtime";
+import { validateUpsertInput } from "kibi-runtime";
 import { isMcpDebugEnabled } from "../env.js";
 import { createMutationContext } from "./mutation-context.js";
 export async function handleKbUpsert(prolog, args) {

package/dist/tools/validate-upsert.js

@@ -1,4 +1,4 @@
-import { validateUpsertSpec } from "kibi-cli/operations";
+import { validateUpsertSpec } from "kibi-runtime";
 import { createMutationContext } from "./mutation-context.js";
 function isUpsertArgs(value) {
     return "type" in value && "id" in value && "properties" in value;

package/dist/tools-config.js

@@ -15,7 +15,7 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
-import { getSpec } from "kibi-cli/operations";
+import { getSpec } from "kibi-runtime";
 import { DIAGNOSTIC_MODE_ENABLED, DIAGNOSTIC_TELEMETRY_SCHEMA, } from "./diagnostics.js";
 const MCP_TOOL_ORDER = [
     "kb_query",
@@ -35,10 +35,19 @@ const MCP_TOOL_ORDER = [
     "kb_check",
     "kb_model_requirement",
     "kb_suggest_predicates",
-    "kb_autopilot_generate",
+    "kb_plan_bootstrap",
+    "kb_compile_intent",
+    "kb_apply_plan",
+    "kb_ingest_proof",
 ];
 // implements REQ-002
 const TOOL_ANNOTATIONS = {
+    kb_query: {
+        title: "Query Kibi entities",
+    },
+    kb_search: {
+        title: "Search Kibi knowledge base",
+    },
     kb_status: {
         title: "Inspect Kibi branch status",
         readOnlyHint: true,
@@ -67,6 +76,18 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: false,
     },
+    kb_find_gaps: {
+        title: "Find missing Kibi relationships",
+    },
+    kb_coverage: {
+        title: "Report Kibi coverage and proofs",
+    },
+    kb_graph: {
+        title: "Traverse Kibi graph",
+    },
+    kb_sparql_remote: {
+        title: "Run a remote SPARQL query",
+    },
     kb_semantic_advisor: {
         title: "Advise on Kibi requirement modeling",
         readOnlyHint: true,
@@ -81,14 +102,67 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: false,
     },
+    kb_upsert: {
+        title: "Create or update Kibi entities",
+    },
+    kb_validate_upsert: {
+        title: "Validate a Kibi upsert payload",
+    },
+    kb_delete: {
+        title: "Delete a Kibi entity",
+    },
+    kb_check: {
+        title: "Validate Kibi knowledge base",
+    },
+    kb_model_requirement: {
+        title: "Model a Kibi requirement",
+    },
+    kb_compile_intent: {
+        title: "Compile Kibi change intent",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    kb_plan_bootstrap: {
+        title: "Plan Kibi bootstrap",
+    },
+    kb_apply_plan: {
+        title: "Apply an approved Kibi plan",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+    kb_ingest_proof: {
+        title: "Ingest proof-run evidence",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
 };
 const BASE_TOOLS = MCP_TOOL_ORDER.map((name) => {
     const spec = getSpec(name);
+    const effects = spec.declaredEffects;
+    const derived = {
+        readOnlyHint: effects.every((effect) => effect.mutability === "read"),
+        destructiveHint: effects.some((effect) => effect.destructive),
+        idempotentHint: effects.every((effect) => effect.retrySafety === "safe"),
+        openWorldHint: effects.some((effect) => effect.openWorld),
+    };
     return {
         name: spec.name,
         description: spec.description,
         inputSchema: spec.businessInputSchema,
-        ...(TOOL_ANNOTATIONS[name] ? { annotations: TOOL_ANNOTATIONS[name] } : {}),
+        ...(spec.outputSchema ? { outputSchema: spec.outputSchema } : {}),
+        annotations: {
+            ...(TOOL_ANNOTATIONS[name] ?? {}),
+            // Mutability and world-model hints are generated from the authoritative
+            // operation effects. Hand-authored entries may supply presentation-only
+            // metadata such as a title, but cannot contradict the catalog contract.
+            ...derived,
+        },
     };
 });
 /**