@snaptrude/plugin-core 0.6.0 → 0.7.0

package/src/api/program/areas.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PluginAreaUnit } from "./metrics"
+import { PluginAreaClass } from "../entity/space"
 import { ComponentHandle } from "../../handles"
 
 /**
@@ -12,15 +13,25 @@ import { ComponentHandle } from "../../handles"
  * department-allocation lens (targets vs allocated area per department); this
  * namespace is the whole-program area/FAR summary and its groupings.
  *
+ * **Net vs gross:** the `carpet` / `builtUp` / `excluded` figures are the three
+ * area *classes* — every space's whole footprint lands in exactly one, chosen
+ * by its `areaClass` (see {@linkcode PluginProgramAreaMember.areaClass}). In UI
+ * terms `carpet` is the **Net Internal Area** (Σ of `NET`-classed spaces), and
+ * `builtUp` is the **Gross External Area** (Σ of `GROSS`-classed spaces) — so
+ * "net" and "gross" are the plain-English synonyms for `carpet` and `builtUp`.
+ * These are not wall-thickness carpet-vs-super-built-up; there is no common-area
+ * math. Note the summary also folds in non-mass elements (floors count as NET,
+ * slabs as GROSS), so **summing `listMembers` spaces does not reconcile to the
+ * summary totals**.
+ *
  * `achievedFar` is **derived and read-only** — computed from built-up area and
  * site area. `targetFar` is the goal you set (via {@linkcode
  * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
  * one intended. The surface speaks **FAR only** — there is no FSI alias.
  *
- * Reads return plain records and never throw. The write member typed as optional
- * (`?`) is **authored ahead of the host** — declared so plugins and codegen can
- * see the shape, but kept out of the discovery manifest until the host lands it
- * (at which point it is promoted to a required `abstract` member).
+ * Reads return plain records and never throw. The only write —
+ * {@linkcode PluginProgramAreasApi.update} — is a non-undoable settings write
+ * for the FAR inputs.
  *
  * Accessed via `snaptrude.program.areas`.
  */
