@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/src/errors/envelope.ts

@@ -0,0 +1,75 @@
+import type { WirePluginErrorCode } from "./codes"
+
+/**
+ * Structured error payload carried on the `{success: false}` branch of the RPC
+ * wire result, next to the legacy `error: string` field (additive — old
+ * clients ignore it, old hosts never set it).
+ *
+ * Errors cross the worker boundary as THIS plain object, never as a thrown
+ * class: Comlink's throw transfer strips subclasses and custom fields and
+ * leaks host stacks. plugin-client reconstructs a typed `PluginError` from it
+ * (`fromEnvelope`).
+ */
+export const ERROR_ENVELOPE_VERSION = 1 as const
+
+export interface ErrorEnvelope {
+  envelopeVersion: typeof ERROR_ENVELOPE_VERSION
+  code: WirePluginErrorCode
+  /**
+   * Human-readable failure description. For INTERNAL/UNKNOWN this is a GENERIC
+   * message — the real message and stack stay host-side, logged under
+   * `errorId` (the worker is untrusted; internals must not leak).
+   */
+  message: string
+  /**
+   * Per-occurrence id. For INTERNAL the host logs the real message and stack
+   * under this id (the sanitized message would otherwise be an undebuggable
+   * dead end). Other codes carry the id only to identify the occurrence in
+   * bug reports — the host does not log them. Client-minted ids carry a `c-`
+   * prefix.
+   */
+  errorId: string
+  /** Structured, JSON-safe, code-specific data (issues / retryAfterMs / didYouMean / handles…). */
+  details?: Record<string, unknown>
+  /**
+   * Wire id of the single primary offending handle, when the failure is
+   * handle-scoped. Multiple offenders go in `details.handles: string[]`.
+   * May echo ONLY ids the caller itself supplied (anti-oracle rule).
+   */
+  handle?: string
+  /** Dotted method path of the failed call (e.g. "design.boolean.union"). */
+  methodPath?: string
+  /** Machine-actionable fix suggestion (written for LLM plugin authors). */
+  hint?: string
+}
+
+/**
+ * Structural guard for a wire value claiming to be an `ErrorEnvelope`.
+ *
+ * Checks shape only — deliberately does NOT reject codes outside the known
+ * union, so envelopes from a newer host still pass (forward compatibility).
+ */
+export function isErrorEnvelope(value: unknown): value is ErrorEnvelope {
+  if (typeof value !== "object" || value === null) return false
+  const record = value as Record<string, unknown>
+  return (
+    record.envelopeVersion === ERROR_ENVELOPE_VERSION &&
+    typeof record.code === "string" &&
+    typeof record.message === "string" &&
+    typeof record.errorId === "string"
+  )
+}
+
+let idCounter = 0
+
+/**
+ * Mint a per-occurrence error id. Uses `crypto.randomUUID` when available
+ * (browser main thread and workers both have it); falls back to a
+ * counter+random suffix — uniqueness within a session is all that is needed.
+ */
+export function newErrorId(prefix = ""): string {
+  const cryptoApi = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto
+  if (cryptoApi?.randomUUID) return `${prefix}${cryptoApi.randomUUID()}`
+  idCounter += 1
+  return `${prefix}${Date.now().toString(36)}-${idCounter}-${Math.random().toString(36).slice(2, 10)}`
+}

package/src/errors/index.ts

@@ -0,0 +1,21 @@
+export { PLUGIN_ERROR_CODES, CODE_META, isPluginErrorCode } from "./codes"
+export type { PluginErrorCode, WirePluginErrorCode, PluginErrorCategory, CodeMeta } from "./codes"
+
+export { ERROR_ENVELOPE_VERSION, isErrorEnvelope, newErrorId } from "./envelope"
+export type { ErrorEnvelope } from "./envelope"
+
+export {
+  PluginError,
+  PluginValidationError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginHandleError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginLifecycleError,
+  PluginExecutionError,
+  PluginInternalError,
+  fromEnvelope,
+  makeClientEnvelope,
+} from "./plugin-error"

package/src/errors/plugin-error.ts

