peaks-loop 4.1.1 → 4.1.3

package/dist/services/mcp/json-rpc.d.ts

@@ -0,0 +1,81 @@
+/** The only JSON-RPC version this server speaks. */
+export declare const JSON_RPC_VERSION: "2.0";
+/** A request/response correlation id. `null` is legal and means "unknown". */
+export type JsonRpcId = string | number | null;
+export interface JsonRpcErrorObject {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcRequest {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+/** A request WITHOUT an id. JSON-RPC forbids replying to one. */
+export interface JsonRpcNotification {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcSuccess {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly result: unknown;
+}
+export interface JsonRpcFailure {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly error: JsonRpcErrorObject;
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+/** Standard JSON-RPC codes. The server adds no private codes of its own. */
+export declare const JSON_RPC_PARSE_ERROR = -32700;
+export declare const JSON_RPC_INVALID_REQUEST = -32600;
+export declare const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export declare const JSON_RPC_INVALID_PARAMS = -32602;
+export declare const JSON_RPC_INTERNAL_ERROR = -32603;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** What one decoded line turned out to be. */
+export type DecodedMessage = {
+    readonly kind: 'request';
+    readonly request: JsonRpcRequest;
+} | {
+    readonly kind: 'notification';
+    readonly notification: JsonRpcNotification;
+} | {
+    readonly kind: 'invalid';
+    readonly id: JsonRpcId;
+    readonly error: JsonRpcErrorObject;
+};
+export declare function makeError(code: number, message: string, data?: unknown): JsonRpcErrorObject;
+export declare function successResponse(id: JsonRpcId, result: unknown): JsonRpcSuccess;
+export declare function failureResponse(id: JsonRpcId, error: JsonRpcErrorObject): JsonRpcFailure;
+/**
+ * Decode one frame.
+ *
+ * `undefined` means "nothing to answer" — an empty line, which is legal padding
+ * and must not be reported as a parse error (an empty line is not a message the
+ * peer sent; it is whitespace between messages).
+ */
+export declare function decodeMessage(line: string): DecodedMessage | undefined;
+/**
+ * Encode one frame for the wire. `JSON.stringify` escapes every newline inside
+ * a string, which is what keeps one message on one line.
+ */
+export declare function encodeMessage(message: JsonRpcResponse | JsonRpcNotification): string;
+/**
+ * The buffer that turns an arbitrary chunking of bytes into whole lines.
+ *
+ * Needed because a pipe delivers no framing of its own: one `data` event may
+ * carry half a message or three of them, and a server that parsed each event as
+ * a message would work on a fast local pipe and fail on a loaded one.
+ */
+export declare class LineDecoder {
+    private buffer;
+    /** Feed a chunk; get back the complete lines it completed (no trailing newline). */
+    push(chunk: string): string[];
+    /** Whatever is left when the stream ends. A peer that never sent a newline still sent a message. */
+    flush(): string[];
+}

package/dist/services/mcp/json-rpc.js

@@ -0,0 +1,116 @@
+// src/services/mcp/json-rpc.ts
+//
+// JSON-RPC 2.0 message shapes plus the stdio framing MCP uses, implemented in
+// this tree rather than pulled in as a dependency.
+//
+// WHY NOT THE SDK. peaks-loop ships 12 runtime dependencies to every user
+// globally, and the protocol surface this server needs is four methods and five
+// error codes — all frozen since the first MCP revision. A dependency would be
+// the larger commitment. See the slice report for the exact surface list.
+//
+// THE FRAMING IS NEWLINE-DELIMITED JSON, not LSP's `Content-Length` headers.
+// That is the MCP stdio transport's rule, and it is also why a message may not
+// contain a raw newline: this module therefore serializes with `JSON.stringify`
+// (which escapes newlines inside strings) and never pretty-prints.
+/** The only JSON-RPC version this server speaks. */
+export const JSON_RPC_VERSION = '2.0';
+/** Standard JSON-RPC codes. The server adds no private codes of its own. */
+export const JSON_RPC_PARSE_ERROR = -32700;
+export const JSON_RPC_INVALID_REQUEST = -32600;
+export const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export const JSON_RPC_INVALID_PARAMS = -32602;
+export const JSON_RPC_INTERNAL_ERROR = -32603;
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isJsonRpcId(value) {
+    return typeof value === 'string' || typeof value === 'number' || value === null;
+}
+export function makeError(code, message, data) {
+    return data === undefined ? { code, message } : { code, message, data };
+}
+export function successResponse(id, result) {
+    return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+export function failureResponse(id, error) {
+    return { jsonrpc: JSON_RPC_VERSION, id, error };
+}
+function invalid(id, code, message) {
+    return { kind: 'invalid', id, error: makeError(code, message) };
+}
+/** The message's id when it carries a legal one, else the protocol's `null`. */
+function idOf(parsed) {
+    const id = parsed['id'];
+    return isJsonRpcId(id) ? id : null;
+}
+/**
+ * Build the message from a well-formed envelope. The presence of the `id` KEY is
+ * the only thing separating a request from a notification — `id: null` is a legal
+ * id, so this cannot be written as a null check.
+ */
+function buildMessage(parsed, method) {
+    const params = parsed['params'];
+    const head = { jsonrpc: JSON_RPC_VERSION, method, ...(params === undefined ? {} : { params }) };
+    return 'id' in parsed
+        ? { kind: 'request', request: { ...head, id: idOf(parsed) } }
+        : { kind: 'notification', notification: head };
+}
+/**
+ * Decode one frame.
+ *
+ * `undefined` means "nothing to answer" — an empty line, which is legal padding
+ * and must not be reported as a parse error (an empty line is not a message the
+ * peer sent; it is whitespace between messages).
+ */
+export function decodeMessage(line) {
+    if (line.trim().length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return invalid(null, JSON_RPC_PARSE_ERROR, 'Invalid JSON received on the transport.');
+    }
+    if (!isPlainObject(parsed) || parsed['jsonrpc'] !== JSON_RPC_VERSION) {
+        const id = isPlainObject(parsed) ? idOf(parsed) : null;
+        return invalid(id, JSON_RPC_INVALID_REQUEST, `Messages must declare jsonrpc "${JSON_RPC_VERSION}".`);
+    }
+    const method = parsed['method'];
+    if (typeof method !== 'string' || method.length === 0) {
+        return invalid(idOf(parsed), JSON_RPC_INVALID_REQUEST, 'Messages must carry a non-empty "method".');
+    }
+    return buildMessage(parsed, method);
+}
+/**
+ * Encode one frame for the wire. `JSON.stringify` escapes every newline inside
+ * a string, which is what keeps one message on one line.
+ */
+export function encodeMessage(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+/**
+ * The buffer that turns an arbitrary chunking of bytes into whole lines.
+ *
+ * Needed because a pipe delivers no framing of its own: one `data` event may
+ * carry half a message or three of them, and a server that parsed each event as
+ * a message would work on a fast local pipe and fail on a loaded one.
+ */
+export class LineDecoder {
+    buffer = '';
+    /** Feed a chunk; get back the complete lines it completed (no trailing newline). */
+    push(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        // The last element is either an incomplete line or '' when the chunk ended
+        // on a newline. Either way it stays buffered for the next push.
+        this.buffer = lines.pop() ?? '';
+        return lines;
+    }
+    /** Whatever is left when the stream ends. A peer that never sent a newline still sent a message. */
+    flush() {
+        const remainder = this.buffer.trim().length > 0 ? [this.buffer] : [];
+        this.buffer = '';
+        return remainder;
+    }
+}

package/dist/services/mcp/memory-tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext, type ToolCallResult } from './tool-core.js';
+export declare function callMemorySearchTool(tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Promise<ToolCallResult>;

package/dist/services/mcp/memory-tool.js

@@ -0,0 +1,62 @@
+// src/services/mcp/memory-tool.ts
+//
+// `peaks_memory_search`: one argv, a bounded reply (§7.1).
+//
+// It answers "is there anything, and what is it called" — never "what does it
+// say". The raw CLI output is measured in megabytes, so the reply is bounded
+// twice over: a hard ceiling on how many matches come back, and a truncated
+// excerpt per match. Both are on §3.2's allowed list for a composite tool
+// (field selection and truncation), and neither concludes anything: the count,
+// the names and the first characters are all the CLI's.
+import { buildArgv } from '../readonly-surface/argv-guard.js';
+import { MEMORY_EXCERPT_CHARS, MEMORY_MAX_RETURNED, rejectedResult, resultOf, runArgv, valuesForEntry } from './tool-core.js';
+/** Project one raw CLI match down to the fields §7.1 allows, with a bounded excerpt. */
+function boundMatch(raw) {
+    const match = typeof raw === 'object' && raw !== null ? raw : {};
+    const description = typeof match['description'] === 'string' ? match['description'] : '';
+    return {
+        name: match['name'],
+        kind: match['kind'],
+        excerpt: description.slice(0, MEMORY_EXCERPT_CHARS)
+    };
+}
+export async function callMemorySearchTool(tool, args, context) {
+    const entry = tool.entries[0];
+    if (entry === undefined) {
+        return { content: [{ type: 'text', text: '{"reason":"no entry"}' }], isError: true };
+    }
+    const values = valuesForEntry(entry, args, context);
+    if (values === undefined) {
+        return rejectedResult(entry, 'A search query is required.');
+    }
+    const built = buildArgv(entry, values);
+    if (!built.ok) {
+        return rejectedResult(entry, `Parameter ${built.param} was refused: ${built.message}`);
+    }
+    const outcome = await runArgv(entry.id, built.argv, context);
+    if (outcome.failure !== undefined)
+        return resultOf([outcome]);
+    const envelope = outcome.envelope;
+    const record = typeof envelope === 'object' && envelope !== null ? envelope : {};
+    const matches = record['matches'];
+    if (!Array.isArray(matches)) {
+        // No `matches` array is not "nothing matched" — it is a shape this tool does
+        // not understand, and reporting it as empty is the failure §9 rule 3 names.
+        const argv = outcome.execution.argv.join(' ');
+        return resultOf([
+            { ...outcome, failure: `peaks memory search returned no matches array: peaks ${argv}` }
+        ]);
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    query: record['query'],
+                    total: record['total'],
+                    matches: matches.slice(0, MEMORY_MAX_RETURNED).map(boundMatch)
+                })
+            }
+        ]
+    };
+}

package/dist/services/mcp/server-main.d.ts

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

package/dist/services/mcp/server-main.js

@@ -0,0 +1,66 @@
+// src/services/mcp/server-main.ts
+//
+// The process entry: a stdin pipe, a stdout pipe, and spec §6's L4 check before
+// either is used.
+//
+// STDOUT CARRIES PROTOCOL AND NOTHING ELSE. Any diagnostic goes to stderr,
+// because a harness reads stdout as the message stream and one stray line is a
+// parse error that is indistinguishable from a broken server. That is also why
+// the startup refusal below writes to stderr and exits non-zero rather than
+// printing a JSON error: at that point there is no session to answer in.
+//
+// L4 REFUSES TO START. If the surface cannot be served as proven — a tool with
+// no description, an argv the whitelist does not carry, a whitelisted argv
+// reachable from no tool, or a tool with no handler — this process exits 1.
+// A server that started anyway would be serving something nobody proved, and the
+// failure would surface as data rather than as a refusal (spec §6, L4).
+import { loadReadOnlyWhitelist } from '../readonly-surface/readonly-whitelist.js';
+import { LineDecoder } from './json-rpc.js';
+import { buildToolDefinitions, validateSurface } from './surface.js';
+import { createMcpServer } from './server.js';
+import { missingHandlers } from './tools.js';
+function refuse(reason) {
+    process.stderr.write(`peaks mcp: ${reason}\n`);
+    process.exit(1);
+}
+function start() {
+    let tools;
+    try {
+        const whitelist = loadReadOnlyWhitelist();
+        tools = buildToolDefinitions(whitelist);
+        validateSurface(whitelist, tools);
+    }
+    catch (error) {
+        refuse(`refusing to start: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const unserved = missingHandlers(tools);
+    if (unserved.length > 0) {
+        refuse(`refusing to start: no handler for tool(s) ${unserved.join(', ')}`);
+    }
+    const server = createMcpServer({ tools });
+    const decoder = new LineDecoder();
+    const write = (line) => {
+        if (line !== undefined)
+            process.stdout.write(line);
+    };
+    const consume = (line) => {
+        void server.handleLine(line).then(write);
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+        for (const line of decoder.push(chunk))
+            consume(line);
+    });
+    process.stdin.on('end', () => {
+        for (const line of decoder.flush())
+            consume(line);
+    });
+    // A read error on our own transport is not recoverable and not ours to
+    // interpret: report it and stop, so the harness sees a dead server instead of
+    // a live one that answers nothing.
+    process.stdin.on('error', (error) => {
+        process.stderr.write(`peaks mcp: stdin error: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+}
+start();

package/dist/services/mcp/server.d.ts

@@ -0,0 +1,22 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext } from './tool-core.js';
+/** Used when the client names no protocol version. */
+export declare const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+/** The server's own name, as it appears in `initialize`. */
+export declare const SERVER_NAME = "peaks";
+export declare const METHOD_INITIALIZE = "initialize";
+export declare const METHOD_INITIALIZED = "notifications/initialized";
+export declare const METHOD_TOOLS_LIST = "tools/list";
+export declare const METHOD_TOOLS_CALL = "tools/call";
+export interface McpServerOptions {
+    readonly tools: readonly McpToolDefinition[];
+    readonly context?: ToolCallContext;
+    readonly serverVersion?: string;
+}
+export interface McpServer {
+    /** Answer one line. A notification (or blank line) yields `undefined`. */
+    handleLine(line: string): Promise<string | undefined>;
+    /** The tools, for a caller that wants to assert what it built. */
+    readonly tools: readonly McpToolDefinition[];
+}
+export declare function createMcpServer(options: McpServerOptions): McpServer;

package/dist/services/mcp/server.js

@@ -0,0 +1,152 @@
+// src/services/mcp/server.ts
+//
+// The protocol core: one decoded line in, at most one encoded line out.
+//
+// WHAT THIS SERVER IS. A table lookup, an execution, and the CLI's own answer —
+// nothing else (spec §3, component 3: "there is no fourth responsibility").
+// It does not know what a gate is, does not cache, keeps no state between
+// messages, and never rewrites a CLI result. `handleLine` is a pure function of
+// (line, surface, context), which is also what makes it testable without a pipe.
+//
+// THE PROTOCOL SURFACE IS DELIBERATELY SMALL and is listed in full here so it can
+// be checked line by line rather than inferred:
+//
+//   initialize                -> protocolVersion, capabilities.tools, serverInfo
+//   notifications/initialized -> accepted, no reply (it is a notification)
+//   tools/list                -> tools[] {name, description, inputSchema}
+//   tools/call                -> params {name, arguments} -> content[] | isError
+//   (anything else, request)  -> -32601 METHOD_NOT_FOUND
+//   (anything else, notification) -> ignored; JSON-RPC forbids replying
+//   malformed JSON            -> -32700   wrong envelope -> -32600
+//   bad tools/call params     -> -32602   handler crash  -> -32603
+//
+// NOT IMPLEMENTED, on purpose: `ping`, `resources/*`, `prompts/*`, `logging/*`,
+// `completion/*`, `notifications/*` beyond `initialized`, progress tokens,
+// cancellation, and resource subscriptions. Any of them arrives as a
+// METHOD_NOT_FOUND rather than as silence.
+//
+// NO HANDSHAKE STATE. The server does not track whether `initialize` has been
+// seen; every method is answerable on any line. MCP asks clients to initialize
+// first, and this server simply does not depend on it — a state machine here
+// would be state kept for no decision.
+//
+// PROTOCOL VERSION. The client's requested version is echoed when it names one,
+// and a constant is used otherwise. Echoing is honest for this surface and not a
+// claim of unlimited support: the four methods above have had identical request
+// and response shapes across every published revision, so there is no version
+// whose meaning this server would get wrong.
+import { CLI_VERSION } from 'peaks-loop-shared/version';
+import { decodeMessage, encodeMessage, failureResponse, isPlainObject, makeError, successResponse, JSON_RPC_INTERNAL_ERROR, JSON_RPC_INVALID_PARAMS, JSON_RPC_METHOD_NOT_FOUND } from './json-rpc.js';
+import { handlerFor } from './tools.js';
+/** Used when the client names no protocol version. */
+export const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+/** The server's own name, as it appears in `initialize`. */
+export const SERVER_NAME = 'peaks';
+export const METHOD_INITIALIZE = 'initialize';
+export const METHOD_INITIALIZED = 'notifications/initialized';
+export const METHOD_TOOLS_LIST = 'tools/list';
+export const METHOD_TOOLS_CALL = 'tools/call';
+/** The tool shape that goes on the wire — behaviour without the whitelist entries. */
+function wireTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+    };
+}
+function requestedVersion(params) {
+    if (!isPlainObject(params))
+        return undefined;
+    const version = params['protocolVersion'];
+    return typeof version === 'string' && version.length > 0 ? version : undefined;
+}
+function callArguments(params) {
+    const args = params['arguments'];
+    if (args === undefined)
+        return {};
+    return isPlainObject(args) ? args : undefined;
+}
+/**
+ * Reject an argument the tool does not declare, BEFORE anything runs. The tool
+ * schemas set `additionalProperties: false`; enforcing it here is what makes
+ * that a promise rather than a hint, and it is the boundary at which an
+ * injection-shaped key ("--apply") stops being an argument.
+ */
+function unknownArgument(tool, args) {
+    const declared = new Set(Object.keys(tool.inputSchema.properties));
+    return Object.keys(args).find((name) => !declared.has(name));
+}
+function initializeResult(params, version) {
+    return {
+        protocolVersion: requestedVersion(params) ?? DEFAULT_PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, version }
+    };
+}
+function fail(id, message) {
+    return encodeMessage(failureResponse(id, makeError(JSON_RPC_INVALID_PARAMS, message)));
+}
+async function toolsCallResult(tools, context, id, params) {
+    if (!isPlainObject(params)) {
+        return fail(id, 'tools/call requires an object of parameters.');
+    }
+    const name = params['name'];
+    if (typeof name !== 'string' || name.length === 0) {
+        return fail(id, 'tools/call requires a tool "name".');
+    }
+    const tool = tools.find((candidate) => candidate.name === name);
+    const handler = tool === undefined ? undefined : handlerFor(tool.name);
+    if (tool === undefined || handler === undefined) {
+        return fail(id, `Unknown tool: ${name}`);
+    }
+    const args = callArguments(params);
+    if (args === undefined) {
+        return fail(id, 'tools/call "arguments" must be an object.');
+    }
+    const unexpected = unknownArgument(tool, args);
+    if (unexpected !== undefined) {
+        return fail(id, `Tool ${name} declares no argument "${unexpected}".`);
+    }
+    return encodeMessage(successResponse(id, await handler(tool, args, context)));
+}
+export function createMcpServer(options) {
+    const tools = options.tools;
+    const context = options.context ?? {};
+    const version = options.serverVersion ?? CLI_VERSION;
+    const respond = async (id, method, params) => {
+        switch (method) {
+            case METHOD_INITIALIZE:
+                return encodeMessage(successResponse(id, initializeResult(params, version)));
+            case METHOD_TOOLS_LIST:
+                return encodeMessage(successResponse(id, { tools: tools.map(wireTool) }));
+            case METHOD_TOOLS_CALL:
+                return toolsCallResult(tools, context, id, params);
+            default:
+                return encodeMessage(failureResponse(id, makeError(JSON_RPC_METHOD_NOT_FOUND, `Unknown method: ${method}`)));
+        }
+    };
+    const handleLine = async (line) => {
+        const decoded = decodeMessage(line);
+        if (decoded === undefined)
+            return undefined;
+        if (decoded.kind === 'invalid') {
+            return encodeMessage(failureResponse(decoded.id, decoded.error));
+        }
+        if (decoded.kind === 'notification') {
+            // Notifications are answered by not answering. `initialized` needs no
+            // branch of its own for that reason — but an unknown one is silently
+            // dropped, which is the protocol's rule, not this server's leniency.
+            return undefined;
+        }
+        try {
+            return await respond(decoded.request.id, decoded.request.method, decoded.request.params);
+        }
+        catch (error) {
+            // A handler crash is reported, never swallowed: the caller has to know the
+            // answer is missing rather than empty.
+            const message = error instanceof Error ? error.message : 'Internal error';
+            return encodeMessage(failureResponse(decoded.request.id, makeError(JSON_RPC_INTERNAL_ERROR, message)));
+        }
+    };
+    return { tools, handleLine };
+}

