firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/mcp-connection.js

@@ -0,0 +1,109 @@
+import { api, credentialOverview } from './auth.js';
+import { selectedWorkspace } from './world-access.js';
+import { APP_ORIGIN, CliError, endpoint, jsonRequest } from './http.js';
+import { mcpConnectionRead } from '../../contracts/mcp-contracts.js';
+export const MCP_CLIENTS = ['codex', 'claude', 'other'];
+/**
+ * Management MCP addresses of the fixed platform profiles (root release
+ * configuration, confirmed 2026-11-10). Used before sign-in only when the
+ * platform's public terminal configuration predates its MCP fields; once signed
+ * in, the workspace's own connection read is authoritative.
+ */
+const PROFILE_MCP = {
+    'https://app.firedrill.run': 'https://mcp.firedrill.run',
+    'https://app.sim-dev.firedrill.run': 'https://mcp.sim-dev.firedrill.run',
+};
+/** A bare https origin has no shell-special characters, so one printed command works in every shell. */
+const SAFE_ORIGIN = /^https:\/\/[a-z0-9.-]+(?::443)?$/;
+/**
+ * The platform's management MCP address from its public terminal configuration
+ * (root `cli/config`, 2026-11-10): a bare https origin with transport
+ * `streamable-http`, or both null when MCP is disabled or not configured.
+ * Returns undefined for a platform whose configuration predates these fields.
+ * The sign-in fields are not checked here, so MCP guidance never depends on them.
+ */
+async function platformMcp(signal) {
+    const result = await jsonRequest(endpoint('/api/auth/cli/config'), { signal });
+    const body = result.body;
+    if (result.status !== 200 || !body || typeof body !== 'object' || Array.isArray(body)) {
+        throw new CliError('mcp_not_configured', 'The platform\'s MCP address could not be read. Your terminal commands remain available.', 2);
+    }
+    const { management_mcp_url: url, management_mcp_transport: transport } = body;
+    if (url === undefined && transport === undefined)
+        return undefined;
+    if (url === null && transport === null)
+        return null;
+    if (typeof url === 'string' && SAFE_ORIGIN.test(url) && transport === 'streamable-http')
+        return url;
+    throw new CliError('mcp_not_configured', 'The platform\'s MCP address could not be printed safely. Your terminal commands remain available.', 2);
+}
+function guidanceFor(url, agent) {
+    const guidance = [];
+    if (agent === undefined || agent === 'codex')
+        guidance.push({ client: 'codex', label: 'Codex',
+            commands: [`codex mcp add firedrill --url ${url}`, 'codex mcp login firedrill'],
+            authentication: 'codex mcp login opens the browser to authorize Firedrill for Codex.',
+            scope: 'This adds the server to your Codex user configuration; a trusted project can instead list it in .codex/config.toml.',
+            removal: 'codex mcp remove firedrill' });
+    if (agent === undefined || agent === 'claude')
+        guidance.push({ client: 'claude', label: 'Claude Code',
+            commands: [`claude mcp add --transport http firedrill ${url}`],
+            authentication: 'Open /mcp in Claude Code and choose firedrill to authorize it in the browser.',
+            scope: 'By default only you see it, in this project. Add --scope user for all your projects, or --scope project to share it through .mcp.json.',
+            removal: 'claude mcp remove firedrill (add the same --scope if you used one)' });
+    if (agent === undefined || agent === 'other')
+        guidance.push({ client: 'other', label: 'Other MCP clients',
+            commands: [],
+            authentication: `Add a remote (Streamable HTTP) MCP server named firedrill with this URL: ${url}\nYour client handles the OAuth browser sign-in. No token or header is needed.`,
+            scope: null, removal: null });
+    return guidance;
+}
+function guidanceText(url, guidance, source) {
+    return [
+        `MCP server: ${url}${source !== 'workspace' ? ' (this platform\'s address; sign in with firedrill init to confirm it is enabled for your workspace)' : ''}`,
+        ...guidance.map(item => [item.label, ...item.commands, item.authentication,
+            ...(item.scope ? [item.scope] : []), ...(item.removal ? [`To remove: ${item.removal}`] : [])].join('\n')),
+        'These commands work in macOS and Linux shells, PowerShell and Command Prompt. Firedrill has not changed any client settings.',
+        'Approve access in the browser opened by your MCP client. This is separate from firedrill init.',
+        'If a firedrill connection already exists, inspect its URL in your client before adding or replacing it. Other servers in your client configuration are left as they are.',
+        'Remote MCP cannot read project files or start processes on this computer. Local targets run only through firedrill run with a plan you approve.',
+    ].join('\n\n');
+}
+/**
+ * Prints connection guidance only. Firedrill never writes or edits an MCP
+ * client's configuration. Signed in, the server URL is the remote root the
+ * workspace's connection read returns (validated by mcpConnectionRead: https
+ * origin, no path suffix). Before sign-in it is the address the platform's
+ * public configuration publishes (or, for a platform that predates it, the fixed
+ * profile's address), so MCP setup does not depend on terminal device sign-in.
+ */
+export async function mcpConnection(options, output) {
+    if (options.agent !== undefined && !MCP_CLIENTS.includes(options.agent))
+        throw new CliError('invalid_agent', 'Choose codex, claude or other for MCP connection guidance.', 2);
+    const signedIn = (await credentialOverview(options.signal)).signed_in;
+    if (!signedIn && options.workspace === undefined) {
+        const published = await platformMcp(options.signal);
+        if (published === null)
+            throw new CliError('mcp_not_configured', 'MCP access is not configured for this platform. Your terminal commands remain available.', 2);
+        const url = published ?? PROFILE_MCP[APP_ORIGIN];
+        if (!url)
+            throw new CliError('authentication_required', 'This platform has no published MCP address. Run firedrill init, then firedrill mcp.', 2);
+        const source = published ? 'platform_configuration' : 'platform_profile';
+        const guidance = guidanceFor(url, options.agent);
+        output({ enabled: null, url, source, authentication: 'oauth', guidance, client_configuration_changed: false }, guidanceText(url, guidance, source));
+        return;
+    }
+    const scope = await selectedWorkspace({ workspace: options.workspace,
+        interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY,
+        signal: options.signal, openBrowser: options.openBrowser && !options.json });
+    const result = mcpConnectionRead(await api(`/api/workspaces/${scope.workspace}/mcp-connection`, {
+        actor: scope.owner, workspace: scope.workspace, signal: options.signal
+    }), scope.owner, scope.workspace, APP_ORIGIN);
+    if (!result.enabled || !result.url)
+        throw new CliError('mcp_not_configured', 'MCP access is not configured for this platform. Your terminal commands remain available.', 2);
+    const url = result.url;
+    if (!SAFE_ORIGIN.test(url))
+        throw new CliError('mcp_not_configured', 'The configured MCP address could not be printed safely. Your terminal commands remain available.', 2);
+    const guidance = guidanceFor(url, options.agent);
+    output({ ...result, source: 'workspace', guidance, client_configuration_changed: false }, guidanceText(url, guidance, 'workspace'));
+}

