@synergenius/flow-weaver 0.33.2 → 0.44.0

package/docs/reference/error-codes.md

@@ -210,7 +210,7 @@ const myNode = (execute: boolean, input: string) => { ... };
 | Field         | Value                                                                                                                                    |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | Severity      | Error                                                                                                                                    |
-| Meaning       | A node instance in the `@instance` annotation uses a reserved ID (`Start` or `Exit`).                                                    |
+| Meaning       | A `@node` declaration uses a reserved instance ID (`Start` or `Exit`).                                                                   |
 | Common Causes | Explicitly naming an instance `Start` or `Exit` in the workflow annotations.                                                             |
 | Fix           | Choose a different instance ID. The names `Start` and `Exit` are reserved for the implicit entry and exit nodes that every workflow has. |
 
@@ -220,14 +220,26 @@ const myNode = (execute: boolean, input: string) => { ... };
 
 **Example:**
 
+<!-- example: invalid RESERVED_INSTANCE_ID -->
 ```typescript
-// BAD: Using reserved names
-/** @instance Start: MyNodeType */ // RESERVED_INSTANCE_ID
-/** @instance Exit: MyNodeType */ // RESERVED_INSTANCE_ID
+/** @flowWeaver nodeType @expression */
+function myNodeType(value: string): { value: string } {
+  return { value };
+}
+
+// BAD: Start and Exit are reserved instance IDs (RESERVED_INSTANCE_ID)
+/**
+ * @flowWeaver workflow
+ * @node Start myNodeType
+ * @node Exit myNodeType
+ */
 
 // GOOD: Non-reserved names
-/** @instance startHandler: MyNodeType */
-/** @instance exitHandler: MyNodeType */
+/**
+ * @flowWeaver workflow
+ * @node startHandler myNodeType
+ * @node exitHandler myNodeType
+ */
 ```
 
 ---
@@ -329,7 +341,7 @@ const myNode = (execute: boolean, input: string) => { ... };
 | Severity      | Error                                                                                                                                                                                                                                                                                                                                                                                                          |
 | Meaning       | A non-STEP input port has more than one incoming connection. Only one value can be received per data input.                                                                                                                                                                                                                                                                                                    |
 | Common Causes | Two different nodes both send data to the same input port. Accidentally duplicating a `@connect` line with a different source.                                                                                                                                                                                                                                                                                 |
-| Fix           | Remove one of the connections. If you need to merge multiple values, either: (1) use a merge node that combines the values and outputs a single result, (2) add a `@mergeStrategy` tag to the port (FIRST, LAST, COLLECT, MERGE, CONCAT), or (3) use separate input ports on the target node. Note: STEP ports (like `execute`) can have multiple connections because control flow supports multiple triggers. |
+| Fix           | Remove one of the connections. If you need to merge multiple values, either: (1) use a merge node that combines the values and outputs a single result, (2) declare a merge strategy on the input port, `@input items [mergeStrategy:COLLECT]` (FIRST, LAST, COLLECT, MERGE, CONCAT), or (3) use separate input ports on the target node. Note: STEP ports (like `execute`) can have multiple connections because control flow supports multiple triggers. |
 
 > **Beginner explanation:** Two different nodes are sending data to the same input port. Each data input can only receive from one source.
 >
@@ -359,7 +371,7 @@ const myNode = (execute: boolean, input: string) => { ... };
 | Severity      | Warning                                                                                                                                                                                          |
 | Meaning       | Both ports are OBJECT type but their TypeScript structural types (`tsType`) differ.                                                                                                              |
 | Common Causes | Connecting a port that outputs `{ name: string }` to a port that expects `{ id: number, name: string }`. Different interfaces that happen to share the OBJECT data type.                         |
-| Fix           | Verify that the source object shape is compatible with what the target expects. If the structures are intentionally different, ensure the target handles missing or extra properties gracefully. |
+| Fix           | Verify that the source object shape is compatible with what the target expects. If the structures are intentionally different, ensure the target handles missing or extra properties gracefully. Expected when a shared context object is threaded through a chain and a consumer declares only the fields it reads: the run is unaffected (structural subtyping), so widen the consumer's type to match the producer, or accept the warning. See the port-design rule in `export-interface`. |
 
 #### LOSSY_TYPE_COERCION (warning)
 
