import type { SuaveplanErrorOptions } from "@suaveplan/error";
import { defineCodes, SuaveplanError } from "@suaveplan/error";

/**
 * Stable error-code registry for `@suaveplan/api-sandbox-vm-host-bridge`.
 *
 * Every failure surface inside the bridge raises a
 * {@link SandboxVmBridgeError} whose `code` is one of the namespaced
 * `SAND_VM_BRIDGE.*` strings declared below.
 *
 * Code semantics:
 *
 *  - `INVALID_PLUGIN_SURFACE` — the sandboxed plugin did not register any
 *    routes via the host-installed `bridge.registerRoute` capability
 *    before its module body finished evaluating, OR a registration was
 *    structurally invalid (missing method, missing path, non-function
 *    handler). The bridge refuses to expose a partially-initialised
 *    plugin to the host.
 *  - `MARSHAL_FAILED` — the host's `Request` could not be serialised
 *    into a {@link SerializedRequest}. The most common cause is an
 *    unsupported body type (e.g. `ReadableStream` that the marshal layer
 *    cannot drain inside the request handler) or a header value that
 *    failed the Zod validator. The route handler does NOT reach the
 *    sandbox in this case.
 *  - `UNMARSHAL_FAILED` — the sandbox-side handler returned a value the
 *    bridge could not turn into a {@link SerializedResponse} — either
 *    a non-object, an object missing the required fields, or a body of
 *    an unsupported type.
 *  - `HANDLER_REJECTED` — the sandboxed handler threw or its returned
 *    promise rejected. The thrown value is preserved as `cause` so the
 *    host's error boundary can walk the chain back to the original
 *    `SandboxVmError` (or whatever the sandbox emitted).
 *  - `LIFECYCLE_FAILED` — a delegated `start` or `dispose` call into the
 *    sandbox failed. Used only when the underlying sandbox throws — the
 *    bridge's own idempotency guards never raise this code.
 */
export const SAND_VM_BRIDGE_CODES = defineCodes("SAND_VM_BRIDGE", [
    "INVALID_PLUGIN_SURFACE",
    "MARSHAL_FAILED",
    "UNMARSHAL_FAILED",
    "HANDLER_REJECTED",
    "LIFECYCLE_FAILED",
] as const);

/** Union of every fully-qualified code in {@link SAND_VM_BRIDGE_CODES}. */
export type SandboxVmBridgeCode =
    (typeof SAND_VM_BRIDGE_CODES)[keyof typeof SAND_VM_BRIDGE_CODES];

/**
 * Typed error class for `@suaveplan/api-sandbox-vm-host-bridge`. Extends
 * {@link SuaveplanError} so callers may discriminate by
 * `instanceof SandboxVmBridgeError` OR by `code` string.
 */
export class SandboxVmBridgeError extends SuaveplanError<SandboxVmBridgeCode> {
    public constructor(
        code: SandboxVmBridgeCode,
        message: string,
        options?: SuaveplanErrorOptions
    ) {
        super(code, message, options);
        this.name = "SandboxVmBridgeError";
    }
}