@@ -0,0 +1,134 @@
+import { CODE_META, isPluginErrorCode } from "./codes"
+import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes"
+import { ERROR_ENVELOPE_VERSION, newErrorId } from "./envelope"
+import type { ErrorEnvelope } from "./envelope"
+
+/**
+ * Cross-copy brand: a plugin bundle may contain its OWN copy of this module,
+ * in which case `instanceof` fails across the two class identities.
+ * `Symbol.for` resolves to the same symbol in every copy within a realm, so
+ * `PluginError.is()` keeps working. Canonical check = `.is()` + `code`.
+ */
+const BRAND = Symbol.for("snaptrude.pluginError")
+
+interface Branded {
+  [BRAND]?: boolean
+}
+
+/**
+ * Typed error every failed plugin API call rejects with.
+ *
+ * Rehydrated client-side from the wire `ErrorEnvelope` (`fromEnvelope`) — the
+ * class itself never crosses the worker boundary. Branch on the stable string
+ * `code`; use `PluginError.is()` rather than `instanceof` (a bundled duplicate
+ * SDK copy breaks `instanceof`, never the brand).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await snaptrude.design.boolean.union(handles)
+ * } catch (e) {
+ *   if (PluginError.is(e) && e.code === "RATE_LIMITED") {
+ *     await sleep(e.details?.retryAfterMs as number)
+ *   } else {
+ *     throw e
+ *   }
+ * }
+ * ```
+ */
+export class PluginError extends Error {
+  readonly code: WirePluginErrorCode
+  readonly errorId: string
+  readonly details?: Record<string, unknown>
+  readonly handle?: string
+  readonly methodPath?: string
+  readonly hint?: string
+
+  constructor(envelope: ErrorEnvelope) {
+    super(envelope.message)
+    this.name = new.target.name
+    this.code = envelope.code
+    this.errorId = envelope.errorId
+    this.details = envelope.details
+    this.handle = envelope.handle
+    this.methodPath = envelope.methodPath
+    this.hint = envelope.hint ?? hintFor(envelope.code)
+    ;(this as Branded)[BRAND] = true
+  }
+
+  /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
+  static is(value: unknown): value is PluginError {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as Branded)[BRAND] === true
+    )
+  }
+
+  /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
+  get category(): PluginErrorCategory {
+    return isPluginErrorCode(this.code) ? CODE_META[this.code].category : "internal"
+  }
+}
+
+// Category sugar — same brand, so `PluginError.is()` matches all of them.
+// Convenience for single-SDK-copy plugins; docs teach `.is()` + `code`.
+export class PluginValidationError extends PluginError {}
+export class PluginNotFoundError extends PluginError {}
+export class PluginPermissionError extends PluginError {}
+export class PluginHandleError extends PluginError {}
+export class PluginQuotaError extends PluginError {}
+export class PluginTimeoutError extends PluginError {}
+export class PluginTransportError extends PluginError {}
+export class PluginLifecycleError extends PluginError {}
+export class PluginExecutionError extends PluginError {}
+export class PluginInternalError extends PluginError {}
+
+type PluginErrorConstructor = new (envelope: ErrorEnvelope) => PluginError
+
+const CATEGORY_CLASS: Record<PluginErrorCategory, PluginErrorConstructor> = {
+  validation: PluginValidationError,
+  not_found: PluginNotFoundError,
+  permission: PluginPermissionError,
+  handle: PluginHandleError,
+  quota: PluginQuotaError,
+  timeout: PluginTimeoutError,
+  transport: PluginTransportError,
+  lifecycle: PluginLifecycleError,
+  execution: PluginExecutionError,
+  internal: PluginInternalError,
+}
+
+function hintFor(code: WirePluginErrorCode): string | undefined {
+  return isPluginErrorCode(code) ? CODE_META[code].hintTemplate : undefined
+}
+
+/**
+ * Rehydrate a wire envelope into the typed error the plugin catches.
+ * A code outside the known union (newer host) constructs the base
+ * `PluginError` with the code preserved verbatim.
+ */
+export function fromEnvelope(envelope: ErrorEnvelope): PluginError {
+  if (!isPluginErrorCode(envelope.code)) return new PluginError(envelope)
+  const ErrorClass = CATEGORY_CLASS[CODE_META[envelope.code].category]
+  return new ErrorClass(envelope)
+}
+
+/**
+ * Build an envelope for a CLIENT-detected failure (transport rejection,
+ * legacy host without `errorInfo`). Host-originated envelopes are built by
+ * the host's `toErrorEnvelope` mapper, never by this.
+ */
+export function makeClientEnvelope(
+  code: PluginErrorCode,
+  message: string,
+  extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>
+): ErrorEnvelope {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code,
+    message,
+    errorId: newErrorId("c-"),
+    ...extra,
+  }
+}

package/src/handles.ts

