@honua/react 0.1.4-beta.0 → 0.1.9-beta.0

package/control-plane/commands/catalog.js

@@ -0,0 +1,353 @@
+/**
+ * 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.
+ *
+ * Modelled as an `action` rather than a `read` so repeated probes carry an
+ * `Idempotency-Key` and collapse server-side; the probe itself does not mutate
+ * the connection.
+ */
+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: "action",
+    resourceKind: "connection",
+    inputSchema: {
+        type: "object",
+        description: "Identifies the stored connection to probe.",
+        properties: {
+            connectionId: { type: "string", minLength: 1, description: "Identifier of the stored connection." },
+            workspaceId: { type: "string", minLength: 1, description: "Owning workspace, when the deployment scopes them." },
+        },
+        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.input.workspaceId ? { body: { workspaceId: context.input.workspaceId } } : {}),
+            ...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,
+        ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+    };
+}
+/** `POST /imports` — enqueue an import job. */
+export const importCreateCommand = {
+    id: "import.create",
+    title: "Create an import job",
+    description: "Enqueue a control-plane import job for a source URL or a stored connection.",
+    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: "Stored connection, when the import reads a system." },
+            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) {
+        // JSON Schema cannot say "one of these two", and this has to run before the
+        // dry-run short circuit: a preview that accepts an import with no source
+        // would be a preview of a request the server never sees.
+        if (!input.sourceUrl && !input.connectionId) {
+            return [{ path: "", message: "one of `sourceUrl` or `connectionId` is required" }];
+        }
+        return [];
+    },
+    plan(context) {
+        const { input } = context;
+        return {
+            method: "POST",
+            path: "/imports",
+            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"}

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"}