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

package/control-plane/commands/errors.js

@@ -0,0 +1,130 @@
+/**
+ * Typed failure taxonomy for the shared control-plane command layer.
+ *
+ * Every transport surfaces the *same* five discriminants for the same
+ * underlying failure, so a negative RBAC or cross-tenant test written once
+ * behaves identically from the CLI, MCP, Studio, and direct JS.
+ *
+ * Like {@link ../../studio/lifecycle-errors.js | HonuaStudioError} and
+ * `HonuaCollaborationError`, this module intentionally does not join the
+ * central `HonuaSdkError` registry (`src/core/error-code-registry.ts`):
+ * `control-plane` is an `@experimental`, not-yet-semver-covered domain and a
+ * registry migration is scoped separately.
+ *
+ * @experimental
+ * @module
+ */
+import { HonuaHttpError } from "../../core/errors.js";
+const RETRYABLE_KINDS = new Set(["conflict", "transport"]);
+/**
+ * The single error type every command raises. Callers branch on `.kind`
+ * rather than on HTTP status numbers or transport-specific error classes.
+ */
+export class HonuaCommandError extends Error {
+    kind;
+    commandId;
+    correlationId;
+    idempotencyKey;
+    statusCode;
+    problem;
+    issues;
+    /** `conflict` and `transport` are worth retrying; the rest are terminal. */
+    retryable;
+    constructor(kind, commandId, message, options = {}) {
+        super(message, "cause" in options ? { cause: options.cause } : undefined);
+        this.name = "HonuaCommandError";
+        this.kind = kind;
+        this.commandId = commandId;
+        this.correlationId = options.correlationId;
+        this.idempotencyKey = options.idempotencyKey;
+        this.statusCode = options.statusCode;
+        this.problem = options.problem;
+        this.issues = options.issues;
+        this.retryable = RETRYABLE_KINDS.has(kind);
+    }
+    /** Safe JSON projection: no message, stack, cause, or response body. */
+    toJSON() {
+        return {
+            kind: "honua.command.error.v1",
+            errorKind: this.kind,
+            commandId: this.commandId,
+            retryable: this.retryable,
+            ...(this.correlationId ? { correlationId: this.correlationId } : {}),
+            ...(this.idempotencyKey ? { idempotencyKey: this.idempotencyKey } : {}),
+            ...(this.statusCode !== undefined ? { statusCode: this.statusCode } : {}),
+            ...(this.issues ? { issues: this.issues } : {}),
+        };
+    }
+}
+/** Type guard for {@link HonuaCommandError}. */
+export function isHonuaCommandError(error) {
+    return error instanceof HonuaCommandError;
+}
+/** True when the failure is an optimistic-concurrency loss worth reloading and retrying. */
+export function isHonuaCommandConflict(error) {
+    return isHonuaCommandError(error) && error.kind === "conflict";
+}
+/** Map an HTTP status code onto the command taxonomy. */
+export function classifyCommandStatus(statusCode) {
+    if (statusCode === 400 || statusCode === 422)
+        return "validation";
+    if (statusCode === 401 || statusCode === 403)
+        return "authorization";
+    if (statusCode === 409 || statusCode === 412 || statusCode === 428)
+        return "conflict";
+    return "transport";
+}
+/**
+ * Normalize anything thrown beneath a command into a {@link HonuaCommandError}.
+ *
+ * Recognizes `AbortError`/`AbortSignal.reason` (→ `cancelled`), `HonuaHttpError`
+ * and any structurally equivalent error carrying `statusCode` (→ the status
+ * classification, which also covers `HonuaStudioError`'s `409`
+ * `generation-conflict`), and falls back to `transport`.
+ */
+export function toHonuaCommandError(error, commandId, context) {
+    if (isHonuaCommandError(error))
+        return error;
+    const base = {
+        cause: error,
+        correlationId: context.correlationId,
+        idempotencyKey: context.idempotencyKey,
+    };
+    if (isAbortLike(error) || context.signal?.aborted === true) {
+        return new HonuaCommandError("cancelled", commandId, `Command ${commandId} was cancelled by the caller.`, base);
+    }
+    const statusCode = httpStatusOf(error);
+    if (statusCode !== undefined) {
+        const kind = classifyCommandStatus(statusCode);
+        return new HonuaCommandError(kind, commandId, `Command ${commandId} failed with HTTP ${statusCode}.`, {
+            ...base,
+            statusCode,
+            ...(problemOf(error) ? { problem: problemOf(error) } : {}),
+        });
+    }
+    return new HonuaCommandError("transport", commandId, `Command ${commandId} failed before a response was read.`, base);
+}
+function isAbortLike(error) {
+    if (typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError")
+        return true;
+    return error instanceof Error && error.name === "AbortError";
+}
+/**
+ * Read an HTTP status off `HonuaHttpError` or any structurally equivalent
+ * error. Studio's `HonuaStudioError` is matched structurally on purpose — it
+ * ships in a different split package, so `instanceof` is not reliable.
+ */
+function httpStatusOf(error) {
+    if (error instanceof HonuaHttpError)
+        return error.statusCode;
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const statusCode = error.statusCode;
+    return typeof statusCode === "number" && Number.isInteger(statusCode) ? statusCode : undefined;
+}
+function problemOf(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const problem = error.problem;
+    return typeof problem === "object" && problem !== null ? problem : undefined;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Deterministic identity primitives for command receipts.
+ *
+ * A receipt has to be reproducible: the same command with the same input and
+ * the same tenant must yield the same `idempotencyKey`, `correlationId`, and
+ * `auditKey` regardless of which transport issued it, which process it ran in,
+ * or when. Nothing here reads the clock, the network, or a random source.
+ *
+ * The canonical serializer mirrors `canonicalJson` in `src/offline/digest.ts`
+ * (sorted own keys, no `undefined` members); it is redeclared rather than
+ * imported so the control-plane split package does not depend on the offline
+ * module. The hash is a 128-bit FNV-1a variant: an identity key, deliberately
+ * **not** a security primitive — nothing authorizes on it.
+ *
+ * @experimental
+ * @module
+ */
+import type { HonuaCommandIdentity, HonuaCommandReceipt } from "./types.js";
+/**
+ * Serialize `value` with sorted own keys, dropping `undefined` members.
+ *
+ * Dropping (rather than throwing on) `undefined` matches how the command layer
+ * builds inputs: optional fields are routinely absent, and an absent field and
+ * an explicit `undefined` must hash the same so a CLI adapter that always sets
+ * every flag key agrees with a JS caller that omits them.
+ */
+export declare function canonicalCommandJson(value: unknown): string;
+/**
+ * 128-bit FNV-1a over UTF-16 code units, rendered as 32 lowercase hex digits.
+ *
+ * Four independently seeded 32-bit lanes. Stable across engines and platforms
+ * because it never touches `TextEncoder`, `crypto`, or locale-sensitive APIs.
+ */
+export declare function commandDigest(text: string): string;
+/**
+ * Derive the `Idempotency-Key` for a command invocation.
+ *
+ * Bound to the command id, the canonicalized input, and the tenant echo — so
+ * the *same* logical request retried from any transport collapses to one
+ * server-side effect, while the same input under a different tenant does not.
+ */
+export declare function deriveIdempotencyKey(commandId: string, input: unknown, identity: HonuaCommandIdentity): string;
+/**
+ * Derive a correlation id from the idempotency key.
+ *
+ * Deterministic on purpose: a random trace id would make receipts differ
+ * between transports and break the audit join the issue asks for. Callers that
+ * already own a trace id pass it in and this is not used.
+ */
+export declare function deriveCorrelationId(commandId: string, idempotencyKey: string): string;
+/** Normalize a claimed identity: trimmed values, sorted deduplicated scopes, no empty keys. */
+export declare function normalizeCommandIdentity(identity: HonuaCommandIdentity | undefined): HonuaCommandIdentity;
+/**
+ * The transport-independent projection of a receipt.
+ *
+ * Everything a server-side audit join needs, minus the one field that is
+ * allowed to differ between two equivalent calls (`transport`) and minus the
+ * `auditKey` itself.
+ */
+export declare function honuaCommandReceiptProjection(receipt: HonuaCommandReceipt): Record<string, unknown>;
+/**
+ * Stable join key for a receipt. Equal for equivalent CLI, MCP, Studio, and JS
+ * calls; changes whenever any recorded field of the invocation changes.
+ */
+export declare function honuaCommandAuditKey(receipt: HonuaCommandReceipt): string;
+/**
+ * Canonical, byte-stable serialization of a receipt — sorted keys, no
+ * `undefined`. Use this when persisting a receipt or comparing two of them.
+ */
+export declare function serializeHonuaCommandReceipt(receipt: HonuaCommandReceipt): string;
+//# sourceMappingURL=identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAU5E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAY3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASlD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAO9G;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAErF;AAED,+FAA+F;AAC/F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GAAG,oBAAoB,CAUzG;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGnG;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAEzE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAEjF"}

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

@@ -0,0 +1,39 @@
+/**
+ * Shared, idempotent application commands for the Honua control plane.
+ *
+ * One typed command layer behind every surface. The CLI, the MCP server,
+ * Studio, and direct JS all call {@link HonuaCommandRuntime.execute} with the
+ * same {@link HonuaCommand} objects and get back the same deterministic
+ * {@link HonuaCommandReceipt}; transports adapt input and output only.
+ *
+ * ```ts
+ * import {
+ *   createHonuaCommandRuntime,
+ *   mapPackagePublishCommand,
+ * } from "@honua/sdk-js/control-plane";
+ *
+ * const runtime = createHonuaCommandRuntime({ client });
+ * const receipt = await runtime.execute(
+ *   mapPackagePublishCommand,
+ *   { mapId: "map-ops", package: mapPackage },
+ *   { transport: "sdk", identity: { actor: "user-1", tenantId: "acme" } },
+ * );
+ * receipt.auditKey; // identical for the equivalent `honua map publish` call
+ * ```
+ *
+ * @experimental Reachable from the experimental
+ *   `@honua/sdk-js/control-plane` entrypoint; not yet covered by the SDK's
+ *   semver contract.
+ * @module
+ */
+export { HONUA_COMMANDS, HONUA_COMMAND_IDS, connectionTestCommand, importCreateCommand, isHonuaCommandId, mapPackagePublishCommand, studioDraftSaveVersionCommand, } from "./catalog.js";
+export type { ConnectionTestInput, ConnectionTestOutput, HonuaCommandId, ImportCreateInput, MapPackagePublishInput, StudioDraftSaveVersionInput, } from "./catalog.js";
+export { HonuaCommandError, classifyCommandStatus, isHonuaCommandConflict, isHonuaCommandError, toHonuaCommandError, } from "./errors.js";
+export type { HonuaCommandErrorKind, HonuaCommandErrorOptions, HonuaCommandValidationIssue, SerializedHonuaCommandError, } from "./errors.js";
+export { canonicalCommandJson, commandDigest, deriveCorrelationId, deriveIdempotencyKey, honuaCommandAuditKey, honuaCommandReceiptProjection, normalizeCommandIdentity, serializeHonuaCommandReceipt, } from "./identity.js";
+export { HONUA_COMMAND_OWNED_HEADERS, HONUA_COMMAND_RESERVED_HEADERS, HonuaCommandRuntime, assertNoAuthorityOverride, assertNoCommandKeyOverride, createHonuaCommandRuntime, } from "./runtime.js";
+export type { HonuaCommandInvocation, HonuaCommandRuntimeOptions } from "./runtime.js";
+export { HONUA_COMMAND_RECEIPT_KIND, HONUA_COMMAND_TRANSPORTS } from "./types.js";
+export type { HonuaAnyCommand, HonuaCommand, HonuaCommandContext, HonuaCommandIdentity, HonuaCommandJsonSchema, HonuaCommandMode, HonuaCommandOutcome, HonuaCommandPlan, HonuaCommandReceipt, HonuaCommandResourceRef, HonuaCommandStatus, HonuaCommandTransport, } from "./types.js";
+export { validateCommandInput } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,EAC9B,mBAAmB,EACnB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAClF,YAAY,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/control-plane/commands/index.js

@@ -0,0 +1,34 @@
+/**
+ * Shared, idempotent application commands for the Honua control plane.
+ *
+ * One typed command layer behind every surface. The CLI, the MCP server,
+ * Studio, and direct JS all call {@link HonuaCommandRuntime.execute} with the
+ * same {@link HonuaCommand} objects and get back the same deterministic
+ * {@link HonuaCommandReceipt}; transports adapt input and output only.
+ *
+ * ```ts
+ * import {
+ *   createHonuaCommandRuntime,
+ *   mapPackagePublishCommand,
+ * } from "@honua/sdk-js/control-plane";
+ *
+ * const runtime = createHonuaCommandRuntime({ client });
+ * const receipt = await runtime.execute(
+ *   mapPackagePublishCommand,
+ *   { mapId: "map-ops", package: mapPackage },
+ *   { transport: "sdk", identity: { actor: "user-1", tenantId: "acme" } },
+ * );
+ * receipt.auditKey; // identical for the equivalent `honua map publish` call
+ * ```
+ *
+ * @experimental Reachable from the experimental
+ *   `@honua/sdk-js/control-plane` entrypoint; not yet covered by the SDK's
+ *   semver contract.
+ * @module
+ */
+export { HONUA_COMMANDS, HONUA_COMMAND_IDS, connectionTestCommand, importCreateCommand, isHonuaCommandId, mapPackagePublishCommand, studioDraftSaveVersionCommand, } from "./catalog.js";
+export { HonuaCommandError, classifyCommandStatus, isHonuaCommandConflict, isHonuaCommandError, toHonuaCommandError, } from "./errors.js";
+export { canonicalCommandJson, commandDigest, deriveCorrelationId, deriveIdempotencyKey, honuaCommandAuditKey, honuaCommandReceiptProjection, normalizeCommandIdentity, serializeHonuaCommandReceipt, } from "./identity.js";
+export { HONUA_COMMAND_OWNED_HEADERS, HONUA_COMMAND_RESERVED_HEADERS, HonuaCommandRuntime, assertNoAuthorityOverride, assertNoCommandKeyOverride, createHonuaCommandRuntime, } from "./runtime.js";
+export { HONUA_COMMAND_RECEIPT_KIND, HONUA_COMMAND_TRANSPORTS } from "./types.js";
+export { validateCommandInput } from "./validate.js";

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

@@ -0,0 +1,146 @@
+/**
+ * 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 type { HonuaClient } from "../../core/client.js";
+import type { HonuaStudioLifecycleClient } from "../../studio/lifecycle-client.js";
+import { HonuaControlPlaneClient } from "../client.js";
+import { type HonuaCommand, type HonuaCommandIdentity, type HonuaCommandReceipt, type HonuaCommandTransport } from "./types.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 declare const HONUA_COMMAND_RESERVED_HEADERS: readonly ["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"];
+/**
+ * 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 declare const HONUA_COMMAND_OWNED_HEADERS: readonly ["idempotency-key", "if-match", "x-correlation-id"];
+/** Options accepted by every {@link HonuaCommandRuntime.execute} call. */
+export interface HonuaCommandInvocation {
+    /** Surface issuing the call. Recorded on the receipt; never trusted. */
+    readonly transport: HonuaCommandTransport;
+    /** Acting identity and tenant echo. Never sent as headers. */
+    readonly identity?: HonuaCommandIdentity;
+    /** Explicit `Idempotency-Key`; derived deterministically from the input when omitted. */
+    readonly idempotencyKey?: string;
+    /** Explicit server correlation id (1–64 ASCII letters, digits, `-_.:`); derived when omitted. */
+    readonly correlationId?: string;
+    /** Preview only — the runtime returns the plan and never calls `execute`. */
+    readonly dryRun?: boolean;
+    /** Optimistic-concurrency validator, sent as `If-Match`. */
+    readonly ifMatch?: string;
+    /** Cancellation. An abort surfaces as a `cancelled` {@link HonuaCommandError}. */
+    readonly signal?: AbortSignal;
+    /** Extra request headers. Reserved credential/authority headers are refused. */
+    readonly headers?: HeadersInit;
+}
+/** Constructor options for {@link createHonuaCommandRuntime}. */
+export interface HonuaCommandRuntimeOptions {
+    /**
+     * Transport client. Its credential *is* the acting identity — the runtime
+     * never adds one of its own.
+     */
+    readonly client?: HonuaClient;
+    /** Pre-built control-plane client; constructed from `client` when omitted. */
+    readonly controlPlane?: HonuaControlPlaneClient;
+    /**
+     * Studio lifecycle client. Supplied by the host because Studio ships in a
+     * different split package; `studio.*` commands fail with a `transport` error
+     * when it is absent.
+     */
+    readonly studio?: HonuaStudioLifecycleClient;
+    /** Default identity echo, overridable per invocation. */
+    readonly identity?: HonuaCommandIdentity;
+}
+/** Build a {@link HonuaCommandRuntime}. */
+export declare function createHonuaCommandRuntime(options: HonuaCommandRuntimeOptions): HonuaCommandRuntime;
+/**
+ * Executes {@link HonuaCommand}s. One instance per connection; share it across
+ * every transport a process hosts.
+ *
+ * @experimental
+ */
+export declare class HonuaCommandRuntime {
+    #private;
+    constructor(options: HonuaCommandRuntimeOptions);
+    get controlPlane(): HonuaControlPlaneClient;
+    get studio(): HonuaStudioLifecycleClient | undefined;
+    /**
+     * Validate, plan, and (unless `dryRun`) execute `command`, returning a
+     * deterministic {@link HonuaCommandReceipt}.
+     *
+     * @throws {HonuaCommandError} for every failure mode, already classified.
+     */
+    execute<TInput, TOutput>(command: HonuaCommand<TInput, TOutput>, input: TInput, invocation: HonuaCommandInvocation): Promise<HonuaCommandReceipt<TOutput>>;
+}
+/**
+ * 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 declare function assertNoAuthorityOverride(commandId: string, headers: HeadersInit | undefined, context?: {
+    readonly correlationId?: string;
+    readonly idempotencyKey?: string;
+}): void;
+/**
+ * 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 declare function assertNoCommandKeyOverride(commandId: string, headers: HeadersInit | undefined, context?: {
+    readonly correlationId?: string;
+    readonly idempotencyKey?: string;
+}): void;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAUvD,OAAO,EAGL,KAAK,YAAY,EAEjB,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EAExB,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,4WAmBjC,CAAC;AAIX;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,8DAA+D,CAAC;AAIxG,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC,yFAAyF;IACzF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iGAAiG;IACjG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,iEAAiE;AACjE,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC;IAC7C,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC1C;AAED,2CAA2C;AAC3C,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CAElG;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;;gBAKX,OAAO,EAAE,0BAA0B;IAWtD,IAAW,YAAY,IAAI,uBAAuB,CAEjD;IAED,IAAW,MAAM,IAAI,0BAA0B,GAAG,SAAS,CAE1D;IAED;;;;;OAKG;IACU,OAAO,CAAC,MAAM,EAAE,OAAO,EAClC,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;CAyGzC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,GAAE;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAClF,IAAI,CAUN;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,GAAE;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAClF,IAAI,CAgBN"}