@@ -1,22 +1,71 @@
 import * as z from "zod"
+import type { ArenaKind } from "./api/core/handles"
+
+// Runtime polyfill: engines without explicit-resource-management would otherwise
+// evaluate the class's computed [Symbol.asyncDispose] key as undefined and
+// silently create a property literally named "undefined".
+;(Symbol as { asyncDispose?: symbol }).asyncDispose ??= Symbol.for("Symbol.asyncDispose")
 
 /**
  * An opaque, kind-tagged reference to a host-side object that crosses the RPC
  * boundary by IDENTITY rather than by value. See `PLUGIN_API_EXPOSURE_HLD.md` §9.
  *
- * The phantom `__handle` brand makes a `Handle<"profile">` incompatible with a
- * `Handle<"mass">` at compile time. At runtime a handle is just a string of the
- * form `"<kind>_<token>"` (e.g. `"profile_k3f9a2x"`), so it is structured-clone
- * safe and engine-free — plugin-core never imports the engine type it points at.
+ * A handle is a small CLASS instance wrapping the wire id. The phantom
+ * `__handle` brand makes a `Handle<"profile">` incompatible with a
+ * `Handle<"vec3">` at compile time. On the wire the id string is all that
+ * travels: the client SDK unwraps `Handle` arguments to `.id` before the RPC
+ * call, and the host tags returned handles as `{ __h: "<id>" }` (via
+ * {@linkcode Handle.toJSON}) for the client to re-wrap.
+ *
+ * Plugin-side lifecycle: the client SDK interns one live instance per id and
+ * registers it with a FinalizationRegistry — dropping every reference to a
+ * handle eventually releases its host registry entry. Deterministic release is
+ * still preferred: `core.handles.release/releaseAll` or scopes.
+ *
+ * Crossing non-RPC boundaries (UI postMessage, persistence, logging):
+ * send {@linkcode Handle.id} — structured clone strips the class prototype.
  */
-export type Handle<K extends string> = string & { readonly __handle: K }
+export class Handle<K extends string> {
+  /** Phantom brand — keeps `Handle<"vec3">` ≠ `Handle<"mass">` at compile time. */
+  declare readonly __handle: K
+
+  constructor(readonly id: string) {}
+
+  /** Wire tag — the host's result serialization (JSON round-trip) calls this. */
+  toJSON(): { __h: string } {
+    return { __h: this.id }
+  }
+
+  /** Template-string / logging form stays the bare id. */
+  toString(): string {
+    return this.id
+  }
+
+  /** Identity comparison by id — safe across re-wraps. */
+  equals(other: Handle<string>): boolean {
+    return this.id === other.id
+  }
+
+  /**
+   * Explicit-resource-management hook (`await using`). A no-op here; the
+   * plugin-client runtime installs the real enqueue-release behavior on the
+   * interned instance.
+   */
+  async [Symbol.asyncDispose](): Promise<void> {}
+}
+
+/** Union of all releasable (arena-backed) handle kinds. */
+export type AnyArenaHandle = Handle<ArenaKind>
 
 /**
  * A scene-entity handle. Backed by the host `Component.id` and resolved live via
  * the host scene index (StructureCollection) — never stored in the resource
  * registry. Stable across undo/redo and persistable across sessions (§9.2).
+ * Entity handles remain raw branded STRINGS (not {@linkcode Handle} instances):
+ * they have no arena entry, no lifecycle, and are equality-matched against
+ * plain ids embedded in result records.
  */
-export type EntityId<K extends string = string> = Handle<K>
+export type EntityId<K extends string = string> = string & { readonly __handle: K }
 
 /** Resource handle: a host-resident, session-ephemeral geometry object (§9.2). */
 export type ProfileHandle = Handle<"profile">
@@ -46,6 +95,34 @@ export type ComponentHandle = EntityId<"component">
  */
 export type MaterialHandle = EntityId<"material">
 
