@everfur/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2511 @@
+/**
+ * CREDENTIAL RESOLUTION, and the rules that make "the CLI never prints a secret" a structural
+ * property rather than a promise.
+ *
+ *  1. A credential comes from a NAMED ENVIRONMENT VARIABLE or from nowhere. This package never
+ *     reads a `.env` file, never walks up looking for one, and has no dotenv dependency: a repo
+ *     `.env` is a file a partner commits by accident, and a tool that reads one teaches them
+ *     that committing it is fine. The names are documented in README.md and printed by
+ *     `--help`, so an operator is told what to export rather than where a file should live.
+ *  2. The resolved value is wrapped. `toString` and `toJSON` both return `[redacted]`, so the
+ *     two ways a value normally escapes (string interpolation into a message, and
+ *     `JSON.stringify` of an outcome) yield the marker instead of the secret. Only `reveal()`
+ *     returns the real bytes, and `tests/unit/secret-never-printed.test.ts` asserts that the
+ *     HTTP client is the only module that calls it.
+ *  3. Shape is checked before the value is used. A truncated paste is reported by NAME as a
+ *     malformed credential, which is a better answer than the opaque 401 the server gives for
+ *     every credential failure alike (`sessions_router._auth_rejected`).
+ */
+declare const REDACTED = "[redacted]";
+interface Credential {
+    /** The variable this came from. Safe to print; it is a name, not a value. */
+    readonly envVar: string;
+    toString(): string;
+    toJSON(): string;
+    /** The real value. Called by `src/http/client.ts` and nowhere else. */
+    reveal(): string;
+}
+interface CredentialSpec {
+    readonly envVar: string;
+    /** Required literal prefix, or null when the value is opaque (a bearer token). */
+    readonly prefix: string | null;
+    /**
+     * Additional accepted prefixes, beyond `prefix`.
+     *
+     * A publishable key is `pk_live_` on a production deployment and `pk_test_` on a sandbox one, and the
+     * CLI cannot tell which host it is pointed at before it makes a call. Hardcoding one of them would make
+     * the CLI reject exactly the sandbox credentials the platform now issues, which is the opposite of what
+     * a test-mode tool should do. The SERVER is the authority: it accepts one prefix per deployment and
+     * refuses the other on the fast-fail path, so accepting both here narrows nothing.
+     */
+    readonly alsoAccepts?: readonly string[];
+    /** Exact expected length when the prefix is known, or null. */
+    readonly length: number | null;
+    readonly summary: string;
+}
+/** The publishable key. Public by construction, but still never echoed back to the operator. */
+declare const PARTNER_KEY: CredentialSpec;
+/**
+ * The server-side half of the session mint. The variable name is the same constant `plan`
+ * already names in its configure step; see `src/commands/plan/planner.ts`.
+ */
+declare const PARTNER_SECRET_KEY: CredentialSpec;
+/** An already minted device bearer, for diagnosing the signed path without a mint. */
+declare const SESSION_TOKEN: CredentialSpec;
+/** The operator bearer for the admin routes. */
+declare const ADMIN_TOKEN: CredentialSpec;
+declare const CREDENTIAL_SPECS: readonly CredentialSpec[];
+type CredentialStatus = 'present' | 'absent' | 'malformed';
+interface ResolvedCredential {
+    readonly spec: CredentialSpec;
+    readonly status: CredentialStatus;
+    /** Populated only when `status` is `present`. */
+    readonly credential: Credential | null;
+    /** Why the value was rejected. Names the variable and the expected shape, never the value. */
+    readonly reason: string | null;
+}
+/**
+ * Wrap a value that did NOT come from the environment, for example a session token the CLI just
+ * minted. It is exactly as unprintable as an environment credential, which is the point: a
+ * token that arrives over the wire is no less a secret than one an operator exported, and
+ * `verify` has to carry one from step one to step two without it reaching a report.
+ *
+ * `envVar` names the origin rather than a variable, because there is no variable.
+ */
+declare function ephemeralCredential(origin: string, value: string): Credential;
+/**
+ * Wrap a credential so a scheme is prepended when it is finally revealed, for example turning a
+ * session token into `Bearer <token>`. The value is never interpolated here: the concatenation
+ * happens inside `reveal`, which only the HTTP client calls, so a prefixed credential is exactly
+ * as unprintable as an unprefixed one.
+ */
+declare function withPrefix(credential: Credential, prefix: string): Credential;
+/**
+ * Read one credential out of the injected environment. Absent and malformed are DIFFERENT
+ * answers, exactly as an absent and an invalid flag are different to `plan`: absent means the
+ * operator has not set it up yet, malformed means they did and it is wrong.
+ */
+declare function resolveCredential(env: Readonly<Record<string, string | undefined>>, spec: CredentialSpec): ResolvedCredential;
+
+/**
+ * The filesystem seam. Detection and contract loading are pure functions over this interface,
+ * which is the whole reason they can be tested against fixtures without a temp directory
+ * dance and without a process spawn.
+ *
+ * Synchronous by design. The CLI reads a handful of small manifests and then exits; async
+ * would buy nothing and would make every detection helper a promise for no reason.
+ *
+ * `readFile` returns null rather than throwing for a missing or unreadable path. Detection
+ * probes many paths that are legitimately absent, so absence is a value, not an exception.
+ */
+interface FileSystemPort {
+    /** UTF-8 contents, or null when the path is missing, unreadable, or a directory. */
+    readFile(path: string): string | null;
+    /** True when the path exists, whatever its type. */
+    exists(path: string): boolean;
+    /** True when the path exists and is a directory. */
+    isDirectory(path: string): boolean;
+}
+
+/**
+ * THE NETWORK SEAM. One interface, injected exactly like `FileSystemPort`, which is what lets
+ * every command that talks to the API be exercised in a unit test with a scripted transport and
+ * no socket. Nothing above this file knows that `fetch` exists.
+ *
+ * The request and response are plain data. In particular a `HttpRequest` is NEVER carried into
+ * a `CommandOutcome`: it holds the credential headers, and an outcome is a thing the formatter
+ * prints. Failures carry the method, the path, and the request id, never the request object.
+ */
+type HttpMethod = 'GET' | 'POST' | 'DELETE';
+/** Methods that may be retried. A retry of anything else could mint a second credential. */
+declare const IDEMPOTENT_METHODS: readonly HttpMethod[];
+interface HttpRequest {
+    readonly method: HttpMethod;
+    readonly url: string;
+    /** Header names as written. Values may include a credential; see the note above. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string | null;
+    /** Hard ceiling for this single attempt, in milliseconds. Enforced by the adapter. */
+    readonly timeoutMs: number;
+}
+interface HttpResponse {
+    readonly status: number;
+    /** Header names LOWERCASED by the adapter, so callers never guess at casing. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/**
+ * The only exception a transport may throw. Anything else escaping an adapter is a bug in that
+ * adapter; `createApiClient` still catches it and reports it as a network failure rather than
+ * letting a raw stack reach the user.
+ */
+declare class TransportError extends Error {
+    readonly kind: 'timeout' | 'network';
+    constructor(kind: 'timeout' | 'network', message: string);
+}
+interface TransportPort {
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/** True when a method may be retried after a transport fault or a retryable server answer. */
+declare function isIdempotent(method: HttpMethod): boolean;
+
+/**
+ * The time seam. Only `verify` needs it, to space out its entitlement poll, and only because a
+ * real sleep in a unit test is a slow test that eventually becomes a flaky one.
+ *
+ * Deliberately minimal: no `now()`. Every timestamp this CLI emits comes from the server
+ * (`evaluated_at`, `expires_at`), so there is no clock reading to inject and no output that
+ * changes between two runs of the same command.
+ */
+interface ClockPort {
+    sleep(milliseconds: number): Promise<void>;
+}
+declare const systemClock: ClockPort;
+/** A clock that never waits and records what it was asked to wait for. For tests. */
+declare function createRecordingClock(): ClockPort & {
+    readonly waits: readonly number[];
+};
+
+/**
+ * A command declares its flags as data. Binding is a pure function from that declaration plus
+ * a ParsedArgv to either typed values or a list of usage errors, so "is --identity a known
+ * flag on this command" is answered by the registry, not by each command re-implementing it.
+ */
+interface FlagSpec {
+    readonly name: string;
+    readonly kind: 'string' | 'boolean';
+    readonly summary: string;
+    /** Rendered in help as `--name <placeholder>`. Value flags only. */
+    readonly placeholder?: string;
+    readonly required?: boolean;
+}
+interface BoundFlags {
+    /** Value of a string flag, or null when absent. */
+    string(name: string): string | null;
+    /** Value of a boolean flag. Absent means false. */
+    boolean(name: string): boolean;
+}
+
+/**
+ * The frozen exit-code table. Every command settles to one of these; nothing else may
+ * reach the process. Codes are additive: a future command may claim a new code, but an
+ * existing code never changes meaning, because CI pipelines branch on them.
+ *
+ * The split between UNDERSPECIFIED (3) and INVALID_CONTRACT (4) / DIGEST_MISMATCH (5) is
+ * deliberate. 3 means "the CLI declined to answer because you did not tell it enough";
+ * it is a refusal, not a failure, and a wrapper script is expected to prompt and retry.
+ * 4 and 5 mean an artifact on disk is wrong and a human has to look at it.
+ */
+declare const ExitCode: Readonly<{
+    /** The command produced a complete answer. */
+    readonly OK: 0;
+    /** An unexpected internal failure. A bug in the CLI, or an unreadable filesystem. */
+    readonly INTERNAL_ERROR: 1;
+    /** The invocation was malformed: unknown command, unknown flag, missing flag value. */
+    readonly USAGE_ERROR: 2;
+    /** The CLI refused to guess. Required facts were missing; see `missingFacts`. */
+    readonly UNDERSPECIFIED: 3;
+    /**
+     * A NAMED ARTIFACT was missing, unparseable, or failed shape validation against its JSON
+     * Schema. All three mean the same thing to a caller: a file this command was pointed at
+     * cannot be used, and a human has to look at that file.
+     *
+     * The wording was tightened from "failed shape validation" because `file_not_found` and
+     * `invalid_json` have always mapped here too, and a code whose documented meaning is
+     * narrower than its behaviour is a code CI branches on wrongly. What does NOT belong here is
+     * a bad INVOCATION: `--cwd /nope` is a usage error (2), because nothing was loaded.
+     */
+    readonly INVALID_CONTRACT: 4;
+    /** A loaded artifact was well shaped but its digest did not match its content. */
+    readonly DIGEST_MISMATCH: 5;
+    /**
+     * The API could not be reached, did not answer in time, or answered with a typed error.
+     * The invocation was fine and no local artifact is wrong: the far side is the problem, so a
+     * CI wrapper branching on this retries or pages rather than sending someone to edit a file.
+     */
+    readonly REMOTE_FAILURE: 6;
+    /**
+     * `verify` completed and at least one step FAILED. Distinct from 6 because the wire worked:
+     * the CLI got answers and one of them was wrong, which is a report to read rather than an
+     * outage to retry. A run with no failures but a skipped step settles at 3, not here, because
+     * a skip means the operator did not supply enough to exercise that step.
+     */
+    readonly VERIFICATION_FAILED: 7;
+    /**
+     * `sandbox create` provisioned a key, and the server offered no claim URL for its secret.
+     * The CLI will not print a raw secret, so it discarded the one it was handed unread. The key
+     * exists and nobody can use it; the human projection prints the revoke command.
+     */
+    readonly SECRET_UNCLAIMABLE: 8;
+    /**
+     * `plan` was told everything it needed and NOTHING the caller asked for can be built: every
+     * capability named resolved to a BLOCKED terminal in the contract.
+     *
+     * Distinct from 3 because supplying another flag will not help, and distinct from 0 because
+     * no plan was produced. A CI wrapper branching on 3 prompts for more input, which would loop
+     * forever here; one branching on 9 reads the reason and the request path out of the document
+     * and escalates to a human, which is the only thing that resolves it.
+     */
+    readonly BLOCKED: 9;
+}>;
+type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+
+/**
+ * The JSON value lattice. Command outcomes carry a `JsonValue`, never an arbitrary object,
+ * so the machine projection is provably serialisable and provably free of class instances,
+ * functions, and `undefined` holes that would silently vanish through JSON.stringify.
+ */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+
+/**
+ * The single shared result type every command settles to. There is exactly one of these and
+ * every future command returns it, which is what lets the formatter, the bin shim, and the
+ * exit-code table stay unaware of what any individual command does.
+ *
+ * Both projections are always populated. A command never chooses a rendering: it produces the
+ * machine document and the human text, and `formatOutcome` decides which one reaches which
+ * stream. That is why command logic never imports a stream and never calls console.
+ */
+interface CommandOutcome {
+    readonly exitCode: ExitCode;
+    /** The machine projection. Emitted verbatim under `--json`, on stdout, success or failure. */
+    readonly json: JsonObject;
+    /** The human projection. Already wrapped; the formatter adds only a trailing newline. */
+    readonly text: string;
+    /**
+     * Where the human projection goes. Diagnostics belong on stderr so that `everfur plan > out`
+     * still shows the operator why nothing useful landed in the file.
+     */
+    readonly stream: 'stdout' | 'stderr';
+}
+
+/**
+ * Everything a command is allowed to touch, injected. There is no ambient `process.cwd()`,
+ * no ambient `process.env`, and no module-level filesystem. That is what lets every command
+ * be exercised in a unit test with a fixture directory and no child process.
+ */
+interface CommandContext {
+    readonly fs: FileSystemPort;
+    /** Absolute working directory. Resolved once, in the bin shim. */
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** The CLI's own version, stamped into every document it emits. */
+    readonly version: string;
+    /**
+     * The network seam. Injected for the same reason the filesystem is: a test scripts it and no
+     * socket opens. `src/bin` supplies the one real adapter.
+     */
+    readonly transport: TransportPort;
+    /** Waiting, injected so a poll loop in a test costs nothing. */
+    readonly clock: ClockPort;
+}
+/**
+ * A positional argument. Declared as data beside the flags so `--help` documents it and the
+ * orchestrator can enforce arity, rather than each command counting its own leftovers.
+ */
+interface PositionalSpec {
+    readonly name: string;
+    readonly summary: string;
+    readonly required: boolean;
+}
+/**
+ * A command is data plus one pure-ish function. `run` may read the filesystem through the
+ * injected port and nothing else: no writing, no network, no stream, no exit.
+ *
+ * Adding a future command is adding one of these to the registry array. No other file changes,
+ * which is the property this scaffold exists to establish before there are five more commands.
+ */
+interface Command {
+    /** Command path tokens, for example `["contract", "validate"]`. Matched in order. */
+    readonly path: readonly string[];
+    readonly summary: string;
+    /** Usage line shown by `--help`, without the leading `everfur `. */
+    readonly usage: string;
+    readonly flags: readonly FlagSpec[];
+    /** Ordered positional arguments this command accepts. Absent means it accepts none. */
+    readonly positionals?: readonly PositionalSpec[];
+    /**
+     * The credentials this command can actually use, declared as data for the same reason the
+     * flags are: `--help` renders what the command declares, so a credential a command reads is a
+     * credential its own help names. Absent means the command touches none, which is the truth
+     * for `plan`, `contract validate`, and `explain-error`.
+     *
+     * This exists because per-command help used to render only the flags. A partner told to run
+     * one command had no way to learn from the tool that they must export EVERFUR_PARTNER_KEY;
+     * they found out from a `credential_missing` failure at runtime instead.
+     */
+    readonly credentials?: readonly CredentialSpec[];
+    run(context: CommandContext, flags: BoundFlags, positionals: readonly string[]): Promise<CommandOutcome>;
+}
+
+/**
+ * THE single output formatter. Every byte the CLI writes is produced here, from a
+ * CommandOutcome, which is why no command needs a stream and why `--json` needed no per-command
+ * support.
+ *
+ * The rule, chosen once so scripts can rely on it:
+ *
+ *  - with `--json`, the machine document goes to stdout ALWAYS, success or failure. A caller
+ *    that has to parse a failure differently from a success ends up parsing stderr, and then
+ *    the contract is prose.
+ *  - without `--json`, human text goes to stdout on success and stderr on failure, so
+ *    `everfur plan > plan.txt` still shows the operator why the file is empty.
+ *  - exactly one trailing newline on each non-empty stream, and nothing at all on the other.
+ */
+interface FormattedOutput {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+interface FormatOptions {
+    readonly json: boolean;
+}
+declare function formatOutcome(outcome: CommandOutcome, options: FormatOptions): FormattedOutput;
+
+/**
+ * The orchestrator: argv in, formatted output plus exit code out. It writes nothing and exits
+ * nothing, so the whole CLI including its exit codes can be asserted in a unit test without a
+ * child process. `src/bin/everfur.ts` is the only file that turns this return value into an
+ * actual process effect.
+ *
+ * `--json` is read from the raw parse rather than from bound flags, because the formatter has
+ * to honour it even for an invocation whose flags failed to bind. A usage error under `--json`
+ * still emits a JSON error document.
+ */
+interface RunOptions {
+    readonly argv: readonly string[];
+    readonly context: CommandContext;
+    readonly commands?: readonly Command[];
+}
+declare function runCli(options: RunOptions): Promise<FormattedOutput>;
+
+/**
+ * THE REGISTRY. Exactly the commands this release ships, and nothing else.
+ *
+ * `login` and `test message` are deliberately ABSENT. They are described in ROADMAP.md and have
+ * no code here, registered or otherwise. A stub that resolves to "not implemented" is worse than
+ * a missing command: it teaches a partner that the command exists and then wastes their time,
+ * and it invites a half-implementation to accrete behind it. `everfur login` prints
+ * "unknown command", which is the truth.
+ *
+ * Longer paths are matched first so `contract validate` and `sandbox create` win over any future
+ * bare `contract` or `sandbox`.
+ */
+declare const COMMANDS: readonly Command[];
+interface CommandMatch {
+    readonly command: Command;
+    /** Argv path tokens the command consumed. */
+    readonly consumed: number;
+}
+/**
+ * Resolve a command path prefix to a command. Returns null when nothing matches, which the
+ * caller renders as a usage error rather than falling back to a default command.
+ */
+declare function matchCommand(path: readonly string[], commands?: readonly Command[]): CommandMatch | null;
+
+/**
+ * The one real transport adapter, and the only place in the package that opens a socket.
+ * Everything it can go wrong with collapses to a `TransportError` with a kind, so the client
+ * above it branches on two values rather than on the shape of an undici error.
+ *
+ * `AbortSignal.timeout` bounds the whole attempt including the body read, which a
+ * `setTimeout` around the fetch promise would not: a response whose headers arrive quickly and
+ * whose body never finishes would hang forever under the naive version.
+ *
+ * No redirect following, because a redirect off the configured base URL would carry the
+ * partner's credential headers to whatever host answered.
+ */
+declare const fetchTransport: TransportPort;
+
+/**
+ * WHERE THE CLI TALKS TO, resolved once and passed down. Two sources, in this order:
+ *
+ *   1. `--base-url <url>`, which wins.
+ *   2. `EVERFUR_API_BASE_URL`, the configured default for a shell that works against one
+ *      environment all day.
+ *
+ * There is deliberately NO built-in default. A partner CLI that silently points at production
+ * when nothing is configured is one typo away from an operator diagnosing staging and reading a
+ * production answer, and the failure is invisible because both answers look plausible. Absent
+ * configuration is a usage error that names both ways to fix it.
+ *
+ * `API_PREFIX` is appended by this module rather than being part of what the operator types,
+ * because it is a deployment fact of the API and not a choice. A base URL that already ends in
+ * the prefix is accepted as-is, so both spellings work and neither doubles up.
+ */
+declare const BASE_URL_ENV_VAR = "EVERFUR_API_BASE_URL";
+/** `app/main.py` mounts every router used here at `settings.api_prefix`. */
+declare const API_PREFIX = "/api/v1";
+interface ResolvedEndpoint {
+    /** Normalised, without a trailing slash. Safe to print: it is never a credential. */
+    readonly baseUrl: string;
+    /** True when the operator's base URL already carried `API_PREFIX`. */
+    readonly prefixIncluded: boolean;
+    readonly source: 'flag' | 'env';
+}
+type EndpointResolution = {
+    readonly ok: true;
+    readonly endpoint: ResolvedEndpoint;
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+declare function resolveEndpoint(flagValue: string | null, env: Readonly<Record<string, string | undefined>>): EndpointResolution;
+/**
+ * Join an API-relative path (one starting `/widget/v1/...` or `/admin/...`) onto the resolved
+ * base, inserting `API_PREFIX` exactly once.
+ */
+declare function apiUrl(endpoint: ResolvedEndpoint, path: string): string;
+
+/**
+ * The JSON Schema files are the single source of truth for validation, and the TypeScript types
+ * beside them are the compile-time view of the same contract. Nothing hand-rolls a second
+ * validator: `tests/contract` runs real emitted output through these compiled schemas, so a
+ * type that drifts from its schema fails the suite rather than shipping.
+ *
+ * The schemas are imported, not read from disk at runtime, so a globally installed CLI cannot
+ * end up validating against a schema file that a different version left lying around.
+ *
+ * Compilation is lazy and memoised: a `plan` run that never emits JSON should not pay for ajv
+ * compiling a schema it will not use.
+ */
+interface SchemaViolation {
+    /** JSON Pointer into the validated document, for example `/steps/2/phase`. */
+    readonly path: string;
+    readonly message: string;
+}
+interface SchemaValidation {
+    readonly valid: boolean;
+    readonly violations: readonly SchemaViolation[];
+}
+/** Validate a document against the committed plan contract. */
+declare function validatePlanDocument(document: unknown): SchemaValidation;
+/** Validate a document against the contract-public envelope contract. */
+declare function validateContractPublicEnvelope(document: unknown): SchemaValidation;
+/** Validate a document against the committed `everfur diagnose --json` contract. */
+declare function validateDiagnosisDocument(document: unknown): SchemaValidation;
+/** Validate a document against the committed `everfur sandbox create --json` contract. */
+declare function validateSandboxCreateDocument(document: unknown): SchemaValidation;
+/** Validate a document against the committed `everfur verify --json` contract. */
+declare function validateVerificationDocument(document: unknown): SchemaValidation;
+/** Validate a document against the committed `everfur explain-error --json` contract. */
+declare function validateErrorExplanationDocument(document: unknown): SchemaValidation;
+/** The raw schema objects, exported so tests and downstream tools can assert against them. */
+declare const SCHEMAS: Readonly<{
+    plan: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        required: string[];
+        properties: {
+            schemaVersion: {
+                const: number;
+            };
+            kind: {
+                const: string;
+            };
+            generatedBy: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    version: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            status: {
+                enum: string[];
+            };
+            detected: {
+                $ref: string;
+            };
+            supplied: {
+                type: string;
+                required: string[];
+                properties: {
+                    capabilities: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            minItems?: never;
+                            items?: never;
+                            uniqueItems?: never;
+                        } | {
+                            type: string;
+                            minItems: number;
+                            items: {
+                                $ref: string;
+                            };
+                            uniqueItems: boolean;
+                        })[];
+                    };
+                    identityMode: {
+                        oneOf: ({
+                            type: string;
+                            $ref?: never;
+                        } | {
+                            $ref: string;
+                            type?: never;
+                        })[];
+                    };
+                    sessionMintLanguage: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            $ref?: never;
+                        } | {
+                            $ref: string;
+                            type?: never;
+                        })[];
+                    };
+                };
+            };
+            missingFacts: {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
+            steps: {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
+            blocked: {
+                description: string;
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
+            principles: {
+                description: string;
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
+            warnings: {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
+            decisionSpace: {
+                description: string;
+                oneOf: ({
+                    type: string;
+                    $ref?: never;
+                } | {
+                    $ref: string;
+                    type?: never;
+                })[];
+            };
+        };
+        allOf: ({
+            description: string;
+            if: {
+                properties: {
+                    status: {
+                        const: string;
+                    };
+                };
+                required: string[];
+            };
+            then: {
+                properties: {
+                    missingFacts: {
+                        minItems: number;
+                        maxItems?: never;
+                    };
+                    steps: {
+                        maxItems: number;
+                        minItems?: never;
+                    };
+                    blocked?: never;
+                };
+                required?: never;
+                $comment?: never;
+            };
+        } | {
+            description: string;
+            if: {
+                properties: {
+                    status: {
+                        const: string;
+                    };
+                };
+                required: string[];
+            };
+            then: {
+                properties: {
+                    missingFacts: {
+                        maxItems: number;
+                        minItems?: never;
+                    };
+                    steps: {
+                        minItems: number;
+                        maxItems?: never;
+                    };
+                    blocked?: never;
+                };
+                required: string[];
+                $comment: string;
+            };
+        } | {
+            description: string;
+            if: {
+                properties: {
+                    status: {
+                        const: string;
+                    };
+                };
+                required: string[];
+            };
+            then: {
+                properties: {
+                    missingFacts: {
+                        maxItems: number;
+                        minItems?: never;
+                    };
+                    steps: {
+                        maxItems: number;
+                        minItems?: never;
+                    };
+                    blocked: {
+                        minItems: number;
+                    };
+                };
+                required?: never;
+                $comment?: never;
+            };
+        })[];
+        $defs: {
+            OptionId: {
+                description: string;
+                type: string;
+                pattern: string;
+            };
+            Capability: {
+                description: string;
+                $ref: string;
+            };
+            IdentityMode: {
+                description: string;
+                $ref: string;
+            };
+            ProjectType: {
+                enum: string[];
+            };
+            PackageManager: {
+                enum: string[];
+            };
+            Detection: {
+                type: string;
+                required: string[];
+                properties: {
+                    root: {
+                        type: string;
+                        minLength: number;
+                    };
+                    projectType: {
+                        $ref: string;
+                    };
+                    projectTypeEvidence: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                    packageManager: {
+                        $ref: string;
+                    };
+                    packageManagerEvidence: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                    dependencies: {
+                        type: string;
+                        items: {
+                            $ref: string;
+                        };
+                    };
+                };
+            };
+            Dependency: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    declared: {
+                        oneOf: {
+                            type: string;
+                        }[];
+                    };
+                    installed: {
+                        oneOf: {
+                            type: string;
+                        }[];
+                    };
+                    source: {
+                        enum: string[];
+                    };
+                    scope: {
+                        enum: string[];
+                    };
+                };
+            };
+            BlockedCapability: {
+                type: string;
+                required: string[];
+                properties: {
+                    capability: {
+                        $ref: string;
+                    };
+                    reason: {
+                        type: string;
+                        minLength: number;
+                    };
+                    unblockOwner: {
+                        type: string;
+                        minLength: number;
+                    };
+                    requestPath: {
+                        description: string;
+                        type: string;
+                        pattern: string;
+                    };
+                    capabilityKeys: {
+                        description: string;
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                };
+            };
+            PlanPrinciple: {
+                type: string;
+                required: string[];
+                properties: {
+                    treeId: {
+                        $ref: string;
+                    };
+                    id: {
+                        $ref: string;
+                    };
+                    title: {
+                        type: string;
+                        minLength: number;
+                    };
+                    statement: {
+                        type: string;
+                        minLength: number;
+                    };
+                    docPath: {
+                        oneOf: ({
+                            type: string;
+                            pattern?: never;
+                        } | {
+                            type: string;
+                            pattern: string;
+                        })[];
+                    };
+                };
+            };
+            DecisionSpaceProvenance: {
+                type: string;
+                required: string[];
+                properties: {
+                    source: {
+                        type: string;
+                        minLength: number;
+                    };
+                    digest: {
+                        type: string;
+                        pattern: string;
+                    };
+                    trees: {
+                        type: string;
+                        items: {
+                            $ref: string;
+                        };
+                    };
+                };
+            };
+            MissingFact: {
+                type: string;
+                required: string[];
+                properties: {
+                    fact: {
+                        enum: string[];
+                    };
+                    reason: {
+                        type: string;
+                        minLength: number;
+                    };
+                    supplyWith: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            PlanStep: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                        pattern: string;
+                    };
+                    phase: {
+                        enum: string[];
+                    };
+                    title: {
+                        type: string;
+                        minLength: number;
+                    };
+                    detail: {
+                        type: string;
+                        minLength: number;
+                    };
+                    commands: {
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                    files: {
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                };
+            };
+            PlanWarning: {
+                type: string;
+                required: string[];
+                properties: {
+                    code: {
+                        type: string;
+                        pattern: string;
+                    };
+                    message: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+        };
+    };
+    contractPublic: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        required: string[];
+        properties: {
+            schemaVersion: {
+                const: number;
+            };
+            kind: {
+                const: string;
+            };
+            generatedAt: {
+                type: string;
+                format: string;
+                description: string;
+            };
+            digest: {
+                type: string;
+                required: string[];
+                properties: {
+                    algorithm: {
+                        const: string;
+                        description: string;
+                    };
+                    value: {
+                        type: string;
+                        pattern: string;
+                        description: string;
+                    };
+                };
+            };
+            projection: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    diagnosis: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        required: string[];
+        properties: {
+            schemaVersion: {
+                const: number;
+            };
+            kind: {
+                const: string;
+            };
+            generatedBy: {
+                $ref: string;
+            };
+            endpoint: {
+                type: string;
+                required: string[];
+                properties: {
+                    baseUrl: {
+                        type: string;
+                        minLength: number;
+                    };
+                    path: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            requestId: {
+                description: string;
+                oneOf: ({
+                    type: string;
+                    minLength?: never;
+                } | {
+                    type: string;
+                    minLength: number;
+                })[];
+            };
+            evaluatedAt: {
+                type: string;
+            };
+            client: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                    slug: {
+                        type: string;
+                    };
+                };
+            };
+            auth: {
+                type: string;
+                required: string[];
+                properties: {
+                    mode: {
+                        type: string;
+                    };
+                    anonymous: {
+                        type: string;
+                    };
+                    userRefPrefix: {
+                        description: string;
+                        type: string;
+                        maxLength: number;
+                    };
+                    userRole: {
+                        type: string;
+                    };
+                    roleSource: {
+                        type: string;
+                    };
+                    sessionId: {
+                        type: string;
+                    };
+                    partnerKeyScopeResolved: {
+                        type: string;
+                    };
+                };
+            };
+            scope: {
+                type: string;
+                required: string[];
+                properties: {
+                    provisioned: {
+                        type: string;
+                    };
+                    resolverStatus: {
+                        type: string;
+                    };
+                    revision: {
+                        type: string;
+                        minimum: number;
+                    };
+                    region: {
+                        type: string;
+                    };
+                    levels: {
+                        type: string;
+                        items: {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                level: {
+                                    type: string;
+                                    minimum: number;
+                                    maximum: number;
+                                };
+                                kind: {
+                                    type: string;
+                                };
+                                present: {
+                                    type: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            summary: {
+                type: string;
+                required: string[];
+                properties: {
+                    total: {
+                        type: string;
+                        minimum: number;
+                    };
+                    available: {
+                        type: string;
+                        minimum: number;
+                    };
+                    unavailable: {
+                        type: string;
+                        minimum: number;
+                    };
+                    byReasonCode: {
+                        description: string;
+                        type: string;
+                        additionalProperties: {
+                            type: string;
+                            minimum: number;
+                        };
+                    };
+                };
+            };
+            capabilities: {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
+        };
+        $defs: {
+            GeneratedBy: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    version: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            CapabilityDiagnosis: {
+                type: string;
+                required: string[];
+                properties: {
+                    key: {
+                        type: string;
+                        minLength: number;
+                    };
+                    available: {
+                        type: string;
+                    };
+                    reasonCode: {
+                        description: string;
+                        type: string;
+                        minLength: number;
+                    };
+                    reason: {
+                        description: string;
+                        type: string;
+                    };
+                    entitlementReasonCode: {
+                        description: string;
+                        type: string;
+                        minLength: number;
+                    };
+                    decidedAtLevel: {
+                        oneOf: ({
+                            type: string;
+                            minimum?: never;
+                            maximum?: never;
+                        } | {
+                            type: string;
+                            minimum: number;
+                            maximum: number;
+                        })[];
+                    };
+                    decidedAtKind: {
+                        oneOf: {
+                            type: string;
+                        }[];
+                    };
+                    surface: {
+                        description: string;
+                        oneOf: {
+                            type: string;
+                        }[];
+                    };
+                    nextAction: {
+                        description: string;
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+        };
+    };
+    sandboxCreate: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        required: string[];
+        properties: {
+            schemaVersion: {
+                const: number;
+            };
+            kind: {
+                const: string;
+            };
+            generatedBy: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    version: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            status: {
+                enum: string[];
+            };
+            requestId: {
+                oneOf: ({
+                    type: string;
+                    minLength?: never;
+                } | {
+                    type: string;
+                    minLength: number;
+                })[];
+            };
+            clientId: {
+                type: string;
+            };
+            keyId: {
+                type: string;
+                minLength: number;
+            };
+            label: {
+                oneOf: {
+                    type: string;
+                }[];
+            };
+            createdAt: {
+                oneOf: {
+                    type: string;
+                }[];
+            };
+            claimUrl: {
+                description: string;
+                oneOf: ({
+                    type: string;
+                    minLength?: never;
+                } | {
+                    type: string;
+                    minLength: number;
+                })[];
+            };
+            claimExpiresAt: {
+                oneOf: {
+                    type: string;
+                }[];
+            };
+            secretDisclosed: {
+                description: string;
+                const: boolean;
+            };
+            secretDiscarded: {
+                description: string;
+                type: string;
+            };
+            orphanedKey: {
+                description: string;
+                enum: string[];
+            };
+            nextActions: {
+                type: string;
+                minItems: number;
+                items: {
+                    type: string;
+                    minLength: number;
+                };
+            };
+        };
+        allOf: ({
+            if: {
+                properties: {
+                    status: {
+                        const: string;
+                    };
+                };
+                required: string[];
+            };
+            then: {
+                properties: {
+                    claimUrl: {
+                        type: string;
+                        minLength?: never;
+                    };
+                };
+            };
+        } | {
+            if: {
+                properties: {
+                    status: {
+                        const: string;
+                    };
+                };
+                required: string[];
+            };
+            then: {
+                properties: {
+                    claimUrl: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+        })[];
+    };
+    verification: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        required: string[];
+        properties: {
+            schemaVersion: {
+                const: number;
+            };
+            kind: {
+                const: string;
+            };
+            generatedBy: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    version: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            status: {
+                description: string;
+                enum: string[];
+            };
+            baseUrl: {
+                type: string;
+                minLength: number;
+            };
+            summary: {
+                type: string;
+                required: string[];
+                properties: {
+                    passed: {
+                        type: string;
+                        minimum: number;
+                    };
+                    failed: {
+                        type: string;
+                        minimum: number;
+                    };
+                    skipped: {
+                        type: string;
+                        minimum: number;
+                    };
+                };
+            };
+            steps: {
+                type: string;
+                minItems: number;
+                items: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        id: {
+                            type: string;
+                            minLength: number;
+                        };
+                        title: {
+                            type: string;
+                            minLength: number;
+                        };
+                        result: {
+                            enum: string[];
+                        };
+                        reason: {
+                            description: string;
+                            type: string;
+                            minLength: number;
+                        };
+                        requestId: {
+                            oneOf: ({
+                                type: string;
+                                minLength?: never;
+                            } | {
+                                type: string;
+                                minLength: number;
+                            })[];
+                        };
+                        details: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    errorExplanation: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        required: string[];
+        properties: {
+            schemaVersion: {
+                const: number;
+            };
+            kind: {
+                const: string;
+            };
+            generatedBy: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    version: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+            code: {
+                description: string;
+                type: string;
+                minLength: number;
+            };
+            source: {
+                type: string;
+                required: string[];
+                properties: {
+                    path: {
+                        type: string;
+                        minLength: number;
+                    };
+                    digest: {
+                        type: string;
+                        pattern: string;
+                    };
+                };
+            };
+            envelope: {
+                type: string;
+                minLength: number;
+            };
+            httpStatus: {
+                type: string;
+                minimum: number;
+            };
+            namingFamily: {
+                type: string;
+                minLength: number;
+            };
+            retryable: {
+                type: string;
+            };
+            confirmedOnWire: {
+                description: string;
+                type: string;
+            };
+            surfaces: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            cause: {
+                type: string;
+            };
+            display: {
+                description: string;
+                type: string;
+            };
+            docUrl: {
+                type: string;
+            };
+            nextAction: {
+                type: string;
+                minLength: number;
+            };
+        };
+    };
+}>;
+
+/**
+ * THE DIGEST RULE, stated once so both sides of the wire can implement it independently:
+ *
+ *   digest.value = lowercase hex sha256( utf8( canonicalJson( envelope.projection ) ) )
+ *
+ * Three consequences worth being explicit about, because each one is a bug someone would
+ * otherwise hit:
+ *
+ *  1. The digest covers `projection` ONLY. `generatedAt`, `kind`, `schemaVersion`, and the
+ *     digest field itself are outside it, so re-stamping a projection with a new timestamp does
+ *     not invalidate a digest, and the producer never has to solve the self-reference problem
+ *     of hashing a document that contains its own hash.
+ *  2. Canonicalisation sorts object keys, so a producer that serialises in insertion order and
+ *     a producer that serialises alphabetically agree.
+ *  3. The comparison is constant time. A digest is not a secret, so this is belt and braces
+ *     rather than a requirement, but the cost is a few microseconds and the habit is worth more.
+ */
+interface DigestCheck {
+    readonly matches: boolean;
+    readonly expected: string;
+    readonly actual: string;
+}
+/** Compute the digest of a projection value under the rule above. */
+declare function digestOfProjection(projection: JsonValue): string;
+/** Length-independent, value-independent comparison of two hex digests. */
+declare function digestsEqual(left: string, right: string): boolean;
+/** Recompute and compare in one step. */
+declare function verifyDigest(projection: JsonValue, declared: string): DigestCheck;
+
+/**
+ * Load a contract-public projection from disk and answer three questions in order, stopping at
+ * the first failure because the later answers are meaningless without the earlier ones:
+ *
+ *   1. Is it there and is it JSON?
+ *   2. Does the envelope match the committed schema?
+ *   3. Does the declared digest match the projection it wraps?
+ *
+ * Entirely offline and entirely local. The real projection is produced by the contract lane;
+ * this reads whatever file it is pointed at, which is why it works today against a fixture and
+ * will work unchanged against the real artifact.
+ */
+type ContractValidationOutcome = {
+    readonly kind: 'file_not_found';
+    readonly path: string;
+} | {
+    readonly kind: 'invalid_json';
+    readonly path: string;
+    readonly detail: string;
+} | {
+    readonly kind: 'invalid_contract';
+    readonly path: string;
+    readonly violations: readonly SchemaViolation[];
+} | {
+    readonly kind: 'digest_mismatch';
+    readonly path: string;
+    readonly digest: DigestCheck;
+} | {
+    readonly kind: 'valid';
+    readonly path: string;
+    readonly digest: DigestCheck;
+    readonly generatedAt: string;
+    readonly projectionKeys: readonly string[];
+    /**
+     * The parsed projection this validation just proved intact.
+     *
+     * Carried out rather than thrown away because the alternative is what the error registry
+     * used to do: call this function, take the keys, then re-read and re-JSON.parse the SAME
+     * file. Two reads of one path is a race (a projection rewritten between them by a
+     * concurrent `tools.contract.compile --write` surfaces as a raw SyntaxError escaping a
+     * command, in a package whose whole design is that every anticipated failure settles as a
+     * CommandOutcome), and the second parse had no try/catch while the one above does.
+     */
+    readonly projection: JsonObject;
+};
+/** Resolve a possibly relative `--path` against the injected cwd. Never touches process.cwd. */
+declare function resolveContractPath(cwd: string, path: string): string;
+declare function validateContractFile(fs: FileSystemPort, path: string): ContractValidationOutcome;
+
+/**
+ * THE ERROR REGISTRY, read from the contract-public projection rather than restated here.
+ *
+ * The platform compiles `contract/errors.yaml` into the redacted projection; this module reads
+ * the `errors.yaml` document out of that projection and nothing else. Copying the table into
+ * TypeScript would have been less code today and a guaranteed drift tomorrow: the wire codes
+ * change when a handler changes, and only the compiler sees that happen.
+ *
+ * The registry is reachable ONLY through `validateContractFile`, so the envelope schema and the
+ * digest are both checked before a single code is trusted. An operator running
+ * `everfur explain-error` against a file someone edited gets a digest mismatch, not a confident
+ * answer from a tampered table.
+ *
+ * `internal` and `evidence` are absent from the projection by design (the compiler redacts
+ * them), which is why this shape has no field for either.
+ */
+interface ErrorRegistryEntry {
+    /** Exactly the string the wire carries. Not normalised; three naming families are live. */
+    readonly code: string;
+    readonly envelope: string;
+    readonly httpStatus: number;
+    readonly namingFamily: string;
+    readonly retryable: boolean;
+    /** False means the code exists in source but no live route was traced emitting it. */
+    readonly confirmedOnWire: boolean;
+    readonly surfaces: readonly string[];
+    /** Safe copy a client may show a person as-is. */
+    readonly display: string;
+    readonly docUrl: string;
+    /** The mechanical cause, authored by the contract lane. */
+    readonly note: string;
+}
+interface ErrorRegistry {
+    lookup(code: string): ErrorRegistryEntry | null;
+    readonly codes: readonly string[];
+}
+/**
+ * The registry a command falls back to when no projection was supplied. Every lookup misses,
+ * which downgrades an HTTP failure's rendering to code plus status rather than inventing copy.
+ */
+declare const EMPTY_REGISTRY: ErrorRegistry;
+/** The projection document key the compiler writes the registry under. */
+declare const ERRORS_DOCUMENT_KEY = "errors.yaml";
+/**
+ * Narrow one raw projection row. A row missing `code` is dropped rather than defaulted: an
+ * entry whose identity is unknown cannot be looked up, so keeping it would only inflate a count.
+ * Every other field falls back to a neutral value, because a registry that refuses to load over
+ * one missing `note` is a registry that stops answering during the incident it exists for.
+ */
+declare function entryFromRow(row: unknown): ErrorRegistryEntry | null;
+type RegistryLoad = {
+    readonly kind: 'loaded';
+    readonly registry: ErrorRegistry;
+    readonly path: string;
+    readonly digest: string;
+} | {
+    readonly kind: 'no_registry';
+    readonly path: string;
+} | {
+    readonly kind: 'contract_rejected';
+    readonly outcome: ContractValidationOutcome;
+};
+/**
+ * Load the registry out of a contract-public envelope on disk. Contract failures are handed
+ * back unchanged so the caller can reuse `contract validate`'s exact error rendering rather
+ * than inventing a second, subtly different set of messages for the same three failures.
+ */
+declare function loadErrorRegistry(fs: FileSystemPort, path: string): RegistryLoad;
+
+declare const DEFAULT_TIMEOUT_MS = 10000;
+interface ApiSuccess<T> {
+    readonly ok: true;
+    readonly value: T;
+    readonly status: number;
+    /** The server's id, or null when the response carried none. */
+    readonly requestId: string | null;
+    readonly attempts: number;
+}
+type ApiFailure = {
+    readonly ok: false;
+    readonly kind: 'network';
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly detail: string;
+    readonly attempts: number;
+    readonly requestId: null;
+} | {
+    readonly ok: false;
+    readonly kind: 'timeout';
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly timeoutMs: number;
+    readonly attempts: number;
+    readonly requestId: null;
+} | {
+    readonly ok: false;
+    readonly kind: 'http';
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly status: number;
+    /** The wire code, or null when the body carried none. */
+    readonly code: string | null;
+    /**
+     * UNTRUSTED server free text, kept for a debugger and NEVER rendered.
+     *
+     * This field used to be called `message` and used to be interpolated into the failure
+     * summary, on the assumption that "the API's handlers emit vetted copy". They do not:
+     * `grep 'detail=str(exc'` across the platform's api service finds twenty-odd handlers
+     * that put a caught exception's `str()` straight into `detail`, so an upstream key, a
+     * connection string, or a bearer becomes CLI output on a path where the operator typed
+     * nothing sensitive. `describeFailure` now renders operator-owned data only.
+     *
+     * It is defined NON-ENUMERABLE (see `httpFailure` below), mirroring the SDK's
+     * `EverfurError.wireMessage`, so the serialisers that normally walk an object,
+     * `JSON.stringify`, spread, `Object.entries`, cannot carry it into a `--json` document
+     * either. Only a deliberate read reaches it.
+     */
+    readonly wireMessage: string;
+    readonly entry: ErrorRegistryEntry | null;
+    readonly retryable: boolean;
+    readonly requestId: string | null;
+    readonly attempts: number;
+} | {
+    readonly ok: false;
+    readonly kind: 'malformed';
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly status: number;
+    readonly detail: string;
+    readonly requestId: string | null;
+    readonly attempts: number;
+};
+type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+interface ApiClientOptions {
+    readonly transport: TransportPort;
+    readonly clock: ClockPort;
+    readonly endpoint: ResolvedEndpoint;
+    readonly registry?: ErrorRegistry;
+    readonly timeoutMs?: number;
+    /** Caller supplied correlation id. Sent only when it is a shape the API will reuse. */
+    readonly requestId?: string | null;
+    /** Attempts allowed for an IDEMPOTENT call. Non-idempotent calls always get exactly one. */
+    readonly maxAttempts?: number;
+    /** Delay between attempts, in milliseconds. */
+    readonly retryDelayMs?: number;
+}
+interface RequestSpec {
+    readonly method: HttpMethod;
+    /** API-relative, for example `/widget/v1/diagnostics`. The prefix is added here. */
+    readonly path: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Header name to credential. Revealed into the outgoing header map only. */
+    readonly credentials?: Readonly<Record<string, Credential>>;
+    readonly body?: JsonValue;
+    /** Statuses that are a successful outcome for this call, in addition to 2xx. */
+    readonly acceptStatuses?: readonly number[];
+}
+interface ApiClient {
+    request(spec: RequestSpec): Promise<ApiResult<JsonValue>>;
+    /** The resolved base URL, for reporting. Never a credential. */
+    readonly baseUrl: string;
+}
+declare function clampTimeout(value: number): number;
+/** True when the value is a shape `RequestIDMiddleware` will reuse rather than replace. */
+declare function isCorrelatableRequestId(value: string): boolean;
+/**
+ * Read the wire code out of an error body. Three shapes are live at once and the registry says
+ * so, so this reads all three rather than pretending there is one:
+ *
+ *   {"code": "...", "message": ...}            the status-mapped envelope
+ *   {"error": "...", "message": ...}           a dict-detail dependency, flattened
+ *   {"detail": {"error": "...", ...}}          the same, unflattened by a passthrough handler
+ *
+ * THE CODE IS TRUSTED, THE TEXT IS NOT. `code` is a wire enum this CLI matches against the
+ * compiled registry, so it is operator-safe to print. `wireMessage` is whatever the server
+ * chose to say, from any of the four branches below, and every one of those branches can carry
+ * a caught exception's `str()`. It is named `wireMessage` rather than `message` precisely so
+ * that no future caller reads it as "the copy to show".
+ */
+declare function errorCodeOf(body: unknown): {
+    readonly code: string | null;
+    readonly wireMessage: string;
+};
+declare function createApiClient(options: ApiClientOptions): ApiClient;
+/**
+ * One-line human summary of a failure. Assembled from OPERATOR-OWNED DATA ONLY: the method and
+ * path the operator's own command named, the status, the wire code, and, when that code
+ * resolves, the registry's own vetted `display` copy. Never a credential and never server free
+ * text, which are the same rule: this CLI cannot tell them apart at the point of rendering.
+ *
+ * The `network` and `malformed` details are Node's own (a DNS failure, a `JSON.parse` message),
+ * not the server's, so they stay. The `http` case is the one that used to interpolate
+ * `failure.wireMessage`, and that is exactly the string a handler builds from `str(exc)`.
+ */
+declare function describeFailure(failure: ApiFailure): string;
+/** The detail lines a command appends under `describeFailure`. */
+declare function failureDetails(failure: ApiFailure): readonly string[];
+
+declare function failureOutcome(failure: ApiFailure, extraDetails?: readonly string[]): CommandOutcome;
+
+/**
+ * Narrow `GET /widget/v1/diagnostics` into the CLI's own shape.
+ *
+ * Two rules, both deliberate:
+ *
+ *  1. STRUCTURAL fields are required. A body with no `capabilities` array is not a diagnosis,
+ *     and pretending it is would print a confident "0 capabilities" for what is actually a
+ *     proxy error page. Those cases surface as `malformed_response`, exit 6.
+ *  2. VALUE fields are tolerated. A new reason code, a new lattice kind, or an added field is
+ *     the platform growing, and this CLI must keep answering across that. Unknown reason codes
+ *     are carried through verbatim and get the upgrade next-action.
+ *
+ * Field names are snake_case on the wire and camelCase here, converted once, at this boundary.
+ */
+interface CapabilityDiagnosis {
+    readonly key: string;
+    readonly available: boolean;
+    readonly reasonCode: string;
+    readonly reason: string;
+    readonly entitlementReasonCode: string;
+    readonly decidedAtLevel: number | null;
+    readonly decidedAtKind: string | null;
+    readonly surface: string | null;
+    /** CLI-authored. What the partner should do; see `reasons.ts`. */
+    readonly nextAction: string;
+}
+interface ScopeLevelDiagnosis {
+    readonly level: number;
+    readonly kind: string;
+    readonly present: boolean;
+}
+interface Diagnosis {
+    readonly requestId: string | null;
+    readonly evaluatedAt: string;
+    readonly clientId: string;
+    readonly clientSlug: string;
+    readonly auth: {
+        readonly mode: string;
+        readonly anonymous: boolean;
+        readonly userRefPrefix: string;
+        readonly userRole: string;
+        readonly roleSource: string;
+        readonly sessionId: string;
+        readonly partnerKeyScopeResolved: boolean;
+    };
+    readonly scope: {
+        readonly provisioned: boolean;
+        readonly resolverStatus: string;
+        readonly revision: number;
+        readonly region: string;
+        readonly levels: readonly ScopeLevelDiagnosis[];
+    };
+    readonly capabilities: readonly CapabilityDiagnosis[];
+}
+type DiagnosisParse = {
+    readonly ok: true;
+    readonly diagnosis: Diagnosis;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+declare function parseDiagnostics(body: unknown, headerRequestId: string | null): DiagnosisParse;
+
+interface DiagnosisDocumentInput {
+    readonly diagnosis: Diagnosis;
+    readonly baseUrl: string;
+    readonly path: string;
+    readonly cliVersion: string;
+}
+declare function buildDiagnosisDocument(input: DiagnosisDocumentInput): JsonObject;
+
+/**
+ * The human projection of a diagnosis. Same facts as the JSON, same order, nothing added.
+ *
+ * The unavailable list is GROUPED BY CAUSE rather than printed key by key. That is the whole
+ * point of the command: a partner staring at eight unavailable capabilities needs to see that
+ * they are eight symptoms of one unprovisioned scope, not eight problems. Each group prints its
+ * machine code once, the server's copy once, and the next action once.
+ */
+interface DiagnosisRenderInput {
+    readonly diagnosis: Diagnosis;
+    readonly baseUrl: string;
+}
+declare function renderDiagnosis(input: DiagnosisRenderInput): string;
+
+/**
+ * WHY A CAPABILITY IS UNAVAILABLE, and what to do about it.
+ *
+ * The nine codes are the platform's own `DiagnosticsReasonCode`, which exists because an empty
+ * `capabilities:{}` verdict has five byte-identical causes and the render payload deliberately
+ * carries no "why". The server sends the code and its own safe copy; this table adds the part
+ * the server cannot know, which is what the PARTNER should do next.
+ *
+ * The distinction that makes this table worth having: three of these are somebody else's job
+ * (`scope_not_provisioned`, `not_in_grant`, `runtime_gate_off`), one is a commercial
+ * conversation (`outside_ceiling`), one is deliberate configuration (`capability_denied`), one
+ * is transient (`resolver_unavailable`), and one is a bug to report (`gate_unknown`). A single
+ * "the feature is unavailable" message collapses all seven into one wrong next step.
+ *
+ * An UNKNOWN code is not an error. The enum grows when the platform grows a new decision point,
+ * and a CLI that rejected the answer would be useless exactly when something new broke. It
+ * renders the code verbatim with an upgrade instruction.
+ */
+declare const REASON_CODES: readonly ["granted", "scope_not_provisioned", "capability_denied", "outside_ceiling", "not_in_grant", "runtime_gate_off", "gate_unknown", "platform_invariant", "resolver_unavailable"];
+type ReasonCode = (typeof REASON_CODES)[number];
+declare function isKnownReasonCode(value: string): value is ReasonCode;
+/** The next action for a code, including one this CLI has never heard of. */
+declare function nextActionFor$1(code: string): string;
+
+/**
+ * THE SECRET FENCE. This module turns an admin mint response into the only shape this CLI is
+ * allowed to hand back, and it is written so that a raw secret CANNOT travel through it.
+ *
+ * The rule, stated once and enforced by construction rather than by care:
+ *
+ *   The projection reads a FIXED LIST OF FIELD NAMES off the response. There is no spread, no
+ *   `Object.entries` loop, no "copy everything except". `secret_value` is not in the list, so
+ *   no future field added to the response can arrive here by accident either.
+ *
+ * That mirrors the reasoning in the platform's own `_metadata` helper, which forbids a
+ * `**record` splat for the same reason: the one field that must never reach a response is
+ * exactly the field a splat would carry.
+ *
+ * THE SERVER-SIDE GAP. The approved design has this command return `{key_id, claim_url,
+ * claim_expires_at}` and a human claiming the secret in a browser. The live route
+ * (`POST /api/v1/admin/clients/{client_id}/secret-keys`) returns `secret_value` inline and no
+ * claim URL at all: there is no claim flow on the server yet. This client models the approved
+ * design, reads a `claim_url` when one appears, and reports `claim_unavailable` when it does
+ * not. It never falls back to printing what it was handed. See DECISIONS.md, open question 6.
+ *
+ * AND IT CLEANS UP AFTER ITSELF. Discarding the secret is only half an answer: the key is
+ * still live server side, so a command that stopped there would leave a credential nobody
+ * holds behind on EVERY invocation against the live route, and then print an instruction
+ * telling the operator to go and revoke it by hand. That is worse than the stub the registry's
+ * own doctrine forbids, because it has a side effect. So `claim_unavailable` now REVOKES the
+ * key it just minted, through the route's own idempotent
+ * `DELETE /admin/clients/{client_id}/secret-keys/{key_id}`, and reports whether that worked.
+ * The operator is only ever asked to revoke by hand when the revoke itself failed.
+ */
+type SandboxCreateStatus = 'claim_issued' | 'claim_unavailable';
+/**
+ * What happened to the key on the `claim_unavailable` path.
+ *
+ *   not_needed    a claim URL was issued, so the key is wanted and stays.
+ *   revoked       the mint produced an unclaimable key and this command revoked it.
+ *   revoke_failed the revoke was attempted and did not succeed. THIS is the only case where a
+ *                 live orphaned credential is left behind, and the only case where the report
+ *                 asks a human to remove it.
+ */
+type SandboxRevocation = 'not_needed' | 'revoked' | 'revoke_failed';
+interface SandboxCreation {
+    readonly status: SandboxCreateStatus;
+    readonly keyId: string;
+    readonly clientId: string;
+    readonly label: string | null;
+    readonly createdAt: string | null;
+    readonly claimUrl: string | null;
+    readonly claimExpiresAt: string | null;
+    /**
+     * True when the response carried a raw secret that this CLI discarded unread. Reported
+     * because it is operationally important: a credential now exists that nobody holds.
+     */
+    readonly secretDiscarded: boolean;
+}
+type SandboxCreateParse = {
+    readonly ok: true;
+    readonly creation: SandboxCreation;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/**
+ * Project the mint response. Every field is named; nothing is copied wholesale.
+ *
+ * `secretDiscarded` is derived by TESTING FOR PRESENCE ONLY. The value is never bound to a
+ * variable, never returned, and never reaches a string, which is why a `--json` document and a
+ * rendered report are both provably free of it whatever the server sent.
+ */
+declare function projectSandboxCreate(body: unknown): SandboxCreateParse;
+interface SandboxDocumentInput {
+    readonly creation: SandboxCreation;
+    readonly revocation: SandboxRevocation;
+    readonly requestId: string | null;
+    readonly cliVersion: string;
+}
+/** The next actions for each status. Never contains a value, only names and commands. */
+declare function nextActionsFor(creation: SandboxCreation, revocation: SandboxRevocation): readonly string[];
+declare function buildSandboxDocument(input: SandboxDocumentInput): JsonObject;
+/** The human projection. */
+declare function renderSandboxCreate(creation: SandboxCreation, revocation: SandboxRevocation, requestId: string | null): string;
+
+/**
+ * THE WIRE EXERCISE. Three steps, run in order, each of which reports what happened rather than
+ * what the process is about to exit with.
+ *
+ *   mint-session       POST /widget/v1/sessions with the sk + pk pair.
+ *   poll-entitlements  GET  /widget/v1/entitlements with the minted bearer.
+ *   assert-verdict     the verdict carries at least one capability.
+ *
+ * Three properties this file exists to guarantee:
+ *
+ *  1. EVERY STEP CARRIES A REASON, including a passing one. "PASS" alone tells an operator
+ *     nothing they can paste into a ticket; "PASS: minted a session valid until ..." does.
+ *  2. A STEP THAT COULD NOT RUN IS SKIP, NOT FAIL. Missing credentials are not a broken
+ *     integration, and reporting them as failures would send someone debugging the API when
+ *     they simply have not exported a key yet.
+ *  3. THE MINTED TOKEN NEVER REACHES A REPORT. It is wrapped as an ephemeral credential the
+ *     moment it is read, so the only thing that can travel into step two is a header the HTTP
+ *     client writes, and the only thing that can travel into the report is its expiry.
+ *
+ * The mint is a POST and gets exactly one attempt. The poll is a GET, so repeating it is safe,
+ * and it repeats on purpose: an entitlement scope provisioned seconds ago propagates on a
+ * revision bump, and a single read would report a stale empty verdict as a failure.
+ */
+type StepResult = 'PASS' | 'FAIL' | 'SKIP';
+interface VerifyStep {
+    /** Stable within a schemaVersion. Callers may key on it. */
+    readonly id: string;
+    readonly title: string;
+    readonly result: StepResult;
+    /** Always populated, for every result including PASS. */
+    readonly reason: string;
+    readonly requestId: string | null;
+    readonly details: readonly string[];
+}
+interface VerifyOptions {
+    readonly client: ApiClient;
+    readonly clock: ClockPort;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly userRef: string;
+    /** How many times to read the verdict before concluding it is empty. */
+    readonly attempts: number;
+    readonly pollDelayMs: number;
+}
+interface Verification {
+    readonly steps: readonly VerifyStep[];
+    readonly status: 'passed' | 'failed' | 'incomplete';
+}
+declare function runVerification(options: VerifyOptions): Promise<Verification>;
+
+declare function buildVerificationDocument(verification: Verification, baseUrl: string, cliVersion: string): JsonObject;
+declare function renderVerification(verification: Verification, baseUrl: string): string;
+
+declare function nextActionFor(entry: ErrorRegistryEntry): string;
+interface ExplanationInput {
+    readonly entry: ErrorRegistryEntry;
+    readonly contractPath: string;
+    readonly digest: string;
+    readonly cliVersion: string;
+}
+declare function buildExplanationDocument(input: ExplanationInput): JsonObject;
+declare function renderExplanation(input: ExplanationInput): string;
+
+/**
+ * Suggestions for a code the registry does not list.
+ *
+ * Worth the twenty lines because the registry deliberately keeps THREE naming families at once
+ * (`AuthorizationException`, `authExpired`, `session_required`), so a partner guessing at a code
+ * guesses in the wrong family constantly, and the codes are case sensitive because a client
+ * branches on the literal. "Did you mean authExpired" is the whole answer in that case.
+ *
+ * Ranked: an exact case-insensitive hit first, then a containment hit, then a near miss by edit
+ * distance. Capped, because a list of twenty guesses is not a suggestion.
+ */
+/** Iterative Levenshtein over two rows. No dependency for something this small. */
+declare function editDistance(left: string, right: string): number;
+declare function suggestCodes(query: string, codes: readonly string[]): readonly string[];
+
+/**
+ * The one real filesystem adapter. Every syscall failure collapses to a null or false, so no
+ * EACCES on an unrelated probe can take the whole command down; a genuinely required file
+ * that reads as null surfaces as a typed `file_not_found` error at the call site instead.
+ */
+declare const nodeFileSystem: FileSystemPort;
+
+/**
+ * An in-memory FileSystemPort for tests that need a shape no fixture on disk should carry,
+ * for example two competing lockfiles or a manifest that is not valid JSON. Fixture projects
+ * on disk stay the primary detection test surface; this covers the pathological cases.
+ *
+ * Directories are implied by the file keys, so a caller only ever declares files.
+ */
+declare function createMemoryFileSystem(files: Readonly<Record<string, string>>): FileSystemPort;
+
+/**
+ * The detection vocabulary. Every value here is something the CLI can establish from files on
+ * disk. Anything it cannot establish lives in `src/commands/plan/facts.ts` as a supplied fact,
+ * and the two sets are deliberately disjoint.
+ */
+type ProjectType = 'expo-managed' | 'bare-react-native' | 'flutter' | 'web' | 'unknown';
+type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'not-applicable' | 'undetermined';
+type DependencySource = 'package.json' | 'pubspec.yaml';
+type DependencyScope = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'sdk';
+/**
+ * `declared` is the range written in the manifest. `installed` is the exact version resolved
+ * on disk when the dependency tree is present. Reporting both is the honest answer: a plan
+ * built against `^50.0.0` with nothing installed is materially less certain than one built
+ * against a resolved 50.0.17, and a reader deserves to see which of the two they are getting.
+ */
+interface DetectedDependency {
+    readonly name: string;
+    readonly declared: string | null;
+    readonly installed: string | null;
+    readonly source: DependencySource;
+    readonly scope: DependencyScope;
+}
+interface ProjectDetection {
+    readonly root: string;
+    readonly projectType: ProjectType;
+    /** Human-readable file-level facts that produced `projectType`, in the order they were found. */
+    readonly projectTypeEvidence: readonly string[];
+    readonly packageManager: PackageManager;
+    readonly packageManagerEvidence: readonly string[];
+    readonly dependencies: readonly DetectedDependency[];
+}
+
+declare function detectProject(fs: FileSystemPort, root: string): ProjectDetection;
+
+type AttributeValue = string | number | boolean | null | readonly string[];
+interface TreePrinciple {
+    readonly id: string;
+    readonly title: string;
+    readonly statement: string;
+    readonly docPath: string | null;
+}
+interface BranchOutcome {
+    readonly kind: 'branch';
+    readonly nextQuestionId: string;
+}
+interface TerminalOutcome {
+    readonly kind: 'terminal';
+    readonly attributes: Readonly<Record<string, AttributeValue>>;
+    readonly docPaths: readonly string[];
+    readonly capabilityRefs: readonly string[];
+    /** The tree that must be answered next, or null when this answer stands alone. */
+    readonly thenAskTreeId: string | null;
+}
+interface BlockedOutcome {
+    readonly kind: 'blocked';
+    readonly reason: string;
+    readonly unblockOwner: string;
+    readonly requestPath: string;
+    readonly capabilityRefs: readonly string[];
+}
+type Outcome = BranchOutcome | TerminalOutcome | BlockedOutcome;
+interface TreeOption {
+    readonly id: string;
+    readonly label: string;
+    readonly when: string;
+    readonly outcome: Outcome;
+}
+interface TreeQuestion {
+    readonly id: string;
+    readonly prompt: string;
+    readonly whyItIsAsked: string;
+    /**
+     * The exact invocation change that answers this question, or null when there is none. Null is
+     * an answer, not an omission: a question whose only option is implied has no flag.
+     */
+    readonly supplyWith: string | null;
+    readonly detectable: boolean;
+    /** Sorted by id, because the published order is alphabetical and means nothing. */
+    readonly options: readonly TreeOption[];
+}
+interface DecisionTree {
+    readonly treeId: string;
+    readonly title: string;
+    readonly decides: string;
+    /** The exact invocation change that answers this tree. Rendered in a refusal. */
+    readonly supplyWith: string;
+    readonly entryQuestionId: string;
+    readonly principles: readonly TreePrinciple[];
+    readonly questions: readonly TreeQuestion[];
+}
+interface DecisionSpace {
+    readonly trees: readonly DecisionTree[];
+    /** Where it came from and what it hashed to, carried into the plan document. */
+    readonly source: string;
+    readonly digest: string;
+    tree(treeId: string): DecisionTree | null;
+    question(treeId: string, questionId: string): TreeQuestion | null;
+    /** The option ids of one question, sorted. The enum a flag is parsed against. */
+    choices(treeId: string, questionId: string): readonly string[];
+}
+declare function buildDecisionSpace(trees: readonly DecisionTree[], source: string, digest: string): DecisionSpace;
+type DecisionSpaceLoad = {
+    readonly kind: 'loaded';
+    readonly space: DecisionSpace;
+} | {
+    readonly kind: 'no_trees';
+    readonly path: string;
+} | {
+    readonly kind: 'contract_rejected';
+    readonly outcome: ContractValidationOutcome;
+};
+/**
+ * Load the decision space out of a contract-public envelope on disk. Contract failures are
+ * handed back unchanged so the caller can reuse `contract validate`'s exact error rendering
+ * rather than inventing a second, subtly different set of messages for the same three failures.
+ */
+declare function loadDecisionSpace(fs: FileSystemPort, path: string): DecisionSpaceLoad;
+/** One question the walk passed through, and the option it took. */
+interface WalkStep {
+    readonly questionId: string;
+    readonly optionId: string;
+    /** True when the question had exactly one option, so nothing was chosen. */
+    readonly implied: boolean;
+}
+type WalkResult = {
+    readonly kind: 'terminal';
+    readonly outcome: TerminalOutcome;
+    readonly path: readonly WalkStep[];
+} | {
+    readonly kind: 'blocked';
+    readonly outcome: BlockedOutcome;
+    readonly path: readonly WalkStep[];
+} | {
+    readonly kind: 'unanswered';
+    readonly question: TreeQuestion;
+} | {
+    readonly kind: 'unknown_option';
+    readonly question: TreeQuestion;
+    readonly given: string;
+} | {
+    readonly kind: 'unwalkable';
+    readonly detail: string;
+};
+/** Supplies the answer to one question, or null when the caller has not answered it. */
+type AnswerFor = (questionId: string) => string | null;
+/**
+ * Walk one tree. Terminates on a terminal, a block, or the first question nobody answered.
+ *
+ * A QUESTION WITH EXACTLY ONE OPTION IS TAKEN WITHOUT AN ANSWER, and the step records that it
+ * was implied. One option is not a decision: it is the contract saying "everyone who gets here
+ * ends up in the same place", which is how three backend languages with no first-party minter
+ * converge on one description of the direct call. Demanding a flag for it would be demanding
+ * the caller confirm the only thing that could happen.
+ *
+ * The `visited` guard is not a substitute for the compiler's cycle check; it is what keeps a
+ * projection built by something other than that compiler from hanging this process.
+ */
+declare function walkTree(tree: DecisionTree, answerFor: AnswerFor): WalkResult;
+/** Walk a tree whose whole answer is one option of its entry question. */
+declare function walkSingle(tree: DecisionTree, answer: string): WalkResult;
+
+/** One file a plan tells the caller to write. */
+interface PlanCode {
+    /** Suggested path, relative to the project root. */
+    readonly path: string;
+    /** For syntax highlighting and for an agent deciding how to write it. */
+    readonly language: 'tsx' | 'ts' | 'dart';
+    readonly contents: string;
+}
+
+/**
+ * THE PLAN CONTRACT.
+ *
+ * This file and `schema/plan.v1.schema.json` are two views of one committed artifact. Anything
+ * a caller can parse out of `everfur plan --json` is declared here, and `tests/contract`
+ * validates real emitted output against the JSON Schema on every run, so the two cannot drift
+ * without the suite going red.
+ *
+ * Compatibility rule for `schemaVersion: 1`: fields may be ADDED, and enum members may be
+ * ADDED. A field is never removed, never renamed, and never changes type or meaning. Any of
+ * those is `schemaVersion: 2` and a new schema file beside this one.
+ *
+ * WHAT CHANGED WHEN THE DECISION TREES LANDED, and why it stayed v1:
+ *
+ *  - `status` gained `blocked`, `missingFacts[].fact` gained `decisionTrees` and
+ *    `sessionMintLanguage`: added enum members, which v1 permits.
+ *  - `blocked`, `principles` and `decisionSpace` are new fields, which v1 permits.
+ *  - `Capability` and `IdentityMode` stopped being enums and became patterned strings. This is
+ *    the one change worth arguing about, so it is argued here: the set was never this package's
+ *    to own. It lives in `contract/decision-trees/`, and an enum here would reject a capability
+ *    the platform published until somebody remembered to edit a CLI. The relaxation accepts
+ *    every document v1 already accepted and rejects nothing it used to, which is the test that
+ *    keeps it inside v1.
+ */
+declare const PLAN_SCHEMA_VERSION = 1;
+declare const PLAN_DOCUMENT_KIND = "everfur.plan";
+/**
+ * A capability id: one option of the capabilities tree's entry question. NOT an enum here.
+ * The authoritative list is the contract's, and `everfur plan` reads it from the projection.
+ */
+type Capability = string;
+/** An identity mode id: one option of the identity-mode tree's entry question. */
+type IdentityMode = string;
+/** A backend language id: one option of the session-mint-language tree's entry question. */
+type SessionMintLanguage = string;
+type PlanStatus = 'ready' | 'underspecified' | 'blocked';
+/**
+ * The facts `plan` needs. Each is either detected from disk, supplied by flag, or loaded from
+ * the contract, and never guessed.
+ *
+ * `decisionTrees` comes first because it is the fact the others are judged against: with no
+ * decision space the CLI cannot say whether a capability exists, let alone whether it is
+ * reachable. It is a REFUSAL rather than a broken-artifact failure because nothing was loaded
+ * and nothing on disk is wrong; the operator simply has not said where the contract is.
+ */
+declare const MISSING_FACT_NAMES: readonly ["decisionTrees", "projectType", "packageManager", "capabilities", "identityMode", "sessionMintLanguage"];
+type MissingFactName = (typeof MISSING_FACT_NAMES)[number];
+interface MissingFact {
+    readonly fact: MissingFactName;
+    /** Why the CLI could not establish it, phrased as what it looked at. */
+    readonly reason: string;
+    /** The exact invocation change that resolves it. */
+    readonly supplyWith: string;
+}
+type PlanPhase = 'install' | 'native' | 'configure' | 'code' | 'verify';
+interface PlanStep {
+    /** Stable within a schemaVersion. Callers may key on it. */
+    readonly id: string;
+    readonly phase: PlanPhase;
+    readonly title: string;
+    readonly detail: string;
+    /** Shell commands, in order. Never contains a credential value. */
+    readonly commands: readonly string[];
+    /** Files the partner is expected to create or edit. */
+    readonly files: readonly string[];
+    /**
+     * Code to write, when this package can name every symbol in it.
+     *
+     * Absent rather than invented when it cannot: a plausible-looking snippet naming a component that
+     * does not exist is worse than no snippet, because it compiles in the reader's head and fails in
+     * their editor. See codegen.ts for which surfaces qualify.
+     */
+    readonly code?: readonly PlanCode[];
+}
+interface PlanWarning {
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * A capability the caller asked for that a planner must not build against, lifted verbatim from
+ * a BLOCKED terminal in the contract.
+ *
+ * This is the field that stops the CLI producing a confident, wrong plan. Without it, a
+ * capability whose runtime gate is a control-plane switch reads as ordinary: the plan installs
+ * the SDK, mounts the surface, and every route answers 404 in production, which the partner
+ * reads as a broken SDK rather than as a switch nobody turned on.
+ */
+interface BlockedCapability {
+    /** The capability id the caller named. */
+    readonly capability: string;
+    readonly reason: string;
+    readonly unblockOwner: string;
+    /** Site-relative path on the partner documentation site. Resolved at compile time. */
+    readonly requestPath: string;
+    /** The capability pack keys the block derives from. */
+    readonly capabilityKeys: readonly string[];
+}
+/**
+ * Guidance that is true regardless of what was answered, carried in the document rather than
+ * left in a prompt. An agent that has compacted its context away still holds these.
+ */
+interface PlanPrinciple {
+    readonly treeId: string;
+    readonly id: string;
+    readonly title: string;
+    readonly statement: string;
+    readonly docPath: string | null;
+}
+/** Which decision space produced this plan, so a stale plan can be traced to a stale contract. */
+interface DecisionSpaceProvenance {
+    readonly source: string;
+    readonly digest: string;
+    readonly trees: readonly string[];
+}
+interface PlanDetection {
+    readonly root: string;
+    readonly projectType: ProjectType;
+    readonly projectTypeEvidence: readonly string[];
+    readonly packageManager: PackageManager;
+    readonly packageManagerEvidence: readonly string[];
+    readonly dependencies: readonly {
+        readonly name: string;
+        readonly declared: string | null;
+        readonly installed: string | null;
+        readonly source: string;
+        readonly scope: string;
+    }[];
+}
+interface PlanDocument {
+    readonly schemaVersion: typeof PLAN_SCHEMA_VERSION;
+    readonly kind: typeof PLAN_DOCUMENT_KIND;
+    readonly generatedBy: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly status: PlanStatus;
+    /** What the CLI established by reading the project. Always populated, refusal included. */
+    readonly detected: PlanDetection;
+    /** What the caller supplied. `null` means the flag was absent. */
+    readonly supplied: {
+        readonly capabilities: readonly Capability[] | null;
+        readonly identityMode: IdentityMode | null;
+        readonly sessionMintLanguage: SessionMintLanguage | null;
+    };
+    /** Empty when `status` is `ready`. Non-empty exactly when it is `underspecified`. */
+    readonly missingFacts: readonly MissingFact[];
+    /** Empty when `status` is `underspecified` or `blocked`. The CLI emits no partial plan. */
+    readonly steps: readonly PlanStep[];
+    /** Non-empty exactly when a selected capability cannot be built today. */
+    readonly blocked: readonly BlockedCapability[];
+    /** The principles of every tree this plan consulted. */
+    readonly principles: readonly PlanPrinciple[];
+    readonly warnings: readonly PlanWarning[];
+    /** Null only on the refusal that says no decision space was found. */
+    readonly decisionSpace: DecisionSpaceProvenance | null;
+}
+
+/**
+ * The planner. A pure function from (what was detected, what was supplied, what the contract
+ * says) to a plan document. No filesystem, no clock, no network, no environment: the same
+ * inputs always produce a byte-identical document, which is what makes the JSON contract
+ * testable and diffable in CI.
+ *
+ * THE HEADLINE BEHAVIOUR IS STILL THE REFUSAL. When any required fact is absent the planner
+ * returns a complete, schema-valid document with `status: "underspecified"`, an empty `steps`,
+ * and a `missingFacts` entry per absent fact naming both the reason and the exact flag that
+ * supplies it. It does not emit a partial plan, and it never substitutes a default. A wrong
+ * plan that looks right costs a partner a day; a refusal costs them one flag.
+ *
+ * THE SECOND BEHAVIOUR IS THE BLOCK, and it is new. The decision space now comes from the
+ * contract, and the contract can say that a capability is not buildable: its runtime gate is a
+ * control-plane switch that is off, or every action in it is closed to an agent. Before this,
+ * asking for such a capability produced a confident plan whose every route answers 404 in
+ * production, which a partner reads as a broken SDK. Now it produces the reason and the path to
+ * ask, and no steps for that capability at all.
+ *
+ * WHAT THIS FILE NO LONGER DECIDES: which capabilities exist, which identity modes exist, what
+ * a capability's import target is, which optional native peers it binds, which verb installs
+ * into this project, and what to tell somebody who is missing a fact. All of that is read from
+ * the trees. What is left here is composition: turning answers into ordered steps.
+ *
+ * SECRETS. Nothing in this file mints, derives, reads, or prints a credential. Configuration
+ * steps name ENVIRONMENT VARIABLES and never values, and `tests/unit/plan-no-secrets.test.ts`
+ * asserts that over the emitted document for every capability and identity combination.
+ */
+interface PlanInput {
+    readonly detection: ProjectDetection;
+    readonly capabilities: readonly Capability[] | null;
+    readonly identityMode: IdentityMode | null;
+    readonly sessionMintLanguage: SessionMintLanguage | null;
+    /** The decision space from the contract projection, or null when none was found. */
+    readonly space: DecisionSpace | null;
+    readonly cliVersion: string;
+}
+/**
+ * Compute the missing facts in a fixed order: the contract first, because everything else is
+ * judged against it; then the detected facts, which the operator fixes by pointing the CLI
+ * somewhere else; then the supplied facts, which are fixed by adding a flag.
+ */
+declare function missingFactsFor(input: PlanInput): readonly MissingFact[];
+/**
+ * Build the plan.
+ *
+ * Three outcomes, and the order between them is deliberate:
+ *
+ *  1. `underspecified` when any required fact is absent. Nothing else is decidable, so this
+ *     wins even when some capability is also blocked.
+ *  2. `blocked` when everything was answered and NOTHING the caller asked for can be built.
+ *     Steps are empty: an install plan for a surface that answers 404 is not a smaller plan,
+ *     it is a wrong one.
+ *  3. `ready` otherwise, with the blocked capabilities still reported beside the steps that
+ *     cover the rest.
+ */
+declare function planIntegration(input: PlanInput): PlanDocument;
+
+/** Render whichever projection of the plan the status calls for. Total over `status`. */
+declare function renderPlan(document: PlanDocument): string;
+
+/**
+ * Parsing for the facts the CLI cannot detect.
+ *
+ * The distinction this file protects: an ABSENT flag is a missing fact, which the planner turns
+ * into a structured refusal. A PRESENT but invalid flag is a usage error, which fails at exit
+ * code 2 before the planner runs. Collapsing the two would let a typo'd `--identity partner`
+ * read as "the operator did not tell us", which is a materially different and much worse report.
+ *
+ * WHAT IS VALID COMES FROM THE CONTRACT. The accepted values are the option ids of one question
+ * of one decision tree, so a capability the platform published is accepted the day the
+ * projection carries it, with no release of this package. When no decision space is available
+ * the flags are parsed but NOT judged: without the trees this CLI does not know what a valid
+ * capability is, and rejecting a value it cannot evaluate would be guessing in the direction
+ * that looks strict rather than the direction that is honest. The refusal names `decisionTrees`
+ * instead, which is the fact that is actually missing.
+ */
+interface SuppliedFactsResult {
+    readonly ok: boolean;
+    readonly capabilities: readonly Capability[] | null;
+    readonly identityMode: IdentityMode | null;
+    readonly sessionMintLanguage: SessionMintLanguage | null;
+    readonly errors: readonly string[];
+}
+/**
+ * Parse `--capabilities chat,records`. Order is normalised to sorted order and duplicates
+ * collapse, so two equivalent invocations produce a byte-identical plan document.
+ */
+declare function parseCapabilities(raw: string | null, space: DecisionSpace | null): {
+    readonly value: readonly Capability[] | null;
+    readonly errors: readonly string[];
+};
+declare function parseIdentityMode(raw: string | null, space: DecisionSpace | null): {
+    readonly value: IdentityMode | null;
+    readonly errors: readonly string[];
+};
+/** Parse `--backend node`. */
+declare function parseSessionMintLanguage(raw: string | null, space: DecisionSpace | null): {
+    readonly value: SessionMintLanguage | null;
+    readonly errors: readonly string[];
+};
+/** Parse every supplied fact, accumulating all errors rather than stopping at the first. */
+declare function parseSuppliedFacts(capabilitiesRaw: string | null, identityRaw: string | null, backendRaw: string | null, space: DecisionSpace | null): SuppliedFactsResult;
+
+/**
+ * The CLI version, stamped into every emitted document under `generatedBy.version`.
+ *
+ * Declared here rather than read from package.json at runtime so the bundled bin has no
+ * dependency on its own package layout, which differs between a local checkout, a global
+ * install, and a bundled artifact. `tests/unit/version.test.ts` asserts this constant equals
+ * the package.json version, so the two cannot drift.
+ */
+declare const CLI_VERSION = "0.1.0";
+
+export { ADMIN_TOKEN, API_PREFIX, type ApiClient, type ApiFailure, type ApiResult, type ApiSuccess, BASE_URL_ENV_VAR, type BlockedCapability, type BlockedOutcome, CLI_VERSION, COMMANDS, CREDENTIAL_SPECS, type Capability, type CapabilityDiagnosis, type ClockPort, type Command, type CommandContext, type CommandOutcome, type ContractValidationOutcome, type Credential, type CredentialSpec, DEFAULT_TIMEOUT_MS, type DecisionSpace, type DecisionSpaceProvenance, type DecisionTree, type DetectedDependency, type Diagnosis, EMPTY_REGISTRY, ERRORS_DOCUMENT_KEY, type ErrorRegistry, type ErrorRegistryEntry, ExitCode, type FileSystemPort, type FormatOptions, type FormattedOutput, type HttpMethod, type HttpRequest, type HttpResponse, IDEMPOTENT_METHODS, type IdentityMode, MISSING_FACT_NAMES, type MissingFact, type MissingFactName, type Outcome, PARTNER_KEY, PARTNER_SECRET_KEY, PLAN_DOCUMENT_KIND, PLAN_SCHEMA_VERSION, type PackageManager, type PlanDocument, type PlanInput, type PlanPrinciple, type PlanStep, type PlanWarning, type PositionalSpec, type ProjectDetection, type ProjectType, REASON_CODES, REDACTED, type ReasonCode, type RegistryLoad, type RequestSpec, type ResolvedCredential, type ResolvedEndpoint, type RunOptions, SCHEMAS, SESSION_TOKEN, type SandboxCreateStatus, type SandboxCreation, type SchemaValidation, type SchemaViolation, type SessionMintLanguage, type StepResult, type TerminalOutcome, TransportError, type TransportPort, type TreeOption, type TreeQuestion, type Verification, type VerifyStep, type WalkResult, apiUrl, buildDecisionSpace, buildDiagnosisDocument, buildExplanationDocument, buildSandboxDocument, buildVerificationDocument, clampTimeout, createApiClient, createMemoryFileSystem, createRecordingClock, describeFailure, detectProject, digestOfProjection, digestsEqual, editDistance, entryFromRow, ephemeralCredential, errorCodeOf, failureDetails, failureOutcome, fetchTransport, formatOutcome, isCorrelatableRequestId, isIdempotent, isKnownReasonCode, loadDecisionSpace, loadErrorRegistry, matchCommand, missingFactsFor, nextActionFor as nextActionForErrorCode, nextActionFor$1 as nextActionForReason, nextActionsFor, nodeFileSystem, parseCapabilities, parseDiagnostics, parseIdentityMode, parseSessionMintLanguage, parseSuppliedFacts, planIntegration, projectSandboxCreate, renderDiagnosis, renderExplanation, renderPlan, renderSandboxCreate, renderVerification, resolveContractPath, resolveCredential, resolveEndpoint, runCli, runVerification, suggestCodes, systemClock, validateContractFile, validateContractPublicEnvelope, validateDiagnosisDocument, validateErrorExplanationDocument, validatePlanDocument, validateSandboxCreateDocument, validateVerificationDocument, verifyDigest, walkSingle, walkTree, withPrefix };