@synergenius/flow-weaver 0.33.2 → 0.44.0

package/docs/reference/compilation.md

@@ -1,7 +1,7 @@
 ---
 name: Compilation
-description: How compilation works, TypeScript and Inngest targets, compile options, and serve handler generation
-keywords: [compile, compilation, target, typescript, inngest, production, source-map, format, strict, clean, serve, framework, step.run, durable, trigger, cancelOn, retries, timeout, throttle, cron, markers]
+description: How compilation works, the TypeScript target, pack targets and target options, compile options
+keywords: [compile, compilation, target, typescript, production, source-map, format, strict, clean, trigger, cancelOn, retries, timeout, throttle, cron, markers, pack target]
 ---
 
 # Compilation
@@ -13,16 +13,16 @@ Flow Weaver compiles annotated TypeScript into executable workflow code. The com
 Compilation is **in-place** by default. The compiler inserts generated code into marker sections within your source file:
 
 ```typescript
-// Your node types and annotations above — untouched
+// Your node types and annotations above (untouched)
 
-// @flow-weaver-runtime — start
+// @flow-weaver-runtime-start
 // Generated imports and runtime setup
-// @flow-weaver-runtime — end
+// @flow-weaver-runtime-end
 
 export function myWorkflow(params: { data: string }) {
-  // @flow-weaver-body — start
+  // @flow-weaver-body-start
   // Generated execution logic
-  // @flow-weaver-body — end
+  // @flow-weaver-body-end
 }
 ```
 
@@ -58,73 +58,31 @@ fw compile workflow.ts
 
 Generates code like:
 ```typescript
-// @flow-weaver-runtime — start
+// @flow-weaver-runtime-start
 // (inline runtime: GeneratedExecutionContext, CancellationError, types)
-// @flow-weaver-runtime — end
+// @flow-weaver-runtime-end
 
 export function myWorkflow(params: { data: string }) {
-  // @flow-weaver-body — start
+  // @flow-weaver-body-start
   const ctx = new ExecutionContext();
   const validate_result = validateRecord(true, params.data);
   // ... execution chain
   return { onSuccess: true, onFailure: false, result: score_result.score };
-  // @flow-weaver-body — end
+  // @flow-weaver-body-end
 }
 ```
 
 ---
 
-## Inngest Target
+## Other Platforms
 