package/dist/cli/src/native/bindings.js

@@ -0,0 +1,137 @@
+/**
+ * Simulated dependency routes (Plan20 FIR-490, root `native-dependency-access.v1`).
+ *
+ * Root does not hand the client endpoints or credentials for a target's
+ * dependencies. Each simulated (`synthetic`) dependency the descriptor declares
+ * is reached through the companion's per-drill loopback proxy
+ * (dependency-proxy.ts), which keeps root's short-lived token in memory. This
+ * module checks, before anything is waited for or started, that the approved plan
+ * routes every declared dependency into a process launched for this drill, and
+ * maps the proxy's loopback URLs onto the environment names the plan declares:
+ *  - `dependency_env` entries on the dependency's service, `{alias, name, url}`,
+ *    where `url` is `invoke` for an `http` dependency and `mcp` for an `mcp` one;
+ *  - for `mcp` dependencies, the service's `mcp_config_env`, which receives the
+ *    path of a private MCP client configuration (mcp-config.ts).
+ * A dependency the plan does not route is refused rather than left to reach a
+ * live service, and a `real-grant-required` dependency is refused because this
+ * version issues no real grants.
+ *
+ * Network posture: no root CA, proxy variable, TLS verification change or DNS
+ * change is made or accepted here. Proxy/CA/TLS environment names are refused as
+ * route targets, so a route can never redirect or weaken target traffic.
+ *
+ * Secrets: the loopback URLs carry the proxy's per-drill path capability, so they
+ * stay inside SecretValue until the injection point (child env value, private MCP
+ * config file). Error messages name aliases and env names only, never URLs.
+ */
+import { nativeError } from './contracts.js';
+// ---------------------------------------------------------------------------
+// Shared validation helpers (also used by mcp-config.ts and target-auth.ts).
+export const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
+/** Headers an identity grant may never set (transport-controlled or hop-by-hop). */
+const FORBIDDEN_HEADERS = new Set(['host', 'content-length', 'transfer-encoding', 'connection', 'keep-alive', 'upgrade',
+    'te', 'trailer', 'expect', 'proxy-authorization', 'proxy-authenticate', 'proxy-connection']);
+/**
+ * Environment names a dependency route may never write. They control process
+ * loading, the base environment the supervisor builds, or network trust/routing.
+ * The comparison is case-insensitive because Windows env names are.
+ */
+const RESERVED_ENV = new Set(['PATH', 'HOME', 'LANG', 'TMPDIR', 'TEMP', 'TMP', 'USERPROFILE', 'SYSTEMROOT', 'COMSPEC',
+    'PATHEXT', 'SHELL', 'USER', 'LOGNAME', 'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS', 'NODE_TLS_REJECT_UNAUTHORIZED',
+    'SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'GIT_SSL_NO_VERIFY', 'PYTHONHTTPSVERIFY',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'FTP_PROXY', 'PYTHONPATH', 'PYTHONSTARTUP', 'RUBYOPT', 'PERL5OPT',
+    'BASH_ENV', 'ENV']);
+const RESERVED_ENV_PREFIXES = ['LD_', 'DYLD_', 'FIREDRILL_'];
+export function isReservedEnvName(name) {
+    const upper = name.toUpperCase();
+    return RESERVED_ENV.has(upper) || RESERVED_ENV_PREFIXES.some((prefix) => upper.startsWith(prefix));
+}
+export function isValidHeaderName(name) {
+    return HEADER_TOKEN.test(name) && !FORBIDDEN_HEADERS.has(name.toLowerCase());
+}
+/**
+ * Every declared dependency's route, checked before anything starts. Throws
+ * `native_binding_invalid` (naming aliases and env names only) when:
+ *  - a dependency requires a real grant (none is issued; no live service replaces it);
+ *  - its service is not in the approved plan, or is shared or attached (it cannot
+ *    receive per-drill URLs);
+ *  - the plan gives it no env name and no MCP client configuration;
+ *  - a plan route names an undeclared dependency, a dependency another service
+ *    hosts, the wrong URL kind for the protocol, or an env name that is malformed,
+ *    reserved, undeclared in the service configuration or used twice.
+ */
+export function validateDependencyRoutes(descriptor, plan, options) {
+    const dependencies = new Map(descriptor.dependencies.map((dependency) => [dependency.alias, dependency]));
+    for (const service of plan.services) {
+        const configured = new Set((descriptor.services.find((entry) => entry.alias === service.alias)?.configuration ?? [])
+            .map((config) => config.name));
+        const taken = new Set([service.port_env, service.mcp_config_env]
+            .flatMap((name) => typeof name === 'string' && name ? [name.toUpperCase()] : []));
+        for (const entry of service.dependency_env ?? []) {
+            const dependency = dependencies.get(entry.alias);
+            if (!dependency || dependency.service_alias !== service.alias) {
+                throw nativeError('binding_invalid', `The approved plan routes dependency "${entry.alias}" into service "${service.alias}", which does not declare it. No drill was started.`);
+            }
+            if ((dependency.protocol === 'http' ? 'invoke' : 'mcp') !== entry.url) {
+                throw nativeError('binding_invalid', `The approved plan routes ${dependency.protocol} dependency "${entry.alias}" as ${entry.url}. No drill was started.`);
+            }
+            if (!ENV_NAME.test(entry.name) || isReservedEnvName(entry.name)) {
+                throw nativeError('binding_invalid', `Environment name ${entry.name} is reserved and cannot carry dependency "${entry.alias}". No drill was started.`);
+            }
+            if (!configured.has(entry.name)) {
+                throw nativeError('binding_invalid', `Environment name ${entry.name} for dependency "${entry.alias}" is not declared in the configuration of service "${service.alias}". No drill was started.`);
+            }
+            if (taken.has(entry.name.toUpperCase())) {
+                throw nativeError('binding_invalid', `Environment name ${entry.name} of service "${service.alias}" is already used. No drill was started.`);
+            }
+            taken.add(entry.name.toUpperCase());
+        }
+    }
+    const routes = [];
+    for (const dependency of descriptor.dependencies) {
+        if (dependency.mode === 'real-grant-required') {
+            throw nativeError('binding_invalid', `Dependency "${dependency.alias}" requires a real grant, which this version does not issue. No drill was started and no live service is used in its place.`);
+        }
+        const service = plan.services.find((entry) => entry.alias === dependency.service_alias);
+        if (!service) {
+            throw nativeError('binding_invalid', `Dependency "${dependency.alias}" was not routed: its service "${dependency.service_alias}" is not in the approved plan. No drill was started.`);
+        }
+        const env = (service.dependency_env ?? []).filter((entry) => entry.alias === dependency.alias)
+            .map((entry) => ({ name: entry.name, url: entry.url }));
+        const mcpConfig = dependency.protocol === 'mcp' && typeof service.mcp_config_env === 'string' && service.mcp_config_env.length > 0;
+        if (env.length === 0 && !mcpConfig) {
+            throw nativeError('binding_invalid', `Dependency "${dependency.alias}" was not routed: the approved plan gives service "${service.alias}" no environment name${dependency.protocol === 'mcp' ? ' or MCP client configuration' : ''} for it. No drill was started and no live service is used in its place.`);
+        }
+        if (!options.freshForDrill(service)) {
+            throw nativeError('binding_invalid', `Dependency "${dependency.alias}" was not routed: service "${service.alias}" must be launched for each drill to receive drill-scoped dependency URLs. No drill was started.`);
+        }
+        routes.push({ dependency, service, env, mcp_config: mcpConfig });
+    }
+    return routes;
+}
+/**
+ * One service's dependency env: each routed name receives its loopback URL. The
+ * supervisor applies these after `env_passthrough` and `env_static`, so a route
+ * always wins over a user-supplied value of the same name.
+ */
+export function dependencyEnv(routes, serviceAlias, urls) {
+    const env = {};
+    const secrets = [];
+    for (const route of routes) {
+        if (route.service.alias !== serviceAlias)
+            continue;
+        for (const entry of route.env) {
+            const url = urls.url(route.dependency.alias, entry.url);
+            // Injection point: revealed only into the child env value.
+            env[entry.name] = url.reveal();
+            secrets.push(url);
+        }
+    }
+    return { env, secrets };
+}
+/** The MCP servers one service's private client configuration lists (server name = dependency alias). */
+export function mcpServers(routes, serviceAlias, urls) {
+    return routes.filter((route) => route.service.alias === serviceAlias && route.mcp_config)
+        .map((route) => ({ name: route.dependency.alias, url: urls.url(route.dependency.alias, 'mcp') }));
+}

