@snaptrude/plugin-core 0.6.0 → 0.7.1

package/dist/api/program/layout.d.ts

@@ -8,8 +8,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`.
  */
@@ -17,7 +29,29 @@ export declare abstract class PluginProgramLayoutApi {
     constructor();
     /**
      * 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
@@ -26,13 +60,40 @@ export declare 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()
+     * }
      * ```
      */
-    arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>;
+    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
@@ -40,19 +101,91 @@ export declare 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()
+     * }
+     * ```
+     */
+    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")
+     * ```
+     */
+    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()
      * ```
      */
-    pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>;
+    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 declare const PluginProgramLayoutRunArgs: z.ZodObject<{
+    spaceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    departmentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    envelopeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginProgramLayoutRunResult: z.ZodObject<{
@@ -60,4 +193,46 @@ export declare const PluginProgramLayoutRunResult: z.ZodObject<{
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 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 declare const PluginProgramLayoutJobStatus: z.ZodEnum<{
+    running: "running";
+    active: "active";
+    inactive: "inactive";
+}>;
+export type PluginProgramLayoutJobStatus = z.infer<typeof PluginProgramLayoutJobStatus>;
+/**
+ * The state of a layout run.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` |
+ */
+export declare const PluginProgramLayoutJobState: z.ZodObject<{
+    status: z.ZodEnum<{
+        running: "running";
+        active: "active";
+        inactive: "inactive";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramLayoutStateResult: z.ZodNullable<z.ZodObject<{
+    status: z.ZodEnum<{
+        running: "running";
+        active: "active";
+        inactive: "inactive";
+    }>;
+}, z.core.$strip>>;
+export type PluginProgramLayoutStateResult = z.infer<typeof PluginProgramLayoutStateResult>;
 //# sourceMappingURL=layout.d.ts.map

package/dist/api/program/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;OAaG;IACI,OAAO,CAAC,EAAE,MAAM,eAAe,CAAC,4BAA4B,CAAC,CAAA;IAEpE;;;;;;;;;;;;;OAaG;IACI,IAAI,CAAC,EAAE,MAAM,eAAe,CAAC,4BAA4B,CAAC,CAAA;CAClE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;aACa,OAAO,CACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;aACa,IAAI,CAClB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;aACa,QAAQ,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAE3E;;;;;;;;;;;;;;;;;;OAkBG;aACa,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;iBAIrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;;EAIvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAEtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;kBACH,CAAA;AACxC,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}

package/dist/errors/codes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare const PLUGIN_ERROR_CODES: readonly ["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"];
+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 declare const CODE_META: Record<PluginErrorCode, CodeMeta>;
+/** Narrow an arbitrary string to a member of the closed code union. */
+export declare function isPluginErrorCode(value: string): value is PluginErrorCode;
+//# sourceMappingURL=codes.d.ts.map

package/dist/errors/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,kgBA0BrB,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjE;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjE,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,CAAA;AAEd;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CA2DvD,CAAA;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE"}

package/dist/errors/envelope.d.ts

@@ -0,0 +1,56 @@
+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 declare const ERROR_ENVELOPE_VERSION: 1;
+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 declare function isErrorEnvelope(value: unknown): value is ErrorEnvelope;
+/**
+ * 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 declare function newErrorId(prefix?: string): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/errors/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/errors/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAElD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAA;AAEhD,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,OAAO,sBAAsB,CAAA;IAC9C,IAAI,EAAE,mBAAmB,CAAA;IACzB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAStE;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAK,GAAG,MAAM,CAK9C"}

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC1E,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAElG,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAChF,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAA"}

package/dist/errors/plugin-error.d.ts

@@ -0,0 +1,69 @@
+import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes";
+import type { ErrorEnvelope } from "./envelope";
+/**
+ * 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 declare 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);
+    /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
+    static is(value: unknown): value is PluginError;
+    /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
+    get category(): PluginErrorCategory;
+}
+export declare class PluginValidationError extends PluginError {
+}
+export declare class PluginNotFoundError extends PluginError {
+}
+export declare class PluginPermissionError extends PluginError {
+}
+export declare class PluginHandleError extends PluginError {
+}
+export declare class PluginQuotaError extends PluginError {
+}
+export declare class PluginTimeoutError extends PluginError {
+}
+export declare class PluginTransportError extends PluginError {
+}
+export declare class PluginLifecycleError extends PluginError {
+}
+export declare class PluginExecutionError extends PluginError {
+}
+export declare class PluginInternalError extends PluginError {
+}
+/**
+ * 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 declare function fromEnvelope(envelope: ErrorEnvelope): PluginError;
+/**
+ * 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 declare function makeClientEnvelope(code: PluginErrorCode, message: string, extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>): ErrorEnvelope;
+//# sourceMappingURL=plugin-error.d.ts.map

package/dist/errors/plugin-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-error.d.ts","sourceRoot":"","sources":["../../src/errors/plugin-error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAExF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAc/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;gBAEV,QAAQ,EAAE,aAAa;IAYnC,wFAAwF;IACxF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;IAQ/C,sFAAsF;IACtF,IAAI,QAAQ,IAAI,mBAAmB,CAElC;CACF;AAID,qBAAa,qBAAsB,SAAQ,WAAW;CAAG;AACzD,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AACvD,qBAAa,qBAAsB,SAAQ,WAAW;CAAG;AACzD,qBAAa,iBAAkB,SAAQ,WAAW;CAAG;AACrD,qBAAa,gBAAiB,SAAQ,WAAW;CAAG;AACpD,qBAAa,kBAAmB,SAAQ,WAAW;CAAG;AACtD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AAqBvD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,CAIjE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC,GACjF,aAAa,CAQf"}

package/dist/host-utils.d.ts

@@ -1,4 +1,5 @@
 import type { PluginApi } from "./api";
+import type { ErrorEnvelope } from "./errors";
 /**
  * UnionToIntersection is a type utility that converts a union type to an intersection type.
  */
@@ -37,7 +38,10 @@ export type PluginApiCallResult<M extends PluginApiMethod> = PluginApiMethodMap[
 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;
 };
 export {};
 //# sourceMappingURL=host-utils.d.ts.map

package/dist/host-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-utils.d.ts","sourceRoot":"","sources":["../src/host-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;GAEG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAC7E,CAAC,EAAE,MAAM,CAAC,KACP,IAAI,GACL,CAAC,GACD,KAAK,CAAA;AAET,KAAK,OAAO,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1C;;;GAGG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;AAElE,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAE7E;;;GAGG;AACH,KAAK,kBAAkB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI;KACtD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GACzD,MAAM,CACJ,GAAG,MAAM,GAAG,CAAC,EAAE,EACf;QAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CACvD,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,GAC1C,KAAK;CACZ,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAInB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,mBAAmB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CACnD,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI;IAC9E,MAAM,EAAE,CAAC,CAAA;IACT,wEAAwE;IACxE,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,eAAe,IACvD,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAEjC,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,eAAe,IAAI;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAA"}
+{"version":3,"file":"host-utils.d.ts","sourceRoot":"","sources":["../src/host-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI7C;;GAEG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAC7E,CAAC,EAAE,MAAM,CAAC,KACP,IAAI,GACL,CAAC,GACD,KAAK,CAAA;AAET,KAAK,OAAO,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1C;;;GAGG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;AAElE,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAE7E;;;GAGG;AACH,KAAK,kBAAkB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI;KACtD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GACzD,MAAM,CACJ,GAAG,MAAM,GAAG,CAAC,EAAE,EACf;QAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CACvD,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,GAC1C,KAAK;CACZ,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAInB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,mBAAmB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CACnD,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI;IAC9E,MAAM,EAAE,CAAC,CAAA;IACT,wEAAwE;IACxE,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,eAAe,IACvD,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAEjC,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,eAAe,IAAI;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B,CAAA"}