-The `inngest` target generates **durable functions** using [Inngest](https://www.inngest.com/). Each workflow node becomes a `step.run()` call, providing automatic retries, event-driven triggers, and crash recovery.
-
-```bash
-fw compile workflow.ts --target inngest
-```
-
-### Per-Node Durability
-
-Each node in the workflow becomes an individually durable step:
-
-```typescript
-const validate_result = await step.run('validate', async () => {
-  return validateRecord(true, params.data);
-});
-
-const enrich_result = await step.run('enrich', async () => {
-  return enrichRecord(true, validate_result.data);
-});
-```
-
-If the process crashes after `validate` completes, Inngest replays the function and skips already-completed steps.
-
-### Parallel Execution
-
-Independent nodes execute in parallel using `Promise.all`:
-
-```typescript
-const [branch_a, branch_b] = await Promise.all([
-  step.run('branchA', async () => processA(true, data)),
-  step.run('branchB', async () => processB(true, data)),
-]);
-```
-
-### Iteration
-
-ForEach patterns use indexed `step.run()` for per-element durability:
-
-```typescript
-const results = [];
-for (let i = 0; i < items.length; i++) {
-  results.push(await step.run(`process-${i}`, async () => processItem(true, items[i])));
-}
-```
+`fw compile` and `fw_compile` always produce the TypeScript described above. Generating code for another platform is an export: `fw export --target <name>` hands the parsed workflow to a target an installed pack provides, and the pack documents what it writes. See [Deployment](deployment.md) and [Marketplace](marketplace.md).
 
 ---
 
-## Inngest Annotations
+## Deployment Annotations
 
-These annotations configure Inngest-specific behavior. They go inside `@flowWeaver workflow` blocks.
+These workflow-level annotations are parsed by core into the workflow's options. The compiler ignores them; an export target reads the ones it supports. They go inside `@flowWeaver workflow` blocks.
 
 ### `@trigger`
 
@@ -208,6 +166,17 @@ Rate limiting:
 ### Complete Example
 
 ```typescript
+/** @flowWeaver nodeType @expression */
+function validateExpense(expenseId: string, amount: number): { expenseId: string; amount: number } {
+  if (amount <= 0) throw new Error('amount must be positive');
+  return { expenseId, amount };
+}
+
+/** @flowWeaver nodeType @expression */
+async function processPayment(expenseId: string, amount: number): Promise<{ result: object }> {
+  return { result: { expenseId, paid: amount } };
+}
+
 /**
  * @flowWeaver workflow
  * @trigger event="app/expense.submitted"
@@ -218,13 +187,14 @@ Rate limiting:
  *
  * @node v validateExpense
  * @node pay processPayment
- * @node wait waitForEvent [expr: eventName="'app/expense.approved'", match="'data.expenseId'", timeout="'48h'"]
+ * @node wait delay [expr: duration="'48h'"]
  * @path Start -> v -> wait -> pay -> Exit
  */
 export async function expenseWorkflow(
+  execute: boolean,
   params: { expenseId: string; amount: number }
-): Promise<{ result: object }> {
-  throw new Error('Not compiled');
+): Promise<{ onSuccess: boolean; onFailure: boolean; result: object }> {
+  throw new Error('generated body was not installed');
 }
 ```
 
@@ -290,54 +260,11 @@ fw compile workflow.ts --dry-run
 
 ---
 
-## Serve Handler Generation
-
-Generate a complete HTTP handler for receiving Inngest events:
-
-```bash
-fw compile workflow.ts --target inngest --serve --framework next
-```
-
-### Supported Frameworks
-
-| Framework | Handler |
-|-----------|---------|
-| `next` | Next.js App Router route handler |
-| `express` | Express middleware |
-| `hono` | Hono route handler |
-| `fastify` | Fastify plugin |
-| `remix` | Remix action |
-
-### Typed Events (`--typed-events`)
-
-Generate Zod schemas for event validation from `@param` annotations:
-
-```bash
-fw compile workflow.ts --target inngest --typed-events
-```
-
----
-
-## CLI Overrides
-
-Several Inngest annotations can be overridden from the CLI without modifying the source file:
-
-| CLI Flag | Overrides |
-|----------|-----------|
-| `--cron <schedule>` | `@trigger cron=` |
-| `--retries <n>` | `@retries` |
-| `--timeout <duration>` | `@timeout` |
-
-```bash
-fw compile workflow.ts --target inngest --retries 5 --timeout "1h"
-```
-
----
-
 ## Related Topics
 
-- [CLI Reference](cli-reference) — Full compile command flags
-- [Deployment](deployment) — Export to serverless platforms
-- [Advanced Annotations](advanced-annotations) — Annotations that affect compilation
-- [Debugging](debugging) — Debug instrumentation and WebSocket events
-- [Built-in Nodes](built-in-nodes) — delay, waitForEvent, invokeWorkflow
+- [CLI Reference](cli-reference.md) — Full compile command flags
+- [Deployment](deployment.md) — Export targets, HTTP serve mode, OpenAPI
+- [Advanced Annotations](advanced-annotations.md) — Annotations that affect compilation
+- [Debugging](debugging.md) — Debug instrumentation and WebSocket events
+- [Built-in Nodes](built-in-nodes.md) — delay, waitForEvent, invokeWorkflow, waitForAgent
+- [Durable Gates](durable-gates.md) — Workflows that pause and resume across processes

package/docs/reference/concepts.md

@@ -8,7 +8,7 @@ keywords: [annotations, nodes, workflows, ports, scopes, STEP, expression, conne
 
 # Direct Code Editing
 
-**The code IS the workflow. The visual editor is a view.**
+**The code IS the workflow.**
 
 Flow Weaver workflows are plain TypeScript files with JSDoc annotations. You write functions, annotate them, and the compiler handles everything else. No drag-and-drop required.
 
@@ -23,39 +23,37 @@ Here is a complete, minimal workflow written entirely by hand:
  * @output message - Greeting message
  */
 function greet(name: string): string {
-  return `Hello, ${name}!`;
+  return "Hello, " + name + "!";
 }
 
 /**
  * @flowWeaver nodeType
  * @expression
  * @label Uppercase
- * @input text - Text to transform
+ * @input message - Text to transform
  * @output result - Uppercased text
  */
-function uppercase(text: string): string {
-  return text.toUpperCase();
+function uppercase(message: string): string {
+  return message.toUpperCase();
 }
 
 /**
  * @flowWeaver workflow
  * @param name - Name to greet
  * @returns result - Uppercased greeting
- * @node greeter greet [position: 180 0]
- * @node transform uppercase [position: 360 0]
- * @connect Start.name -> greeter.name
- * @connect greeter.message -> transform.text
- * @connect transform.result -> Exit.result
+ * @node greeter greet
+ * @node transform uppercase
+ * @path Start -> greeter -> transform -> Exit
  */
 export function greetingWorkflow(
   execute: boolean,
   params: { name: string }
 ): { onSuccess: boolean; onFailure: boolean; result: string } {
-  return { onSuccess: true, onFailure: false, result: '' };
+  throw new Error('generated body was not installed');
 }
 ```
 
-That is it. Two expression-mode functions, one workflow annotation, zero boilerplate. The compiler infers STEP connections from the data flow -- no `execute`, `onSuccess`, or `onFailure` wiring needed.
+That is it. Two expression-mode functions, one workflow annotation, zero boilerplate. The `@path` line declares the route, and the compiler wires the data ports by name (`Start.name -> greeter.name`, `greeter.message -> transform.message`, `transform.result -> Exit.result`) together with the STEP connections along the way -- no `execute`, `onSuccess`, `onFailure`, or `@connect` lines needed. The exported function is a stub; the compiler installs the real body.
 
 ---
 
@@ -72,14 +70,15 @@ That is it. Two expression-mode functions, one workflow annotation, zero boilerp
 | Convert existing functions       | `node-conversion`            | concepts            |
 | Debug validation errors          | `debugging`                  | error-codes         |
 | Look up specific error code      | `error-codes`                | debugging           |
-| Reuse workflow fragments         | `patterns`                   | concepts            |
 | Check annotation syntax          | `jsdoc-grammar`              | concepts            |
 | Look up CLI commands/flags       | `cli-reference`              | —                   |
 | Pull execution, merge strategies | `advanced-annotations`       | jsdoc-grammar       |
-| Compile to Inngest               | `compilation`                | cli-reference       |
+| Compile to a pack target         | `compilation`                | cli-reference       |
 | Deploy to cloud                  | `deployment`                 | compilation         |
-| Build a CI/CD pipeline           | `cicd`                       | deployment, scaffold |
-| Use delay/waitForEvent/mocks     | `built-in-nodes`             | debugging           |
+| Get the one-page map first       | `orientation`                | concepts            |
+| Use delay/invokeWorkflow/mocks   | `built-in-nodes`             | debugging           |
+| Pause for approval/input/agent   | `durable-gates`              | built-in-nodes      |
+| Drive Flow Weaver from an editor | `mcp-tools`                  | cli-reference       |
 | Publish marketplace packages     | `marketplace`                | —                   |
 
 Use `fw docs <topic>` to read any topic.
@@ -99,19 +98,19 @@ fw watch <file>      # Watch mode
 fw dev <file>        # Watch + compile + run in one command
 fw serve [dir]       # HTTP server exposing workflows as endpoints
 fw diagram <file>    # Generate SVG diagram
-fw export <file>     # Export as serverless function or CI/CD pipeline
+fw export <file>     # Export through a target provided by an installed pack
 fw docs              # Browse documentation
 fw docs <topic>      # Read a specific topic
 fw docs search <q>   # Search across all docs
 ```
 
-Options: `-w/--workflow-name`, `--json`, `--format text|mermaid`. See `cli-reference` for all commands and flags.
+Options: `-w/--workflow`, `--json`, `--format text|mermaid`. See `cli-reference` for all commands and flags.
 
 ## Core Annotations
 
 ### Expression Node Type (Recommended)
 
-> **Tip:** Most nodes should use `@expression` mode. Use normal mode only for custom error handling or void returns.
+> **Tip:** A node type is an `@expression` function unless it has one of the reasons listed under "Node Type (Normal Mode)" below.
 
 ```typescript
 /**
@@ -139,7 +138,7 @@ Expression nodes are pure functions where:
 - Best for: transformers, math, utilities, data mapping, async fetchers, API calls
 - Optional `@color` and `@icon` annotations customize the node's appearance in SVG diagrams (see `advanced-annotations` for available values)
 
-> **Start with expression mode.** Only switch to normal mode when you need to return data alongside a failure (error-with-data patterns) or for void side-effect functions. Expression nodes handle success/failure branching automatically — throw to trigger the `onFailure` path.
+> **Start with expression mode.** Only switch to normal mode when the node must route a failure to another node or to `Exit.onFailure`, return data alongside a failure (error-with-data), is a void side-effect, is a boolean branch, owns a scope, or is a durable gate or effect. When an expression node throws, the runtime marks its `onFailure` port and then rethrows: the error propagates out of the workflow call, so a `:fail` route from an expression node is not taken. A failure that downstream nodes must react to is returned, not thrown, from a normal-mode node.
 
 #### Async Expression Example
 
@@ -159,7 +158,15 @@ async function fetchUser(userId: string): Promise<User> {
 
 ### Node Type (Normal Mode)
 
-Use normal mode when you need to return error data alongside the failure signal, or for `void` side-effect functions.
+Normal mode is the exception, not the definition of a node type. Drop `@expression` only when the node has to take over control flow itself, for one of these reasons:
+
+- **Error-with-data** -- it must return data alongside the failure signal, not just fail
+- **Void side-effect** -- it returns nothing, so there is no value to map to an output
+- **Boolean branch** -- it routes on a condition (`onSuccess = cond`, `onFailure = !cond`) rather than on an error
+- **Scope owner** -- it drives scoped ports itself, like a forEach or retry node (see Scoped Nodes below)
+- **Durable gate or effect** -- see `durable-gates`
+
+A normal-mode function takes `execute: boolean` as its first parameter, then each `@input` as a direct parameter, and returns `onSuccess`/`onFailure` next to its outputs. Say the reason in a comment so the next reader does not "fix" it back to expression mode:
 
 ```typescript
 /**
@@ -174,31 +181,38 @@ function nodeName(
   inputA: TypeA, // Each @input becomes a direct parameter
   inputB: TypeB // NOT wrapped in an object
 ): { onSuccess: boolean; onFailure: boolean; outputName: Type } {
+  // Normal mode: outputName is returned even when the node fails (error-with-data)
   if (!execute) return { onSuccess: false, onFailure: false, outputName: null };
+  if (!ok) return { onSuccess: false, onFailure: true, outputName: partial };
   return { onSuccess: true, onFailure: false, outputName: result };
 }
 ```
 
 ### Workflow Export
 
+<!-- example: fragment -->
 ```typescript
 /**
  * @flowWeaver workflow
  * @param inputPort - Description
  * @returns outputPort - Description
- * @node instanceId nodeTypeName [position: 180 0]
- * @connect Start.inputPort -> instanceId.input
+ * @node instanceId nodeTypeName
+ * @path Start -> instanceId -> Exit
  * @connect instanceId.output -> Exit.outputPort
  */
 export function workflowName(
   execute: boolean,
   params: { inputPort: Type }
 ): { onSuccess: boolean; onFailure: boolean; outputPort: Type } {
-  return { onSuccess: true, onFailure: false, outputPort: null };
+  throw new Error('generated body was not installed');
 }
 ```
 
-> STEP connections (`execute`, `onSuccess`, `onFailure`) are auto-wired for expression nodes. Add explicit STEP connections only for normal mode nodes or to override the automatic wiring.
+`@path` declares the control flow and wires every data port by name: each input of a step resolves to the nearest earlier step with a same-name output, and Exit's `@returns` ports resolve the same way (`Start.inputPort -> instanceId.inputPort` above). Add `@connect` only for ports whose names differ, like `instanceId.output -> Exit.outputPort`; an explicit `@connect` always wins over the name resolution. A `Start` param never passes straight through to `Exit` by name -- write that as an explicit `@connect`.
+
+The exported function keeps this signature (`execute: boolean`, a `params` object, `onSuccess`/`onFailure` plus the `@returns` ports) and a throwing stub body; the compiler installs the real body.
+
+> `@path` writes the STEP connections (`execute`, `onSuccess`, `onFailure`) for every step, whatever the node's mode. Use `:ok`/`:fail` suffixes on a step to branch, and explicit STEP `@connect` lines only to override the automatic wiring. See `advanced-annotations` for the full `@path` rules.
 
 ### Importing External Functions
 
@@ -207,10 +221,10 @@ Use `@fwImport` to turn npm package functions or local module exports into node
 ```typescript
 /**
  * @flowWeaver workflow
- * @fwImport npm/lodash/map map from "lodash"
+ * @fwImport npm/lodash/uniq uniq from "lodash"
  * @fwImport local/utils/format formatDate from "./utils"
- * @node mapper npm/lodash/map
- * @connect Start.items -> mapper.collection
+ * @node dedupe npm/lodash/uniq
+ * @connect Start.items -> dedupe.array
  */
 ```
 
@@ -237,6 +251,18 @@ Use `@fwImport` to turn npm package functions or local module exports into node
 
 ### Node Types (direct parameters)
 
+Expression mode (the default, with `@expression`):
+
+```typescript
+function myNode(inputA: Type, inputB: Type): ReturnType
+```
+
+- Params: each `@input` as a direct parameter, in declaration order
+- Return: the value of the single `@output`, or an object with one property per `@output`
+- Failure: throw; the runtime marks `onFailure` and rethrows, so the error leaves the workflow call
+
+Normal mode (only for the reasons listed under "Node Type (Normal Mode)"):
+
 ```typescript
 function myNode(execute: boolean, inputA: Type, inputB: Type): {...}
 ```
@@ -255,35 +281,30 @@ export function myWorkflow(execute: boolean, params: { inputA: Type }): {...}
 - Second param: `params: {...}` object containing all `@param` inputs
 - Return: `{ onSuccess: boolean, onFailure: boolean, ...outputs }`
 
-> **Key difference:** Nodes use direct params, workflows use `params` object.
+> **Key difference:** Nodes use direct params, workflows use `params` object. The workflow export always has the `execute` / `onSuccess` / `onFailure` shape, even when every node in it is an expression node.
 
 ## Node Registration
 
-Every node used in a workflow must be explicitly declared with `@node`. The compiler builds a static directed graph from annotations at compile time, so it needs to know about every node before code generation begins. This is different from normal function calls where you just invoke a function directly.
+Every node used in a workflow must be declared with `@node`. The compiler builds a static directed graph from annotations at compile time, so it needs to know about every node before code generation begins. This is different from normal function calls where you just invoke a function directly.
 
-Built-in nodes (`delay`, `waitForEvent`, `invokeWorkflow`, `waitForAgent`) are exported from the library but still need explicit declaration in your workflow file. The compiler validates all `@node` references against the set of available node types — functions annotated with `@flowWeaver nodeType` in the same file or imported via `@fwImport`.
+A `@node` reference must resolve to a node type the compiler knows: a function annotated `@flowWeaver nodeType` in the same file, one imported via `@fwImport`, or a built-in.
 
-To use a built-in node, define or import the function and annotate it:
+Built-in nodes (`delay`, `waitForEvent`, `invokeWorkflow`, `waitForAgent`) need no import and no declaration — the parser injects them and the compiler inlines their bodies:
 
 ```typescript
-import { waitForEvent } from '@synergenius/flow-weaver/built-in-nodes';
-
-/**
- * @flowWeaver nodeType
- * @input eventName - Event to wait for
- * @output eventData - Received event payload
- */
-// (function body provided by the library)
-
 /**
  * @flowWeaver workflow
- * @node wait waitForEvent
- * @connect Start.eventName -> wait.eventName
- * @connect wait.eventData -> Exit.data
+ * @node wait delay [expr: duration="'30s'"]
+ * @path Start -> wait -> Exit
  */
-export function myWorkflow(execute: boolean, params: { eventName: string }) { ... }
+export async function myWorkflow(execute: boolean): Promise<{ onSuccess: boolean; onFailure: boolean }> {
+  throw new Error('generated body was not installed');
+}
 ```
 
+- `waitForEvent` and `waitForAgent` are durable gates: using either makes the workflow pause and yield, and every other node must then be classified `@durablePure`, `@durableGate`, or `@durableEffect`. See [Durable Gates](durable-gates.md)
+- The full signatures are in [Built-in Nodes](built-in-nodes.md)
+
 ## Port Types
 
 STRING, NUMBER, BOOLEAN, OBJECT, ARRAY, FUNCTION, ANY, STEP
@@ -299,6 +320,8 @@ Types are inferred from TypeScript signature. STEP is for control flow (execute,
 
 For loops/iteration, use **per-port scopes** with explicit `scope:scopeName` suffixes.
 
+A scope owner is one of the cases that needs normal mode: the node receives `execute`, calls the generated callback for each item itself, and reports `onSuccess`/`onFailure` when the loop is done. The nodes inside the scope are ordinary expression nodes.
+
 ### ForEach Node Pattern
 
 ```typescript
@@ -317,6 +340,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 };
@@ -329,10 +353,16 @@ Key points:
 - Callback parameter is auto-generated, receives scoped ports as args
 - Node iterates by calling callback for each item
 - `start`, `success`, `failure` are mandatory scoped STEP ports
+- Scoped STEP wiring is written with `@connect` and the `:scopeName` suffix; `@path` does not express it
 
 ### Workflow Usage
 
 ```typescript
+/** @flowWeaver nodeType @expression */
+function processor(item: any): { result: any } {
+  return { result: item };
+}
+
 /**
  * @flowWeaver workflow
  * @node loop forEach
@@ -352,21 +382,6 @@ Key points:
 
 See `fw docs export-interface` for full scope documentation.
 
-## Node Positioning
-
-Instance nodes use a bracket attribute on the `@node` line: `@node id Type [position: x y]`
-
-The standalone `@position nodeId x y` syntax is reserved for Start and Exit virtual nodes, which have no `@node` line.
-
-Values are in pixels on a 90px grid.
-
-Default layout:
-
-- Start: -450px (col -5)
-- Exit: 450px (col 5)
-
-Spacing: 180px horizontal (standard), 150px vertical for branches
-
 ## Workflow Recipes
 
 ### Recipe 1: Build a Workflow from Scratch
@@ -384,7 +399,7 @@ Spacing: 180px horizontal (standard), 150px vertical for branches
 
 ```
 1. fw describe my-workflow.ts --format text   # understand current structure
-2. Edit the file: add @flowWeaver nodeType function + @node + @connect annotations
+2. Edit the file: add an @expression nodeType function, a @node line, and put it on the @path (add @connect only for ports whose names differ)
 3. fw validate my-workflow.ts                 # verify
 ```
 
@@ -433,9 +448,11 @@ See `advanced-annotations` for full documentation.
 
 - `cli-reference` - Complete CLI command reference
 - `advanced-annotations` - Pull execution, merge strategies, auto-connect, and more
-- `compilation` - Compilation targets (TypeScript, Inngest) and options
+- `compilation` - Compilation targets (TypeScript and pack targets) and options
 - `deployment` - Export to cloud, serve mode, OpenAPI
-- `built-in-nodes` - delay, waitForEvent, invokeWorkflow, and mock system
+- `built-in-nodes` - delay, waitForEvent, invokeWorkflow, waitForAgent, and mock system
+- `durable-gates` - Pausing at a gate, resuming, and driving a run from an AI assistant
+- `mcp-tools` - Every MCP tool, which to prefer, and result sizes
 - `marketplace` - Package ecosystem and plugins
 - `export-interface` - Interface ports and scoped iteration
 - `iterative-development` - Step-by-step building