@honua/react 0.1.7-beta.0 → 0.1.10-beta.0

package/control-plane/commands/runtime.js

@@ -0,0 +1,330 @@
+/**
+ * The one place a command actually runs.
+ *
+ * `HonuaCommandRuntime.execute` owns everything that must be identical across
+ * transports: authority-header refusal, schema validation, idempotency-key and
+ * correlation-id derivation, dry-run short-circuiting, cancellation, error
+ * normalization, and receipt assembly. A transport contributes argument
+ * parsing on the way in and rendering on the way out — nothing else.
+ *
+ * ## Security contract
+ *
+ * - **No shared administrator credential.** The runtime is built from a
+ *   {@link HonuaControlPlaneClient} (and optionally a Studio lifecycle client),
+ *   both of which carry the *caller's own* credential from the `HonuaClient`
+ *   they were constructed with. There is no admin-key path here and no
+ *   `HonuaAdminClient` dependency.
+ * - **No client-side authorization bypass.** Caller-supplied per-call headers
+ *   are screened against {@link HONUA_COMMAND_RESERVED_HEADERS}; any attempt to
+ *   set a credential, actor, tenant, policy, or approver header fails with an
+ *   `authorization` {@link HonuaCommandError} *before* the command runs, on
+ *   every transport. The claimed {@link HonuaCommandIdentity} is echoed onto
+ *   the receipt and never placed on the wire.
+ * - **No caller-owned request identity.** The same screen refuses
+ *   {@link HONUA_COMMAND_OWNED_HEADERS} — the `Idempotency-Key`, `If-Match`, and `X-Correlation-ID`
+ *   the runtime derives and records on the receipt. Both screens compare
+ *   header names case-insensitively, so `Idempotency-Key`, `idempotency-key`,
+ *   and `IDEMPOTENCY-KEY` are the same header to them. Without this a caller
+ *   could put one key on the wire while the receipt and the invocation record
+ *   claimed another, breaking retry collapsing and the audit join.
+ * - **No self-approval.** Command input schemas are closed, so no transport can
+ *   introduce an approval field the others lack; every receipt records
+ *   `authorization: "server-enforced"`.
+ * - **No credential in the receipt's rendered fields.** A receipt is built to be
+ *   persisted and printed, so the plan's human-readable `summary` goes through
+ *   the SDK's one credential recognizer before it is recorded — an import's
+ *   presigned `sourceUrl` must not outlive its request in an audit log.
+ *
+ * @experimental
+ * @module
+ */
+import { redactHonuaExportText } from "../../core/credential-redaction.js";
+import { HonuaControlPlaneClient } from "../client.js";
+import { HonuaCommandError, toHonuaCommandError } from "./errors.js";
+import { canonicalCommandJson, commandDigest, deriveCorrelationId, deriveIdempotencyKey, normalizeCommandIdentity, } from "./identity.js";
+import { HONUA_COMMAND_RECEIPT_KIND, HONUA_COMMAND_TRANSPORTS, } from "./types.js";
+import { validateCommandInput } from "./validate.js";
+/**
+ * Headers a caller may never set on a command invocation.
+ *
+ * Two families: credential headers (which would let a transport swap in a
+ * different — possibly shared administrator — identity) and authority headers
+ * (which would let a transport assert an actor, tenant, policy decision, or
+ * approval the server did not derive itself). Compared case-insensitively.
+ */
+export const HONUA_COMMAND_RESERVED_HEADERS = [
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "x-api-key",
+    "x-honua-api-key",
+    "x-honua-admin-key",
+    "x-honua-actor",
+    "x-honua-act-as",
+    "x-honua-impersonate",
+    "x-honua-tenant",
+    "x-honua-tenant-id",
+    "x-honua-scope",
+    "x-honua-scopes",
+    "x-honua-policy-decision",
+    "x-honua-approver",
+    "x-honua-approved-by",
+    "x-forwarded-user",
+    "x-forwarded-access-token",
+];
+const RESERVED_HEADER_SET = new Set(HONUA_COMMAND_RESERVED_HEADERS);
+/**
+ * Headers the runtime derives and records on the receipt.
+ *
+ * A caller-supplied value would put a different key on the wire
+ * than the receipt claims, which breaks exactly the two guarantees the receipt
+ * exists to provide: that a retry collapses to one server-side effect, and that
+ * an audit join can match a receipt to the request it describes. Callers set
+ * these through {@link HonuaCommandInvocation.idempotencyKey},
+ * {@link HonuaCommandInvocation.ifMatch}, and {@link HonuaCommandInvocation.correlationId}, which are recorded.
+ */
+export const HONUA_COMMAND_OWNED_HEADERS = ["idempotency-key", "if-match", "x-correlation-id"];
+const OWNED_HEADER_SET = new Set(HONUA_COMMAND_OWNED_HEADERS);
+/** Build a {@link HonuaCommandRuntime}. */
+export function createHonuaCommandRuntime(options) {
+    return new HonuaCommandRuntime(options);
+}
+/**
+ * Executes {@link HonuaCommand}s. One instance per connection; share it across
+ * every transport a process hosts.
+ *
+ * @experimental
+ */
+export class HonuaCommandRuntime {
+    #controlPlane;
+    #studio;
+    #identity;
+    constructor(options) {
+        const controlPlane = options.controlPlane ?? (options.client ? new HonuaControlPlaneClient({ client: options.client }) : undefined);
+        if (!controlPlane) {
+            throw new TypeError("createHonuaCommandRuntime requires either a `client` or a prebuilt `controlPlane`.");
+        }
+        this.#controlPlane = controlPlane;
+        this.#studio = options.studio;
+        this.#identity = normalizeCommandIdentity(options.identity);
+    }
+    get controlPlane() {
+        return this.#controlPlane;
+    }
+    get studio() {
+        return this.#studio;
+    }
+    /**
+     * Validate, plan, and (unless `dryRun`) execute `command`, returning a
+     * deterministic {@link HonuaCommandReceipt}.
+     *
+     * @throws {HonuaCommandError} for every failure mode, already classified.
+     */
+    async execute(command, input, invocation) {
+        const transport = assertTransport(command.id, invocation.transport);
+        const identity = normalizeCommandIdentity({ ...this.#identity, ...invocation.identity });
+        const idempotencyKey = invocation.idempotencyKey?.trim() || deriveIdempotencyKey(command.id, input, identity);
+        const correlationId = invocation.correlationId?.trim() || deriveCorrelationId(command.id, idempotencyKey);
+        const failureContext = { correlationId, idempotencyKey, signal: invocation.signal };
+        assertNoAuthorityOverride(command.id, invocation.headers, { correlationId, idempotencyKey });
+        assertNoCommandKeyOverride(command.id, invocation.headers, { correlationId, idempotencyKey });
+        // Match the server's CorrelationIdMiddleware contract. An unsupported id
+        // would be silently replaced there, leaving the receipt unable to join it.
+        if (!/^[A-Za-z0-9_.:-]{1,64}$/.test(correlationId)) {
+            throw new HonuaCommandError("validation", command.id, "Command correlationId must contain 1–64 ASCII letters, digits, hyphens, underscores, dots, or colons.", {
+                ...failureContext,
+                issues: [{ path: "correlationId", message: "must match the server correlation-id format" }],
+            });
+        }
+        // Schema first, then the command's own cross-field rules. Both run before
+        // `plan`, so the dry-run preview below is reachable only for input the real
+        // invocation would also accept.
+        const issues = [...validateCommandInput(command.inputSchema, input), ...(command.validate?.(input) ?? [])];
+        if (issues.length > 0) {
+            throw new HonuaCommandError("validation", command.id, `Command ${command.id} received invalid input: ${issues.map((issue) => `${issue.path || "(root)"} ${issue.message}`).join("; ")}.`, { ...failureContext, issues });
+        }
+        if (invocation.signal?.aborted) {
+            throw new HonuaCommandError("cancelled", command.id, `Command ${command.id} was cancelled before it started.`, {
+                ...failureContext,
+                cause: invocation.signal.reason,
+            });
+        }
+        const context = {
+            input,
+            controlPlane: this.#controlPlane,
+            ...(this.#studio ? { studio: this.#studio } : {}),
+            identity,
+            transport,
+            idempotencyKey,
+            correlationId,
+            dryRun: invocation.dryRun === true,
+            ...(invocation.signal ? { signal: invocation.signal } : {}),
+            requestOptions: (overrides = {}) => {
+                const headers = new Headers(overrides.headers ?? invocation.headers);
+                headers.set("X-Correlation-ID", correlationId);
+                return {
+                    ...(invocation.signal ? { signal: invocation.signal } : {}),
+                    ...(command.mode === "action" ? { idempotencyKey } : {}),
+                    ...(invocation.ifMatch ? { ifMatch: invocation.ifMatch } : {}),
+                    ...overrides,
+                    headers,
+                };
+            },
+        };
+        let plan;
+        try {
+            plan = withoutResourceLink(command.plan(context));
+        }
+        catch (error) {
+            throw toHonuaCommandError(error, command.id, failureContext);
+        }
+        if (context.dryRun) {
+            return buildReceipt({
+                command,
+                status: "dry-run",
+                idempotencyKey,
+                correlationId,
+                identity,
+                transport,
+                plan,
+                ...(plan.resourceRef ? { resourceRef: plan.resourceRef } : {}),
+            });
+        }
+        try {
+            const outcome = await command.execute(context);
+            return buildReceipt({
+                command,
+                status: outcome.status ?? "ok",
+                idempotencyKey,
+                correlationId,
+                identity,
+                transport,
+                plan,
+                ...((outcome.resourceRef ?? plan.resourceRef) ? { resourceRef: outcome.resourceRef ?? plan.resourceRef } : {}),
+                ...(outcome.validators ? { validators: outcome.validators } : {}),
+                ...(outcome.problem ? { problem: outcome.problem } : {}),
+                output: outcome.output,
+            });
+        }
+        catch (error) {
+            throw toHonuaCommandError(error, command.id, failureContext);
+        }
+    }
+}
+/**
+ * Refuse a caller-supplied credential or authority header.
+ *
+ * Exported so a transport can screen its own header pass-through before it
+ * builds an invocation, but the runtime applies it unconditionally — a
+ * transport that forgets cannot weaken the guarantee.
+ */
+export function assertNoAuthorityOverride(commandId, headers, context = {}) {
+    const offending = headerNames(headers).filter((name) => RESERVED_HEADER_SET.has(name));
+    if (offending.length === 0)
+        return;
+    const named = offending.sort().join(", ");
+    throw new HonuaCommandError("authorization", commandId, `Command ${commandId} refused caller-supplied authority header(s): ${named}. Authorization is derived server-side from the connection credential; no transport may assert it.`, context);
+}
+/**
+ * Refuse a caller-supplied value for a header the runtime derives.
+ *
+ * Classified `validation` rather than `authorization`: this is caller misuse of
+ * the invocation contract, not an attempt to assert authority. Use
+ * {@link HonuaCommandInvocation.idempotencyKey} / `.ifMatch` instead, so the
+ * value that travels is the value the receipt records.
+ */
+export function assertNoCommandKeyOverride(commandId, headers, context = {}) {
+    const offending = headerNames(headers).filter((name) => OWNED_HEADER_SET.has(name));
+    if (offending.length === 0)
+        return;
+    const named = offending.sort().join(", ");
+    throw new HonuaCommandError("validation", commandId, `Command ${commandId} refused caller-supplied header(s) it derives itself: ${named}. Set them through the invocation's \`idempotencyKey\` / \`ifMatch\` / \`correlationId\` so the value on the wire is the value the receipt records.`, {
+        ...context,
+        issues: offending.sort().map((name) => ({
+            path: `headers.${name}`,
+            message: "is derived by the command runtime and cannot be set by a caller",
+        })),
+    });
+}
+/**
+ * Strip the resource link from a plan.
+ *
+ * A plan describes a request that has *not been issued* — and on a dry run it
+ * is the whole receipt, because `execute` is never reached. A link on it would
+ * therefore be a URL for a resource that may not exist, printed by the CLI and
+ * Studio next to the word "dry run", which is precisely honua-sdk-js#1426's
+ * "preview is never reported as persisted or published" failing. `plan` is
+ * already documented to carry no request body for a related reason; carrying no
+ * resource link is the same rule applied to the response side.
+ *
+ * The executed path is unaffected: a real invocation reports the `href` the
+ * *server* returned, on `HonuaCommandOutcome.resourceRef`. What a command can
+ * no longer do is predict one.
+ */
+function withoutResourceLink(plan) {
+    const ref = plan.resourceRef;
+    if (!ref || ref.href === undefined)
+        return plan;
+    const { href: _href, ...rest } = ref;
+    return { ...plan, resourceRef: rest };
+}
+function headerNames(headers) {
+    if (!headers)
+        return [];
+    if (headers instanceof Headers)
+        return [...headers.keys()].map((name) => name.toLowerCase());
+    if (Array.isArray(headers))
+        return headers.map(([name]) => String(name).toLowerCase());
+    return Object.keys(headers).map((name) => name.toLowerCase());
+}
+function assertTransport(commandId, transport) {
+    if (HONUA_COMMAND_TRANSPORTS.includes(transport))
+        return transport;
+    throw new HonuaCommandError("validation", commandId, `Unknown command transport "${String(transport)}"; expected one of ${HONUA_COMMAND_TRANSPORTS.join(", ")}.`);
+}
+/**
+ * Withhold credential material from the plan's human-readable summary.
+ *
+ * {@link HonuaCommandPlan} promises it "carries no request body: command inputs
+ * can contain connection credentials, and a plan is rendered to terminals and
+ * logs". Omitting the body is not on its own enough: a command builds its
+ * `summary` from its own input, and an import's `sourceUrl` is routinely a
+ * presigned URL whose query string *is* the credential. Interpolated into a
+ * receipt — which `serializeHonuaCommandReceipt` exists to persist, and which
+ * `honua map publish --json` prints verbatim — that URL outlives the request it
+ * authorized, in a log the caller believes is safe to keep.
+ *
+ * So the summary goes through the SDK's one credential recognizer
+ * (`src/core/credential-redaction.ts`) on the way onto the receipt. The
+ * substitution is deterministic, so two equivalent calls still agree on
+ * `auditKey`. `path` is deliberately left alone: it is documented as the
+ * request exactly as issued, is built only from percent-encoded resource ids,
+ * and redacting an id would misreport the request. `output` is left alone too
+ * — it is the command's return value, not a rendered preview.
+ */
+function redactPlanSummary(plan) {
+    const summary = redactHonuaExportText(plan.summary);
+    return summary === plan.summary ? plan : { ...plan, summary };
+}
+function buildReceipt(parts) {
+    const projection = {
+        kind: HONUA_COMMAND_RECEIPT_KIND,
+        commandId: parts.command.id,
+        mode: parts.command.mode,
+        status: parts.status,
+        ...(parts.command.mode === "action" ? { idempotencyKey: parts.idempotencyKey } : {}),
+        correlationId: parts.correlationId,
+        identity: parts.identity,
+        authorization: "server-enforced",
+        plan: redactPlanSummary(parts.plan),
+        ...(parts.resourceRef ? { resourceRef: parts.resourceRef } : {}),
+        ...(parts.validators ? { validators: parts.validators } : {}),
+        ...(parts.problem ? { problem: parts.problem } : {}),
+        ...(parts.output !== undefined ? { output: parts.output } : {}),
+    };
+    return {
+        ...projection,
+        transport: parts.transport,
+        auditKey: commandDigest(canonicalCommandJson(projection)),
+    };
+}

package/control-plane/commands/types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Shared application-command contract for the Honua control plane.
+ *
+ * Every surface — the `honua` CLI, the MCP server, Studio, and direct JS —
+ * invokes the *same* {@link HonuaCommand} objects. A transport adapts input
+ * and output only: it parses its own argument shape into the command's
+ * declared JSON-schema input, hands the result to
+ * `HonuaCommandRuntime.execute`, and renders the returned
+ * {@link HonuaCommandReceipt}. Domain sequencing (read-modify-write,
+ * optimistic-concurrency checks, job hand-off) and the dry-run projection live
+ * on the command, never on the transport.
+ *
+ * Authorization is deliberately **not** modelled here beyond an echo. The
+ * command layer carries no administrator credential of its own, refuses
+ * caller-supplied authority headers and the request-identity headers it derives
+ * itself (see `assertNoAuthorityOverride` and `assertNoCommandKeyOverride` in
+ * `./runtime.js`), and stamps every receipt `authorization:
+ * "server-enforced"`. A client cannot approve its own publication by choosing
+ * a different transport because no transport can express approval at all —
+ * the shared command inputs have no approval field and every command input
+ * schema is closed (`additionalProperties: false`).
+ *
+ * @experimental Part of the `@honua/sdk-js/control-plane` experimental
+ *   entrypoint; not yet covered by the SDK's semver contract.
+ * @module
+ */
+import type { QueryMethod } from "../../core/types.js";
+import type { HonuaStudioLifecycleClient } from "../../studio/lifecycle-client.js";
+import type { HonuaControlPlaneClient } from "../client.js";
+import type { HonuaControlPlaneRequestOptions, HonuaEntityValidators, HonuaProblemDetails } from "../types.js";
+import type { HonuaCommandValidationIssue } from "./errors.js";
+/**
+ * JSON-Schema subset used to describe a command's input.
+ *
+ * Structurally the same dialect `HonuaAgentToolDefinition.inputSchema` uses
+ * (`src/agent-tools/index.ts`) so MCP tool schemas, CLI help, and Studio forms
+ * can all project from one description. It is redeclared here rather than
+ * imported so the control-plane split package does not pull in the agent-tool
+ * runtime. `src/` is deliberately zod-free.
+ */
+export interface HonuaCommandJsonSchema {
+    readonly type?: string | readonly string[];
+    readonly description?: string;
+    readonly enum?: readonly unknown[];
+    readonly format?: string;
+    readonly properties?: Readonly<Record<string, HonuaCommandJsonSchema>>;
+    readonly items?: HonuaCommandJsonSchema;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | HonuaCommandJsonSchema;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly default?: unknown;
+}
+/**
+ * `read` commands never mutate and never carry an idempotency key on the
+ * wire; `action` commands do both. Mirrors `HonuaAgentToolMode`.
+ */
+export type HonuaCommandMode = "read" | "action";
+/**
+ * Terminal state recorded on a {@link HonuaCommandReceipt}. Mirrors
+ * `HonuaAgentToolStatus` and adds `cancelled` for `AbortSignal` aborts.
+ */
+export type HonuaCommandStatus = "ok" | "dry-run" | "denied" | "cancelled" | "error";
+/** Surfaces that may invoke a command. Recorded, never trusted. */
+export declare const HONUA_COMMAND_TRANSPORTS: readonly ["cli", "mcp", "studio", "sdk"];
+/** One of {@link HONUA_COMMAND_TRANSPORTS}. */
+export type HonuaCommandTransport = (typeof HONUA_COMMAND_TRANSPORTS)[number];
+/**
+ * Acting identity and tenant, as the *caller claims them*.
+ *
+ * These values are echoed onto the receipt so a downstream audit join can line
+ * a receipt up with the server-side record. They are never sent as request
+ * headers and never used to make a local authorization decision — the server
+ * derives the real acting identity from the credential on the
+ * {@link HonuaControlPlaneClient}'s underlying `HonuaClient`.
+ */
+export interface HonuaCommandIdentity {
+    /** Acting principal id as claimed by the caller. */
+    readonly actor?: string;
+    /** Tenant / workspace-owner echo. */
+    readonly tenantId?: string;
+    /** OAuth scope ceiling the caller believes it holds, sorted for determinism. */
+    readonly scopes?: readonly string[];
+}
+/** Stable pointer to the resource a command read or affected. */
+export interface HonuaCommandResourceRef {
+    /** Resource kind, e.g. `map-package`, `import-job`, `connection`. */
+    readonly type: string;
+    /** Server-assigned identifier, when the server returned one. */
+    readonly id?: string;
+    /** Owning workspace, when scoped. */
+    readonly workspaceId?: string;
+    /** Absolute or root-relative link the server returned for the resource. */
+    readonly href?: string;
+}
+/**
+ * The request a command *would* issue. Produced by {@link HonuaCommand.plan},
+ * recorded on every receipt, and the only thing a dry run evaluates — a dry
+ * run never reaches {@link HonuaCommand.execute}, so no transport can
+ * accidentally execute while previewing.
+ *
+ * Deliberately carries no request body: command inputs can contain connection
+ * credentials, and a plan is rendered to terminals and logs.
+ *
+ * It also carries no **resource link**. `resourceRef.href` is dropped by the
+ * runtime before the plan reaches a receipt, so a dry run — which is nothing
+ * but this plan — cannot print a URL for a resource that was never created or
+ * published (honua-sdk-js#1426). A link appears on a receipt only when the
+ * *server* returned one to {@link HonuaCommand.execute}.
+ */
+export interface HonuaCommandPlan {
+    readonly method: QueryMethod;
+    /** Path relative to the client's base path, exactly as the command will call it. */
+    readonly path: string;
+    /**
+     * One-line human summary for CLI/Studio previews.
+     *
+     * A command builds this from its own input, so it can name a source URL. The
+     * runtime passes it through the SDK's credential recognizer before it reaches
+     * a receipt, so a presigned URL or an embedded secret is withheld rather than
+     * persisted into an audit record. Commands should still prefer identifiers to
+     * URLs here.
+     */
+    readonly summary: string;
+    /** Resource this request addresses. Any `href` is stripped by the runtime. */
+    readonly resourceRef?: HonuaCommandResourceRef;
+}
+/** What {@link HonuaCommand.execute} returns to the runtime. */
+export interface HonuaCommandOutcome<TOutput> {
+    readonly output: TOutput;
+    /** Overrides `ok`; use `denied` when the server durably recorded a refusal. */
+    readonly status?: Extract<HonuaCommandStatus, "ok" | "denied">;
+    readonly resourceRef?: HonuaCommandResourceRef;
+    readonly validators?: HonuaEntityValidators;
+    readonly problem?: HonuaProblemDetails;
+}
+/** Discriminating tag on {@link HonuaCommandReceipt}. */
+export declare const HONUA_COMMAND_RECEIPT_KIND: "honua.command.receipt.v1";
+/**
+ * Deterministic, serializable record of one command invocation.
+ *
+ * Two equivalent calls made from different transports produce identical
+ * receipts apart from {@link HonuaCommandReceipt.transport}; `auditKey` hashes
+ * the transport-independent projection so a server-side audit join can match
+ * them. Nothing here is time-, host-, or random-dependent: `idempotencyKey`
+ * and `correlationId` are derived from the command id, the canonicalized
+ * input, and the tenant unless the caller supplies them. Read commands omit
+ * `idempotencyKey` because no such key is sent to the server.
+ */
+export interface HonuaCommandReceipt<TOutput = unknown> {
+    readonly kind: typeof HONUA_COMMAND_RECEIPT_KIND;
+    readonly commandId: string;
+    readonly mode: HonuaCommandMode;
+    readonly status: HonuaCommandStatus;
+    readonly idempotencyKey?: string;
+    /** Sent as `X-Correlation-ID` on every request belonging to this command. */
+    readonly correlationId: string;
+    readonly identity: HonuaCommandIdentity;
+    /** Surface that issued the call. Recorded for audit; excluded from `auditKey`. */
+    readonly transport: HonuaCommandTransport;
+    /** Always `server-enforced`: the command layer makes no authorization decision. */
+    readonly authorization: "server-enforced";
+    readonly plan: HonuaCommandPlan;
+    readonly resourceRef?: HonuaCommandResourceRef;
+    readonly validators?: HonuaEntityValidators;
+    readonly problem?: HonuaProblemDetails;
+    readonly output?: TOutput;
+    /** Hash of the transport-independent projection. Equal across transports. */
+    readonly auditKey: string;
+}
+/** Per-invocation context handed to {@link HonuaCommand.plan} and `execute`. */
+export interface HonuaCommandContext<TInput> {
+    /** Input after schema validation. */
+    readonly input: TInput;
+    readonly controlPlane: HonuaControlPlaneClient;
+    /**
+     * Studio lifecycle client, present only when the host supplied one. Commands
+     * in the `studio.*` namespace throw a `transport` `HonuaCommandError` when it
+     * is absent rather than reaching for a second credential.
+     */
+    readonly studio?: HonuaStudioLifecycleClient;
+    readonly identity: HonuaCommandIdentity;
+    readonly transport: HonuaCommandTransport;
+    readonly idempotencyKey: string;
+    readonly correlationId: string;
+    readonly dryRun: boolean;
+    readonly signal?: AbortSignal;
+    /**
+     * Request options for the underlying resource client, with `Idempotency-Key`
+     * (action commands only), `If-Match`, the caller's `AbortSignal`, and the
+     * caller's remaining headers already threaded. The headers that reach here
+     * can carry neither an authority claim nor a command-owned key: both
+     * families are refused before `plan` runs.
+     */
+    requestOptions(overrides?: HonuaControlPlaneRequestOptions): HonuaControlPlaneRequestOptions;
+}
+/**
+ * One idempotent application command, shared verbatim by every transport.
+ *
+ * @typeParam TInput - Validated input shape, described by `inputSchema`.
+ * @typeParam TOutput - Value carried on the receipt's `output`.
+ */
+export interface HonuaCommand<TInput, TOutput> {
+    /** Stable dotted id, e.g. `map-package.publish`. */
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly mode: HonuaCommandMode;
+    /** Resource kind this command addresses; used for the receipt's `resourceRef`. */
+    readonly resourceKind: string;
+    readonly inputSchema: HonuaCommandJsonSchema;
+    /**
+     * Cross-field checks the JSON schema cannot express ("one of these two is
+     * required"). Called by the runtime after schema validation and **before**
+     * `plan`, so a dry run can never approve an input the real invocation would
+     * reject. Must be pure. Return an empty array when the input is valid.
+     */
+    validate?(input: TInput): readonly HonuaCommandValidationIssue[];
+    /** Describe the request without issuing it. Must be pure and side-effect free. */
+    plan(context: HonuaCommandContext<TInput>): HonuaCommandPlan;
+    /** Issue the request. Never called during a dry run. */
+    execute(context: HonuaCommandContext<TInput>): Promise<HonuaCommandOutcome<TOutput>>;
+}
+/** Any command, for registries and transport dispatch tables. */
+export type HonuaAnyCommand = HonuaCommand<any, any>;
+//# sourceMappingURL=types.d.ts.map

package/control-plane/commands/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/types.ts"],"names":[],"mappings":"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"}

package/control-plane/commands/types.js

@@ -0,0 +1,30 @@
+/**
+ * Shared application-command contract for the Honua control plane.
+ *
+ * Every surface — the `honua` CLI, the MCP server, Studio, and direct JS —
+ * invokes the *same* {@link HonuaCommand} objects. A transport adapts input
+ * and output only: it parses its own argument shape into the command's
+ * declared JSON-schema input, hands the result to
+ * `HonuaCommandRuntime.execute`, and renders the returned
+ * {@link HonuaCommandReceipt}. Domain sequencing (read-modify-write,
+ * optimistic-concurrency checks, job hand-off) and the dry-run projection live
+ * on the command, never on the transport.
+ *
+ * Authorization is deliberately **not** modelled here beyond an echo. The
+ * command layer carries no administrator credential of its own, refuses
+ * caller-supplied authority headers and the request-identity headers it derives
+ * itself (see `assertNoAuthorityOverride` and `assertNoCommandKeyOverride` in
+ * `./runtime.js`), and stamps every receipt `authorization:
+ * "server-enforced"`. A client cannot approve its own publication by choosing
+ * a different transport because no transport can express approval at all —
+ * the shared command inputs have no approval field and every command input
+ * schema is closed (`additionalProperties: false`).
+ *
+ * @experimental Part of the `@honua/sdk-js/control-plane` experimental
+ *   entrypoint; not yet covered by the SDK's semver contract.
+ * @module
+ */
+/** Surfaces that may invoke a command. Recorded, never trusted. */
+export const HONUA_COMMAND_TRANSPORTS = ["cli", "mcp", "studio", "sdk"];
+/** Discriminating tag on {@link HonuaCommandReceipt}. */
+export const HONUA_COMMAND_RECEIPT_KIND = "honua.command.receipt.v1";

package/control-plane/commands/validate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Structural validation for command inputs.
+ *
+ * Commands describe their input with the JSON-Schema subset in `./types.js`,
+ * the same dialect `src/agent-tools/index.ts` uses for agent tool definitions.
+ * That one description drives CLI argument checking, MCP tool schemas, Studio
+ * forms, and this validator — so an input rejected by one transport is
+ * rejected identically by all of them.
+ *
+ * The validator covers exactly the keywords the dialect declares. It is not a
+ * general JSON-Schema implementation and deliberately adds no dependency;
+ * `src/` is zod-free.
+ *
+ * @experimental
+ * @module
+ */
+import type { HonuaCommandValidationIssue } from "./errors.js";
+import type { HonuaCommandJsonSchema } from "./types.js";
+/**
+ * Validate `value` against `schema`, returning every finding.
+ *
+ * `additionalProperties: false` is the load-bearing rule for the security
+ * contract: a closed input schema is why no transport can smuggle an approval
+ * or authority field into a shared command.
+ */
+export declare function validateCommandInput(schema: HonuaCommandJsonSchema, value: unknown): HonuaCommandValidationIssue[];
+//# sourceMappingURL=validate.d.ts.map

package/control-plane/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,OAAO,GAAG,2BAA2B,EAAE,CAIlH"}