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

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

@@ -0,0 +1,133 @@
+/**
+ * The 2026.1 command catalog: real commands over the existing control-plane and
+ * Studio resource clients.
+ *
+ * These four cover one end-to-end slice of the terminal release journey —
+ * probe a connection, start an import, publish a map package, and save a Studio
+ * draft as an immutable version — and exercise every capability the shared
+ * layer promises: idempotency, dry run, cancellation, validation, typed errors,
+ * and deterministic receipts. Each command owns its own sequencing, which is
+ * why `studio.draft.saveVersion` performs the optimistic-generation check here
+ * rather than in four transports.
+ *
+ * ## Where the concurrency check is bracketed, not atomic
+ *
+ * `studio.draft.saveVersion` cannot make its generation check atomic with the
+ * write, because the Studio lifecycle API offers nothing to make it atomic
+ * with: `POST /package-drafts/{draftId}/content-versions` takes no request body
+ * (`HonuaStudioDraftsClient.createContentVersion`, and the pinned contract
+ * fixture `test/fixtures/studio-lifecycle/content-version-create.v1.json`) and
+ * `HonuaStudioRequestOptions` has no `ifMatch` — unlike its control-plane
+ * sibling `HonuaControlPlaneRequestOptions`. The one optimistic-concurrency
+ * primitive in the surface is the `generation` field on the
+ * `PUT /package-drafts/{draftId}` *body* (`StudioPackageDraftReplaceRequest`),
+ * which this route has no analogue for.
+ *
+ * So the command brackets the write instead of pretending the check was
+ * atomic: it reads the generation before, re-reads it after, and raises a
+ * `conflict` naming the version it created if the draft moved at any point.
+ * `generation` is documented to increment on every successful `PUT`
+ * (`StudioPackageDraft`), so no concurrent edit can slip through the bracket
+ * unseen. When honua-server grows a real precondition on this route, the
+ * bracket collapses into it and the second read goes away.
+ *
+ * @experimental
+ * @module
+ */
+import type { HonuaMapPackage } from "../../runtime/index.js";
+import type { StudioContentVersion } from "../../studio/lifecycle-types.js";
+import type { HonuaControlPlaneJob, HonuaPublishMapPackageResponse } from "../types.js";
+import type { HonuaCommand } from "./types.js";
+/** Input for {@link connectionTestCommand}. */
+export interface ConnectionTestInput {
+    /** Existing connection to probe. */
+    readonly connectionId: string;
+}
+/** Server probe result. Left open: the probe payload is deployment-specific. */
+export interface ConnectionTestOutput {
+    readonly ok?: boolean;
+    readonly status?: string;
+    readonly detail?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * `POST /connections/{connectionId}/test` — probe a stored connection.
+ *
+ * The server does not consume an idempotency key or a workspace body. Keep the
+ * command identity limited to the connection route so receipts describe the
+ * request the server actually processed.
+ */
+export declare const connectionTestCommand: HonuaCommand<ConnectionTestInput, ConnectionTestOutput>;
+/**
+ * Input for {@link importCreateCommand}.
+ *
+ * The server's own `dryRun` request field is deliberately not exposed: dry run
+ * is a command-layer concept here, and two spellings of it would let one
+ * transport preview while another executed. The current file-import endpoint
+ * accepts public source URLs only; stored-connection imports have no matching
+ * server route yet and are rejected before a request is issued.
+ */
+export interface ImportCreateInput {
+    readonly sourceKind: string;
+    readonly sourceUrl?: string;
+    readonly connectionId?: string;
+    readonly workspaceId?: string;
+    readonly title?: string;
+    readonly options?: Record<string, unknown>;
+}
+/** `POST /import/upload-url` — enqueue a URL import job. */
+export declare const importCreateCommand: HonuaCommand<ImportCreateInput, HonuaControlPlaneJob>;
+/**
+ * Input for {@link mapPackagePublishCommand}.
+ *
+ * There is no approval field, and the schema is closed: publication approval is
+ * a server decision, and no transport may express one. The optimistic-
+ * concurrency validator travels on `HonuaCommandInvocation.ifMatch`, not in the
+ * input, so it can never become part of the idempotency identity.
+ */
+export interface MapPackagePublishInput {
+    /** Hosted map the package belongs to. */
+    readonly mapId?: string;
+    readonly workspaceId?: string;
+    /** The `honua_map_package.v1` document to publish. */
+    readonly package: HonuaMapPackage;
+    /** Publication message recorded with the version. */
+    readonly message?: string;
+}
+/** `POST /packages` — publish a map package version. */
+export declare const mapPackagePublishCommand: HonuaCommand<MapPackagePublishInput, HonuaPublishMapPackageResponse>;
+/** Input for {@link studioDraftSaveVersionCommand}. */
+export interface StudioDraftSaveVersionInput {
+    readonly draftId: string;
+    /**
+     * Last-seen draft `generation`. When supplied, the command brackets the write
+     * with a generation read on each side and fails with a `conflict` error if
+     * the draft moved — the optimistic-concurrency sequencing every transport
+     * would otherwise reimplement.
+     *
+     * The check is *detected*, not *enforced*: the route accepts no precondition,
+     * so a concurrent edit surfaces as a loud conflict naming the version that
+     * was created rather than as a rejected write. See this module's
+     * "Where the concurrency check is bracketed, not atomic".
+     */
+    readonly generation?: number;
+}
+/** `POST /package-drafts/{draftId}/content-versions` — save a draft as an immutable version. */
+export declare const studioDraftSaveVersionCommand: HonuaCommand<StudioDraftSaveVersionInput, StudioContentVersion>;
+/** Every command id in the 2026.1 catalog, in registry order. */
+export declare const HONUA_COMMAND_IDS: readonly ["connection.test", "import.create", "map-package.publish", "studio.draft.saveVersion"];
+/** One of {@link HONUA_COMMAND_IDS}. */
+export type HonuaCommandId = (typeof HONUA_COMMAND_IDS)[number];
+/**
+ * The shared registry every transport dispatches through. MCP tool schemas,
+ * CLI help, Studio clients, and JS methods all project from these entries.
+ */
+export declare const HONUA_COMMANDS: {
+    readonly "connection.test": HonuaCommand<ConnectionTestInput, ConnectionTestOutput>;
+    readonly "import.create": HonuaCommand<ImportCreateInput, HonuaControlPlaneJob>;
+    readonly "map-package.publish": HonuaCommand<MapPackagePublishInput, HonuaPublishMapPackageResponse>;
+    readonly "studio.draft.saveVersion": HonuaCommand<StudioDraftSaveVersionInput, StudioContentVersion>;
+};
+/** Type guard narrowing an arbitrary string to a registered command id. */
+export declare function isHonuaCommandId(value: string): value is HonuaCommandId;
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EACV,oBAAoB,EAGpB,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAmB,YAAY,EAA2B,MAAM,YAAY,CAAC;AAMzF,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAAY,CAAC,mBAAmB,EAAE,oBAAoB,CAuCzF,CAAC;AAiBF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,iBAAiB,EAAE,oBAAoB,CAqFrF,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,EAAE,YAAY,CAAC,sBAAsB,EAAE,8BAA8B,CAwDzG,CAAC;AAMF,uDAAuD;AACvD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gGAAgG;AAChG,eAAO,MAAM,6BAA6B,EAAE,YAAY,CAAC,2BAA2B,EAAE,oBAAoB,CA0FzG,CAAC;AAMF,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,kGAKpB,CAAC;AAEX,wCAAwC;AACxC,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKiC,CAAC;AAE7D,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEvE"}

package/control-plane/commands/catalog.js

@@ -0,0 +1,365 @@
+/**
+ * The 2026.1 command catalog: real commands over the existing control-plane and
+ * Studio resource clients.
+ *
+ * These four cover one end-to-end slice of the terminal release journey —
+ * probe a connection, start an import, publish a map package, and save a Studio
+ * draft as an immutable version — and exercise every capability the shared
+ * layer promises: idempotency, dry run, cancellation, validation, typed errors,
+ * and deterministic receipts. Each command owns its own sequencing, which is
+ * why `studio.draft.saveVersion` performs the optimistic-generation check here
+ * rather than in four transports.
+ *
+ * ## Where the concurrency check is bracketed, not atomic
+ *
+ * `studio.draft.saveVersion` cannot make its generation check atomic with the
+ * write, because the Studio lifecycle API offers nothing to make it atomic
+ * with: `POST /package-drafts/{draftId}/content-versions` takes no request body
+ * (`HonuaStudioDraftsClient.createContentVersion`, and the pinned contract
+ * fixture `test/fixtures/studio-lifecycle/content-version-create.v1.json`) and
+ * `HonuaStudioRequestOptions` has no `ifMatch` — unlike its control-plane
+ * sibling `HonuaControlPlaneRequestOptions`. The one optimistic-concurrency
+ * primitive in the surface is the `generation` field on the
+ * `PUT /package-drafts/{draftId}` *body* (`StudioPackageDraftReplaceRequest`),
+ * which this route has no analogue for.
+ *
+ * So the command brackets the write instead of pretending the check was
+ * atomic: it reads the generation before, re-reads it after, and raises a
+ * `conflict` naming the version it created if the draft moved at any point.
+ * `generation` is documented to increment on every successful `PUT`
+ * (`StudioPackageDraft`), so no concurrent edit can slip through the bracket
+ * unseen. When honua-server grows a real precondition on this route, the
+ * bracket collapses into it and the second read goes away.
+ *
+ * @experimental
+ * @module
+ */
+import { HonuaCommandError } from "./errors.js";
+/**
+ * `POST /connections/{connectionId}/test` — probe a stored connection.
+ *
+ * The server does not consume an idempotency key or a workspace body. Keep the
+ * command identity limited to the connection route so receipts describe the
+ * request the server actually processed.
+ */
+export const connectionTestCommand = {
+    id: "connection.test",
+    title: "Test a connection",
+    description: "Probe a stored control-plane connection and report whether the server can reach it.",
+    mode: "read",
+    resourceKind: "connection",
+    inputSchema: {
+        type: "object",
+        description: "Identifies the stored connection to probe.",
+        properties: {
+            connectionId: { type: "string", minLength: 1, description: "Identifier of the stored connection." },
+        },
+        required: ["connectionId"],
+        additionalProperties: false,
+    },
+    plan(context) {
+        return {
+            method: "POST",
+            path: connectionTestPath(context.input.connectionId),
+            summary: `Probe connection ${context.input.connectionId}`,
+            resourceRef: connectionRef(context.input),
+        };
+    },
+    async execute(context) {
+        const result = await context.controlPlane.raw({
+            method: "POST",
+            path: connectionTestPath(context.input.connectionId),
+            ...context.requestOptions(),
+        });
+        const value = unwrap(result, this.id, {
+            correlationId: context.correlationId,
+            idempotencyKey: context.idempotencyKey,
+        });
+        return {
+            output: value ?? {},
+            ...(value?.ok === false ? { status: "denied" } : {}),
+            resourceRef: connectionRef(context.input),
+        };
+    },
+};
+function connectionTestPath(connectionId) {
+    return `/connections/${encodeURIComponent(connectionId)}/test`;
+}
+function connectionRef(input) {
+    return {
+        type: "connection",
+        id: input.connectionId,
+    };
+}
+/** `POST /import/upload-url` — enqueue a URL import job. */
+export const importCreateCommand = {
+    id: "import.create",
+    title: "Create an import job",
+    description: "Enqueue a control-plane import job for a source URL.",
+    mode: "action",
+    resourceKind: "import-job",
+    inputSchema: {
+        type: "object",
+        description: "Describes the source to import.",
+        properties: {
+            sourceKind: { type: "string", minLength: 1, description: "Import source kind, e.g. `geojson` or `postgis`." },
+            sourceUrl: { type: "string", minLength: 1, description: "Source URL, when the import reads a location." },
+            connectionId: {
+                type: "string",
+                minLength: 1,
+                description: "Compatibility input; the current /import/upload-url endpoint accepts sourceUrl only.",
+            },
+            workspaceId: { type: "string", minLength: 1, description: "Workspace that will own the imported content." },
+            title: { type: "string", minLength: 1, description: "Human title for the resulting content." },
+            options: { type: "object", description: "Import-kind-specific options, passed through verbatim." },
+        },
+        required: ["sourceKind"],
+        additionalProperties: false,
+    },
+    validate(input) {
+        // This has to run before the dry-run short circuit: a preview that accepts
+        // an import with no URL would be a preview of a request the server never
+        // sees.
+        if (!input.sourceUrl && !input.connectionId) {
+            return [{ path: "sourceUrl", message: "`sourceUrl` is required by /import/upload-url" }];
+        }
+        if (!input.sourceUrl && input.connectionId) {
+            return [
+                {
+                    path: "connectionId",
+                    message: "stored-connection imports are not supported by /import/upload-url; provide `sourceUrl`",
+                },
+            ];
+        }
+        if (input.sourceUrl && input.connectionId) {
+            return [{ path: "", message: "provide only one of `sourceUrl` or `connectionId`" }];
+        }
+        return [];
+    },
+    plan(context) {
+        const { input } = context;
+        return {
+            method: "POST",
+            path: "/import/upload-url",
+            summary: `Import ${input.sourceKind} from ${input.sourceUrl ?? input.connectionId ?? "(unspecified source)"}`,
+            resourceRef: {
+                type: "import-job",
+                ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+            },
+        };
+    },
+    async execute(context) {
+        const { input } = context;
+        const result = await context.controlPlane.imports.create({
+            sourceKind: input.sourceKind,
+            ...(input.sourceUrl ? { sourceUrl: input.sourceUrl } : {}),
+            ...(input.connectionId ? { connectionId: input.connectionId } : {}),
+            ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+            ...(input.title ? { title: input.title } : {}),
+            ...(input.options ? { options: input.options } : {}),
+        }, context.requestOptions());
+        const job = unwrap(result, this.id, {
+            correlationId: context.correlationId,
+            idempotencyKey: context.idempotencyKey,
+        });
+        return {
+            output: job,
+            resourceRef: {
+                type: "import-job",
+                ...(job?.id ? { id: job.id } : {}),
+                ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+                ...(job?.links?.self ? { href: job.links.self } : {}),
+            },
+            ...(validatorsOf(job) ? { validators: validatorsOf(job) } : {}),
+            ...(job?.problem ? { problem: job.problem } : {}),
+        };
+    },
+};
+/** `POST /packages` — publish a map package version. */
+export const mapPackagePublishCommand = {
+    id: "map-package.publish",
+    title: "Publish a map package",
+    description: "Publish a map package version. Approval and visibility remain server-side decisions.",
+    mode: "action",
+    resourceKind: "map-package",
+    inputSchema: {
+        type: "object",
+        description: "The map package to publish and where it belongs.",
+        properties: {
+            mapId: { type: "string", minLength: 1, description: "Hosted map the package version belongs to." },
+            workspaceId: { type: "string", minLength: 1, description: "Owning workspace." },
+            package: { type: "object", description: "The `honua_map_package.v1` document." },
+            message: { type: "string", description: "Publication message recorded with the version." },
+        },
+        required: ["package"],
+        additionalProperties: false,
+    },
+    plan(context) {
+        const { input } = context;
+        return {
+            method: "POST",
+            path: "/packages",
+            summary: input.mapId ? `Publish a package version for map ${input.mapId}` : "Publish a map package version",
+            resourceRef: {
+                type: "map-package",
+                ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+            },
+        };
+    },
+    async execute(context) {
+        const { input } = context;
+        const result = await context.controlPlane.packages.publish({
+            package: input.package,
+            ...(input.mapId ? { mapId: input.mapId } : {}),
+            ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+            ...(input.message ? { message: input.message } : {}),
+        }, context.requestOptions());
+        const response = unwrap(result, this.id, {
+            correlationId: context.correlationId,
+            idempotencyKey: context.idempotencyKey,
+        });
+        return {
+            output: response,
+            resourceRef: {
+                type: "map-package",
+                ...(response?.packageId ? { id: response.packageId } : {}),
+                ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+                ...(response?.links?.self ? { href: response.links.self } : {}),
+            },
+            ...(validatorsOf(response) ? { validators: validatorsOf(response) } : {}),
+        };
+    },
+};
+/** `POST /package-drafts/{draftId}/content-versions` — save a draft as an immutable version. */
+export const studioDraftSaveVersionCommand = {
+    id: "studio.draft.saveVersion",
+    title: "Save a Studio draft as a version",
+    description: "Freeze a mutable Studio package draft into an immutable content version, checking the generation.",
+    mode: "action",
+    resourceKind: "studio-content-version",
+    inputSchema: {
+        type: "object",
+        description: "Identifies the draft to freeze.",
+        properties: {
+            draftId: { type: "string", minLength: 1, description: "Mutable draft identifier." },
+            generation: { type: "integer", minimum: 0, description: "Last-seen draft generation for concurrency checking." },
+        },
+        required: ["draftId"],
+        additionalProperties: false,
+    },
+    plan(context) {
+        return {
+            method: "POST",
+            path: `/package-drafts/${encodeURIComponent(context.input.draftId)}/content-versions`,
+            summary: `Save draft ${context.input.draftId} as an immutable content version`,
+            resourceRef: { type: "studio-package-draft", id: context.input.draftId },
+        };
+    },
+    async execute(context) {
+        const studio = context.studio;
+        if (!studio) {
+            throw new HonuaCommandError("transport", this.id, "studio.draft.saveVersion requires a Studio lifecycle client; construct the runtime with `studio`.", { correlationId: context.correlationId, idempotencyKey: context.idempotencyKey });
+        }
+        // The Studio lifecycle client takes `{ signal, headers }` rather than the
+        // control-plane option bag, so the idempotency key is threaded as the
+        // header it becomes — and only onto the mutating call.
+        const options = context.requestOptions();
+        const readOptions = {
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.headers ? { headers: options.headers } : {}),
+        };
+        // The command-owned key goes on last: the runtime already refuses a caller
+        // header that would replace it, and this keeps the value on the wire equal
+        // to the value the receipt records even if that guard is ever relaxed.
+        const writeOptions = {
+            ...readOptions,
+            headers: { ...headersToRecord(options.headers), "Idempotency-Key": context.idempotencyKey },
+        };
+        if (context.input.generation !== undefined) {
+            const draft = await studio.drafts.get(context.input.draftId, readOptions);
+            if (draft.generation !== context.input.generation) {
+                throw new HonuaCommandError("conflict", this.id, `Studio draft ${context.input.draftId} moved from generation ${context.input.generation} to ${draft.generation}; reload and retry.`, { correlationId: context.correlationId, idempotencyKey: context.idempotencyKey, statusCode: 409 });
+            }
+        }
+        const version = await studio.drafts.createContentVersion(context.input.draftId, writeOptions);
+        // The lifecycle API exposes no precondition on the content-version POST, so
+        // the pre-read alone leaves a window in which another editor's `PUT` lands
+        // between the check and the write. When the caller asked for concurrency
+        // protection, close the bracket: re-read and refuse to report a success we
+        // cannot vouch for. The created version is named so the caller can
+        // reconcile it rather than lose track of it.
+        if (context.input.generation !== undefined) {
+            const after = await studio.drafts.get(context.input.draftId, readOptions);
+            if (after.generation !== context.input.generation) {
+                throw new HonuaCommandError("conflict", this.id, `Studio draft ${context.input.draftId} moved from generation ${context.input.generation} to ${after.generation} while version ${version?.versionId ?? "(unknown)"} was being cut; reconcile that version, then reload and retry.`, { correlationId: context.correlationId, idempotencyKey: context.idempotencyKey, statusCode: 409 });
+            }
+        }
+        return {
+            output: version,
+            resourceRef: {
+                type: "studio-content-version",
+                ...(version?.versionId ? { id: version.versionId } : {}),
+            },
+        };
+    },
+};
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/** Every command id in the 2026.1 catalog, in registry order. */
+export const HONUA_COMMAND_IDS = [
+    "connection.test",
+    "import.create",
+    "map-package.publish",
+    "studio.draft.saveVersion",
+];
+/**
+ * The shared registry every transport dispatches through. MCP tool schemas,
+ * CLI help, Studio clients, and JS methods all project from these entries.
+ */
+export const HONUA_COMMANDS = {
+    "connection.test": connectionTestCommand,
+    "import.create": importCreateCommand,
+    "map-package.publish": mapPackagePublishCommand,
+    "studio.draft.saveVersion": studioDraftSaveVersionCommand,
+};
+/** Type guard narrowing an arbitrary string to a registered command id. */
+export function isHonuaCommandId(value) {
+    return Object.hasOwn(HONUA_COMMANDS, value);
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/**
+ * Unwrap a {@link HonuaControlPlaneResult}, converting the "this deployment
+ * does not expose the capability" arm into a typed `transport` failure so every
+ * transport reports the gap the same way.
+ */
+function unwrap(result, commandId, trace) {
+    if (result.supported)
+        return result.value;
+    throw new HonuaCommandError("transport", commandId, result.reason, {
+        correlationId: trace.correlationId,
+        idempotencyKey: trace.idempotencyKey,
+        ...(result.statusCode !== undefined ? { statusCode: result.statusCode } : {}),
+        ...(result.problem ? { problem: result.problem } : {}),
+    });
+}
+function headersToRecord(headers) {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers);
+    return { ...headers };
+}
+function validatorsOf(value) {
+    if (!value)
+        return undefined;
+    const etag = value.etag;
+    const lastModified = value.lastModified;
+    if (!etag && !lastModified)
+        return undefined;
+    return { ...(etag ? { etag } : {}), ...(lastModified ? { lastModified } : {}) };
+}

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

