Unify conditional loop failure handling

Author: tjgreen42

.agents/skills/pg-durable-sql/SKILL.md

@@ -93,9 +93,16 @@ df.if(condition TEXT, then_branch TEXT, else_branch TEXT) → TEXT
 -- result_name is a capture from |=> earlier in the graph.
 df.if_rows(result_name TEXT, then_branch TEXT, else_branch TEXT) → TEXT
 
--- Loop — infinite or while-condition
-df.loop(body TEXT) → TEXT                            -- Infinite loop
-df.loop(body TEXT, condition TEXT) → TEXT             -- While-loop: repeats while condition is truthy
+-- Loop — one unified signature
+df.loop(
+    body TEXT,
+    condition TEXT DEFAULT NULL,
+    continue_on_failure BOOLEAN DEFAULT false
+) → TEXT
+-- NULL condition: infinite loop.
+-- Non-NULL condition: do-while semantics; evaluate it after each successful body.
+-- With continue_on_failure => true, a consumed body activity failure skips the
+-- condition and starts the next iteration. Condition and non-application failures are fatal.
 
 -- Break from enclosing loop
 df.break() → TEXT                                    -- Exit with NULL
@@ -227,7 +234,7 @@ Automatically available during execution:
 
 ## Condition Evaluation (Truthiness)
 
-Used by: `?>`, `!>`, `df.if()`, `df.loop(body, condition)`
+Used by: `?>`, `!>`, `df.if()`, and the optional condition in `df.loop()`
 
 The first column of the first row is evaluated:
 
