lint(flows): warn on an uncontained loop body and on a try_catch with no catch, and document loop { try_catch }

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';

.changeset/flow-loop-per-iteration-containment-lint.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": patch
+---
+
+flows: warn on a `loop` body with a fallible node and no containment, and on a `try_catch` with no `catch` (#14394)
+
+Two authoring-time rules in the flow anti-pattern family, both `warning`:
+
+- **`flow-loop-body-uncontained`** — a `loop` whose `body` region runs a node
+ that can end the run (a record read/write, `http`, `notify`,
+ `connector_action`, `script`, `subflow`, `map`, `approval`) with no
+ `try_catch` between the loop and that node. The `loop` executor iterates with
+ a bare `await` and has no `try`/`catch` at all, so the first failing item ends
+ the whole run: later items are never processed, and the work already done is
+ not even reported. The finding names the loop, the node, and the prescribed
+ spelling.
+- **`flow-try-catch-without-catch`** — the near-miss, and the first target
+ rather than an extra: `catch` is optional in the schema, and omitting it makes
+ the container fail through, so an author who wrapped the node and stopped
+ there gets **zero** containment and previously got no diagnostic either.
+ Measured, the no-`catch` run and the unwrapped control produce identical
+ output; a `retry` policy only delays that.
+
+Both stay warnings under the family's severity bar: a loop deliberately allowed
+to stop at the first failure, and a retry-then-fail `try_catch`, are legitimate
+readings the rule cannot disprove.
+
+`content/docs/automation/flows.mdx` documents `loop { try_catch { … } }` as the
+per-iteration containment spelling, with the measured minimal handler — one bare
+`assignment` node, `edges` and `errorVariable` omitted — and the three `catch`
+spellings the schema refuses (`catch` omitted gives no containment; `catch: {}`
+and `catch: { nodes: [] }` are rejected, the region's `nodes` being `.min(1)`).
+
+No spec, engine or runtime change: the containment capability already exists and
+was measured working (5 of 5 iterations, items 4-5 processed, run completes).

content/docs/automation/flows.mdx

@@ -411,7 +411,15 @@ Runs its `body` region once per item of a collection, binding the current item
  maxIterations: 500, // hard cap (clamped to the engine ceiling)
  body: { // single-entry/single-exit region
  nodes: [
- { id: 'send', type: 'script', label: 'Notify', config: { /* … */ } },
+ // Per-iteration containment — see the subsection below. A body node that
+ // can fail, wrapped in nothing, ends the WHOLE run at the first failure.
+ {
+ id: 'guard', type: 'try_catch', label: 'Guarded iteration',
+ config: {
+ try: { nodes: [{ id: 'send', type: 'script', label: 'Notify', config: { /* … */ } }], edges: [] },
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
  ],
  edges: [],
  },
@@ -422,6 +430,77 @@ Runs its `body` region once per item of a collection, binding the current item
 A `loop` node with **no `body`** keeps the legacy flat-graph behavior — the
 container is additive.
 
+#### Per-iteration containment: `loop { try_catch { … } }`
+
+A `loop` body has **no error handling of its own**. The container iterates with a
+bare `await`, so a body node that returns `success: false` (or throws) propagates
+straight out of the loop and ends the run: every later item is never processed,
+and the work already done is not even reported. Measured on the engine — a 5-item
+sweep whose 3rd item fails touched 3 items, reported `acted: 0`, and finished
+`status: failed`.
+
+The containment spelling is a `try_catch` **inside the body**, one per iteration.
+Measured with the same 5-item sweep: all 5 iterations run, items 4 and 5 are
+processed, and the run completes.
+
+```typescript
+{
+ id: 'each_case',
+ type: 'loop',
+ label: 'For each breached case',
+ config: {
+ collection: '{cases}',
+ iteratorVariable: 'currentCase',
+ body: {
+ nodes: [
+ {
+ id: 'guard',
+ type: 'try_catch',
+ label: 'Guarded iteration',
+ config: {
+ try: {
+ nodes: [
+ {
+ id: 'notify_owner', type: 'notify', label: 'Notify owner',
+ config: { title: 'SLA breach', recipients: ['{currentCase.owner}'] },
+ },
+ ],
+ edges: [],
+ },
+ // The shortest handler that works: ONE bare `assignment` node with no
+ // `config` at all. `edges` omitted; `errorVariable` omitted (it
+ // defaults to `$error`).
+ catch: { nodes: [{ id: 'handled', type: 'assignment', label: 'Handled' }] },
+ },
+ },
+ ],
+ edges: [],
+ },
+ },
+}
+```
+
+**A `catch` region cannot be empty.** `FlowRegionSchema.nodes` is `.min(1)`, so
+only the last row below is usable:
+
+| `catch` spelling | result |
+|:---|:---|
+| omitted entirely | parses — and contains **nothing**: the container fails through exactly like an unwrapped node |
+| `catch: {}` | rejected — `catch.nodes`: expected array, received undefined |
+| `catch: { nodes: [] }` | rejected — `catch.nodes`: too small, expected at least 1 item |
+| `catch: { nodes: [ …one node… ] }` | parses, and contains |
+
+Two authoring-time lint rules cover this pair (both warnings, so neither fails a
+build): `flow-loop-body-uncontained` names a loop body running a node that can
+fail with no `try_catch` between the loop and it, and
+`flow-try-catch-without-catch` names the near-miss — a `try_catch` whose `catch`
+is absent, which gives **zero** containment while looking like containment. A
+`retry` policy does not substitute: it re-runs the `try` region and then fails
+anyway.
+
+Deliberately letting the sweep stop at the first failure is a legitimate choice —
+that is why both rules warn rather than gate.
+
 ### Parallel block
 
 Declares N branch regions that run **concurrently** and **join implicitly** when
@@ -465,6 +544,14 @@ events).
 }
 ```
 
+`catch` is optional in the schema, and omitting it is the trap: with no `catch`
+the container **fails** when the `try` region fails, so the failure propagates
+exactly as if nothing had been wrapped (measured — the no-`catch` run and the
+unwrapped control produce identical output). `retry` only delays that. The
+`flow-try-catch-without-catch` lint rule names the shape at authoring time; the
+minimal handler is one bare `assignment` node, as shown under "Per-iteration
+containment" above.
+
 > BPMN `parallel_gateway` / `join_gateway` / `boundary_event` remain in the
 > protocol as the **interop** representation and map onto these constructs on
 > import/export — they are not the native authoring model.

packages/lint/src/index.ts

@@ -734,6 +734,8 @@ export {
  FLOW_MULTIPLE_DEFAULT_EDGES,
  FLOW_INERT_NODE_CONDITION,
  FLOW_MULTI_WRITE_UNFILTERED,
+ FLOW_LOOP_BODY_UNCONTAINED,
+ FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
 
 export { lintLivenessProperties } from './lint-liveness-properties.js';