Derive node statuses from execution lineage (#263)

Add status_details metadata to df.nodes and stamp each node transition
with deterministic execution lineage. Use the lineage to fence stale
loop-generation writes while preserving older-schema write compatibility.

Move df.instance_nodes() and df.explain() to a shared read-time
inference model. It reports skipped branches and superseded loop-body
nodes without adding new physical node statuses.

Keep df.instance_nodes(text, integer) callable for old schemas and
upgraded callers as a shape-compatible adapter. It no longer queries
execution history and returns one row per node with execution_id = 1.

Update the 0.2.3 to 0.2.4 migration, user/API docs, SQL skill guidance,
and E2E coverage for the inferred-status model.

Author: pinodeca

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

@@ -153,8 +153,9 @@ df.list_instances(status_filter TEXT DEFAULT NULL, limit_count INT DEFAULT 100)
 df.instance_info(instance_id TEXT)
 -- Columns: instance_id, label, function_name, function_version, current_execution_id, status, output
 
-df.instance_nodes(instance_id TEXT, last_n_executions INT DEFAULT 5)
--- Columns: execution_id, node_id, node_type, query, result_name, left_node, right_node, status, result, updated_at
+df.instance_nodes(instance_id TEXT)
+-- Columns: node_id, node_type, query, result_name, left_node, right_node, status, result, status_details, inferred_status, inferred_status_from_ancestor_id, updated_at
+-- inferred_status reinterprets status with a derived 'skipped' (untaken if/then/race branch) and loop re-entry as 'pending'
 
 df.instance_executions(instance_id TEXT, limit_count INT DEFAULT 5)
 -- Columns: execution_id, status, event_count, duration_ms, output

USER_GUIDE.md

@@ -1459,17 +1459,70 @@ SELECT * FROM df.instance_executions('a1b2c3d4', 20);
 
 ### Function Nodes
 
-See the function graph structure:
+See the function graph structure, one row per node, with both the stored status
+and a derived status that interprets the durable-execution state model:
 
 ```sql
--- Last 5 executions (default)
 SELECT * FROM df.instance_nodes('a1b2c3d4');
-
--- Last 10 executions
-SELECT * FROM df.instance_nodes('a1b2c3d4', 10);
 ```
 
-**Columns:** `execution_id`, `node_id`, `node_type`, `query`, `result_name`, `left_node`, `right_node`, `status`, `result`
+**Columns:** `node_id`, `node_type`, `query`, `result_name`, `left_node`, `right_node`, `status`, `result`, `status_details`, `inferred_status`, `inferred_status_from_ancestor_id`, `updated_at`
+
+- **`status`** — the status physically stored on the node: `pending`, `running`,
+  `completed`, or `failed`.
+- **`status_details`** — JSON execution metadata written by the worker (the
+  `execution_id` generation stamp). You normally do not read this directly; it is
+  what `inferred_status` is derived from.
+- **`inferred_status`** — the stored status reinterpreted top-down from the root
+  node. It adds one derived value, **`skipped`**, and reconciles loop re-entry:
+  - `skipped` — a node on a branch that was decided against and will not (further)
+    run: the untaken arm of a completed `df.if()`, the right side of a failed
+    `df.then()`, or the abandoned arm of a resolved `df.race()`.
+  - a node from a previous loop iteration reads back as `pending` (it will re-run),
+    rather than showing the old iteration's terminal status.
+  - a node that physically ran keeps its stored `completed`/`failed`/`running`.
+- **`inferred_status_from_ancestor_id`** — when `inferred_status` was *derived*
+  from an ancestor (a `skipped` branch, or a superseded loop node), this names the
+  ancestor node that drove the inference; otherwise `NULL`.
+
+> This is read-time interpretation only — it does not change how the graph
+> executes. `df.race()` still abandons the losing branch and `df.join()` still
+> waits for every branch; `inferred_status` only changes how those outcomes are
+> *reported*.
+
+#### Node state transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+    pending --> running: scheduled (written)
+    running --> completed: success (written)
+    running --> failed: error (written)
+
+    pending --> skipped: ancestor failed / not taken / race lost (derived)
+    running --> skipped: ancestor failed / not taken / race lost (derived)
+    completed --> pending: superseded by newer execution (derived)
+    failed --> pending: superseded by newer execution (derived)
+
+    classDef physical fill:#dfd,stroke:#080;
+    classDef derived stroke-dasharray: 5 5,fill:#eee;
+    classDef hybrid fill:#dfd,stroke:#080,stroke-dasharray: 5 5;
+    class running,completed,failed physical
+    class skipped derived
+    class pending hybrid
+```
+
+Solid edges are **physical**: the worker writes them and they persist in
+`df.nodes.status` (the `status` column). Dashed edges are **derived**: nothing
+writes them — they are how `df.instance_nodes()` *reinterprets* a stored status
+(via `inferred_status`) when a node's `execution_id` no longer matches its live
+lineage. `pending` (drawn with a dashed border) is **both**: it is written once by
+`df.start()`, and it is *also* what the read path reports for a node superseded by a
+newer loop iteration. That terminal → `pending` edge is therefore not a write — it
+is what a previous iteration's stored `completed`/`failed` (or an in-flight
+`running`) *looks like* once a newer iteration supersedes it and has not yet
+re-reached the node.
+
 
 ### System Metrics (Explicit Grant Required)
 
@@ -2118,14 +2171,17 @@ This shows the graph structure with status markers on each node:
 - `✓ Completed` — node finished successfully
 - `✗ Failed` — node encountered an error
 - `⏳ Running` — node was in progress when the instance failed or was inspected
+- `⊘ Skipped` — branch was decided away (untaken `if` arm, right side of a failed `then`, or race loser) so the node will never run
 - `○ Pending` — node never started
 
+The markers reflect the same derived status as the `inferred_status` column of `df.instance_nodes()`, so the tree view and the node table always agree.
+
 `df.explain()` tells you **where** in the graph execution stopped, but not **why**. For that, inspect individual nodes.
 
 #### Step 4: Inspect Individual Nodes
 
 ```sql
-SELECT node_id, node_type, result_name, status, 
+SELECT node_id, node_type, result_name, status, inferred_status,
        left(query, 80) AS query,
        left(result, 120) AS result
 FROM df.instance_nodes('a1b2c3d4');
@@ -2137,6 +2193,8 @@ This shows every node in the graph with its status and result. Key things to loo
 |---------------|---------------|
 | A node with `status = 'failed'` | This is the node that caused the failure |
 | A node with `result = NULL` and `status = 'completed'` | The SQL returned no rows |
+| A node with `inferred_status = 'skipped'` | The node was on a branch that was decided against (untaken `df.if()` arm, right side of a failed `df.then()`, or losing `df.race()` arm) and never (further) ran |
+| `inferred_status = 'pending'` on a node that previously completed | The node belongs to an earlier loop iteration and will re-run |
 | Result contains `{"jsonb": null}` | Possible type extraction issue — see "Known Limitations" below |
 | A `running` node with no result | Execution was interrupted at this node |
 

docs/api-reference.md

@@ -351,6 +351,68 @@ SELECT df.result('a1b2c3d4');
 
 ---
 
+### df.instance_nodes(instance_id)
+
+Returns one row per node in an instance's graph, with each node's stored physical
+status alongside a read-time **derived** status. This is the primary tool for
+inspecting *where* an instance is and *why* a branch did or did not run.
+
+| Parameter | Type | Auto-wrap | Description |
+|-----------|------|-----------|-------------|
+| `instance_id` | TEXT | ❌ Literal | Target instance ID |
+
+Return columns:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `node_id` | TEXT | Node id (unique within the instance) |
+| `node_type` | TEXT | `SQL`, `THEN`, `IF`, `JOIN`, `RACE`, `LOOP`, `SLEEP`, `SIGNAL`, `HTTP`, … |
+| `query` | TEXT | SQL text for `SQL` nodes; a JSON config for compound/leaf nodes |
+| `result_name` | TEXT | Capture name (`\|=>`), or `NULL` |
+| `left_node` | TEXT | First child node id, or `NULL` |
+| `right_node` | TEXT | Second child node id, or `NULL` |
+| `status` | TEXT | **Physical** stored status: `pending`, `running`, `completed`, `failed` |
+| `result` | JSONB | Result/error payload for `completed`/`failed` nodes, else `NULL` |
+| `status_details` | JSONB | Worker-written node metadata (see below), or `NULL` if never transitioned |
+| `inferred_status` | TEXT | **Derived** status: physical status plus `skipped`, and loop re-entry surfaced as `pending` |
+| `inferred_status_from_ancestor_id` | TEXT | Ancestor node id that drove a derived `skipped`/`pending`, or `NULL` |
+| `updated_at` | TIMESTAMPTZ | Last physical status change |
+
+**`status_details` JSON contract.** Written by the worker through the
+`update-node-status` activity and stored verbatim in `df.nodes.status_details`:
+
+- `execution_id` — the node's full segmented execution path, e.g.
+  `a1b2c3d4::1::7f9a0012::1`. Parse it positionally: the second `::`-token is the
+  root loop generation (used to detect superseded loop iterations), and the
+  trailing segments encode `JOIN`/`RACE` sub-orchestration lineage.
+
+`inferred_status` and `inferred_status_from_ancestor_id` are **computed at read
+time** and are not stored in `df.nodes.status_details`.
+
+**Derived statuses.** `skipped` is never written to `df.nodes.status` (it is not a
+member of the `nodes_status_chk` constraint) — it exists only in `inferred_status`:
+
+- `skipped` — a non-terminal node whose nearest terminal ancestor already decided
+  the branch will not run: the untaken arm of a completed `df.if()`, the right side
+  of a failed `df.then()`/`~>`, or the abandoned (still-running) loser of a resolved
+  `df.race()`. A loser that already reached `completed`/`failed` keeps its physical
+  status.
+- `pending` (derived) — a node from an older loop generation that a newer ancestor
+  generation has superseded; it will re-run, so it reads back as `pending` rather
+  than showing the previous iteration's terminal status.
+
+`df.explain()` renders the same derived status for each node, so the two views
+always agree.
+
+```sql
+SELECT node_id, node_type, status AS physical, inferred_status,
+       status_details->>'execution_id' AS execution_id
+FROM df.instance_nodes('a1b2c3d4')
+ORDER BY node_id;
+```
+
+---
+
 ## Variable Functions
 
 ### df.setvar(name, value)

sql/pg_durable--0.2.3--0.2.4.sql

@@ -256,3 +256,87 @@ DROP INDEX IF EXISTS df.idx_instances_status;
 CREATE INDEX idx_instances_status ON df.instances(status, created_at DESC, id);
 DROP INDEX IF EXISTS df.idx_instances_created_at;
 CREATE INDEX idx_instances_created_at ON df.instances(created_at DESC, id);
+
+-- ============================================================================
+-- Node state-transition model: add df.nodes.status_details (PR #263).
+--
+-- The background worker stamps every node transition with the orchestration
+-- generation "{instance_id}::{execution_id}" in status_details->>'execution_id'.
+-- df.instance_nodes() parses that stamp to derive the pending/skipped statuses
+-- and to reconcile loop re-entry, and update_node_status() uses it to fence stale
+-- writes. The column is nullable and is deliberately NOT added to any user INSERT
+-- grant on df.nodes -- only the background worker writes it.
+--
+-- Backward compatibility (Scenario B1): the new .so probes for this column at
+-- runtime (update_node_status) and degrades to the plain status/result write when
+-- it is absent, so a pre-0.2.4 schema keeps running until this upgrade applies.
+--
+-- Upgrade ordering (in-flight instances): the worker's orchestration history
+-- changed shape in this release -- update_node_status activity inputs gained an
+-- execution_id field, and JOIN/RACE branch sub-orchestrations now use
+-- deterministic composed instance ids instead of auto-generated ones. duroxide
+-- replays by exact equality on recorded inputs/ids, so instances in flight across
+-- the upgrade cannot resume; drain or recreate them before upgrading (the same
+-- constraint documented for issue #129).
+-- ============================================================================
+ALTER TABLE df.nodes ADD COLUMN status_details JSONB;
+
+COMMENT ON COLUMN df.nodes.status_details IS
+    'Execution metadata written by the worker (never inserted by users). JSON object with key '
+    '"execution_id": the orchestration instance_id::execution_id stamp recorded when the node last '
+    'transitioned. df.instance_nodes() parses it to derive pending/skipped statuses; see USER_GUIDE.md.';
+
+-- ============================================================================
+-- df.instance_nodes(): one row per node with derived status (PR #263).
+--
+-- The return shape changed: the per-execution fan-out is gone, replaced by a
+-- single row per node carrying the stored status plus the derived status_details,
+-- inferred_status and inferred_status_from_ancestor_id columns. Keep the old
+-- two-argument overload callable for binary/schema compatibility, but implement
+-- it as a one-row-per-node adapter that ignores last_n_executions and returns a
+-- dummy execution_id of 1. Remove its default argument so one-argument calls
+-- resolve to the new API after the schema upgrade. The definitions below are the
+-- pgrx-generated fresh-install DDL (src/monitoring.rs) verbatim, so the Scenario
+-- A schema snapshot (function arguments + result type) matches a fresh 0.2.4
+-- install.
+-- ============================================================================
+DROP FUNCTION IF EXISTS df.instance_nodes(text, integer);
+
+CREATE  FUNCTION df."instance_nodes"(
+    "instance_id_param" TEXT, /* &str */
+    "_last_n_executions" INT /* i32 */
+) RETURNS TABLE (
+    "execution_id" bigint,  /* i64 */
+    "node_id" TEXT,  /* alloc::string::String */
+    "node_type" TEXT,  /* alloc::string::String */
+    "query" TEXT,  /* core::option::Option<alloc::string::String> */
+    "result_name" TEXT,  /* core::option::Option<alloc::string::String> */
+    "left_node" TEXT,  /* core::option::Option<alloc::string::String> */
+    "right_node" TEXT,  /* core::option::Option<alloc::string::String> */
+    "status" TEXT,  /* core::option::Option<alloc::string::String> */
+    "result" TEXT,  /* core::option::Option<alloc::string::String> */
+    "updated_at" timestamp with time zone  /* core::option::Option<pgrx::datum::time_stamp_with_timezone::TimestampWithTimeZone> */
+)
+STRICT 
+LANGUAGE c /* Rust */
+AS 'MODULE_PATHNAME', 'instance_nodes_wrapper';
+
+CREATE  FUNCTION df."instance_nodes"(
+	"instance_id_param" TEXT /* &str */
+) RETURNS TABLE (
+	"node_id" TEXT,  /* alloc::string::String */
+	"node_type" TEXT,  /* alloc::string::String */
+	"query" TEXT,  /* core::option::Option<alloc::string::String> */
+	"result_name" TEXT,  /* core::option::Option<alloc::string::String> */
+	"left_node" TEXT,  /* core::option::Option<alloc::string::String> */
+	"right_node" TEXT,  /* core::option::Option<alloc::string::String> */
+	"status" TEXT,  /* core::option::Option<alloc::string::String> */
+	"result" TEXT,  /* core::option::Option<alloc::string::String> */
+	"status_details" TEXT,  /* core::option::Option<alloc::string::String> */
+	"inferred_status" TEXT,  /* alloc::string::String */
+	"inferred_status_from_ancestor_id" TEXT,  /* core::option::Option<alloc::string::String> */
+	"updated_at" timestamp with time zone  /* core::option::Option<pgrx::datum::time_stamp_with_timezone::TimestampWithTimeZone> */
+)
+STRICT 
+LANGUAGE c /* Rust */
+AS 'MODULE_PATHNAME', 'instance_nodes_v2_wrapper';