@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/errors/codes.ts

@@ -1,136 +1,143 @@
-/**
- * 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)
-}
+/**
+ * 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.
+ * `HANDLE_STALE` is the one deliberate exception: a handle the caller
+ * legitimately held whose entity was since retired (deleted or rebuilt).
+ */
+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",
+  "HANDLE_STALE",
+] 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" },
+  HANDLE_STALE: {
+    category: "handle",
+    hintTemplate: "The entity was deleted or rebuilt; re-query it for a fresh 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

@@ -1,75 +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)}`
-}
+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

@@ -1,21 +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"
+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"