+/**
+ * A placed **scene underlay** — an imported reference plane the user traces over:
+ * an image `FloorPlan`, a `PDF` overlay, or a `CAD` sketch. Entity-style: the token
+ * IS the raw `Component.id` (`fp_…` / a pdf id / `cad_…`). Resolved live host-side
+ * via the import-order layer walk (`collectStoreyImportItems`) — NOT via
+ * `ComponentUtility.FindComponentById`, which does not index underlays. No arena, no
+ * quota, stable across undo/redo. Returned by `core.io.import.{image,pdf,cadJson}`
+ * and consumed by every `core.io.underlay.*` method.
+ */
+export type UnderlayHandle = EntityId<"underlay">
+
+/**
+ * The project's **site terrain** — a Mapbox-derived topography mesh. Entity-style
+ * and a project **singleton** (one terrain per project): the token is the terrain
+ * `Component.id` (`terrain-…`), resolved live via `TerrainOperations.getTerrain()`
+ * (absent from the level component collections, so NOT `FindComponentById`).
+ * Returned by `core.io.import.terrain`.
+ */
+export type TerrainHandle = EntityId<"terrain">
+
+/**
+ * A handle to an **asynchronous import job** (today: a DWG → Forge conversion, which
+ * can take minutes). Returned immediately by `core.io.import.dwg`; poll it via
+ * `core.io.job.*` (`getStatus` / `isComplete` / `getResult` / `getError`). The token
+ * is the engine's import request id; job state lives in a host-side registry.
+ */
+export type ImportJobHandle = EntityId<"importJob">
+
 // ── Value-kind handles (all-handle model, §11) ──────────────────────────────
 // Under the all-handle decision every structured type is a handle. The only
 // non-handles crossing the boundary are JS primitives (number/string/boolean)
@@ -91,19 +168,34 @@ export type BBoxComponents = { min: Vec3Components; max: Vec3Components }
 
 /**
  * Build a Zod schema validating a handle of the given `kind` at the trust
- * boundary. It checks only the `"<kind>_"` prefix shape; existence, kind, and
- * ownership are enforced host-side by the HandleRegistry (§9.7). Keeping it to
- * the prefix is engine-free and avoids an existence oracle.
+ * boundary and emitting a {@linkcode Handle} instance for impl code. Inbound
+ * forms accepted:
+ *  - the bare id string (the wire form — the client unwraps args to ids)
+ *  - a live `Handle` instance (host-internal re-parse, direct host callers)
+ *  - `{ __h: string }` (the tagged result form, echoed back as an arg)
+ *  - `{ id: string }` (a Handle stripped by structured clone at the UI boundary)
+ * Shape checking stays prefix-only; existence, kind, and ownership are enforced
+ * host-side by the HandleRegistry (§9.7) — no existence oracle.
  */
 export const handleSchema = <K extends string>(kind: K) =>
   z
-    .string()
-    .regex(new RegExp(`^${kind}_[A-Za-z0-9_-]+$`), `expected a "${kind}" handle`)
-    .transform((s) => s as Handle<K>)
+    .preprocess(
+      (v) => {
+        if (typeof v === "string") return v
+        if (v instanceof Handle) return v.id
+        if (v && typeof v === "object") {
+          const o = v as Record<string, unknown>
+          if (typeof o.__h === "string") return o.__h
+          if (typeof o.id === "string") return o.id
+        }
+        return v
+      },
+      z.string().regex(new RegExp(`^${kind}_[A-Za-z0-9_-]+$`), `expected a "${kind}" handle`)
+    )
+    .transform((s) => new Handle<K>(s))
 
 export const ProfileHandle = handleSchema("profile")
 export const ContourHandle = handleSchema("contour")
-export const MassHandle = handleSchema("mass")
 
 /**
  * Entity handles are raw `Component.id` strings (no `"<kind>_"` prefix) — validated
@@ -123,6 +215,24 @@ export const MaterialHandle = z
   .min(1)
   .transform((s) => s as MaterialHandle)
 
+/**
+ * {@linkcode UnderlayHandle} / {@linkcode TerrainHandle} / {@linkcode ImportJobHandle}
+ * are entity-style handles — raw host ids, validated only as a non-empty string
+ * (no `"<kind>_"` prefix), resolved live host-side (existence enforced there).
+ */
+export const UnderlayHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as UnderlayHandle)
+export const TerrainHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as TerrainHandle)
+export const ImportJobHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as ImportJobHandle)
+
 // Value-kind handle schemas (all-handle model, §11).
 export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")

package/src/host-utils.ts

@@ -1,4 +1,5 @@
 import type { PluginApi } from "./api"
+import type { ErrorEnvelope } from "./errors"
 
 // -- Type Utilities for inferring method paths from the class hierarchy ------
 