@@ -419,22 +431,13 @@ const myNode = (execute: boolean, input: string) => { ... };
 | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Severity      | Error                                                                                                                                                                               |
 | Meaning       | An instance references a node type function name that does not exist in the workflow.                                                                                               |
-| Common Causes | Typo in the `@instance` annotation. The node type function was renamed or removed. The node type is defined in a different file that is not imported.                               |
-| Fix           | Correct the node type name in the `@instance` annotation. The validator suggests the closest match. Ensure the node type function is defined in the same file or properly imported. |
+| Common Causes | Typo in the `@node` line. The node type function was renamed or removed. The node type is defined in a different file that is not imported.                                        |
+| Fix           | Correct the node type name in the `@node` line. The validator suggests the closest match. Ensure the node type function is defined in the same file or properly imported.          |
 
 > **Beginner explanation:** Did you forget to add `@flowWeaver nodeType` above the function? The `@node` annotation references a function name that the compiler cannot find. Either the function does not exist, is misspelled, or is missing its `@flowWeaver nodeType` annotation.
 >
 > **What to do:** Check that the function name in `@node instanceId functionName` exactly matches a function annotated with `@flowWeaver nodeType` in the same file (or imported).
 
-#### UNDEFINED_NODE
-
-| Field         | Value                                                                                                                                                       |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Severity      | Error                                                                                                                                                       |
-| Meaning       | A connection references a node name that appears in the graph but has no corresponding instance definition.                                                 |
-| Common Causes | A `@connect` annotation references a node that was never declared with `@instance`. The instance annotation was removed but connections still reference it. |
-| Fix           | Either add the missing `@instance` annotation or remove/update the connections that reference the undefined node.                                           |
-
 #### MISSING_REQUIRED_INPUT
 
 | Field         | Value                                                                                                                                                                                                                                                                   |
@@ -442,30 +445,38 @@ const myNode = (execute: boolean, input: string) => { ... };
 | Severity      | Error                                                                                                                                                                                                                                                                   |
 | Meaning       | A required input port on a node instance has no connection, no default value, no expression, and is not optional. This will cause a runtime error.                                                                                                                      |
 | Common Causes | Adding a new required input to a node type without connecting it in the workflow. Removing a connection without adding a default or marking the port optional.                                                                                                          |
-| Fix           | Either: (1) connect a source to the missing input port, (2) add a `@default` value to the port in the node type definition, (3) add an `@expression` to compute the value, (4) mark the port as `@optional`, or (5) add an instance-level expression via `@portConfig`. |
+| Fix           | Either: (1) connect a source to the missing input port, or put the node on a `@path` after a step that outputs the same name, (2) give the port a default in the node type, `@input [apiKey="default-key"]`, (3) mark it optional, `@input [apiKey]`, or (4) bind it on the instance with an expression, `@node fetcher fetchData [expr: apiKey="process.env.API_KEY"]`. |
 
 **Example:**
 
+<!-- example: invalid MISSING_REQUIRED_INPUT -->
 ```typescript
 // BAD: "apiKey" has no connection or default
-/** @flowWeaver nodeType */
-const fetchData = (execute: boolean, url: string, apiKey: string) => { ... };
-
-/** @instance fetcher: fetchData */
-/** @connect Start.url -> fetcher.url */
+/**
+ * @flowWeaver nodeType
+ * @input url - URL to fetch
+ * @input apiKey - Bearer token
+ */
+function fetchData(execute: boolean, url: string, apiKey: string) { ... }
+
+/**
+ * @flowWeaver workflow
+ * @node fetcher fetchData
+ * @connect Start.url -> fetcher.url
+ */
 // Missing: nothing connects to fetcher.apiKey -> MISSING_REQUIRED_INPUT
 
-// Fix option 1: Add connection
-/** @connect Start.apiKey -> fetcher.apiKey */
+// Fix option 1: connect it (or name the Start param apiKey and put fetcher on a @path)
+// @connect Start.apiKey -> fetcher.apiKey
 
-// Fix option 2: Add default in node type
-// @default apiKey "default-key"
+// Fix option 2: default in the node type
+// @input [apiKey="default-key"] - Bearer token
 
-// Fix option 3: Add expression in node type
-// @expression apiKey process.env.API_KEY
+// Fix option 3: optional in the node type
+// @input [apiKey] - Bearer token
 
-// Fix option 4: Make optional
-// @optional apiKey
+// Fix option 4: expression on the instance
+// @node fetcher fetchData [expr: apiKey="process.env.API_KEY"]
 ```
 
 ---
