@snaptrude/plugin-core 0.10.0 → 0.11.0-rc.1

package/src/errors/codes.ts

@@ -5,8 +5,13 @@
  * 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.
+ * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6) — with one deliberate
+ * exception: `HANDLE_STALE` marks a handle the caller legitimately held that a
+ * parametric resolution (merge / split / rebuild) has since retired — a
+ * lifetime fact about the caller's own write-scoped handle, not an oracle
+ * (forged / never-issued ids still collapse to `HANDLE_INVALID`).
+ * `HANDLE_KIND_MISMATCH` stays distinct because the kind is information the
+ * caller already holds.
  */
 export const PLUGIN_ERROR_CODES = [
   "VALIDATION",
@@ -32,6 +37,10 @@ export const PLUGIN_ERROR_CODES = [
   "NO_ACTIVE_STRUCTURE",
   "NO_ELIGIBLE_ELEMENTS",
   "PROPOSAL_SWITCH_BLOCKED",
+  "HANDLE_STALE",
+  "KIND_HIDDEN_IN_MODE",
+  "MERGED_INTO_EXISTING",
+  "BLOCKED_IN_BIM",
   "INTERNAL",
   "UNKNOWN",
 ] as const
@@ -123,6 +132,25 @@ export const CODE_META: Record<PluginErrorCode, CodeMeta> = {
     category: "execution",
     hintTemplate: "Wait for the in-canvas agent run to finish, then retry.",
   },
+  HANDLE_STALE: {
+    category: "handle",
+    hintTemplate:
+      "The entity was retired by a parametric resolution (merge/split/rebuild); re-query for its successor.",
+  },
+  KIND_HIDDEN_IN_MODE: {
+    category: "execution",
+    hintTemplate:
+      "This entity kind has no representation in the current mode/LOD; switch mode or target a visible kind.",
+  },
+  MERGED_INTO_EXISTING: {
+    category: "execution",
+    hintTemplate:
+      "The created geometry merged into an existing entity; use the surviving handles from details.",
+  },
+  BLOCKED_IN_BIM: {
+    category: "execution",
+    hintTemplate: "This operation is unavailable in BIM mode; switch to Design and retry.",
+  },
   INTERNAL: {
     category: "internal",
     hintTemplate: "Host-side fault. Report with errorId.",

package/test/errors.test.mjs

@@ -178,6 +178,10 @@ test("PLUGIN_ERROR_CODES matches the reviewed snapshot (append-only contract)",
     "NO_ACTIVE_STRUCTURE",
     "NO_ELIGIBLE_ELEMENTS",
     "PROPOSAL_SWITCH_BLOCKED",
+    "HANDLE_STALE",
+    "KIND_HIDDEN_IN_MODE",
+    "MERGED_INTO_EXISTING",
+    "BLOCKED_IN_BIM",
     "INTERNAL",
     "UNKNOWN",
   ])