peaks-loop 4.1.2 → 4.1.3

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;

package/dist/services/mcp/surface.js

@@ -0,0 +1,198 @@
+// src/services/mcp/surface.ts
+//
+// The tool surface, DERIVED from the generated read-only whitelist rather than
+// restated beside it.
+//
+// WHY DERIVED. "Every argv a tool can run is whitelisted" is only checkable if
+// there is no second list to disagree with. So the tools ARE the whitelist's
+// entries grouped by their `tool` field: adding a tool means editing
+// `contracts/readonly-surface.json` and regenerating, and a tool whose argv was
+// never proven read-only cannot be declared here at all.
+//
+// `validateSurface` is spec §6's L4 — the startup check. L1 ("the server only
+// runs whitelisted argv") is a property of the code; L4 turns "someone put a
+// write argv into the surface" from a silent hole into a refusal to start. Its
+// unit is the ARGV, not the tool: a composite tool carries several, and checking
+// per tool would wave through all but one of them.
+//
+// JSON SCHEMA, NOT COMMANDER. The parameter constraints below come from the
+// whitelist's `params`, which the generator introspected out of the live
+// Commander registry when it wrote the artifact (`constraintSource` marks the
+// few that were hand-written). One build of latency is the price of not loading
+// the whole CLI command registry into a read-only server process; the artifact
+// is regenerated in the build and CI fails on a diff, so it cannot drift.
+import { loadReadOnlyWhitelist } from '../readonly-surface/readonly-whitelist.js';
+/**
+ * LLM-facing prose, per tool name. Every tool the whitelist declares must have
+ * an entry here or `validateSurface` refuses to start — spec §8.4 rule 2 asks
+ * the description to state the precondition, and a tool that silently has none
+ * is how an LLM ends up calling it outside a peaks project.
+ */
+const TOOL_DESCRIPTIONS = {
+    peaks_status: 'Where a Peaks-Loop workflow currently is. Read-only. Composes `peaks skill presence --json`, ' +
+        '`peaks session list --json` and, when both `rid` and `role` are given, `peaks request show ' +
+        '<rid> --role <role> --json --project <project>`. Each CLI result is returned verbatim under ' +
+        'its own key; a key is absent when that call was not run. Requires a Peaks-Loop project ' +
+        '(a `.peaks/` directory) as the working directory.',
+    peaks_memory_search: 'Search this project’s durable memory for a term, and get back NAMES and short excerpts — ' +
+        'never note bodies. Read-only. Use it to answer "has this project settled anything about X?" ' +
+        'Requires a Peaks-Loop project (a `.peaks/` directory) as the working directory.'
+};
+/** Per-parameter prose, by placeholder name. Absent names simply carry no description. */
+const PARAM_DESCRIPTIONS = {
+    rid: 'The id of the request to read.',
+    role: 'Role whose artifact to read. One of the declared enum values.',
+    project: 'Absolute path of the Peaks-Loop project. Defaults to the server’s working directory.',
+    query: 'The term to search project memory for.',
+    limit: 'Maximum number of matching notes to return.'
+};
+const TYPE_SHAPES = {
+    slug: (spec) => spec.pattern === undefined ? { type: 'string' } : { type: 'string', pattern: spec.pattern },
+    enum: (spec) => ({ type: 'string', enum: spec.values ?? [] }),
+    integer: (spec) => ({
+        type: 'integer',
+        minimum: spec.min ?? 0,
+        maximum: spec.max ?? Number.MAX_SAFE_INTEGER,
+        ...(spec.default === undefined ? {} : { default: spec.default })
+    }),
+    token: () => ({ type: 'string' }),
+    path: () => ({ type: 'string' })
+};
+function propertyFor(name, spec) {
+    const description = PARAM_DESCRIPTIONS[name];
+    const described = description === undefined ? {} : { description };
+    return { ...TYPE_SHAPES[spec.type](spec), ...described };
+}
+function inputSchemaOf(entries) {
+    const properties = {};
+    for (const entry of entries) {
+        for (const [name, spec] of Object.entries(entry.params)) {
+            properties[name] = propertyFor(name, spec);
+        }
+    }
+    // Nothing is `required` at the tool level. A tool whose entries all take no
+    // parameter is callable with `{}`, and a tool with several entries (three
+    // argv behind `peaks_status`) runs the subset whose parameters the caller
+    // actually supplied. Requiring the union would make the two parameterless
+    // argv unreachable.
+    return { type: 'object', properties, required: [], additionalProperties: false };
+}
+/** Group the whitelist's entries into tools, preserving first-appearance order. */
+export function buildToolDefinitions(whitelist) {
+    const byTool = new Map();
+    for (const entry of whitelist.entries) {
+        const bucket = byTool.get(entry.tool);
+        if (bucket === undefined) {
+            byTool.set(entry.tool, [entry]);
+        }
+        else {
+            bucket.push(entry);
+        }
+    }
+    return [...byTool].map(([name, entries]) => ({
+        name,
+        description: TOOL_DESCRIPTIONS[name] ?? '',
+        inputSchema: inputSchemaOf(entries),
+        entries
+    }));
+}
+/** Load the whitelist artifact and build the surface from it. */
+export function loadToolDefinitions() {
+    return buildToolDefinitions(loadReadOnlyWhitelist());
+}
+/** Why a surface was refused. Named so the server can print it and exit non-zero. */
+export class McpSurfaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'McpSurfaceError';
+    }
+}
+/** An entry's argv as a comparable template key: literals literal, placeholders `{name}`. */
+export function argvTemplateOf(entry) {
+    return entry.argv
+        .map((segment) => (segment.kind === 'literal' ? segment.value : `{${segment.name}}`))
+        .join(' ');
+}
+/**
+ * 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 function validateWhitelist(whitelist) {
+    const seenIds = new Set();
+    for (const entry of whitelist.entries) {
+        if (seenIds.has(entry.id)) {
+            throw new McpSurfaceError(`Whitelist entry id '${entry.id}' is declared twice; refusing to start.`);
+        }
+        seenIds.add(entry.id);
+        const literals = entry.argv
+            .filter((segment) => segment.kind === 'literal')
+            .map((segment) => (segment.kind === 'literal' ? segment.value : ''));
+        // The command path must open the argv: an entry whose template does not
+        // begin with the command it claims to be is an entry about something else.
+        const prefix = literals.slice(0, entry.commandPath.length).join(' ');
+        if (prefix !== entry.commandPath.join(' ')) {
+            throw new McpSurfaceError(`Whitelist entry '${entry.id}' declares commandPath '${entry.commandPath.join(' ')}' but its argv starts '${prefix}'; refusing to start.`);
+        }
+        const used = entry.argv.flatMap((segment) => (segment.kind === 'param' ? [segment.name] : []));
+        for (const name of used) {
+            if (!(name in entry.params)) {
+                throw new McpSurfaceError(`Whitelist entry '${entry.id}' uses placeholder '${name}' that it does not declare; refusing to start.`);
+            }
+            if (used.filter((candidate) => candidate === name).length !== 1) {
+                throw new McpSurfaceError(`Whitelist entry '${entry.id}' uses placeholder '${name}' more than once; refusing to start.`);
+            }
+        }
+        for (const name of Object.keys(entry.params)) {
+            if (!used.includes(name)) {
+                throw new McpSurfaceError(`Whitelist entry '${entry.id}' declares parameter '${name}' that its argv never uses; refusing to start.`);
+            }
+        }
+    }
+}
+/**
+ * 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 function validateSurface(whitelist, tools) {
+    validateWhitelist(whitelist);
+    if (tools.length === 0) {
+        throw new McpSurfaceError('MCP surface declares no tools; refusing to start.');
+    }
+    const whitelistedTemplates = new Set(whitelist.entries.map((entry) => argvTemplateOf(entry)));
+    const servedTemplates = new Set();
+    for (const tool of tools) {
+        if (tool.description.trim().length === 0) {
+            throw new McpSurfaceError(`MCP tool '${tool.name}' has no description; refusing to start (spec §8.4 rule 2).`);
+        }
+        for (const entry of tool.entries) {
+            const template = argvTemplateOf(entry);
+            if (!whitelistedTemplates.has(template)) {
+                throw new McpSurfaceError(`MCP tool '${tool.name}' carries argv '${template}' that is not in the read-only whitelist; refusing to start.`);
+            }
+            servedTemplates.add(template);
+        }
+    }
+    for (const entry of whitelist.entries) {
+        const template = argvTemplateOf(entry);
+        if (!servedTemplates.has(template)) {
+            throw new McpSurfaceError(`Whitelist entry '${entry.id}' ('${template}') is reachable from no MCP tool; refusing to start.`);
+        }
+    }
+}

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

@@ -0,0 +1,42 @@
+import type { ReadOnlyWhitelistEntry } from '../readonly-surface/readonly-whitelist.js';
+import { type CliExecution } from './cli-executor.js';
+/** How much of one memory note's description travels back. */
+export declare const MEMORY_EXCERPT_CHARS = 120;
+/** Hard ceiling on matches returned, independent of what the CLI was asked for. */
+export declare const MEMORY_MAX_RETURNED = 50;
+export interface ToolTextContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+export interface ToolCallResult {
+    readonly content: readonly ToolTextContent[];
+    /** Present and `true` only when something failed. Absent means success. */
+    readonly isError?: boolean;
+}
+/** Injectable execution, so a test can drive a handler without a CLI. */
+export type CliExecutor = (argv: readonly string[]) => Promise<CliExecution>;
+export interface ToolCallContext {
+    readonly execute?: CliExecutor;
+    /** Directory the CLI runs in. Defaults to the server process's own. */
+    readonly cwd?: string;
+}
+/**
+ * The values to render one entry with, or `undefined` when the caller did not
+ * supply enough for this entry to run. A value the caller DID supply is always
+ * present — it is handed to the guard, which is what decides whether it is
+ * allowed, so nothing supplied can be silently skipped.
+ */
+export declare function valuesForEntry(entry: ReadOnlyWhitelistEntry, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Record<string, string> | undefined;
+/** One argv's outcome, kept whole so the caller can see every envelope. */
+export interface EntryOutcome {
+    readonly key: string;
+    readonly execution: CliExecution;
+    readonly envelope: unknown;
+    readonly failure?: string;
+}
+/** Render the outcomes as a tool result, failing the call when any argv failed. */
+export declare function resultOf(outcomes: readonly EntryOutcome[]): ToolCallResult;
+/** A refused call: the parameter guard said no, before anything was executed. */
+export declare function rejectedResult(entry: ReadOnlyWhitelistEntry, reason: string): ToolCallResult;
+/** Execute one already-validated argv and keep its whole outcome. */
+export declare function runArgv(key: string, argv: readonly string[], context: ToolCallContext): Promise<EntryOutcome>;

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

@@ -0,0 +1,137 @@
+// src/services/mcp/tool-core.ts
+//
+// What both tool handlers are made of: the result shape, the argument-to-argv
+// step, and the one place a CLI execution becomes an outcome. Split out of
+// `tools.ts` because that file had grown past the repo's 300-line cap, and the
+// cap is measured per file rather than per concept.
+//
+// ERRORS ARE NEVER FLATTENED HERE, either. A CLI failure becomes a `failure`
+// string on the outcome, never an absent value: a read tool that answers
+// "nothing there" when it actually failed is worse than one that errors, because
+// the reader believes the empty answer (spec §9 rule 3).
+import { executeCliArgv } from './cli-executor.js';
+/** How much of one memory note's description travels back. */
+export const MEMORY_EXCERPT_CHARS = 120;
+/** Hard ceiling on matches returned, independent of what the CLI was asked for. */
+export const MEMORY_MAX_RETURNED = 50;
+/**
+ * Hand-written parameter defaults — the one place this module can drift from the
+ * whitelist (spec §8.1 asks such places to be visible). `project` is a MANDATORY
+ * option of `peaks request show`, and a status caller should not have to repeat
+ * the directory the server already runs in. Nothing else is defaulted: every
+ * other placeholder is either required by the caller or defaulted in the data.
+ */
+function defaultFor(param, context) {
+    return param === 'project' ? (context.cwd ?? process.cwd()) : undefined;
+}
+/**
+ * A transported argument as the guard's input. The JSON transport carries
+ * numbers for integer parameters and the guard can only judge a string, so
+ * coercion happens here, at the boundary — and a wrong JSON type is NOT
+ * stringified into something that looks like data: it becomes the empty string,
+ * which the guard already refuses by name (`EMPTY`).
+ */
+function asGuardInput(supplied) {
+    if (typeof supplied === 'string')
+        return supplied;
+    if (typeof supplied === 'number')
+        return String(supplied);
+    return '';
+}
+/**
+ * The values to render one entry with, or `undefined` when the caller did not
+ * supply enough for this entry to run. A value the caller DID supply is always
+ * present — it is handed to the guard, which is what decides whether it is
+ * allowed, so nothing supplied can be silently skipped.
+ */
+export function valuesForEntry(entry, args, context) {
+    const values = {};
+    for (const [name, spec] of Object.entries(entry.params)) {
+        const supplied = args[name];
+        if (supplied !== undefined) {
+            values[name] = asGuardInput(supplied);
+            continue;
+        }
+        const fallback = spec.default === undefined ? defaultFor(name, context) : String(spec.default);
+        if (fallback === undefined)
+            return undefined;
+        values[name] = fallback;
+    }
+    return values;
+}
+/** True when the CLI process itself failed, or its stdout was not a JSON envelope. */
+function failureReasonOf(execution, envelope) {
+    const called = `peaks ${execution.argv.join(' ')}`;
+    if (execution.launchError !== undefined) {
+        return `The peaks CLI could not be started: ${execution.launchError}`;
+    }
+    if (execution.timedOut) {
+        return `The peaks CLI did not finish in time and was killed: ${called}`;
+    }
+    if (execution.exitCode !== 0) {
+        return `The peaks CLI exited with code ${String(execution.exitCode)}: ${called}`;
+    }
+    if (envelope === undefined) {
+        return `The peaks CLI printed no JSON on stdout: ${called}`;
+    }
+    if (isFailedEnvelope(envelope)) {
+        return `The peaks CLI reported failure: ${called}`;
+    }
+    return undefined;
+}
+function isFailedEnvelope(value) {
+    return typeof value === 'object' && value !== null && 'ok' in value && value.ok === false;
+}
+function parseStdout(stdout) {
+    try {
+        return { parsed: true, value: JSON.parse(stdout) };
+    }
+    catch {
+        return { parsed: false };
+    }
+}
+/** Render the outcomes as a tool result, failing the call when any argv failed. */
+export function resultOf(outcomes) {
+    const payload = {};
+    for (const outcome of outcomes) {
+        payload[outcome.key] =
+            outcome.envelope === undefined
+                ? { ok: false, message: outcome.failure ?? 'no output', argv: outcome.execution.argv }
+                : outcome.envelope;
+    }
+    const failures = outcomes.filter((outcome) => outcome.failure !== undefined);
+    if (failures.length === 0) {
+        return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    ...payload,
+                    failures: failures.map((outcome) => ({ key: outcome.key, reason: outcome.failure }))
+                })
+            }
+        ],
+        isError: true
+    };
+}
+/** A refused call: the parameter guard said no, before anything was executed. */
+export function rejectedResult(entry, reason) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ entry: entry.id, reason }) }],
+        isError: true
+    };
+}
+/** Execute one already-validated argv and keep its whole outcome. */
+export async function runArgv(key, argv, context) {
+    const execute = context.execute ??
+        ((args) => executeCliArgv(args, context.cwd === undefined ? {} : { cwd: context.cwd }));
+    const execution = await execute(argv);
+    const parsed = parseStdout(execution.stdout);
+    const envelope = parsed.parsed ? parsed.value : undefined;
+    const failure = failureReasonOf(execution, envelope);
+    return failure === undefined
+        ? { key, execution, envelope }
+        : { key, execution, envelope, failure };
+}

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