@@ -504,7 +515,7 @@ const fetchData = (execute: boolean, url: string, apiKey: string) => { ... };
 | Severity      | Warning                                                                                                         |
 | Meaning       | A node instance is defined but has no connections (not referenced by any `@connect`).                           |
 | Common Causes | Dead code from a previous iteration. Forgetting to wire up a newly added node.                                  |
-| Fix           | Either connect the node into the workflow graph or remove the `@instance` annotation if it is no longer needed. |
+| Fix           | Either connect the node into the workflow graph or remove its `@node` line if it is no longer needed.           |
 
 #### NO_START_CONNECTIONS (warning)
 
@@ -551,6 +562,15 @@ const fetchData = (execute: boolean, url: string, apiKey: string) => { ... };
 | Common Causes | Defining a return type that includes a property but never connecting anything to the corresponding Exit port. A connection to this Exit port was removed. |
 | Fix           | Connect a node output to this Exit port, or remove the port from the workflow's return type if it is not needed.                                          |
 
+#### HTTP_PARAM_UNKNOWN (error)
+
+| Field         | Value                                                                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Severity      | Error                                                                                                                                                  |
+| Meaning       | An `@http` route has a `:param` segment that names no parameter of the workflow, so a request to it could not bind that part of the path to anything. |
+| Common Causes | A typo in the segment; a parameter renamed after the route was written; a route copied from another workflow.                                          |
+| Fix           | Name the segment after one of the workflow's `@param`s, or take the segment out of the path.                                                          |
+
 #### MULTIPLE_EXIT_CONNECTIONS (warning)
 
 | Field         | Value                                                                                                                                                                                      |
@@ -611,12 +631,12 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Severity      | Warning                                                                                                                                                       |
 | Meaning       | An LLM node routes failures directly to Exit without any retry or fallback logic. Any LLM error immediately aborts the entire workflow.                       |
-| Common Causes | Wiring `llmNode.onFailure -> Exit.onFailure` without a retry or fallback node in between.                                                                    |
-| Fix           | Add a retry node or fallback LLM provider between the LLM's `onFailure` and Exit to improve resilience against transient failures.                           |
+| Common Causes | Wiring `llmNode.onFailure -> Exit.onFailure` without visible retry/fallback handling, or using a shared resilient adapter without declaring its contract. |
+| Fix           | Add a retry/fallback node, or annotate an adapter that already implements it with `@resilience retries=N` and/or `fallback="provider"`.                  |
 
 > **Beginner explanation:** If the LLM fails and goes straight to Exit, the entire workflow stops. Transient errors (rate limits, timeouts) could be retried.
 >
-> **What to do:** Add a retry node or alternative LLM provider between the failure port and Exit.
+> **What to do:** Add a retry/fallback node. If a shared adapter already owns that logic, declare it with `@resilience`; this annotation documents existing behavior and does not implement retries.
 
 #### AGENT_TOOL_NO_OUTPUT_HANDLING (warning)
 
@@ -633,16 +653,16 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
 
 ### Design Quality Rules
 
-These rules detect common workflow design problems that compile fine but indicate poor structure. All are warnings or info-level, suppressible with `@suppress`.
+These rules detect common workflow design problems that compile fine but indicate poor structure. All are warnings or info-level, suppressible per instance with `[suppress: "CODE"]` on the `@node` line.
 
 #### DESIGN_ASYNC_NO_ERROR_PATH (warning)
 
 | Field         | Value                                                                                                                                                         |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Severity      | Warning                                                                                                                                                       |
