docs: fix stale identity model, incorrect examples, and missing documentation (#219)

Fixes found during a reliability audit of the documentation:

Critical:
- Rewrite 'How Identity Is Captured' section to describe the current v0.2.0+
  model (direct connection as submitted_by) instead of the removed v0.1.1
  login_role/SET ROLE model
- Fix df.join(a,b,c) → df.join3(a,b,c) in multi-party approval examples
  (USER_GUIDE.md and spec-signals.md)

High:
- Add df.wait_for_completion() to DSL Reference table
- Mark df.run() as stub in manual grants list
- Add 'Superuser Cannot Start Workflows' troubleshooting entry
- Add 'current_user lacks LOGIN attribute' troubleshooting entry
- Document the result JSON shape ({rows, row_count})
- Update security review docs to remove all login_role references and
  reflect the current identity model

Medium:
- Fix CHANGELOG: $name? substitutes NULL, not empty string
- Fix grammar.md: use {sku} syntax for setvars, not $sku
- Fix df.list_instances() examples to use lowercase status values
- Fix broken JSON accessor in scheduled API polling example

* test: add explicit timeouts to redirect E2E test

The redirect test hit httpbin.org without an explicit HTTP timeout and
used the default 30s wait_for_completion. When httpbin.org is slow, the
wait races the HTTP timeout causing flaky CI failures.

Add 10s HTTP timeout and 60s wait_for_completion to give headroom.

Author: iemejia

CHANGELOG.md

@@ -69,7 +69,7 @@ First open-source release of `pg_durable` on GitHub under the PostgreSQL License
 - Fix: `is_truthy` now correctly treats "false", "no", and "f" as falsy (#57)
 - Docs: add "Debugging Failed Workflows" section to User Guide (#71)
 - New: Azure Functions integration example (#69)
-- Named result substitution now supports dot-notation for column access (`$name.col`), null-safe variants (`$name?`, `$name.col?`), and row-set expansion (`$name.*`). Referencing a named result that returned no rows or a NULL value now fails the orchestration by default; append `?` to substitute an empty string instead.
+- Named result substitution now supports dot-notation for column access (`$name.col`), null-safe variants (`$name?`, `$name.col?`), and row-set expansion (`$name.*`). Referencing a named result that returned no rows or a NULL value now fails the orchestration by default; append `?` to substitute `NULL` instead.
 - New DSL function `df.if_rows()`: branches on whether a named result returned any rows, without executing a SQL condition query.
 - New: Connection limits — four Postmaster-context GUCs (`max_management_connections`, `max_duroxide_connections`, `max_user_connections`, `execution_acquire_timeout`) control the background worker's connection budget. User-execution connections are gated by a semaphore with configurable backpressure timeout. The former polling and activity pools are consolidated into a single management pool. Backend provider pools reduced to 1 connection.
 - Breaking change: simplified user isolation by dropping `login_role` from `df.instances` and `df.nodes`. User isolation now captures only `current_user` as `submitted_by`, and the background worker connects directly as `submitted_by` instead of connecting as `login_role` and running `SET ROLE`. `df.start()` now validates that `current_user` has the `LOGIN` attribute. The new binary remains compatible with the v0.1.1 schema shape, but any pending or running v0.1.1 instance whose `submitted_by` is a NOLOGIN role from the old `SET ROLE` workflow will fail after upgrade and must be recreated under the new model.

USER_GUIDE.md

@@ -193,6 +193,7 @@ df.sql('SELECT 1') ~> df.sql('SELECT 2')
 | `df.wait_for_signal(name)` | Wait for external signal | `df.wait_for_signal('approval')` |
 | `df.wait_for_signal(name, timeout)` | Wait with timeout (seconds) | `df.wait_for_signal('approval', 3600)` |
 | `df.signal(id, name, data)` | Send signal to instance | `df.signal('a1b2', 'go', '{}')` |
+| `df.wait_for_completion(id, timeout)` | Block until instance completes (default 30s timeout) | `df.wait_for_completion('a1b2c3d4', 60)` |
 
 ### Operators
 
@@ -284,6 +285,43 @@ SELECT df.start(
 
 This is useful for passing row sets between steps. The expansion generates SQL like `(VALUES (1,'Alice'), (2,'Bob')) AS batch(id, name)`.
 
+### Result Format
+
+When a SQL node completes, its result is stored as a JSON object with this shape:
+
+```json
+{
+  "rows": [
+    {"column1": "value1", "column2": 42},
+    {"column1": "value2", "column2": 99}
+  ],
+  "row_count": 2
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rows` | Array of objects | Each element is one row; keys are column names |
+| `row_count` | Integer | Number of rows returned |
+
+When accessing results via `df.result(id)`, you get this JSON text. Use PostgreSQL's JSON operators to extract values:
+
+```sql
+-- Get the result
+SELECT df.result('a1b2c3d4');
+-- Returns: '{"rows":[{"answer":42}],"row_count":1}'
+
+-- Extract a specific value
+SELECT df.result('a1b2c3d4')::jsonb->'rows'->0->>'answer';
+-- Returns: '42'
+```
+
+**Special cases:**
+- A query returning no rows produces: `{"rows": [], "row_count": 0}`
+- `df.sleep()` and `df.wait_for_schedule()` produce no result (NULL)
+- `df.http()` results contain `status`, `body`, and `headers` fields inside the row
+- `df.break('value')` stores the literal value as the loop result (not wrapped in `rows`)
+
 
 ### Cron Expression Format
 
@@ -708,7 +746,7 @@ SELECT df.start(
         df.wait_for_schedule('*/5 * * * *')  -- Every 5 minutes
         ~> df.http('https://api.example.com/status', 'GET') |=> 'status'
         ~> df.if(
-            'SELECT ($status::jsonb->''body''::jsonb->>''healthy'')::boolean = false',
+            'SELECT (($status::jsonb->>''body'')::jsonb->>''healthy'')::boolean = false',
             'INSERT INTO playground.logs (msg, level) VALUES (''Service unhealthy!'', ''error'')',
             'SELECT ''healthy'''
         )
@@ -1113,12 +1151,12 @@ SELECT df.signal('a1b2c3d4', 'approval', '{"approved": true, "approver": "jane@a
 
 ### Example: Multi-Party Approval
 
-Wait for multiple approvals using `df.join()`:
+Wait for multiple approvals using `df.join3()`:
 
 ```sql
 SELECT df.start(
     'SELECT doc_id FROM documents WHERE id = 1' |=> 'doc'
-    ~> df.join(
+    ~> df.join3(
         df.wait_for_signal('legal_approval'),
         df.wait_for_signal('tech_approval'),
         df.wait_for_signal('mgmt_approval')
@@ -1384,10 +1422,10 @@ LOOP
 -- All instances
 SELECT * FROM df.list_instances();
 
--- Filter by status
-SELECT * FROM df.list_instances('Running');
-SELECT * FROM df.list_instances('Completed');
-SELECT * FROM df.list_instances('Failed');
+-- Filter by status (lowercase)
+SELECT * FROM df.list_instances('running');
+SELECT * FROM df.list_instances('completed');
+SELECT * FROM df.list_instances('failed');
 
 -- With limit
 SELECT * FROM df.list_instances(NULL, 10);
@@ -1496,37 +1534,47 @@ SELECT df.start('SELECT * FROM bob_data');
 
 ### How Identity Is Captured
 
-When you call `df.start()`, pg_durable captures two pieces of identity:
+When you call `df.start()`, pg_durable captures **one** piece of identity:
+
+- **`current_user`** — Your effective role at the time of submission (stored as `submitted_by`)
 
-1. **Login role** (`session_user`) - The user you authenticated as
-2. **Effective role** (`current_user`) - Your current effective privileges (after `SET ROLE`, if used)
+The background worker then connects to PostgreSQL **directly as `submitted_by`** and executes your SQL with that role's privileges. There is no `SET ROLE` indirection.
 
-The background worker then:
-1. Connects to PostgreSQL as your **login role**
-2. Executes `SET ROLE` to your **effective role** 
-3. Runs your SQL with the correct privileges
+**Important:** The captured role must have the `LOGIN` attribute, because the background worker authenticates as that role. If `current_user` lacks `LOGIN`, `df.start()` will reject the submission with an error.
 
-### Working with Group Roles
+### Working with Roles
 
-You can use `SET ROLE` to switch to a group role before submitting a durable function:
+Since the captured role must have `LOGIN`, you cannot use `SET ROLE` to submit workflows as a `NOLOGIN` group role. Instead, grant the necessary table privileges directly to login-capable roles:
 
 ```sql
--- Create a group role (no LOGIN)
+-- Grant table access to alice directly
+GRANT SELECT ON analyst_reports TO alice;
+
+-- Alice submits as herself (her own login role)
+SET SESSION AUTHORIZATION alice;
+SELECT df.start('SELECT * FROM analyst_reports');
+-- ✅ Runs as 'alice' — alice has LOGIN and the required privileges
+```
+
+If you need multiple users to share access to the same tables, grant privileges via a group role but submit as the individual login role:
+
+```sql
+-- Create a group role and grant it to users
 CREATE ROLE analysts NOLOGIN;
 GRANT analysts TO alice;
+GRANT analysts TO bob;
 
-CREATE TABLE analyst_reports (id INT, report TEXT);
-ALTER TABLE analyst_reports OWNER TO analysts;
+-- Grant table access to the group
+GRANT SELECT ON analyst_reports TO analysts;
 
--- Alice switches to the analysts role
+-- Alice submits as herself (inherits analysts privileges)
 SET SESSION AUTHORIZATION alice;
-SET ROLE analysts;
-
--- Submit as the group role
 SELECT df.start('SELECT * FROM analyst_reports');
--- ✅ Runs as 'analysts', alice's session user is used for authentication
+-- ✅ Runs as 'alice', who inherits SELECT from 'analysts'
 ```
 
+**Note:** `SET ROLE` to a `NOLOGIN` role before calling `df.start()` will fail because the worker cannot authenticate as a role without `LOGIN`.
+
 ### What Happens If a Role Is Dropped?
 
 If the user who submitted a function is dropped **before execution**:
@@ -1624,7 +1672,7 @@ GRANT EXECUTE ON FUNCTION df.status(text) TO app_role;
 GRANT EXECUTE ON FUNCTION df.result(text) TO app_role;
 GRANT EXECUTE ON FUNCTION df.cancel(text, text) TO app_role;
 GRANT EXECUTE ON FUNCTION df.wait_for_completion(text, integer) TO app_role;
-GRANT EXECUTE ON FUNCTION df.run(text) TO app_role;
+GRANT EXECUTE ON FUNCTION df.run(text) TO app_role;  -- NOTE: stub, not yet implemented
 GRANT EXECUTE ON FUNCTION df.list_instances(text, integer) TO app_role;
 GRANT EXECUTE ON FUNCTION df.instance_info(text) TO app_role;
 GRANT EXECUTE ON FUNCTION df.instance_nodes(text, integer) TO app_role;
@@ -1946,6 +1994,46 @@ CREATE EXTENSION pg_durable;
 2. Verify the background worker is running (see "Extension Exists But Workflows Don't Start")
 3. Check for resource contention (CPU, disk I/O, connection limits)
 
+### Superuser Cannot Start Workflows
+
+**Symptom**: A superuser calling `df.start()` gets an error like:
+```
+Superuser-submitted instances are disabled. Set pg_durable.enable_superuser_instances = true to allow.
+```
+
+**Cause**: By default, `pg_durable.enable_superuser_instances` is `false`. This is a security safeguard — superuser-submitted workflows bypass RLS and run with full privileges, which could be dangerous in shared environments.
+
+**Solution**: If you intentionally want to submit workflows as a superuser:
+1. Add to `postgresql.conf`:
+   ```ini
+   pg_durable.enable_superuser_instances = true
+   ```
+2. Restart PostgreSQL (this is a Postmaster-context GUC)
+
+Alternatively, create a dedicated non-superuser role for workflow submission and grant it the necessary privileges.
+
+### "current_user lacks LOGIN attribute" Error
+
+**Symptom**: Calling `df.start()` returns an error:
+```
+current_user 'role_name' does not have the LOGIN attribute
+```
+
+**Cause**: The background worker must connect to PostgreSQL as the role that submitted the workflow. Roles without the `LOGIN` attribute cannot be authenticated, so `df.start()` rejects the submission.
+
+This commonly happens when you use `SET ROLE` to switch to a group role (typically `NOLOGIN`) before calling `df.start()`.
+
+**Solution**:
+- Submit workflows as a login-capable role (your own user, not a group role)
+- If you need shared table access, grant privileges via a group role and submit as the individual user:
+  ```sql
+  -- Instead of SET ROLE analysts; df.start(...):
+  GRANT analysts TO alice;  -- alice inherits privileges
+  SET SESSION AUTHORIZATION alice;
+  SELECT df.start('SELECT * FROM analyst_data');  -- runs as alice
+  ```
+- If a role needs `LOGIN`, alter it: `ALTER ROLE role_name LOGIN;`
+
 ### Debugging Failed Workflows
 
 When a durable function fails or produces unexpected results, use these steps to diagnose the issue from `psql` — no server log access required.

docs/grammar.md

@@ -244,22 +244,22 @@ df.start(
 
 ## Variable Substitution
 
-Variables are set before `df.start()` using `df.setvar()`:
+Variables set with `df.setvar()` use curly-brace syntax `{name}` and are substituted at execution time:
 
 ```sql
 SELECT df.setvar('customer_id', '42');
 SELECT df.setvar('sku', 'WIDGET-001');
-SELECT df.start('SELECT * FROM products WHERE sku = $sku');
+SELECT df.start('SELECT * FROM products WHERE sku = ''{sku}''');
 ```
 
-Result bindings (`|=>`) create variables available in subsequent steps:
+Result bindings (`|=>`) create named results available via dollar-sign syntax `$name` in subsequent steps:
 
 ```sql
-'SELECT id FROM users WHERE email = $email' |=> 'user_id'
+'SELECT id FROM users WHERE email = ''{email}''' |=> 'user_id'
 ~> 'SELECT * FROM orders WHERE user_id = $user_id'
 ```
 
-Variables are substituted at execution time, not at definition time.
+Variables (`{name}`) and named results (`$name`) are substituted at execution time, not at definition time.
 
 ## Auto-Wrapping
 

docs/security-review/ThreatModelDFD.md

@@ -113,16 +113,16 @@ sequenceDiagram
     participant HTTP as External HTTP
 
     User->>Backend: SELECT df.start(df.sql('...'))
-    Note over Backend: Captures session_user_oid<br/>and outer_user_oid
+    Note over Backend: Captures current_user (outer_user_oid);<br/>validates LOGIN attribute
     Backend->>Tables: INSERT nodes + instance<br/>(SPI as calling user, RLS)
     Backend->>Duroxide: Enqueue orchestration<br/>(via cached duroxide client)
     Backend-->>User: Returns instance_id
 
     Worker->>Duroxide: Poll for work items<br/>(as worker role / superuser)
     Duroxide-->>Worker: Orchestration work item
-    Worker->>Tables: Load function graph<br/>(reads submitted_by, login_role)
+    Worker->>Tables: Load function graph<br/>(reads submitted_by)
 
-    Note over Worker: Creates per-user connection:<br/>connect as login_role,<br/>SET ROLE submitted_by
+    Note over Worker: Creates per-user connection:<br/>connect directly as submitted_by
     Worker->>Tables: Execute user SQL<br/>(per-user connection, user privileges)
     Worker->>Tables: Update status/results<br/>(as worker role)
 
@@ -159,7 +159,7 @@ EE-USER ──[PostgreSQL wire protocol]──> P-BACKEND
 |---|---|---|---|
 | **S** Spoofing | Attacker impersonates legitimate user | PostgreSQL pg_hba.conf authentication (password, cert, GSSAPI) | ✅ Mitigated |
 | **T** Tampering | Man-in-middle modifies SQL commands | TLS encryption (if configured in pg_hba.conf); not enforced by default | ⚠️ Partial |
-| **R** Repudiation | User denies submitting a durable function | submitted_by and login_role captured at df.start() via GetOuterUserId()/GetSessionUserId() | ✅ Mitigated |
+| **R** Repudiation | User denies submitting a durable function | submitted_by captured at df.start() via GetOuterUserId(); current_user must have LOGIN | ✅ Mitigated |
 | **I** Information Disclosure | Eavesdropping on wire protocol | TLS encryption (if configured); plaintext by default on localhost | ⚠️ Partial |
 | **D** Denial of Service | Flooding with df.start() calls | No rate limiting implemented | ⛔ NOT IMPLEMENTED |
 | **E** Elevation of Privilege | User escalates via SECURITY DEFINER | GetOuterUserId() captures *caller* not *definer*; tested in E2E | ✅ Mitigated |
@@ -174,7 +174,7 @@ P-BACKEND ──[SPI (in-process)]──> DS-TABLES
 |---|---|
 | Source | P-BACKEND (User Session) |
 | Destination | DS-TABLES (df.instances / df.nodes) |
-| Data | Function graph nodes, instance metadata, user identity (submitted_by, login_role) |
+| Data | Function graph nodes, instance metadata, user identity (submitted_by) |
 | Classification | Internal control-plane data |
 | Encryption | N/A (in-process SPI) |
 | Trust Boundary Crossed | TB-USER → TB-PG (same process, different privilege context) |
@@ -262,7 +262,7 @@ P-WORKER ──[sqlx (TCP localhost)]──> DS-TABLES
 |---|---|
 | Source | P-WORKER (Background Worker) |
 | Destination | DS-TABLES (df.instances / df.nodes) |
-| Data | Function graph nodes including submitted_by, login_role, queries |
+| Data | Function graph nodes including submitted_by, queries |
 | Classification | User-authored SQL + identity metadata |
 | Encryption | Localhost TCP (trust auth) |
 | Trust Boundary Crossed | TB-BGW → TB-PG |
@@ -310,10 +310,10 @@ P-WORKER ──[sqlx per-user connection (TCP localhost)]──> DS-TABLES
 
 | STRIDE | Threat | Mitigation | Status |
 |---|---|---|---|
-| **S** Spoofing | Worker impersonates wrong user | login_role and submitted_by captured via C API (GetSessionUserId, GetOuterUserId); cannot be spoofed | ✅ Mitigated |
-| **T** Tampering | User SQL modifies data beyond their privileges | Connection authenticated as login_role + SET ROLE submitted_by; standard PostgreSQL RBAC applies | ✅ Mitigated |
-| **E** Elevation via RESET ROLE | User SQL contains `RESET ROLE` to escape to worker | RESET ROLE reverts to login_role (user's own identity), not worker role; connection is separate | ✅ Mitigated |
-| **E** Elevation via SET ROLE | User attempts `SET ROLE postgres` | SET ROLE requires role membership (checked against login_role); standard PostgreSQL RBAC | ✅ Mitigated |
+| **S** Spoofing | Worker impersonates wrong user | submitted_by captured via C API (GetOuterUserId); must have LOGIN attribute; cannot be spoofed | ✅ Mitigated |
+| **T** Tampering | User SQL modifies data beyond their privileges | Connection authenticated directly as submitted_by; standard PostgreSQL RBAC applies | ✅ Mitigated |
+| **E** Elevation via RESET ROLE | User SQL contains `RESET ROLE` to escape to worker | RESET ROLE reverts to submitted_by (user's own identity), not worker role; connection is separate | ✅ Mitigated |
+| **E** Elevation via SET ROLE | User attempts `SET ROLE postgres` | SET ROLE requires role membership (checked against submitted_by); standard PostgreSQL RBAC | ✅ Mitigated |
 | **E** Elevation via dynamic SQL | User obfuscates privilege escalation | Dynamic SQL runs on same per-user connection; authenticated identity is immutable | ✅ Mitigated |
 | **T** Tampering | Variable substitution ({var}) injects SQL | By design: vars are SQL fragments substituted as-is; user controls both var content and query; runs with user's own privileges | ⚠️ Accepted |
 | **I** Information Disclosure | Result substitution ($name) leaks cross-user data | Results are per-instance; RLS prevents cross-user access to nodes/instances | ✅ Mitigated |
@@ -340,7 +340,7 @@ P-WORKER ──[HTTP/HTTPS (external network)]──> EE-HTTP-TARGET
 | **T** Tampering | Man-in-middle modifies HTTP response | HTTPS available; HTTP also allowed (user's choice) | ⚠️ Partial |
 | **T** Tampering (SSRF) | User targets internal network (169.254.169.254, 10.x, 127.x) | Compile-time IP blocklist; scheme validation; IP literal check; SsrfSafeResolver; DNS rebinding protection | ✅ Mitigated |
 | **T** Tampering (SSRF) | IPv4-mapped IPv6 bypass (::ffff:169.254.169.254) | IPv4-mapped IPv6 extraction before blocklist check | ✅ Mitigated |
-| **R** Repudiation | User denies making HTTP request | Audit logging: submitted_by, login_role, URL, method in trace_info | ✅ Mitigated |
+| **R** Repudiation | User denies making HTTP request | Audit logging: submitted_by, URL, method in trace_info | ✅ Mitigated |
 | **I** Information Disclosure | Data exfiltration via HTTP POST to attacker endpoint | REVOKE EXECUTE on df.http() not yet default; no URL allowlist | ⛔ NOT IMPLEMENTED |
 | **I** Information Disclosure | Credentials in headers stored in df.nodes | HTTP config (including headers with auth tokens) stored in node query column; RLS-protected | ⚠️ Partial |
 | **D** Denial of Service | Attacker creates many HTTP requests to exhaust outbound connections | No rate limiting; timeout configurable (default 30s) | ⛔ NOT IMPLEMENTED |
@@ -414,17 +414,15 @@ graph LR
         A["pg_hba.conf<br/>Authentication"] --> B["PostgreSQL Backend<br/>session_user established"]
         B --> C["Optional: SET ROLE<br/>current_user changes"]
         C --> D["df.start() called"]
-        D --> E["GetSessionUserId()<br/>→ login_role"]
         D --> F["GetOuterUserId()<br/>→ submitted_by"]
-        E --> G["Stored in df.instances<br/>& df.nodes"]
-        F --> G
+        D --> V["Validates LOGIN attribute"]
+        F --> G["Stored in df.instances<br/>& df.nodes"]
     end
 
     subgraph TB-EXEC["Execution Isolation"]
         G --> H["Worker loads graph"]
-        H --> I["connect_as_user(<br/>login_role)"]
-        I --> J["SET ROLE<br/>submitted_by"]
-        J --> K["Execute user SQL<br/>with user privileges"]
+        H --> I["connect_as_user(<br/>submitted_by)"]
+        I --> K["Execute user SQL<br/>with user privileges"]
     end
 ```