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

* feat(lint): warn on an uncontained loop body and on a try_catch with no catch

Two authoring-time rules in the flow anti-pattern family, both warnings:
`flow-loop-body-uncontained` (a `loop` body running a fallible node with no
`try_catch` between the loop and it) and `flow-try-catch-without-catch` (the
near-miss shape that gives zero containment while looking like containment).

Documents `loop { try_catch { … } }` in the flow docs as the per-iteration
containment spelling, with the measured minimal `catch` — one bare `assignment`
node, `edges` and `errorVariable` omitted — and the two empty-`catch` spellings
the region schema refuses.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

* fix(lint): keep tracker ids out of the containment rules' runtime hints

`check:doc-authoring` refuses a NEW internal issue id in string prose a
runtime surface shows an author: the ids move to the adjacent comments, where
the reader who can resolve them already looks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.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';