-| Meaning       | An async node has no onFailure connection. Async operations (network calls, file I/O, AI calls) can fail, and errors will be silently lost.                  |
-| Common Causes | Adding an async node and connecting onSuccess but forgetting to wire onFailure.                                                                              |
-| Fix           | Connect the node's `onFailure` port to an error handler, retry node, or `Exit.onFailure`.                                                                   |
+| Meaning       | An async node has no `onFailure` connection. Async operations (network calls, file I/O, AI calls) can fail. For a normal-mode node the failure is silently lost. For an `@expression` node a throw aborts the run with the error, whether or not `onFailure` is wired. |
+| Common Causes | Adding an async node and connecting `onSuccess` but forgetting to decide what a failure should do.                                                          |
+| Fix           | Normal mode: connect the node's `onFailure` port to an error handler, retry node, or `Exit.onFailure`. Expression mode: wiring `onFailure` does nothing about a throw; to route the failure inside the graph, write the node in normal mode and return `onFailure: true`. If aborting the run is the intended behaviour, add `[suppress: "DESIGN_ASYNC_NO_ERROR_PATH"]` to the `@node` line. |
 
 #### DESIGN_SCOPE_NO_FAILURE_EXIT (warning)
 
@@ -700,6 +720,15 @@ These rules detect common workflow design problems that compile fine but indicat
 
 ---
 
+## Parse-Level Codes
+
+Two codes come from parsing the file, before validation runs. `fw_validate`, `fw_describe` and the other MCP tools return them as the error `code`; `fw validate --json` prints them as parse errors.
+
+| Code | Meaning | What to do |
+|------|---------|------------|
+| `MULTIPLE_WORKFLOWS_FOUND` | The file declares several workflows and none was named | Pass `workflowName` (`-w` on the CLI), or let the tool handle every workflow in turn where it offers to |
+| `NO_WORKFLOW_FOUND` | The file has node types but no `@flowWeaver workflow` function | Add the workflow annotation above an exported function, or validate the file as node types only (which `fw_validate` does on its own) |
+
 ## Quick Reference: Error Severity Summary
 
 ### Errors (must fix)
@@ -712,6 +741,7 @@ These rules detect common workflow design problems that compile fine but indicat
 | DUPLICATE_NODE_NAME | Two node types share a function name |
 | RESERVED_NODE_NAME | Node type uses "Start" or "Exit" |
 | RESERVED_INSTANCE_ID | Instance ID is "Start" or "Exit" |
+| INVALID_SCOPE_NAME | A scoped port names a scope that is not a JavaScript identifier (scope names become identifiers in generated code) |
 | UNKNOWN_SOURCE_NODE | Connection from nonexistent node |
 | UNKNOWN_TARGET_NODE | Connection to nonexistent node |
 | UNKNOWN_SOURCE_PORT | Connection from nonexistent output port |
@@ -720,15 +750,23 @@ These rules detect common workflow design problems that compile fine but indicat
 | STEP_PORT_TYPE_MISMATCH | STEP port connected to data port or vice versa |
 | TYPE_INCOMPATIBLE | Type mismatch with @strictTypes enabled |
 | UNKNOWN_NODE_TYPE | Instance references nonexistent node type |
-| UNDEFINED_NODE | Connection references node with no instance |
 | MISSING_REQUIRED_INPUT | Required input has no connection/default/expression |
 | CYCLE_DETECTED | Graph contains a loop |
 | INVALID_EXIT_PORT_TYPE | Exit onSuccess/onFailure is not STEP type |
+| HTTP_PARAM_UNKNOWN | An @http route has a :param segment that names no parameter of the workflow |
 | SCOPE_MISSING_REQUIRED_INPUT | Required input port on a scoped child has no connection |
 | SCOPE_WRONG_SCOPE_NAME | Connection uses a scope name not defined on the node |
 | SCOPE_CONNECTION_OUTSIDE | Scoped connection references a node outside the scope |
 | SCOPE_UNKNOWN_PORT | Connection references a port that is not a scoped port of the specified scope |
 | AGENT_LLM_MISSING_ERROR_HANDLER | LLM node's onFailure port is unconnected |
