fix(spec): try_catch nodeId and errorVariable describes say what the engine binds

.changeset/24659-try-catch-describes.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/spec': patch
+---
+
+Automation: two help sentences on `try_catch` now match what the engine binds. The error value's `nodeId` is described as the id of the Try / Catch node itself (not the failing inner step, which is normally named inside `message`), and `errorVariable` says in words what the bound value carries instead of naming a code type. Schema and runtime behaviour are unchanged; the generated reference page and the shipped JSON schema carry the new text.

content/docs/references/automation/control-flow.mdx

@@ -244,7 +244,7 @@ const result = FlowRegionSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **try** | `{ nodes: object[]; edges?: object[] }` | ✅ | Protected region |
 | **catch** | `{ nodes: object[]; edges?: object[] }` | optional | Handler region run when the try region fails |
-| **errorVariable** | `string` | optional (default: `"$error"`) | Variable holding the caught error in the catch region — `$error` (the default), or a name without a leading `$` read as `{{ name.message }}`; any other `$` name is the flow engine's own and refused. The value is a `TryCatchErrorValue`: `nodeId`, `message`, `code` when the failing node carried a platform-classified error code (ADR-0112 — branch on `$error.code` to tell "the row is already there" from "the store is down"), and `iteration` / `item` when the failure happened inside a loop body |
+| **errorVariable** | `string` | optional (default: `"$error"`) | Variable holding the caught error in the catch region — `$error` (the default), or a name without a leading `$` read as `{{ name.message }}`; any other `$` name is the flow engine's own and refused. It carries the id of this Try / Catch node (`nodeId`), the failure message, which normally names the step that failed (`message`), the platform-classified error code when that step reported one (`code`, ADR-0112 — branch on `$error.code` to tell "the row is already there" from "the store is down"), and, when the failure happened inside a loop body, the zero-based pass number (`iteration`) and the item being processed (`item`) |
 | **retry** | `{ maxRetries?: integer; backoffMs?: integer; backoffMultiplier?: number; maxRetryDelayMs?: integer; … }` | optional | Optional retry policy for the try region |
 
 ### Nested Shape: `TryCatchConfig.try`
@@ -281,7 +281,7 @@ const result = FlowRegionSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **nodeId** | `string` | ✅ | Node the failure is attributed to |
+| **nodeId** | `string` | ✅ | Id of this Try / Catch node, not of the step that failed inside its try region; that step is normally named inside `message` |
 | **message** | `string` | ✅ | Message of the error that ended the try region, after any retries |
 | **code** | `string` | optional | Platform-classified error code (ADR-0112) of the failure that ended the try region, e.g. `create_record`'s `DUPLICATE_RECORD`; present only when the failing node's own result carried one, so a catch region branching on `$error.code` treats "unset" as "no classified code", never as "nothing failed". An open `string`, not a closed enum: the vocabulary is `StandardErrorCode` plus registered ledger codes plus tenant-authored codes, and third-party node executors bind their own |
 | **iteration** | `integer` | optional | Zero-based iteration of the enclosing loop when the failure happened inside a loop body; absent outside a loop |

packages/spec/src/automation/control-flow.zod.ts

@@ -339,7 +339,7 @@ export const TryCatchConfigSchema = lazySchema(() => strictObject(
      * any other `$` name is the engine's, and a text slot could not read it
      * (#22502).
      */
-    errorVariable: flowBoundVariableNameSchema('errorVariable').default(ENGINE_ERROR_VARIABLE).describe('Variable holding the caught error in the catch region — `$error` (the default), or a name without a leading `$` read as `{{ name.message }}`; any other `$` name is the flow engine\'s own and refused. The value is a `TryCatchErrorValue`: `nodeId`, `message`, `code` when the failing node carried a platform-classified error code (ADR-0112 — branch on `$error.code` to tell "the row is already there" from "the store is down"), and `iteration` / `item` when the failure happened inside a loop body'),
+    errorVariable: flowBoundVariableNameSchema('errorVariable').default(ENGINE_ERROR_VARIABLE).describe('Variable holding the caught error in the catch region — `$error` (the default), or a name without a leading `$` read as `{{ name.message }}`; any other `$` name is the flow engine\'s own and refused. It carries the id of this Try / Catch node (`nodeId`), the failure message, which normally names the step that failed (`message`), the platform-classified error code when that step reported one (`code`, ADR-0112 — branch on `$error.code` to tell "the row is already there" from "the store is down"), and, when the failure happened inside a loop body, the zero-based pass number (`iteration`) and the item being processed (`item`)'),
     retry: RetryPolicySchema.optional().describe('Optional retry policy for the try region'),
   },
 ));
@@ -383,7 +383,7 @@ export type TryCatchConfigParsed = z.infer<typeof TryCatchConfigSchema>;
  * the `nodeId` / `message` core; this schema declares the try/catch binding.
  */
 export const TryCatchErrorValueSchema = lazySchema(() => z.object({
-  nodeId: z.string().describe('Node the failure is attributed to'),
+  nodeId: z.string().describe('Id of this Try / Catch node, not of the step that failed inside its try region; that step is normally named inside `message`'),
   message: z.string().describe('Message of the error that ended the try region, after any retries'),
   code: z.string().optional()
     .describe('Platform-classified error code (ADR-0112) of the failure that ended the try region, e.g. `create_record`\'s `DUPLICATE_RECORD`; present only when the failing node\'s own result carried one, so a catch region branching on `$error.code` treats "unset" as "no classified code", never as "nothing failed". An open `string`, not a closed enum: the vocabulary is `StandardErrorCode` plus registered ledger codes plus tenant-authored codes, and third-party node executors bind their own'),