package/dist/services/mcp/surface.d.ts

@@ -0,0 +1,62 @@
+import { type ReadOnlyWhitelist, type ReadOnlyWhitelistEntry } from '../readonly-surface/readonly-whitelist.js';
+/** One JSON Schema property, as far as this surface needs one. */
+export interface JsonSchemaProperty {
+    readonly type: 'string' | 'integer';
+    readonly description?: string;
+    readonly pattern?: string;
+    readonly enum?: readonly string[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly default?: number;
+}
+export interface JsonSchema {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, JsonSchemaProperty>>;
+    readonly required: readonly string[];
+    /** The LLM must not send anything else; an unknown key is a refused call. */
+    readonly additionalProperties: false;
+}
+export interface McpToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    /** The whitelist entries this tool runs, in whitelist order. Kept off the wire. */
+    readonly entries: readonly ReadOnlyWhitelistEntry[];
+}
+/** Group the whitelist's entries into tools, preserving first-appearance order. */
+export declare function buildToolDefinitions(whitelist: ReadOnlyWhitelist): readonly McpToolDefinition[];
+/** Load the whitelist artifact and build the surface from it. */
+export declare function loadToolDefinitions(): readonly McpToolDefinition[];
+/** Why a surface was refused. Named so the server can print it and exit non-zero. */
+export declare class McpSurfaceError extends Error {
+    constructor(message: string);
+}
+/** An entry's argv as a comparable template key: literals literal, placeholders `{name}`. */
+export declare function argvTemplateOf(entry: ReadOnlyWhitelistEntry): string;
+/**
+ * Refuse a whitelist artifact that is not internally coherent.
+ *
+ * WHO THIS IS FOR. The artifact is generated and CI re-generates it, so the
+ * shape below holds on a clean checkout. The failure it exists for is the one
+ * that leaves no other trace: the file is edited by hand, or an entry is
+ * half-written, and a server starts up happily serving a surface nothing proved.
+ * Every rule here is a property the generator establishes and a hand-edit
+ * breaks, so a violated rule means "this is not the generated artifact".
+ */
+export declare function validateWhitelist(whitelist: ReadOnlyWhitelist): void;
+/**
+ * L4 (spec §6): refuse to start when the tool surface and the proven whitelist do
+ * not describe the same thing.
+ *
+ * Two properties, each meant to fail loudly rather than degrade:
+ *
+ *   1. Every argv a tool can run is a whitelisted argv, by template. The surface
+ *      is derived from the same artifact today, so on the production path this
+ *      reads as "nothing unproven got in" — but it is the boundary that has to
+ *      hold the moment a tool is authored rather than derived, and the test
+ *      proves it can fail by handing it a surface that names an unproven argv.
+ *   2. Every whitelisted entry is reachable from some tool. This one DOES have a
+ *      live trigger: an entry added to `readonly-surface.json` whose tool name is
+ *      mistyped is proven read-only and then never served.
+ */
+export declare function validateSurface(whitelist: ReadOnlyWhitelist, tools: readonly McpToolDefinition[]): void;