+| DUPLICATE_INSTANCE_ID | Two @node declarations in one workflow use the same ID. Each instance ID must be unique |
+| STUB_NODE | An instance uses a node type that has no implementation. Implement it, or validate in draft mode to check structure only |
+| DUPLICATE_CONNECTION | The same from-port to to-port connection is declared more than once |
+| CROSS_SCOPE_CONNECTION | A connection links nodes that live in different scopes. Nodes in different scopes cannot connect directly |
+| SCOPE_INCONSISTENT | An instance is listed in more than one scope. A node can belong to only one scope |
+| COERCE_ON_FUNCTION_PORT | An `as` coercion is applied to a FUNCTION port. Function values cannot be meaningfully coerced |
+| EXPRESSION_SYNTAX | An [expr:] binding or an Expression: default does not parse as a JavaScript expression (text needs quotes inside the attribute: timeout="'24h'"). It would otherwise fail only when the generated file is transpiled |
+| DURABLE_CLOSURE_INVALID | A workflow with a durable gate breaks a durability rule (a gate/effect in more than one branch region or taking data from outside it, pull/lazy execution, an unclassified node, or a bad effect contract). Surfaced at author time. The coordinator would otherwise reject it only at run time. |
 <!-- AUTO:END error_summary_table -->
 
 ### Warnings (should review)
@@ -757,11 +795,20 @@ These rules detect common workflow design problems that compile fine but indicat
 | AGENT_MISSING_MEMORY_IN_LOOP | Loop has LLM but no conversation memory node |
 | AGENT_LLM_NO_FALLBACK | LLM onFailure routes directly to Exit |
 | AGENT_TOOL_NO_OUTPUT_HANDLING | Tool executor data outputs all unconnected |
-| DESIGN_ASYNC_NO_ERROR_PATH | Async node has no onFailure connection |
+| DESIGN_ASYNC_NO_ERROR_PATH | Async node has no onFailure connection (durable gates are exempt: their body never runs and their failure arm is the resolver's rejection) |
 | DESIGN_SCOPE_NO_FAILURE_EXIT | Scope node has no failure path out |
 | DESIGN_UNBOUNDED_RETRY | Retry scope has no visible attempt limit |
 | DESIGN_FANOUT_NO_FANIN | Fan-out to multiple step targets with no merge back |
 | DESIGN_EXIT_DATA_UNREACHABLE | Exit data port has no connection and no pull-execution provider |
 | DESIGN_PULL_CANDIDATE | Node has no step trigger but its outputs are consumed downstream |
 | DESIGN_PULL_UNUSED | Pull-execution node has no downstream consumers |
+| SCOPE_EMPTY | A scope declared on a node has no child nodes |
+| COERCE_TYPE_MISMATCH | An `as` coercion produces a type the target port does not expect. Use the coercion that matches the target |
+| REDUNDANT_COERCE | An `as` coercion converts between identical source and target types and does nothing |
+| INVALID_PORT_TYPE | A port declares a dataType that is not a recognised Flow Weaver type |
+| INVALID_COLOR | A node type uses an @color value that is not in the palette. See the visual-reference topic for valid colors |
+| INVALID_ICON | A node type uses an @icon value that is not a Material Symbols name (snake_case or camelCase). See the visual-reference topic |
+| INVALID_EXECUTE_WHEN | A node type declares an @executeWhen value that is not a recognised execution strategy |
+| INVALID_PORT_CONFIG_REF | An instance configures a port (portOrder, portLabel, expr) that does not exist on its node type |
+| SUPPRESS_UNKNOWN_CODE | A [suppress: ...] entry cannot be a validation code, so it suppresses nothing. Codes are separate string literals, e.g. [suppress: "A", "B"], not [suppress: "A,B"] |
 <!-- AUTO:END warning_summary_table -->

package/docs/reference/export-interface.md

@@ -26,7 +26,9 @@ Use JSDoc `@param` to define Start node ports:
 export function myWorkflow(
   execute: boolean,
   params: { data: any; optional?: any; withDefault?: number }
-) { ... }
+): { onSuccess: boolean; onFailure: boolean } {
+  throw new Error('generated body was not installed');
+}
 ```
 
 **IMPORTANT:**
@@ -44,42 +46,61 @@ Use JSDoc `@returns` to define Exit node ports:
  * @returns result - The output result
  * @returns status - Status message
  */
-export function myWorkflow(...): {
-  onSuccess: boolean;
-  onFailure: boolean;
-  result: any;
-  status: string
-} { ... }
+export function myWorkflow(
+  execute: boolean,
+  params: { data: any }
+): { onSuccess: boolean; onFailure: boolean; result: any; status: string } {
+  throw new Error('generated body was not installed');
+}
 ```
 
 ## Node Inputs/Outputs
 