@@ -0,0 +1,13 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext, type ToolCallResult } from './tool-core.js';
+/**
+ * `peaks_status`: run every argv the caller supplied enough for, and return each
+ * CLI envelope verbatim under the id of the whitelist entry that produced it.
+ */
+export declare function callStatusTool(tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Promise<ToolCallResult>;
+type ToolHandler = (tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext) => Promise<ToolCallResult>;
+/** Tools the surface declares that no handler can serve. Non-empty = refuse to start. */
+export declare function missingHandlers(tools: readonly McpToolDefinition[]): readonly string[];
+/** Route a `tools/call` to its handler, or `undefined` for a tool nobody serves. */
+export declare function handlerFor(name: string): ToolHandler | undefined;
+export {};

package/dist/services/mcp/tools.js

@@ -0,0 +1,58 @@
+// src/services/mcp/tools.ts
+//
+// `peaks_status`, and the table that routes a `tools/call` to its handler. The
+// result shape, the argument-to-argv step and the outcome rendering live in
+// `tool-core.ts`; the bounded memory tool lives in `memory-tool.ts`.
+//
+// The composite is a pipe with a shape, never a judge (spec §3.2): "a composite
+// tool may arrange and reshape; it may not CONCLUDE." Each CLI envelope is
+// embedded VERBATIM under the whitelist entry id that produced it, so the whole
+// result is an identity transform of the calls it ran. A key is absent when its
+// argv did not run — exactly "subset"; no branch fabricates a value no argv
+// returned.
+import { buildArgv } from '../readonly-surface/argv-guard.js';
+import { callMemorySearchTool } from './memory-tool.js';
+import { rejectedResult, resultOf, runArgv, valuesForEntry } from './tool-core.js';
+/**
+ * `peaks_status`: run every argv the caller supplied enough for, and return each
+ * CLI envelope verbatim under the id of the whitelist entry that produced it.
+ */
+export async function callStatusTool(tool, args, context) {
+    // Every argv is BUILT before any is run. Executing as we go meant a refused
+    // placeholder left the earlier argv of the same call already executed — a
+    // caller's malformed input would have reached the CLI's read path anyway.
+    const plan = [];
+    for (const entry of tool.entries) {
+        const values = valuesForEntry(entry, args, context);
+        if (values === undefined)
+            continue;
+        const built = buildArgv(entry, values);
+        if (!built.ok) {
+            return rejectedResult(entry, `Parameter ${built.param} was refused: ${built.message}`);
+        }
+        plan.push({ id: entry.id, argv: built.argv });
+    }
+    const outcomes = [];
+    for (const step of plan) {
+        outcomes.push(await runArgv(step.id, step.argv, context));
+    }
+    return resultOf(outcomes);
+}
+/**
+ * Tool name -> handler, spelled out rather than derived. A tool the whitelist
+ * declares but this table does not name cannot be served, and `missingHandlers`
+ * below turns that into a refusal to start instead of a call that answers with
+ * whatever the fallback branch happened to do.
+ */
+const TOOL_HANDLERS = {
+    peaks_status: callStatusTool,
+    peaks_memory_search: callMemorySearchTool
+};
+/** Tools the surface declares that no handler can serve. Non-empty = refuse to start. */
+export function missingHandlers(tools) {
+    return tools.map((tool) => tool.name).filter((name) => !(name in TOOL_HANDLERS));
+}
+/** Route a `tools/call` to its handler, or `undefined` for a tool nobody serves. */
+export function handlerFor(name) {
+    return TOOL_HANDLERS[name];
+}

package/dist/services/readonly-surface/argv-guard.d.ts

@@ -0,0 +1,32 @@
+import type { PlaceholderSpec, ReadOnlyWhitelistEntry } from './readonly-whitelist.js';
+/** Upper bound on any single placeholder value, whatever its type. */
+export declare const READONLY_VALUE_MAX_LENGTH = 200;
+export type GuardRejection = {
+    readonly ok: false;
+    readonly param: string;
+    readonly code: GuardRejectionCode;
+    readonly message: string;
+};
+export type GuardRejectionCode = 'NOT_A_STRING' | 'EMPTY' | 'TOO_LONG' | 'FLAG_SHAPED' | 'CONTROL_CHARACTER' | 'WHITESPACE' | 'PATTERN_MISMATCH' | 'NOT_IN_ENUM' | 'NOT_AN_INTEGER' | 'OUT_OF_RANGE' | 'NOT_ABSOLUTE';
+export type GuardResult = {
+    readonly ok: true;
+    readonly value: string;
+} | GuardRejection;
+/** The process options that keep the array from being re-parsed by a shell. */
+export declare function readonlySpawnOptions(): {
+    readonly shell: false;
+};
+/** Validate one placeholder value against its spec. */
+export declare function validatePlaceholderValue(param: string, spec: PlaceholderSpec, raw: unknown): GuardResult;
+export type BuildArgvResult = {
+    readonly ok: true;
+    readonly argv: string[];
+} | GuardRejection;
+/**
+ * Render a whitelist entry into a concrete argv ARRAY.
+ *
+ * The output is never a string: literals and validated values are pushed as
+ * separate elements, so no value can contribute token boundaries. A parameter the
+ * entry does not declare is refused rather than appended.
+ */
+export declare function buildArgv(entry: ReadOnlyWhitelistEntry, values: Readonly<Record<string, string>>): BuildArgvResult;