Initial Commit

packages/api-stack/api/api-sandbox-vm-host-bridge/src/error-codes/error-codes.ts

@@ -0,0 +1,63 @@
+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";
+    }
+}