-Use `@input` and `@output` for node types. **Inputs become direct parameters:**
+Use `@input` and `@output` for node types. **Inputs become direct parameters**, and the return value is the output:
 
 ```typescript
 /**
  * @flowWeaver nodeType
+ * @expression
  * @input value - Value to process
  * @input count - Number of times
  * @output result - Processed result
  */
-function processNode(execute: boolean, value: any, count: number) { ... }
-//                                     ^           ^
-//                               Direct parameters (NOT wrapped in object)
+function processNode(value: any, count: number): any { ... }
+//                   ^           ^
+//             Direct parameters (NOT wrapped in object)
 ```
 
+With one `@output`, the whole return value is that port. With several, return an object with one property per `@output`. A throw marks the node failed and propagates the error out of the workflow call.
+
+**The text after the dash is the port's display label, not a description.** It renders inside the port badge in the diagram, so keep it to **1–2 words** — `@output task - Agent task`, not `@output task - The agent task (agentId, context, prompt), as one value`. There is no separate description field for a port; a long sentence just overflows the badge. Omit the dash entirely when the name already says it (`@output task`).
+
+Only a normal-mode node (see Mandatory Ports) adds `execute: boolean` in front: `function processNode(execute: boolean, value: any, count: number)`.
+
+## Designing ports to avoid connection sprawl
+
+The rule: **scalar ports for what a node reads or transforms; one object port for context that flows through unchanged.** Getting this backwards is the main cause of over-wired workflows.
+
+- **Never create a relay port pair.** An `@input x` plus `@output x` that only passes a value through is a smell. If several nodes need the same unchanging values, carry them in one object port (`@output brief`) instead of re-declaring each scalar on every node. One shared `brief` object replaced eight `surface` re-wirings in one workflow.
+- **Keep port names identical along a chain** so `@path` wires the data with no `@connect`; reserve `@connect` for genuine renames.
+- **Gates read the fields they need with `[expr:]`** (`context="upstream.state.field"`) rather than through relay ports — but only from their **immediate predecessor**. Reaching past a gate to an earlier node puts the gate in two branch regions and is rejected (`DURABLE_CLOSURE_INVALID`). Thread the shared object through each gate so each reads from the one before it.
+
+The cost of an object port: type-checking is per-object, not per-field, and a consumer that declares a narrower shape than the producer emits gets an `OBJECT_TYPE_MISMATCH` warning (it still runs — structural subtyping). Keep the one or two values a node actually transforms as typed scalars so the checker still guards them.
+
 # Mandatory Ports
 
-Always present on every node/workflow:
+Every node and workflow has these STEP ports, and `@path` wires them for every step:
 
 **Input:**
 
-- `execute` (STEP) - First function parameter
+- `execute` (STEP)
 
 **Output:**
 
-- `onSuccess` (STEP) - In return type
-- `onFailure` (STEP) - In return type
+- `onSuccess` (STEP)
+- `onFailure` (STEP)
+
+An expression node never mentions them: the runtime passes `execute`, sets `onSuccess` on return, and on a throw sets `onFailure` and rethrows, so the error leaves the workflow call rather than following a `:fail` route. They appear in a function signature only in **normal mode** (`execute` is the first parameter, `onSuccess`/`onFailure` are in the return type) and in the **workflow export**, whose signature is always `(execute: boolean, params: {...}): { onSuccess: boolean; onFailure: boolean; ...returns }`. Normal mode is reserved for a node that routes a failure to another node or to `Exit.onFailure`, returns data alongside a failure, a void side-effect, a boolean branch, a scope owner (forEach below), or a durable gate or effect.
 
 # Async Workflows
 
@@ -95,7 +116,23 @@ export async function asyncWorkflow(
   execute: boolean,
   params: { data: any }
 ): Promise<{ onSuccess: boolean; onFailure: boolean; result: any }> {
-  // async implementation
+  throw new Error('generated body was not installed');
+}
+```
+
+Async node types work the same way. An `async` expression function's resolved value is its output, and a rejection is its failure:
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @expression
+ * @input url - URL to fetch
+ * @output data - Parsed response body
+ */
+async function fetchJson(url: string): Promise<any> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return await res.json();
 }
 ```
 
