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;