package/dist/cli/src/native/canonical.js

@@ -0,0 +1,370 @@
+/**
+ * Canonical JSON, digests and the local descriptor pre-check (Plan20 W09).
+ *
+ * `canonicalJson` reproduces Python's
+ * `json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=True)`
+ * byte for byte for the JSON values the native client produces, so digests
+ * computed here equal the root service's digests over the same document.
+ *
+ * `normalizeDescriptor` mirrors root `native_descriptor.py` (same bounds, closed
+ * schema, uniqueness, startup order, domain rules, sorting and digest). It is a
+ * client-side pre-check only; the cloud result is authoritative.
+ */
+import { createHash } from 'node:crypto';
+import { CliError } from '../http.js';
+import { ALIAS, DRIVER_PROFILES, LOCAL_DESCRIPTOR_SCHEMA, SERVICE_ROLES, SHA256_HEX, STATE_KINDS, STATE_LOCATIONS, STATE_RESETS, TARGET_AUTHENTICATIONS, } from './contracts.js';
+// ---------------------------------------------------------------------------
+// Canonical JSON.
+const MAX_CANONICAL_DEPTH = 64;
+/** Compare two strings by Unicode code point, which is Python's `str` ordering. */
+export function compareCodePoints(a, b) {
+    if (!/[\ud800-\udfff]/.test(a) && !/[\ud800-\udfff]/.test(b))
+        return a < b ? -1 : a > b ? 1 : 0;
+    const left = Array.from(a, char => char.codePointAt(0));
+    const right = Array.from(b, char => char.codePointAt(0));
+    for (let index = 0; index < Math.min(left.length, right.length); index++) {
+        if (left[index] !== right[index])
+            return left[index] - right[index];
+    }
+    return left.length - right.length;
+}
+function canonicalString(value) {
+    let out = '"';
+    for (let index = 0; index < value.length; index++) {
+        const unit = value.charCodeAt(index);
+        if (unit === 0x22)
+            out += '\\"';
+        else if (unit === 0x5c)
+            out += '\\\\';
+        else if (unit === 0x0a)
+            out += '\\n';
+        else if (unit === 0x0d)
+            out += '\\r';
+        else if (unit === 0x09)
+            out += '\\t';
+        else if (unit === 0x08)
+            out += '\\b';
+        else if (unit === 0x0c)
+            out += '\\f';
+        // Python ensure_ascii escapes everything outside ' '..'~', per UTF-16 unit
+        // (non-BMP characters become surrogate pairs), with lowercase hex.
+        else if (unit < 0x20 || unit > 0x7e)
+            out += '\\u' + unit.toString(16).padStart(4, '0');
+        else
+            out += value[index];
+    }
+    return out + '"';
+}
+/** Python `repr(float)` for a finite, non-integral number. */
+function pythonFloat(value) {
+    const sign = value < 0 ? '-' : '';
+    const [mantissa, exponentText] = Math.abs(value).toExponential().split('e');
+    const digits = mantissa.replace('.', '');
+    const exponent = Number(exponentText);
+    if (exponent < -4 || exponent >= 16) {
+        const body = digits.length > 1 ? `${digits[0]}.${digits.slice(1)}` : digits;
+        return `${sign}${body}e${exponent < 0 ? '-' : '+'}${String(Math.abs(exponent)).padStart(2, '0')}`;
+    }
+    const point = exponent + 1;
+    if (point <= 0)
+        return `${sign}0.${'0'.repeat(-point)}${digits}`;
+    if (point >= digits.length)
+        return `${sign}${digits}${'0'.repeat(point - digits.length)}.0`;
+    return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+function canonicalNumber(value) {
+    if (!Number.isFinite(value))
+        throw canonicalInvalid();
+    // Integral values are written as integers, as Python writes a parsed JSON integer.
+    if (Number.isInteger(value))
+        return Number.isSafeInteger(value) ? String(value === 0 ? 0 : value) : BigInt(value).toString();
+    return pythonFloat(value);
+}
+const canonicalInvalid = () => new CliError('native_canonical_invalid', 'A value could not be written in canonical form. Nothing was hashed or sent.');
+function canonicalValue(value, depth) {
+    if (depth > MAX_CANONICAL_DEPTH)
+        throw canonicalInvalid();
+    if (value === null)
+        return 'null';
+    if (value !== undefined && typeof value.toJSON === 'function') {
+        return canonicalValue(value.toJSON(), depth + 1);
+    }
+    switch (typeof value) {
+        case 'string': return canonicalString(value);
+        case 'boolean': return value ? 'true' : 'false';
+        case 'number': return canonicalNumber(value);
+        case 'bigint': return value.toString();
+        case 'undefined': return undefined;
+        case 'object': break;
+        default: throw canonicalInvalid();
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(item => {
+            const encoded = canonicalValue(item, depth + 1);
+            if (encoded === undefined)
+                throw canonicalInvalid();
+            return encoded;
+        }).join(',') + ']';
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw canonicalInvalid();
+    const parts = [];
+    for (const key of Object.keys(value).sort(compareCodePoints)) {
+        const encoded = canonicalValue(value[key], depth + 1);
+        if (encoded !== undefined)
+            parts.push(canonicalString(key) + ':' + encoded);
+    }
+    return '{' + parts.join(',') + '}';
+}
+/**
+ * Canonical JSON matching Python `json.dumps(sort_keys=True, separators=(',',':'),
+ * ensure_ascii=True)`. Accepts plain objects, arrays, strings, booleans, null,
+ * finite numbers and objects with `toJSON` (SecretValue serializes redacted).
+ * Undefined object properties are omitted. Non-finite numbers, cycles beyond the
+ * depth bound and non-plain objects are refused with `native_canonical_invalid`.
+ */
+export function canonicalJson(value) {
+    const encoded = canonicalValue(value, 0);
+    if (encoded === undefined)
+        throw canonicalInvalid();
+    return encoded;
+}
+/** Lowercase hex SHA-256 of a UTF-8 string or raw bytes. */
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Local descriptor pre-check (mirror of root native_descriptor.py).
+const MAX_BYTES = 262_144;
+const MAX_NODES = 65_536;
+const MAX_DEPTH = 16;
+const CONFIG_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const OPERATION = /^[A-Za-z0-9_.:/-]+$/;
+function invalid(message = 'Check the local agent descriptor fields.') {
+    // Never reflect rejected values.
+    throw new CliError('local_descriptor_invalid', message, 2);
+}
+const codePointLength = (value) => {
+    let count = 0;
+    for (const _ of value)
+        count++;
+    return count;
+};
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function boundedJson(value) {
+    const pending = [[value, 0]];
+    let count = 0;
+    while (pending.length) {
+        const [item, depth] = pending.pop();
+        count++;
+        if (count > MAX_NODES || depth > MAX_DEPTH)
+            invalid('The descriptor is too large or deeply nested.');
+        if (isPlainObject(item)) {
+            const keys = Object.keys(item);
+            if (keys.length > 256 || keys.some(key => codePointLength(key) > 128))
+                invalid();
+            for (const key of keys)
+                pending.push([item[key], depth + 1]);
+        }
+        else if (Array.isArray(item)) {
+            if (item.length > 256)
+                invalid();
+            for (const child of item)
+                pending.push([child, depth + 1]);
+        }
+        else if (typeof item === 'string') {
+            if (codePointLength(item) > 4096 || /[\u0000-\u001f]/.test(item))
+                invalid();
+        }
+        else if (item !== null && typeof item !== 'boolean' && !(typeof item === 'number' && Number.isInteger(item))) {
+            invalid();
+        }
+    }
+    let encoded;
+    try {
+        encoded = canonicalJson(value);
+    }
+    catch {
+        invalid();
+    }
+    if (encoded.length > MAX_BYTES)
+        invalid('The descriptor exceeds the accepted size.');
+    return encoded;
+}
+// Closed-schema checks equivalent to local-descriptor.v1.schema.json.
+function exact(value, keys) {
+    if (!isPlainObject(value))
+        invalid();
+    const present = Object.keys(value);
+    if (present.length !== keys.length || keys.some(key => !Object.hasOwn(value, key)))
+        invalid();
+    return value;
+}
+function array(value, min, max, unique = false) {
+    if (!Array.isArray(value) || value.length < min || value.length > max)
+        invalid();
+    if (unique && new Set(value.map(item => canonicalJson(item))).size !== value.length)
+        invalid();
+    return value;
+}
+function alias(value) {
+    if (typeof value !== 'string' || value.length > 64 || !ALIAS.test(value))
+        invalid();
+}
+function sha(value) {
+    if (typeof value !== 'string' || !SHA256_HEX.test(value))
+        invalid();
+}
+function oneOf(value, options) {
+    if (typeof value !== 'string' || !options.includes(value))
+        invalid();
+}
+function bool(value) {
+    if (typeof value !== 'boolean')
+        invalid();
+}
+function checkSchema(value) {
+    const document = exact(value, ['schema', 'source_roots', 'services', 'entry_service', 'driver', 'state_domains', 'dependencies']);
+    if (document.schema !== LOCAL_DESCRIPTOR_SCHEMA)
+        invalid();
+    for (const item of array(document.source_roots, 1, 128)) {
+        const root = exact(item, ['alias', 'identity_sha256']);
+        alias(root.alias);
+        sha(root.identity_sha256);
+    }
+    for (const item of array(document.services, 1, 128)) {
+        const service = exact(item, ['alias', 'root_alias', 'role', 'depends_on', 'configuration']);
+        alias(service.alias);
+        alias(service.root_alias);
+        oneOf(service.role, SERVICE_ROLES);
+        array(service.depends_on, 0, 128, true).forEach(alias);
+        for (const entry of array(service.configuration, 0, 256)) {
+            const config = exact(entry, ['name', 'phase', 'secret', 'required']);
+            if (typeof config.name !== 'string' || config.name.length > 128 || !CONFIG_NAME.test(config.name))
+                invalid();
+            oneOf(config.phase, ['build', 'runtime', 'both']);
+            bool(config.secret);
+            bool(config.required);
+        }
+    }
+    alias(document.entry_service);
+    const driver = exact(document.driver, ['profile', 'adapter_sha256', 'authentication', 'state_domains']);
+    oneOf(driver.profile, DRIVER_PROFILES);
+    sha(driver.adapter_sha256);
+    oneOf(driver.authentication, TARGET_AUTHENTICATIONS);
+    array(driver.state_domains, 0, 256, true).forEach(alias);
+    for (const item of array(document.state_domains, 0, 256)) {
+        const domain = exact(item, ['alias', 'service_alias', 'kind', 'location', 'reset', 'concurrency', 'hook_sha256']);
+        alias(domain.alias);
+        alias(domain.service_alias);
+        oneOf(domain.kind, STATE_KINDS);
+        oneOf(domain.location, STATE_LOCATIONS);
+        oneOf(domain.reset, STATE_RESETS);
+        oneOf(domain.concurrency, ['independent', 'serial']);
+        if (domain.hook_sha256 !== null)
+            sha(domain.hook_sha256);
+    }
+    for (const item of array(document.dependencies, 0, 256)) {
+        const dependency = exact(item, ['alias', 'service_alias', 'protocol', 'mode', 'operations']);
+        alias(dependency.alias);
+        alias(dependency.service_alias);
+        oneOf(dependency.protocol, ['http', 'mcp']);
+        oneOf(dependency.mode, ['synthetic', 'real-grant-required']);
+        for (const operation of array(dependency.operations, 1, 256, true)) {
+            if (typeof operation !== 'string' || !operation.length || operation.length > 128 || !OPERATION.test(operation))
+                invalid();
+        }
+    }
+}
+function indexed(items, label) {
+    const map = new Map(items.map(item => [item.alias, item]));
+    if (map.size !== items.length)
+        invalid(`Use distinct ${label} aliases.`);
+    return map;
+}
+const byAlias = (a, b) => compareCodePoints(a.alias, b.alias);
+/**
+ * Validate and normalize a local descriptor exactly as root `validate_local_descriptor`
+ * does. Throws `local_descriptor_invalid` (exit 2) without echoing rejected values.
+ */
+export function normalizeDescriptor(value) {
+    const raw = boundedJson(value);
+    checkSchema(value);
+    const document = JSON.parse(raw);
+    const roots = indexed(document.source_roots, 'source root');
+    const services = indexed(document.services, 'service');
+    const domains = indexed(document.state_domains, 'state domain');
+    indexed(document.dependencies, 'dependency');
+    if (!services.has(document.entry_service))
+        invalid('Choose an entry service from the declared services.');
+    const remaining = new Map();
+    for (const [name, service] of services) {
+        const dependencies = new Set(service.depends_on);
+        if (!roots.has(service.root_alias) || [...dependencies].some(item => !services.has(item)) || dependencies.has(name)) {
+            invalid('Use declared roots and other services for startup dependencies.');
+        }
+        const config = service.configuration;
+        if (new Set(config.map(item => item.name)).size !== config.length)
+            invalid('Declare each configuration variable once per service.');
+        service.configuration = [...config].sort((a, b) => compareCodePoints(a.name, b.name));
+        service.depends_on = [...dependencies].sort(compareCodePoints);
+        remaining.set(name, dependencies);
+    }
+    const startupOrder = [];
+    while (remaining.size) {
+        const ready = [...remaining].filter(([, dependencies]) => !dependencies.size).map(([name]) => name).sort(compareCodePoints);
+        if (!ready.length)
+            invalid('Startup dependencies contain a cycle.');
+        startupOrder.push(...ready);
+        for (const name of ready)
+            remaining.delete(name);
+        for (const dependencies of remaining.values())
+            for (const name of ready)
+                dependencies.delete(name);
+    }
+    for (const domain of domains.values()) {
+        if (!services.has(domain.service_alias))
+            invalid('Assign each state domain to a declared service.');
+        const hooked = domain.reset === 'approved-hook';
+        if (hooked !== (domain.hook_sha256 !== null))
+            invalid('Provide a hook digest only for an approved reset hook.');
+        if ((domain.location === 'observation-only' || domain.reset === 'unavailable') && domain.concurrency !== 'serial') {
+            invalid('State without a reset boundary requires serial execution.');
+        }
+        if (domain.location === 'observation-only' && domain.reset !== 'unavailable')
+            invalid('Observation-only state cannot declare a reset capability.');
+        if (domain.reset === 'fresh-process' && domain.kind !== 'process')
+            invalid('Restarting a process does not reset its external state.');
+        if (domain.reset === 'fresh-session' && domain.kind !== 'browser' && domain.kind !== 'session') {
+            invalid('A new session does not reset external storage.');
+        }
+    }
+    const driver = document.driver;
+    const driverDomains = new Set(driver.state_domains);
+    if (driverDomains.size !== domains.size || [...driverDomains].some(name => !domains.has(name))) {
+        invalid('The driver must account for every declared state domain.');
+    }
+    driver.state_domains = [...driver.state_domains].sort(compareCodePoints);
+    for (const dependency of document.dependencies) {
+        if (!services.has(dependency.service_alias))
+            invalid('Assign each dependency to a declared service.');
+        dependency.operations = [...dependency.operations].sort(compareCodePoints);
+    }
+    document.source_roots = [...document.source_roots].sort(byAlias);
+    document.services = [...document.services].sort(byAlias);
+    document.state_domains = [...document.state_domains].sort(byAlias);
+    document.dependencies = [...document.dependencies].sort(byAlias);
+    const canonical = boundedJson(document);
+    return {
+        descriptor: document,
+        descriptor_sha256: sha256Hex(canonical),
+        startup_order: startupOrder,
+        requires_serial_execution: !domains.size || [...domains.values()].some(item => item.concurrency === 'serial'),
+    };
+}