@@ -103,6 +140,17 @@ export async function asyncWorkflow(
 
 For iteration (forEach), use **per-port scopes** with `scope:scopeName` suffix on ports.
 
+The forEach node owns a scope, which is one of the reasons for normal mode: it takes `execute`, calls the generated callback per item itself, and reports `onSuccess`/`onFailure` when the loop is done. The child node inside the scope is an ordinary expression node.
+
+> **A scope and a durable gate cannot share a workflow.** A workflow whose
+> reachable closure contains a gate — `waitForEvent`, `waitForAgent`, or any
+> `@durableGate` — may not contain scoped children at all, and is refused with
+> `DURABLE_CLOSURE_INVALID`. The owner calls the callback itself, so the engine
+> cannot prove on resume that the iteration it is servicing is the one that
+> paused. To loop over work that pauses, run the loop **outside** the workflow
+> and invoke the gated workflow once per item, or write the passes out in full
+> if there are few and the count is fixed. See [Durable Gates](durable-gates.md).
+
 ## 1. Define ForEach Node Type
 
 ```typescript
@@ -122,6 +170,7 @@ function forEach(
   items: any[],
   processItem: (start: boolean, item: any) => { success: boolean; failure: boolean; processed: any }
 ) {
+  // Normal mode: this node owns the processItem scope and drives the callback itself
   if (!execute) return { onSuccess: false, onFailure: false, results: [] };
   const results = items.map((item) => processItem(true, item).processed);
   return { onSuccess: true, onFailure: false, results };
@@ -134,10 +183,18 @@ Key points:
 - Callback is auto-generated by compiler, receives scoped port values as args
 - The node implementation iterates by calling callback for each item
 - Mandatory scoped STEP ports: `start` (output), `success`/`failure` (inputs)
+- Scoped wiring uses `@connect` with the `:scopeName` suffix; `@path` does not express it
 
 ## 2. Use ForEach in Workflow
 
+The child is an ordinary expression node:
+
 ```typescript
+/** @flowWeaver nodeType @expression */
+function processor(item: any): { result: any } {
+  return { result: item };
+}
+
 /**
  * @flowWeaver workflow
  * @node loop forEach
@@ -170,30 +227,38 @@ Key syntax:
 
 ```typescript
 // WRONG - inputs wrapped in object
-function node(execute: boolean, params: { value: any }) { ... }
+function node(params: { value: any }) { ... }
 
 // CORRECT - direct parameters for nodes
-function node(execute: boolean, value: any) { ... }
+function node(value: any): Result { ... } // expression mode
+function node(execute: boolean, value: any) { ... } // normal mode only
 ```
 
-**Missing execute parameter**
+**Signature does not match the mode**
 
 ```typescript
-// WRONG - no execute
+// WRONG - normal mode (no @expression tag) but no execute parameter
 function node(value: any) { ... }
 
-// CORRECT
+// CORRECT - expression mode: add @expression, no execute parameter
+/** @flowWeaver nodeType @expression ... */
+function node(value: any): Result { ... }
+
+// CORRECT - normal mode: execute comes first
 function node(execute: boolean, value: any) { ... }
 ```
 
-**Missing return properties**
+**Missing return properties (normal mode)**
 
 ```typescript
-// WRONG - missing onFailure
+// WRONG - normal mode return missing onFailure
 return { onSuccess: true, result: 42 };
 
-// CORRECT
+// CORRECT - normal mode
 return { onSuccess: true, onFailure: false, result: 42 };
+
+// CORRECT - expression mode returns the value itself
+return 42;
 ```
 
 **Multiple connections to same Exit port**
@@ -212,10 +277,10 @@ return { onSuccess: true, onFailure: false, result: 42 };
 
 ```typescript
 // WRONG - 'process' is a Node.js global
-function process(execute: boolean, item: any) { ... }
+function process(item: any) { ... }
 
 // CORRECT - use non-reserved names
-function processItem(execute: boolean, item: any) { ... }
+function processItem(item: any) { ... }
 ```
 
 Avoid: `process`, `module`, `require`, `exports`, `console`, `global`