@@ -60,5 +61,8 @@ export type PluginApiCallResult<M extends PluginApiMethod> =
 export type PluginApiCallWrappedResult<M extends PluginApiMethod> = {
   success: boolean;
   data?: PluginApiCallResult<M>;
+  /** Legacy failure message — kept verbatim for already-published plugins. */
   error?: string;
+  /** Structured failure (hosts ≥ error-envelope rollout). Present iff `success` is false. */
+  errorInfo?: ErrorEnvelope;
 }

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./api"
 export * from "./types"
 export * from "./host-utils"
 export * from "./handles"
+export * from "./errors"

package/test/errors.test.mjs

@@ -0,0 +1,184 @@
+// Node built-in test runner suite for the error module (codes/envelope/PluginError).
+// Run: node --test test/
+// Imports the BUILT package (dist) — run `pnpm build` first.
+import test from "node:test"
+import assert from "node:assert/strict"
+import {
+  PLUGIN_ERROR_CODES,
+  CODE_META,
+  isPluginErrorCode,
+  ERROR_ENVELOPE_VERSION,
+  isErrorEnvelope,
+  newErrorId,
+  PluginError,
+  PluginValidationError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginInternalError,
+  fromEnvelope,
+  makeClientEnvelope,
+} from "../dist/index.js"
+
+const CATEGORIES = [
+  "validation", "not_found", "permission", "handle", "quota",
+  "timeout", "transport", "lifecycle", "execution", "internal",
+]
+
+function envelope(overrides = {}) {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code: "OPERATION_FAILED",
+    message: "it failed",
+    errorId: "test-id-1",
+    ...overrides,
+  }
+}
+
+// --- codes registry ---------------------------------------------------------
+
+test("every code has CODE_META with a valid category (union↔meta completeness)", () => {
+  for (const code of PLUGIN_ERROR_CODES) {
+    const meta = CODE_META[code]
+    assert.ok(meta, `missing CODE_META for ${code}`)
+    assert.ok(CATEGORIES.includes(meta.category), `bad category for ${code}: ${meta.category}`)
+  }
+  assert.equal(Object.keys(CODE_META).length, PLUGIN_ERROR_CODES.length)
+})
+
+test("codes are unique", () => {
+  assert.equal(new Set(PLUGIN_ERROR_CODES).size, PLUGIN_ERROR_CODES.length)
+})
+
+test("isPluginErrorCode narrows union members and rejects strangers", () => {
+  assert.equal(isPluginErrorCode("HANDLE_INVALID"), true)
+  assert.equal(isPluginErrorCode("TOTALLY_MADE_UP"), false)
+  assert.equal(isPluginErrorCode(""), false)
+})
+
+// --- envelope ----------------------------------------------------------------
+
+test("isErrorEnvelope accepts a minimal valid envelope", () => {
+  assert.equal(isErrorEnvelope(envelope()), true)
+})
+
+test("isErrorEnvelope accepts codes OUTSIDE the union (forward compat)", () => {
+  assert.equal(isErrorEnvelope(envelope({ code: "FUTURE_CODE" })), true)
+})
+
+test("isErrorEnvelope rejects malformed values", () => {
+  assert.equal(isErrorEnvelope(null), false)
+  assert.equal(isErrorEnvelope("boom"), false)
+  assert.equal(isErrorEnvelope({}), false)
+  assert.equal(isErrorEnvelope(envelope({ envelopeVersion: 2 })), false)
+  assert.equal(isErrorEnvelope(envelope({ errorId: undefined })), false)
+})
+
+test("newErrorId returns unique prefixed ids", () => {
+  const a = newErrorId("c-")
+  const b = newErrorId("c-")
+  assert.notEqual(a, b)
+  assert.ok(a.startsWith("c-"))
+})
+
+// --- PluginError rehydration --------------------------------------------------
+
+test("fromEnvelope picks the category sugar subclass", () => {
+  assert.ok(fromEnvelope(envelope({ code: "VALIDATION" })) instanceof PluginValidationError)
+  assert.ok(fromEnvelope(envelope({ code: "RATE_LIMITED" })) instanceof PluginQuotaError)
+  assert.ok(fromEnvelope(envelope({ code: "TIMEOUT" })) instanceof PluginTimeoutError)
+  assert.ok(fromEnvelope(envelope({ code: "TRANSPORT_LOST" })) instanceof PluginTransportError)
+  assert.ok(fromEnvelope(envelope({ code: "INTERNAL" })) instanceof PluginInternalError)
+})
+
+test("fromEnvelope preserves envelope fields on the error", () => {
+  const err = fromEnvelope(
+    envelope({
+      code: "OPERATION_FAILED",
+      details: { op: "union", handles: ["mass_1", "mass_2"] },
+      handle: "mass_1",
+      methodPath: "design.boolean.union",
+      hint: "check overlap",
+    })
+  )
+  assert.equal(err.code, "OPERATION_FAILED")
+  assert.equal(err.message, "it failed")
+  assert.equal(err.errorId, "test-id-1")
+  assert.deepEqual(err.details, { op: "union", handles: ["mass_1", "mass_2"] })
+  assert.equal(err.handle, "mass_1")
+  assert.equal(err.methodPath, "design.boolean.union")
+  assert.equal(err.hint, "check overlap")
+  assert.equal(err.category, "execution")
+})
+
+test("unknown code constructs base PluginError with code preserved verbatim", () => {
+  const err = fromEnvelope(envelope({ code: "FUTURE_CODE" }))
+  assert.equal(err.constructor, PluginError)
+  assert.equal(err.code, "FUTURE_CODE")
+  assert.equal(err.category, "internal")
+  assert.equal(PluginError.is(err), true)
+})
+
+test("hint falls back to the code's template when the envelope has none", () => {
+  const err = fromEnvelope(envelope({ code: "RATE_LIMITED" }))
+  assert.equal(err.hint, CODE_META.RATE_LIMITED.hintTemplate)
+})
+
+test("PluginError.is matches the brand across class identities (dual SDK copy)", () => {
+  // Simulate a second bundled copy: a plain object carrying the Symbol.for
+  // brand but NOT part of this module's prototype chain.
+  const impostor = Object.assign(new Error("from other copy"), {
+    [Symbol.for("snaptrude.pluginError")]: true,
+    code: "TIMEOUT",
+  })
+  assert.equal(impostor instanceof PluginError, false)
+  assert.equal(PluginError.is(impostor), true)
+  assert.equal(PluginError.is(new Error("plain")), false)
+  assert.equal(PluginError.is(null), false)
+})
+
+// --- makeClientEnvelope --------------------------------------------------------
+
+test("makeClientEnvelope mints a c- prefixed id and passes extras through", () => {
+  const env = makeClientEnvelope("TRANSPORT_LOST", "port closed", {
+    methodPath: "design.boolean.union",
+  })
+  assert.equal(isErrorEnvelope(env), true)
+  assert.equal(env.code, "TRANSPORT_LOST")
+  assert.ok(env.errorId.startsWith("c-"))
+  assert.equal(env.methodPath, "design.boolean.union")
+})
+
+// --- Registry snapshot (append-only guard) -----------------------------------
+// Deliberate: adding a code REQUIRES updating this list in the same change so
+// the addition is reviewed; removing or renaming one must fail loudly forever.
+
+test("PLUGIN_ERROR_CODES matches the reviewed snapshot (append-only contract)", () => {
+  assert.deepEqual([...PLUGIN_ERROR_CODES], [
+    "VALIDATION",
+    "INVALID_RPC_FORMAT",
+    "METHOD_NOT_FOUND",
+    "METHOD_NOT_PERMITTED",
+    "HANDLE_INVALID",
+    "HANDLE_KIND_MISMATCH",
+    "RESOURCE_QUOTA_EXCEEDED",
+    "RATE_LIMITED",
+    "PRECONDITION_FAILED",
+    "OPERATION_FAILED",
+    "TIMEOUT",
+    "CALL_TIMEOUT",
+    "TRANSPORT_LOST",
+    "PLUGIN_NOT_READY",
+    "PLUGIN_TERMINATED",
+    "RESULT_NOT_SERIALIZABLE",
+    "RESULT_TOO_LARGE",
+    "BATCH_PARTIAL",
+    "STORY_UPDATE_FAILED",
+    "STORY_HEIGHT_REJECTED",
+    "NO_ACTIVE_STRUCTURE",
+    "NO_ELIGIBLE_ELEMENTS",
+    "PROPOSAL_SWITCH_BLOCKED",
+    "INTERNAL",
+    "UNKNOWN",
+  ])
+})

package/tsconfig.json

@@ -3,7 +3,10 @@
     "target": "ES2020",
     "module": "ES2020",
     "moduleResolution": "bundler",
-    "lib": ["ES2020"],
+    "lib": [
+      "ES2020",
+      "ESNext.Disposable"
+    ],
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
@@ -13,5 +16,7 @@
     "declarationMap": true,
     "outDir": "dist"
   },
-  "include": ["src/**/*.ts"]
+  "include": [
+    "src/**/*.ts"
+  ]
 }