@@ -345,7 +352,7 @@ SELECT df.start(
 -- Cancel with: SELECT df.cancel('instance_id', 'Stopping heartbeat');
 ```
 
-### While-Loop with Break
+### Loop with Break
 
 ```sql
 SELECT df.start(
@@ -361,6 +368,26 @@ SELECT df.start(
 );
 ```
 
+### Conditional Loop with Failure Continuation
+
+```sql
+SELECT df.start(
+    df.loop(
+        'SELECT process_next_item()',
+        'SELECT EXISTS (
+            SELECT 1 FROM work_queue WHERE status = ''pending''
+        )',
+        continue_on_failure => true
+    ),
+    'resilient-worker'
+);
+```
+
+This is a do-while loop: after a successful body execution, the condition is
+evaluated and the loop continues while it is truthy. After a consumed body
+activity failure, the condition is skipped and the body starts again.
+Condition failures and non-application failures remain fatal.
+
 ### Cron Scheduled Job
 
 ```sql

CHANGELOG.md

@@ -8,11 +8,13 @@ Pre-1.0 note: while `pg_durable` is in major version `0`, minor releases may inc
 
 ### Added
 
-- **Failure-isolated loops:** `df.loop(body, continue_on_failure => true)` runs
-  each infinite-loop iteration as a child orchestration. An application failure
-  returned by a body activity does not fail the loop parent, which proceeds to
-  the next iteration. Graph, protocol, child-runtime, and infrastructure
-  failures remain fatal.
+- **Failure-isolated loops:** the unified
+  `df.loop(body, condition DEFAULT NULL, continue_on_failure DEFAULT false)`
+  signature supports resilient infinite and conditional loops. With
+  `continue_on_failure => true`, a consumed typed body activity failure skips
+  the condition and starts the next iteration; after a successful body, the
+  condition is evaluated normally. Condition, graph, protocol,
+  unknown child/runtime failures, and infrastructure failures remain fatal.
 
 ### Changed
 

USER_GUIDE.md

@@ -530,7 +530,8 @@ SELECT df.start(
 
 ### Loop Condition Example
 
-For `df.loop(body, condition)`, the condition is evaluated after each iteration:
+For `df.loop(body, condition)`, the condition is evaluated after each
+successful body execution:
 
 ```sql
 -- Loop while there are pending items
@@ -1181,13 +1182,25 @@ SELECT df.start(
 
 The unified signature is
 `df.loop(body, condition DEFAULT NULL, continue_on_failure DEFAULT false)`.
+
+It supports four call shapes:
+
+```sql
+df.loop(body)
+df.loop(body, condition)
+df.loop(body, continue_on_failure => true)
+df.loop(body, condition, continue_on_failure => true)
+```
+
 By default, it and `@>` are fail-fast: an iteration failure fails the loop.
 Passing `continue_on_failure => false` is equivalent to the default and does
-not change where the loop is hosted. When it is `true`, each iteration runs as
-a child orchestration and the parent starts the next iteration after an
-application failure returned by a body activity. Malformed graph or child
-data, child-runtime failures, child-ID collisions, and
-infrastructure/configuration/poison failures remain fatal.
+not change where the loop is hosted. When it is `true`, each body iteration
+runs as a child orchestration. After a successful body iteration, the child's
+results are merged into the parent result map before the optional condition is
+evaluated. After a consumed typed application failure from a body activity,
+the condition is skipped and the parent starts the next iteration. Condition
+failures, malformed graph or child data, unrecognized child errors, child-ID
+collisions, and child-runtime or infrastructure failures remain fatal.
 
 This is useful for scheduled maintenance such as a pg_textsearch-style indexer:
 
@@ -1324,7 +1337,7 @@ Each loop iteration advances via *continue-as-new*, which restarts the loop with
 - A fail-fast **root loop** (the function graph's outermost node, e.g. `df.start(df.loop(...))` or `df.start(@> 'SELECT work()')`) runs inline on the function's own orchestration. There is no surrounding work to preserve, so each iteration simply restarts the function. The `@>` operator does not make a loop root by itself: `df.seq('SELECT setup()', @> 'SELECT work()')` is non-root because the sequence is the graph root.
 - A fail-fast **non-root loop** (a loop with prefix/suffix nodes, or one nested inside a `df.if()`, JOIN (`&`), or RACE (`|`) branch) runs as its own **child sub-orchestration**. Only the loop body restarts on each iteration — any work *before* the loop runs exactly once and is never re-executed, and a loop nested in a parallel branch gets its own durable instance.
 - Fail-fast iterations execute inline within whichever orchestration hosts the loop. Explicit `continue_on_failure => false` keeps this placement; it does not force a non-root loop into the function's root orchestration.
-- A loop with `continue_on_failure => true` runs every iteration in a child orchestration. The loop parent remains `running` after a body activity returns an application failure and proceeds to the next iteration. Unrecognized child errors and graph, protocol, runtime, or infrastructure failures remain fatal.
+- A loop with `continue_on_failure => true` runs every body iteration in a child orchestration. After a successful body iteration, the child's results are merged into the parent result map before the optional condition is evaluated. After a consumed typed body activity failure, the condition is skipped and the loop parent proceeds to the next iteration. Condition failures and unrecognized child, graph, protocol, runtime, or infrastructure failures remain fatal.
 
 These child sub-orchestrations are internal durable instances and do **not**
 appear in `df.list_instances()`, which lists only instances started with

docs/ARCHITECTURE.md

@@ -477,31 +477,36 @@ of every handler having to recognise an in-band JSON break sentinel:
 pub enum NodeError {
     /// df.break() fired. Carries the break value. Caught only by execute_loop_node.
     Break(String),
-    /// A genuine failure. Surfaces as a failed instance.
+    /// An expected workflow activity failure.
+    Application(String),
+    /// A graph, protocol, configuration, or runtime failure.
     Failure(String),
 }
 
 pub type NodeResult = Result<String, NodeError>;
 
-// Any `?` on an existing Result<_, String> auto-converts the error to Failure, so
-// activity calls and helpers need no per-call changes.
+// Structural/configuration helpers still convert String errors to Failure.
 impl From<String> for NodeError {
     fn from(e: String) -> Self {
         NodeError::Failure(e)
     }
 }
 ```
 
-`execute_loop_node` is the only handler that catches `NodeError::Break` (turning it into the
-loop's `Ok` result); `NodeError::Failure` keeps propagating. The orchestration boundary
-functions (`execute` / `execute_subtree`) still return `Result<String, String>` because they
-are registered with duroxide:
+SQL, HTTP, and multipart activity scheduling boundaries explicitly map activity
+errors to `NodeError::Application`; structural/configuration helper errors use
+`NodeError::Failure`. `execute_loop_node` is the only handler that catches
+`NodeError::Break` (turning it into the loop's `Ok` result). The orchestration
+boundary functions (`execute` / `execute_subtree`) still return
+`Result<String, String>` because they are registered with duroxide:
 
 - `execute`: an uncaught top-level `Break` becomes a clear `Err` ("df.break() was called
   outside of a loop"), so the instance fails instead of completing with a sentinel value.
-- `execute_subtree` (used by JOIN/RACE branches): a `Break` is carried out-of-band in the
-  subtree envelope's `control` field and re-raised as `NodeError::Break` by
-  `parse_subtree_envelope` in the parent orchestration.
+- `execute_subtree`: a `Break` is carried out-of-band in the subtree envelope's
+  `control` field. `NodeError::Application` is encoded as a namespaced,
+  serde-tagged subtree failure so application classification survives nested
+  JOIN, RACE, and LOOP boundaries. `NodeError::Failure` remains an unrecognized
+  child error and propagates fatally.
 
 The orchestration walks the graph recursively:
 
@@ -734,7 +739,25 @@ Loops use duroxide's `continue_as_new` to avoid unbounded history growth. Their
 
 `execute_subtree` is therefore structurally identical to `execute_function_graph`: both root an execution context at their own node and host an inline root loop. They differ only in the input envelope they re-enter with on `continue_as_new` (`FunctionInput` vs `SubtreeInput`), in the fact that only the root orchestration touches instance-level status, and in where their graph comes from — `execute_function_graph` loads it from `df.nodes` on its first generation, while `execute_subtree` receives it inline from its parent. The graph is loaded exactly once per instance and then carried inline through every child input and every `continue_as_new` generation, so `submitted_by` is fixed for the instance's lifetime and a post-start `df.nodes` tamper is never read. Role deletion and privilege revocation are still enforced per node execution, by connecting *as* `submitted_by` for SQL and by re-checking `EXECUTE` privilege per HTTP request.
 
-Both paths call `run_loop_iteration`, which executes the body, catches `NodeError::Break`, evaluates the optional post-body condition, and propagates `NodeError::Failure`. A child stamps its LOOP node `running` on each generation and `completed` or `failed` on exit; because `continue_as_new` returns a future that never resolves, a continuing generation never stamps a terminal status. If a live loop loses a RACE, the parent records the loop node as terminal `failed` with a cancellation reason because duroxide cancellation stops the child before it can run its own terminal stamp.
+Fail-fast loops call `run_loop_iteration`, which executes the body inline,
+catches `NodeError::Break`, evaluates the optional post-body condition, and
+propagates both application and non-application failures. A loop configured
+with `continue_on_failure => true` instead calls
+`run_failure_isolated_body`: each body iteration runs as a fresh
+`execute_subtree` child. On success, the subtree envelope is parsed and its
+named results are merged into the parent result map before the parent evaluates
+the optional condition. On a structurally encoded body application failure,
+the parent consumes the failure, skips the condition because body results may
+be absent, and advances to the next generation. Condition failures, malformed
+envelopes or graph data, child-ID collisions, and other unrecognized
+infrastructure/runtime failures remain fatal.
+
+A child stamps its LOOP node `running` on each generation and `completed` or
+`failed` on exit; because `continue_as_new` returns a future that never
+resolves, a continuing generation never stamps a terminal status. If a live
+loop loses a RACE, the parent records the loop node as terminal `failed` with a
+cancellation reason because duroxide cancellation stops the child before it
+can run its own terminal stamp.
 
 Node status stamps contain the full composed orchestration lineage: `{root_instance}::{generation}::{child_node}::{generation}...`. Read-time inference and the write fence walk that lineage so stale writes and superseded nested branches are evaluated at every ancestor generation.
 

docs/api-reference.md

@@ -160,42 +160,55 @@ df.if_rows('data', 'SELECT $data.id', 'SELECT ''no data''')
 
 ---
 
-### df.loop(body [, condition])
+### df.loop(body, condition DEFAULT NULL, continue_on_failure DEFAULT false)
 
-Repeats `body` forever or while `condition` is true. This form is fail-fast,
-executing each iteration inline within whichever orchestration hosts the loop.
+Repeats `body` forever or while `condition` is true. The supported call shapes
+are:
+
+```sql
+df.loop(body)
+df.loop(body, condition)
+df.loop(body, continue_on_failure => true)
+df.loop(body, condition, continue_on_failure => true)
+```
 
 | Parameter | Type | Auto-wrap | Description |
 |-----------|------|-----------|-------------|
 | `body` | TEXT | ✅ Auto-wrap | Node to repeat |
-| `condition` | TEXT | ✅ Auto-wrap | (Optional) Continue while truthy |
+| `condition` | TEXT | ✅ Auto-wrap | (Optional) Evaluate after a successful body; continue while truthy |
+| `continue_on_failure` | BOOLEAN | ❌ Literal | (Optional) Continue after a body activity failure; default `false` |
 
 ```sql
 -- Infinite loop
 df.loop('SELECT process_item()' ~> df.sleep(1))
 
 -- While loop
 df.loop('SELECT process_item()', 'SELECT count(*) > 0 FROM queue')
-```
-
-### df.loop(body, continue_on_failure => boolean)
-
-Creates an infinite loop. When `continue_on_failure` is `true`, each iteration
-runs in a child orchestration; an application failure returned by a body
-activity does not fail the parent, which starts the next iteration. Malformed
-graph or child data, child-runtime failures, child-ID collisions, and
-infrastructure/configuration/poison failures remain fatal. `false` preserves
-fail-fast execution in the loop's existing host orchestration; it does not force
-root-level execution.
 
-```sql
+-- Infinite loop that continues after body activity failures
 df.loop(
     'SELECT process_item()' ~> df.sleep(1),
     continue_on_failure => true
 )
+
+-- Conditional loop that continues after body activity failures
+df.loop(
+    'SELECT process_item()',
+    'SELECT count(*) > 0 FROM queue',
+    continue_on_failure => true
+)
 ```
 
-The `@>` operator is an infinite, fail-fast loop:
+By default, and when `continue_on_failure` is `false`, loop execution is
+fail-fast. When it is `true`, each body iteration runs in a child
+orchestration. After a successful body iteration, the child's results are
+merged into the parent result map before condition evaluation. A consumed
+typed application failure from a body activity skips condition evaluation and
+starts the next iteration. Condition failures, malformed graph or child data,
+unrecognized child errors, child-ID collisions, and child-runtime or
+infrastructure failures remain fatal.
+
+The `@>` operator remains an infinite, fail-fast loop:
 
 ```sql
 @> ('SELECT process_item()' ~> df.sleep(1))
@@ -663,8 +676,7 @@ SELECT df.clearvars();
 | `df.join3(a, b, c)` | `a`, `b`, `c` |
 | `df.race(a, b)` | `a`, `b` |
 | `df.if(cond, then, else)` | `cond`, `then`, `else` |
-| `df.loop(body, cond)` | `body`, `cond` |
-| `df.loop(body, continue_on_failure => boolean)` | `body` |
+| `df.loop(body, condition, continue_on_failure)` | `body`, `condition` |
 | `df.start(fut, label)` | `fut` |
 | All others | No auto-wrap (literals only) |
 

docs/grammar.md

@@ -61,8 +61,11 @@ node_function ::= df.sql( QUERY )
                 | df.race( expression, expression )
                 | df.seq( expression, expression )
                 | df.if( condition, then_expr, else_expr )
-                | df.loop( expression, condition DEFAULT NULL,
-                           continue_on_failure BOOLEAN DEFAULT false )
+                | df.loop(
+                      expression
+                      [, expression]
+                      [, continue_on_failure => BOOLEAN]
+                  )
                 | df.break( [value] )
                 | df.as( expression, NAME )
 ```

docs/loop_rework_problems.md

@@ -54,9 +54,10 @@ let new_input = SubtreeInput {
 
 The graph snapshot is also copied into every JOIN/RACE child input. A large
 graph or named result is therefore persisted repeatedly across loop generations
-and child histories. `MAX_LOOP_ITERATIONS` limits generations to 100,000, but
-that is not a meaningful byte bound: a 1 MB carried result can still produce
-storage measured in tens of gigabytes before the iteration guard trips.
+and child histories. `MAX_LOOP_ITERATIONS` limits generations to 8,388,608
+(`2^23`), but that is not a meaningful byte bound: a 1 MB carried result can
+still produce roughly 8.4 TB of payload copies (8 TiB for a 1 MiB payload)
+before the iteration guard trips, excluding engine-record and graph overhead.
 
 Child engine records also remain until the root instance is retired. A nested
 loop can create a child under each outer generation, so the retained child
@@ -258,8 +259,9 @@ between parent and descendant stamps at equal generations.
 `MAX_LOOP_ITERATIONS` is enforced per orchestration instance. A non-root inner
 loop starts in its own child and receives its own counter, while an outer loop
 can spawn a new inner child under every outer generation. Two loops that each
-stay under the 100,000-iteration cap can therefore produce a combinatorial
-amount of work and retained child state.
+stay under the 8,388,608 (`2^23`)-iteration cap can therefore produce up to
+`2^46` (70,368,744,177,664) inner iterations, plus outer-loop work, and retain
+a correspondingly large child-state population.
 
 The one-second floor limits the rate of each individual loop but does not place
 a workflow-wide bound on nested work. The existing nested-loop E2E test proves

docs/upgrade-testing.md

@@ -205,17 +205,26 @@ what the upgrade script handles, and any backward compatibility considerations.
 
 ### 0.2.8
 
-- `sql/pg_durable--0.2.7--0.2.8.sql` creates `df.loop(text, boolean)` without
-  dropping or replacing `df.loop(text, text)`.
-- Existing schemas do not expose the boolean overload until
-  `ALTER EXTENSION UPDATE` runs. Until then, the new `.so` retains
-  `loop_fn_wrapper`, so the old text overload remains callable safely.
+- `sql/pg_durable--0.2.7--0.2.8.sql` renames `df.loop(text, text)` to
+  `df._loop_legacy(text, text)`, preserving its function OID and dependent
+  objects, then creates the single public
+  `df.loop(text, text DEFAULT NULL, boolean DEFAULT false)` signature.
+  `_loop_legacy` is an internal upgrade-compatibility object, not a user-facing
+  alternative.
+- For Scenario B1, the new `.so` retains `loop_fn_wrapper`, so every supported
+  schema that has not run `ALTER EXTENSION UPDATE` can continue calling its
+  cataloged `df.loop(text, text)` function safely.
+- For Scenario A, fresh installs and upgraded schemas both contain the unified
+  public signature and the internal `_loop_legacy` object, so their schema
+  snapshots remain equal while upgrade dependencies stay attached to the
+  renamed function OID.
 - Existing LOOP graphs have no `continue_on_failure` key and remain inline and
   fail-fast. Only newly constructed opted-in loops schedule an iteration child.
-- Opted-in loops consume only typed application failures returned by body
-  activities. Malformed graph/protocol data, unrecognized child errors,
-  child-ID collisions, and infrastructure/configuration/poison failures remain
-  fatal.
+- For opted-in conditional loops, a successful body is followed by condition
+  evaluation; a consumed typed body activity failure skips the condition and
+  starts the next iteration. Condition failures, malformed graph/protocol
+  data, unrecognized child errors, child-ID collisions, and
+  infrastructure/configuration/poison failures remain fatal.
 - Raises the loop backstop for all loops from 100,000 to 8,388,608 (`2^23`),
   which is about 80 years at five-minute ticks.
 - Replay is unchanged through iteration 100,000. At the old boundary, loops