@@ -0,0 +1,96 @@
+/**
+ * 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 type { HonuaProblemDetails } from "../types.js";
+/**
+ * Failure classes a command can raise.
+ *
+ * - `validation` — input failed the command's declared JSON schema, or the
+ *   server rejected the request shape (`400`/`422`).
+ * - `conflict` — optimistic concurrency lost: a stale `If-Match` validator or
+ *   Studio `generation` (`409`/`412`). Reload and retry.
+ * - `authorization` — the caller is not permitted (`401`/`403`), or the caller
+ *   tried to override authority locally (a reserved credential/authority
+ *   header). Never retry with different local state.
+ * - `cancelled` — the caller's `AbortSignal` fired.
+ * - `transport` — everything else: network failure, unsupported capability,
+ *   `5xx`, or a missing client the command needs.
+ */
+export type HonuaCommandErrorKind = "validation" | "conflict" | "authorization" | "cancelled" | "transport";
+/** One schema or domain validation finding. */
+export interface HonuaCommandValidationIssue {
+    /** Dotted path into the input, e.g. `package.sources[0].id`; `""` for the root. */
+    readonly path: string;
+    readonly message: string;
+}
+/** Constructor options for {@link HonuaCommandError}. */
+export interface HonuaCommandErrorOptions {
+    readonly cause?: unknown;
+    readonly correlationId?: string;
+    readonly idempotencyKey?: string;
+    readonly statusCode?: number;
+    readonly problem?: HonuaProblemDetails;
+    readonly issues?: readonly HonuaCommandValidationIssue[];
+}
+/** Serialization-safe projection of a {@link HonuaCommandError}. */
+export interface SerializedHonuaCommandError {
+    readonly kind: "honua.command.error.v1";
+    readonly errorKind: HonuaCommandErrorKind;
+    readonly commandId: string;
+    readonly retryable: boolean;
+    readonly correlationId?: string;
+    readonly idempotencyKey?: string;
+    readonly statusCode?: number;
+    readonly issues?: readonly HonuaCommandValidationIssue[];
+}
+/**
+ * The single error type every command raises. Callers branch on `.kind`
+ * rather than on HTTP status numbers or transport-specific error classes.
+ */
+export declare class HonuaCommandError extends Error {
+    readonly kind: HonuaCommandErrorKind;
+    readonly commandId: string;
+    readonly correlationId: string | undefined;
+    readonly idempotencyKey: string | undefined;
+    readonly statusCode: number | undefined;
+    readonly problem: HonuaProblemDetails | undefined;
+    readonly issues: readonly HonuaCommandValidationIssue[] | undefined;
+    /** `conflict` and `transport` are worth retrying; the rest are terminal. */
+    readonly retryable: boolean;
+    constructor(kind: HonuaCommandErrorKind, commandId: string, message: string, options?: HonuaCommandErrorOptions);
+    /** Safe JSON projection: no message, stack, cause, or response body. */
+    toJSON(): SerializedHonuaCommandError;
+}
+/** Type guard for {@link HonuaCommandError}. */
+export declare function isHonuaCommandError(error: unknown): error is HonuaCommandError;
+/** True when the failure is an optimistic-concurrency loss worth reloading and retrying. */
+export declare function isHonuaCommandConflict(error: unknown): error is HonuaCommandError;
+/** Map an HTTP status code onto the command taxonomy. */
+export declare function classifyCommandStatus(statusCode: number): HonuaCommandErrorKind;
+/**
+ * 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 declare function toHonuaCommandError(error: unknown, commandId: string, context: {
+    readonly correlationId: string;
+    readonly idempotencyKey: string;
+    readonly signal?: AbortSignal;
+}): HonuaCommandError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,UAAU,GAAG,eAAe,GAAG,WAAW,GAAG,WAAW,CAAC;AAE5G,+CAA+C;AAC/C,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAC;CAC1D;AAED,oEAAoE;AACpE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAC;CAC1D;AAID;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,IAAI,EAAE,qBAAqB,CAAC;IAC5C,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,SAAgB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnD,SAAgB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,SAAgB,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACzD,SAAgB,MAAM,EAAE,SAAS,2BAA2B,EAAE,GAAG,SAAS,CAAC;IAC3E,4EAA4E;IAC5E,SAAgB,SAAS,EAAE,OAAO,CAAC;gBAGjC,IAAI,EAAE,qBAAqB,EAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,wBAA6B;IAcxC,wEAAwE;IACjE,MAAM,IAAI,2BAA2B;CAY7C;AAED,gDAAgD;AAChD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAEjF;AAED,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,CAK/E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC1G,iBAAiB,CAwBnB"}