@@ -38,6 +49,8 @@ export abstract class PluginProgramAreasApi {
    *
    * @examplePrompt What's my FAR right now?
    * @examplePrompt Give me the program area summary
+   * @examplePrompt What is my net internal area vs gross external area?
+   * @examplePrompt How much net and gross area do I have?
    * @examplePrompt How much built-up area have I used against the site area?
    * @examplePrompt Am I within my FAR target?
    *
@@ -62,6 +75,7 @@ export abstract class PluginProgramAreasApi {
    *   (empty when the program has no spaces).
    *
    * @examplePrompt Break down the area by storey
+   * @examplePrompt Break down net vs gross area by storey
    * @examplePrompt Show the area rollup per department
    * @examplePrompt Group the built-up area by building
    *
@@ -92,6 +106,7 @@ export abstract class PluginProgramAreasApi {
    *   array (empty when the group is missing or empty).
    *
    * @examplePrompt List the spaces on this storey with their areas
+   * @examplePrompt Which spaces are net and which are gross on this storey?
    * @examplePrompt What rooms are in the Bedrooms department bucket?
    * @examplePrompt Break the storey area down into individual spaces
    *
@@ -142,9 +157,9 @@ export abstract class PluginProgramAreasApi {
  * |---|---|---|
  * | `count` | `number` | Number of spaces in the program (a count, not an area) |
  * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
- * | `carpet` | `number` | Total carpet area in `areaUnit` |
- * | `builtUp` | `number` | Total built-up area in `areaUnit` |
- * | `excluded` | `number` | Total excluded area in `areaUnit` |
+ * | `carpet` | `number` | Total **Net Internal Area** ("net") — Σ `NET`-classed spaces + floors — in `areaUnit` |
+ * | `builtUp` | `number` | Total **Gross External Area** ("gross") — Σ `GROSS`-classed spaces + slabs — in `areaUnit` |
+ * | `excluded` | `number` | Total **Excluded Area** — Σ `EXCLUDED`-classed spaces — in `areaUnit` |
  * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
  * | `siteArea` | `number` | Site/plot area in `areaUnit` |
  * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
@@ -177,8 +192,8 @@ export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>
  * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
  * | `name` | `string` | Display name of the group |
  * | `color` | `string` | CSS hex color string for the group |
- * | `carpet` | `number` | Carpet area for this group |
- * | `builtUp` | `number` | Built-up area for this group |
+ * | `carpet` | `number` | Net Internal Area ("net") for this group |
+ * | `builtUp` | `number` | Gross External Area ("gross") for this group |
  * | `excluded` | `number` | Excluded area for this group |
  * | `count` | `number` | Number of spaces in this group |
  * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
@@ -201,18 +216,25 @@ export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>
  * A single space within an area group. Area figures are in the program's area
  * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
  *
+ * `areaClass` is the space's effective classification — it decides which of the
+ * three buckets the space's whole footprint lands in: `NET` → `carpet` ("net"),
+ * `GROSS` → `builtUp` ("gross"), `EXCLUDED` → `excluded`. So for any one member
+ * exactly one of `carpet` / `builtUp` / `excluded` is non-zero.
+ *
  * | Property | Type | Description |
  * |---|---|---|
  * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
  * | `label` | `string` | Display label of the space |
- * | `carpet` | `number` | Carpet area of the space |
- * | `builtUp` | `number` | Built-up area of the space |
- * | `excluded` | `number` | Excluded area of the space |
+ * | `areaClass` | {@linkcode PluginAreaClass} | Effective area class — `"NET"` (→ `carpet`), `"GROSS"` (→ `builtUp`), or `"EXCLUDED"` |
+ * | `carpet` | `number` | Net area of the space (non-zero when `areaClass` is `"NET"`) |
+ * | `builtUp` | `number` | Gross area of the space (non-zero when `areaClass` is `"GROSS"`) |
+ * | `excluded` | `number` | Excluded area of the space (non-zero when `areaClass` is `"EXCLUDED"`) |
  * | `isVisible` | `boolean` | Whether the space is currently visible |
  */
 export const PluginProgramAreaMember = z.object({
   id: ComponentHandle,
   label: z.string(),
+  areaClass: PluginAreaClass,
   carpet: z.number(),
   builtUp: z.number(),
   excluded: z.number(),

package/src/api/program/index.ts

@@ -19,7 +19,7 @@ import { PluginProgramAreasApi } from "./areas"
  *
  * - {@linkcode PluginProgramApi.departments} — Read & edit program departments (groupings + targets)
  * - {@linkcode PluginProgramApi.adjacency} — Read & compute the department/space adjacency matrix
- * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope (authored ahead)
+ * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope
  * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
  * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
@@ -27,11 +27,6 @@ import { PluginProgramAreasApi } from "./areas"
  * - {@linkcode PluginProgramApi.cores} — Read & trigger vertical-circulation cores
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
  *
- * Sub-namespaces typed as optional (`?`) are **authored ahead of the host** —
- * declared so plugins and codegen can see the shape, but not required of host
- * implementations and kept out of the discovery manifest until the host lands
- * them (at which point they are promoted to required `abstract` members).
- *
  * Accessed via `snaptrude.program`.
  */
 export abstract class PluginProgramApi {
@@ -39,11 +34,8 @@ export abstract class PluginProgramApi {
   public abstract departments: PluginProgramDepartmentsApi
   /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
   public abstract adjacency: PluginProgramAdjacencyApi
-  /**
-   * Arrange/pack spaces in the envelope. See {@linkcode PluginProgramLayoutApi}.
-   * _(authored ahead — optional until the host lands it next increment.)_
-   */
-  public layout?: PluginProgramLayoutApi
+  /** Arrange/pack spaces in the envelope (async job family). See {@linkcode PluginProgramLayoutApi}. */
+  public abstract layout: PluginProgramLayoutApi
   /** Area-program summary — targets vs allocated area. See {@linkcode PluginProgramMetricsApi}. */
   public abstract metrics: PluginProgramMetricsApi
   /** FAR / built-up-area rollup and groupings. See {@linkcode PluginProgramAreasApi}. */

package/src/api/program/layout.ts

@@ -9,8 +9,20 @@ import { PluginApiReturn } from "../../types"
  * three of the space-planning workflow that starts with
  * {@linkcode PluginProgramAdjacencyApi} (`program.adjacency`).
  *
- * _(Authored ahead — both methods are optional until the host lands them in
- * the next increment, and are kept out of the discovery manifest until then.)_
+ * Both {@linkcode PluginProgramLayoutApi.arrange} and
+ * {@linkcode PluginProgramLayoutApi.pack} run as an **asynchronous backend
+ * job** on the space-solver service:
+ *
+ * 1. `arrange` / `pack` start the job and **return immediately** — they do
+ *    not wait for the layout.
+ * 2. Poll {@linkcode PluginProgramLayoutApi.getState} until `status` is no
+ *    longer `"running"` — a run can take up to 20 minutes.
+ * 3. {@linkcode PluginProgramLayoutApi.cancel} aborts an in-flight run.
+ *
+ * `arrange` produces several candidate layouts and **auto-commits the first
+ * solution** as one undoable edit (there is no interactive solution-review
+ * over the plugin boundary); `pack` re-shapes and applies its single result
+ * directly. Both are **Pro-plan-gated**, matching the product UI.
  *
  * Accessed via `snaptrude.program.layout`.
  */
@@ -19,7 +31,29 @@ export abstract class PluginProgramLayoutApi {
 
   /**
    * Arrange the spaces inside the envelope using the computed adjacency data.
-   * _(Authored ahead — optional until the host lands.)_
+   *
+   * Starts the backend job and **returns immediately** — poll
+   * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
+   * `"running"` (a run can take up to 20 minutes). The solver produces
+   * several candidate layouts; this **auto-commits the first solution** as one
+   * undoable edit (no interactive review over the plugin boundary). Starting a
+   * run while one is in flight replaces it.
+   *
+   * With no `options`, operates on the eligible Room/Department masses on the
+   * active storey and auto-detects the single buildable envelope there.
+   *
+   * @param options - Optional {@linkcode PluginProgramLayoutRunArgs} — the
+   *   space / department masses to arrange and the envelope to fit them in.
+   *   Omitted fields fall back to the active-storey defaults.
+   * @returns A {@linkcode PluginProgramLayoutRunResult} — `{ success: true }`
+   *   when the job was started. Solver failures surface through
+   *   {@linkcode PluginProgramLayoutApi.getState} (`status: "inactive"`), not
+   *   as a rejected call.
+   * @throws When the project is not on a Pro plan.
+   * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
+   * @throws When more than one envelope is on the active storey and none was
+   *   given (ambiguous).
+   * @throws When plugin writes are disabled.
    *
    * @examplePrompt Arrange the rooms in the envelope
    * @examplePrompt Lay out the departments inside the building envelope
@@ -28,14 +62,43 @@ export abstract class PluginProgramLayoutApi {
    * # Example
    * ```ts
    * const { success, error } = await snaptrude.program.layout.arrange()
-   * if (!success) console.log("Arrange failed:", error)
+   * if (!success) throw new Error(error)
+   * // poll until the layout is applied
+   * let job = await snaptrude.program.layout.getState()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.program.layout.getState()
+   * }
    * ```
    */
-  public arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+  public abstract arrange(
+    options?: PluginProgramLayoutRunArgs,
+  ): PluginApiReturn<PluginProgramLayoutRunResult>
 
   /**
    * Pack the spaces into the envelope (a tighter fit than arrange).
-   * _(Authored ahead — optional until the host lands.)_
+   *
+   * Like {@linkcode PluginProgramLayoutApi.arrange}, this starts the backend
+   * job and **returns immediately** — poll
+   * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
+   * `"running"` (up to 20 minutes). Pack re-shapes mass geometry to fit and
+   * **applies its single result directly** (no solution review). Starting a
+   * run while one is in flight replaces it.
+   *
+   * With no `options`, operates on the eligible Room/Department masses on the
+   * active storey and auto-detects the single buildable envelope there.
+   *
+   * @param options - Optional {@linkcode PluginProgramLayoutRunArgs} — same
+   *   shape as `arrange`; omitted fields fall back to the active-storey
+   *   defaults.
+   * @returns A {@linkcode PluginProgramLayoutRunResult} — `{ success: true }`
+   *   when the job was started. Solver failures surface through
+   *   {@linkcode PluginProgramLayoutApi.getState} (`status: "inactive"`).
+   * @throws When the project is not on a Pro plan.
+   * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
+   * @throws When more than one envelope is on the active storey and none was
+   *   given (ambiguous).
+   * @throws When plugin writes are disabled.
    *
    * @examplePrompt Pack the rooms into the envelope
    * @examplePrompt Fit the program spaces tightly into the building
@@ -43,20 +106,99 @@ export abstract class PluginProgramLayoutApi {
    *
    * # Example
    * ```ts
-   * const { success, error } = await snaptrude.program.layout.pack()
-   * if (!success) console.log("Pack failed:", error)
+   * const { success } = await snaptrude.program.layout.pack({ envelopeId: "be_..." })
+   * let job = await snaptrude.program.layout.getState()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.program.layout.getState()
+   * }
+   * ```
+   */
+  public abstract pack(
+    options?: PluginProgramLayoutRunArgs,
+  ): PluginApiReturn<PluginProgramLayoutRunResult>
+
+  /**
+   * Get the state of the layout run.
+   *
+   * The polling read for the async job started by
+   * {@linkcode PluginProgramLayoutApi.arrange} /
+   * {@linkcode PluginProgramLayoutApi.pack}. `status` values:
+   *
+   * | Status | Meaning |
+   * |---|---|
+   * | `"running"` | A run is in flight — keep polling |
+   * | `"active"` | The run finished and its layout is applied to the model |
+   * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
+   *
+   * @returns A {@linkcode PluginProgramLayoutStateResult} with the run
+   *   `status`, or `null` when no run result is available (never ran or was
+   *   cancelled).
+   *
+   * @examplePrompt Is the arrange done?
+   * @examplePrompt Check the status of the layout run
+   * @examplePrompt Did the pack finish?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.program.layout.getState()
+   * if (job?.status === "active") console.log("layout applied")
+   * ```
+   */
+  public abstract getState(): PluginApiReturn<PluginProgramLayoutStateResult>
+
+  /**
+   * Cancel the in-flight layout run.
+   *
+   * Aborts the backend job and discards any pending solution. A no-op
+   * (returns `false`) when nothing is running.
+   *
+   * @returns `true` when a run was cancelled, `false` when nothing was
+   *   running.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Cancel the arrange
+   * @examplePrompt Stop the running layout job
+   * @examplePrompt Abort the pack in envelope
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.layout.cancel()
    * ```
    */
-  public pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+  public abstract cancel(): PluginApiReturn<boolean>
 }
 
+/**
+ * Arguments for {@linkcode PluginProgramLayoutApi.arrange} /
+ * {@linkcode PluginProgramLayoutApi.pack}. All fields are optional — omitted
+ * fields fall back to the eligible masses and the single envelope on the
+ * active storey.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `string[] \| undefined` | Component ids of the Room masses to lay out |
+ * | `departmentIds` | `string[] \| undefined` | Component ids of the Department masses to lay out |
+ * | `envelopeId` | `string \| undefined` | The envelope to fit into — a mass component id or a buildable-envelope handle (`be_…`); omit to auto-detect the single envelope on the active storey |
+ */
+export const PluginProgramLayoutRunArgs = z.object({
+  spaceIds: z.array(z.string()).optional(),
+  departmentIds: z.array(z.string()).optional(),
+  envelopeId: z.string().optional(),
+})
+export type PluginProgramLayoutRunArgs = z.infer<
+  typeof PluginProgramLayoutRunArgs
+>
+
 /**
  * Result of {@linkcode PluginProgramLayoutApi.arrange} /
- * {@linkcode PluginProgramLayoutApi.pack}.
+ * {@linkcode PluginProgramLayoutApi.pack} — reports whether the run was
+ * **started**, not whether the layout finished (poll
+ * {@linkcode PluginProgramLayoutApi.getState} for completion).
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `success` | `boolean` | Whether the layout run completed |
+ * | `success` | `boolean` | Whether the layout run was started |
  * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
  */
 export const PluginProgramLayoutRunResult = z.object({
@@ -66,3 +208,45 @@ export const PluginProgramLayoutRunResult = z.object({
 export type PluginProgramLayoutRunResult = z.infer<
   typeof PluginProgramLayoutRunResult
 >
+
+/**
+ * The status of a layout run.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"running"` | A run is in flight — keep polling |
+ * | `"active"` | The run finished and its layout is applied to the model |
+ * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
+ */
+export const PluginProgramLayoutJobStatus = z.enum([
+  "running",
+  "active",
+  "inactive",
+])
+export type PluginProgramLayoutJobStatus = z.infer<
+  typeof PluginProgramLayoutJobStatus
+>
+
+/**
+ * The state of a layout run.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` |
+ */
+export const PluginProgramLayoutJobState = z.object({
+  status: PluginProgramLayoutJobStatus,
+})
+export type PluginProgramLayoutJobState = z.infer<
+  typeof PluginProgramLayoutJobState
+>
+
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.getState} — the run state, or
+ * `null` when no run result is available (never ran or was cancelled).
+ */
+export const PluginProgramLayoutStateResult =
+  PluginProgramLayoutJobState.nullable()
+export type PluginProgramLayoutStateResult = z.infer<
+  typeof PluginProgramLayoutStateResult
+>

package/src/errors/codes.ts

@@ -0,0 +1,136 @@
+/**
+ * The closed error-code registry — the single source of truth for every error
+ * that crosses the plugin wire (host → worker) or is minted client-side.
+ *
+ * APPEND-ONLY: codes are a published contract; never rename or remove one.
+ * Handle-resolution failures deliberately collapse to ONE code
+ * (`HANDLE_INVALID`) so error responses cannot be used as an existence /
+ * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6). `HANDLE_KIND_MISMATCH`
+ * stays distinct because the kind is information the caller already holds.
+ */
+export const 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",
+] as const
+
+export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number]
+
+/**
+ * A known code, or a string outside the union — a plugin built against an
+ * older SDK may receive codes a newer host appended. Keeps autocomplete for
+ * known codes while staying open on the wire (forward compatibility).
+ */
+export type WirePluginErrorCode = PluginErrorCode | (string & {})
+
+export type PluginErrorCategory =
+  | "validation"
+  | "not_found"
+  | "permission"
+  | "handle"
+  | "quota"
+  | "timeout"
+  | "transport"
+  | "lifecycle"
+  | "execution"
+  | "internal"
+
+/**
+ * Client-side metadata for a code. NOT carried on the wire — every field is a
+ * pure function of the code, and this table ships inside plugin-core, so both
+ * endpoints derive it locally.
+ */
+export interface CodeMeta {
+  /** Family of the code; picks the `PluginError` sugar subclass. */
+  category: PluginErrorCategory
+  /** Fallback `hint` when the throw site provides none. */
+  hintTemplate?: string
+}
+
+export const CODE_META: Record<PluginErrorCode, CodeMeta> = {
+  VALIDATION: {
+    category: "validation",
+    hintTemplate: "Check details.issues for the failing argument.",
+  },
+  INVALID_RPC_FORMAT: { category: "validation" },
+  METHOD_NOT_FOUND: {
+    category: "not_found",
+    hintTemplate: "Check details.didYouMean for a close match.",
+  },
+  METHOD_NOT_PERMITTED: { category: "permission" },
+  HANDLE_INVALID: {
+    category: "handle",
+    hintTemplate: "Re-query the entity; do not cache handles across undo/reload.",
+  },
+  HANDLE_KIND_MISMATCH: { category: "handle" },
+  RESOURCE_QUOTA_EXCEEDED: {
+    category: "quota",
+    hintTemplate: "Release unused handles (core.handles.release) or use scopes.",
+  },
+  RATE_LIMITED: {
+    category: "quota",
+    hintTemplate: "Wait details.retryAfterMs before retrying.",
+  },
+  PRECONDITION_FAILED: { category: "execution" },
+  OPERATION_FAILED: { category: "execution" },
+  TIMEOUT: { category: "timeout" },
+  CALL_TIMEOUT: { category: "timeout" },
+  TRANSPORT_LOST: { category: "transport" },
+  PLUGIN_NOT_READY: { category: "lifecycle" },
+  PLUGIN_TERMINATED: { category: "lifecycle" },
+  RESULT_NOT_SERIALIZABLE: { category: "execution" },
+  RESULT_TOO_LARGE: { category: "execution" },
+  BATCH_PARTIAL: { category: "execution" },
+  STORY_UPDATE_FAILED: {
+    category: "execution",
+    hintTemplate: "The storey update could not be applied; re-read the storey and retry.",
+  },
+  STORY_HEIGHT_REJECTED: {
+    category: "execution",
+    hintTemplate: "The requested height was out of range; pick a value within the storey's limits.",
+  },
+  NO_ACTIVE_STRUCTURE: {
+    category: "execution",
+    hintTemplate: "Activate a structure before running this operation.",
+  },
+  NO_ELIGIBLE_ELEMENTS: {
+    category: "execution",
+    hintTemplate: "The storey has no elements eligible for this operation.",
+  },
+  PROPOSAL_SWITCH_BLOCKED: {
+    category: "execution",
+    hintTemplate: "Wait for the in-canvas agent run to finish, then retry.",
+  },
+  INTERNAL: {
+    category: "internal",
+    hintTemplate: "Host-side fault. Report with errorId.",
+  },
+  UNKNOWN: { category: "internal" },
+}
+
+/** Narrow an arbitrary string to a member of the closed code union. */
+export function isPluginErrorCode(value: string): value is PluginErrorCode {
+  return (PLUGIN_ERROR_CODES as readonly string[]).includes(value)
+}

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"