@synergenius/flow-weaver 0.33.2 → 0.44.0

package/docs/reference/jsdoc-grammar.md

@@ -1,7 +1,7 @@
 ---
 name: Flow Weaver JSDoc Grammar
 description: Formal syntax grammar for @flowWeaver JSDoc annotations parsed by Chevrotain
-keywords: [grammar, syntax, JSDoc, annotations, input, output, connect, node, Chevrotain, EBNF, scope, position]
+keywords: [grammar, syntax, JSDoc, annotations, input, output, connect, node, Chevrotain, EBNF, scope, durablePure, durableGate, durableEffect]
 ---
 
 # JSDoc Block Structure
@@ -18,7 +18,7 @@ tagLine        ::= "*" "@" TAG_NAME [ tagContent ]
 # Block Types
 
 ```
-flowWeaverTag  ::= "@flowWeaver" ( "nodeType" | "workflow" | "pattern" )
+flowWeaverTag  ::= "@flowWeaver" ( "nodeType" | "workflow" )
 ```
 
 ---
@@ -36,6 +36,8 @@ nodeTypeBlock  ::= "@flowWeaver nodeType"
                    [ "@scope" IDENTIFIER ]
                    [ "@executeWhen" IDENTIFIER ]
                    [ "@pullExecution" IDENTIFIER ]
+                   [ "@resilience" ( "retries=" INTEGER | "fallback=" STRING ) { ( "retries=" INTEGER | "fallback=" STRING ) } ]
+                   [ "@durablePure" | "@durableGate" ( "approval" | "input" | "agent" | "timer" ) | "@durableEffect" ]
                    [ "@color" TEXT ]
                    [ "@icon" TEXT ]
                    { "@tag" IDENTIFIER [ STRING ] }
@@ -44,6 +46,10 @@ nodeTypeBlock  ::= "@flowWeaver nodeType"
                    { stepTag }
 ```
 
+The durable classification is optional for an ordinary node type and required for every node reachable from a workflow that contains a `@durableGate`. See [Durable Gates](durable-gates.md).
+
+`@flowWeaver node` is accepted as shorthand for `@flowWeaver nodeType` with `@expression`: the function takes no `execute` parameter and returns its data directly, and the parser infers the ports from the signature. Prefer the explicit form in files you write.
+
 ---
 
 # Port Tags (Input / Output / Step)
@@ -72,9 +78,13 @@ defaultValue   ::= IDENTIFIER | INTEGER | STRING
 @input [name="hello"]             optional with default (string)
 @input name scope:myScope         scoped input
 @input name [order:2]             with ordering metadata
-@input name - Description text    with description
+@input name - Short Label         dash text is the port LABEL (1-2 words), shown in the diagram badge
 ```
 
+The text after the dash is the port's display **label**, not a description.
+It is drawn inside the port badge, so keep it to one or two words. There is no
+separate port description; a long sentence just overflows the badge.
+
 ## @output
 
 ```
@@ -114,16 +124,19 @@ scopeClause    ::= "scope:" IDENTIFIER
 metadataBracket ::= "[" metadataAttr { "," metadataAttr } "]"
 
 metadataAttr   ::= orderAttr | placementAttr | typeAttr | mergeStrategyAttr
+                 | hiddenAttr | customAttr
 
 orderAttr      ::= "order:" INTEGER
 placementAttr  ::= "placement:" ( "TOP" | "BOTTOM" )
 typeAttr       ::= "type:" IDENTIFIER
 mergeStrategyAttr ::= "mergeStrategy:" IDENTIFIER
+hiddenAttr     ::= "hidden"
+customAttr     ::= IDENTIFIER ":" ( STRING | INTEGER | IDENTIFIER | "true" | "false" )
 
 descriptionClause ::= "-" TEXT
 ```
 
-Metadata brackets can be repeated: `@input name [order:1] [placement:TOP]`
+Metadata brackets can be repeated: `@input name [order:1] [placement:TOP]`. `hidden` keeps the port out of diagrams (`@output onFailure [hidden]`). Any other `key:value` pair is custom metadata, kept on the port for packs and tag handlers to read.
 
 ---
 
@@ -144,7 +157,6 @@ workflowBlock  ::= "@flowWeaver workflow"
                    { connectTag }
                    { pathTag }
                    { mapTag }
-                   { positionTag }
                    { scopeTag }
 ```
 
@@ -185,7 +197,7 @@ fwImportTag    ::= "@fwImport" IDENTIFIER IDENTIFIER "from" QUOTED_STRING
 QUOTED_STRING  ::= STRING | "'" { any character except "'" } "'"
 ```
 
-Import npm package functions or local module exports as node types. The imported function becomes an expression node that can be instantiated with `@node`. Both double and single quotes are accepted for the module specifier.
+Import npm package functions or local module exports as node types. The imported function becomes a node that can be instantiated with `@node`. Both double and single quotes are accepted for the module specifier.
 
 **Examples:**
 
@@ -193,13 +205,16 @@ Import npm package functions or local module exports as node types. The imported
 @fwImport npm/lodash/map map from "lodash"
 @fwImport npm/date-fns/format format from "date-fns"
 @fwImport local/utils/helper helper from './utils'
+@fwImport waitForApproval waitForApproval from "flow-weaver-pack-example"
 ```
 
-- First identifier: node type name (used in `@node` tags, convention: `npm/pkg/fn` or `local/path/fn`)
+- First identifier: node type name (used in `@node` tags, convention: `npm/pkg/fn` or `local/path/fn`, or just the function name for a marketplace pack node)
 - Second identifier: exported function name to import
 - String: package name or relative path
-
-Port types are inferred from TypeScript `.d.ts` files when available. Falls back to a stub with `ANY` result port if inference fails.
+- Port types are inferred from the imported function's TypeScript `.d.ts`
+- Inference follows re-export barrels: packages whose entry `.d.ts` is a barrel (`export * from './sub'` / `export { fn } from './sub'`) resolve correctly. This is the common shape for marketplace packs, whose entry point re-exports their node types
+- A function annotated with `@flowWeaver nodeType` in the `.d.ts` keeps its full port set (inputs, outputs, `onSuccess`/`onFailure`); a plain function maps to an expression node. With no `.d.ts`, the import falls back to a stub with a single `ANY` `result` port
+- The compiler emits a real `import { fn } from "<pkg>"` in the generated output, so the function is callable at run time. The package must be resolvable from where the compiled workflow runs (installed in `node_modules`, or otherwise on the module resolution path)
 
 ## @node
 
@@ -213,7 +228,7 @@ attributeBracket ::= "[" nodeAttr { "," nodeAttr } "]"
 nodeAttr       ::= labelAttr | exprAttr | portOrderAttr | portLabelAttr
                  | minimizedAttr | pullExecutionAttr | sizeAttr
                  | colorAttr | iconAttr | tagsAttr | suppressAttr
-                 | positionAttr | jobAttr | environmentAttr
+                 | jobAttr | environmentAttr
 
 labelAttr      ::= "label:" STRING
 exprAttr       ::= "expr:" IDENTIFIER "=" STRING { "," IDENTIFIER "=" STRING }
@@ -226,7 +241,6 @@ colorAttr      ::= "color:" STRING
 iconAttr       ::= "icon:" STRING
 tagsAttr       ::= "tags:" tagEntry { "," tagEntry }
 tagEntry       ::= STRING [ STRING ]
-positionAttr   ::= "position:" INTEGER INTEGER
 jobAttr        ::= "job:" STRING
 environmentAttr ::= "environment:" STRING
 suppressAttr   ::= "suppress:" STRING { "," STRING }
@@ -241,29 +255,31 @@ Multiple attribute brackets are allowed (zero or more). Attributes can be split
 @node myAdd Add [label: "My Adder"]
 @node myAdd Add parent.loopScope
 @node myAdd Add [expr: a="x + 1", b="y * 2"]
+@node myAdd Add [expr: a="Start.value + 1", b="scale.factor * 2"]   (upstream references, see advanced-annotations)
 @node myAdd Add [portOrder: a=1, b=2]
 @node myAdd Add [minimized, label: "Compact"]
 @node myAdd Add [pullExecution: trigger]
 @node myAdd Add [size: 200 150]
 @node myAdd Add [color: "red", icon: "database"]
 @node myAdd Add [tags: "math" "Math operation", "transform"]
-@node myAdd Add [position: 180 0]
-@node myAdd Add [label: "hi"] [color: "#f00"] [position: 360 0]
-@node build npmBuild [job: "build"]
-@node deploy deploySsh [job: "deploy"] [environment: "production"]
+@node myAdd Add [label: "hi"] [color: "#f00"]
+@node build npmBuild [runner: "ubuntu-latest"]
+@node deploy deploySsh [region: "eu-west-1", environment: "production"]
 @node fetch fetchData [suppress: "UNUSED_OUTPUT_PORT"]
 ```
 
 ## @connect
 
 ```
-connectTag     ::= "@connect" portRef "->" portRef
+connectTag     ::= "@connect" portRef "->" portRef [ "as" coerceType ]
 
 portRef        ::= IDENTIFIER "." IDENTIFIER [ ":" IDENTIFIER ]
                  | IDENTIFIER ":" IDENTIFIER
+
+coerceType     ::= "string" | "number" | "boolean" | "json" | "object"
 ```
 
-The first form is the standard `node.port` reference with optional `:scope` suffix. The second form is a pseudo-node reference for CI/CD secrets: `secret:NAME` resolves to `{ nodeId: "secret:NAME", portName: "value" }`.
+The first form is the standard `node.port` reference with optional `:scope` suffix. The second form is a pseudo-node reference: `secret:NAME` resolves to `{ nodeId: "secret:NAME", portName: "value" }`. The optional `as` clause converts the value on that connection: `string`, `number` and `boolean` apply the JavaScript constructor, `json` serialises with `JSON.stringify`, `object` parses with `JSON.parse`. Without it the compiler coerces only anything→STRING and BOOLEAN→NUMBER on its own. `COERCE_TYPE_MISMATCH` reports an `as` type the target port cannot take.
 
 **Examples:**
 
@@ -300,26 +316,13 @@ Comma-separated (equivalent to two `@path` tags):
 
 - `:ok` follows `onSuccess` (default when no suffix)
 - `:fail` follows `onFailure`
-- Data ports auto-resolve by walking backward through the path to the nearest ancestor with a same-name output port (scope walking)
+- Data ports auto-resolve by walking backward through the path to the nearest ancestor with a same-name output port (scope walking). `Exit` is a step like any other: each `@returns` port resolves to the nearest ancestor output of the same name
+- A `Start` param never resolves straight to an `Exit` port. A pass-through would hide a missing producer, so write it as an explicit `@connect Start.x -> Exit.x`
+- A port that already has an explicit `@connect` is left alone; the explicit connection wins
 - Multiple `@path` lines can coexist; overlapping prefixes are deduplicated
 - Comma-separated paths within a single `@path` are expanded to separate paths
 - Manual `@connect` lines can supplement for cross-named ports
 
-## @position
-
-Standalone `@position` is reserved for Start and Exit virtual nodes, which have no `@node` line. For instance nodes, use the `[position: x y]` bracket attribute on `@node` instead.
-
-```
-positionTag    ::= "@position" IDENTIFIER INTEGER INTEGER
-```
-
-**Examples:**
-
-```
-@position Start -450 0
-@position Exit 450 0
-```
-
 ## @scope
 
 ```
@@ -365,13 +368,13 @@ returnsTag     ::= IDENTIFIER [ scopeClause ] { metadataBracket } [ descriptionC
 
 These follow the same clause syntax as port tags. `@return` is accepted as an alias for `@returns`.
 
-## @trigger (workflow-level, Inngest)
+## @trigger (workflow-level)
 
 ```
 triggerTag     ::= "@trigger" ( "event=" STRING | "cron=" STRING )*
 ```
 
-Declares an event or cron trigger for Inngest deployment. Can specify event, cron, or both.
+Declares an event or cron trigger for a deployment target. Can specify event, cron, or both.
 
 **Examples:**
 
@@ -381,13 +384,32 @@ Declares an event or cron trigger for Inngest deployment. Can specify event, cro
 @trigger event="agent/request" cron="0 9 * * *"
 ```
 
-## @cancelOn (workflow-level, Inngest)
+## @http (workflow-level)
+
+```
+httpTag        ::= "@http" METHOD PATH { "mode=" ("sync"|"async") | "auth=" ("bearer"|"none") | "callback" }
+METHOD         ::= "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+PATH           ::= "/" { segment "/" }            (* a segment is a word or ":param" *)
+```
+
+Declares that the workflow is an HTTP endpoint. `fw serve` and the embeddable server ([Deployment](deployment.md#http-serve-mode)) mount exactly these routes. A `:param` segment binds to the workflow parameter of that name; `GET` reads the remaining parameters from the query string, the other methods from the JSON body. The workflow's return ports are the response body: `onSuccess` answers `200`, `onFailure` answers `422`. A workflow that pauses at a gate answers `202` with a run id to follow. `mode=async` answers `202` at once; `auth=none` makes the route public on a server that has a token; `callback` lets the caller pass a `callbackUrl` that receives the final response. Several tags give several routes; a workflow without one is not an endpoint.
+
+**Examples:**
+
+```
+@http POST /reviews
+@http GET /reviews/:path
+@http POST /reviews mode=async callback
+@http POST /hooks/github auth=none
+```
+
+## @cancelOn (workflow-level)
 
 ```
 cancelOnTag    ::= "@cancelOn" "event=" STRING [ "match=" STRING ] [ "timeout=" STRING ]
 ```
 
-Cancels a running Inngest function when a specified event is received.
+Cancels a running workflow when a specified event is received; used by deployment targets that support cancellation.
 
 **Examples:**
 
@@ -397,13 +419,13 @@ Cancels a running Inngest function when a specified event is received.
 @cancelOn event="x" match="data.id" timeout="1h"
 ```
 
-## @retries (workflow-level, Inngest)
+## @retries (workflow-level)
 
 ```
 retriesTag     ::= "@retries" INTEGER
 ```
 
-Sets the retry count for an Inngest function (overrides default of 3).
+Sets the retry count a deployment target should apply.
 
 **Examples:**
 
@@ -412,13 +434,13 @@ Sets the retry count for an Inngest function (overrides default of 3).
 @retries 0
 ```
 
-## @timeout (workflow-level, Inngest)
+## @timeout (workflow-level)
 
 ```
 timeoutTag     ::= "@timeout" STRING
 ```
 
-Sets the maximum execution time for an Inngest function.
+Sets the maximum execution time a deployment target should apply.
 
 **Examples:**
 
@@ -427,13 +449,13 @@ Sets the maximum execution time for an Inngest function.
 @timeout "2h"
 ```
 
-## @throttle (workflow-level, Inngest)
+## @throttle (workflow-level)
 
 ```
 throttleTag    ::= "@throttle" "limit=" INTEGER [ "period=" STRING ]
 ```
 
-Limits concurrent executions of an Inngest function.
+Limits concurrent executions; applied by deployment targets that support throttling.
 
 **Examples:**
 
@@ -444,272 +466,6 @@ Limits concurrent executions of an Inngest function.
 
 ---
 
-# CI/CD Workflow Annotations
-
-These tags configure CI/CD pipeline behavior when exporting to GitHub Actions or GitLab CI. They are placed inside `@flowWeaver workflow` blocks alongside standard workflow tags.
-
-## @trigger (CI/CD mode)
-
-When the trigger value is one of `push`, `pull_request`, `dispatch`, `tag`, or `schedule`, the parser treats it as a CI/CD trigger rather than an Inngest event trigger.
-
-```
-cicdTriggerTag ::= "@trigger" ( "push" | "pull_request" | "dispatch" | "tag" | "schedule" )
-                   { IDENTIFIER "=" STRING }
-```
-
-Recognized attributes: `branches`, `paths`, `paths-ignore`, `types`, `pattern`, `cron`.
-
-**Examples:**
-
-```
-@trigger push branches="main,develop"
-@trigger pull_request branches="main" types="opened,synchronize"
-@trigger tag pattern="v*"
-@trigger dispatch
-@trigger schedule cron="0 9 * * 1"
-```
-
-## @secret
-
-```
-secretTag      ::= "@secret" IDENTIFIER { IDENTIFIER "=" STRING } [ "-" TEXT ]
-```
-
-**Examples:**
-
-```
-@secret NPM_TOKEN - NPM authentication token
-@secret DEPLOY_KEY scope="deploy" platform="github" - SSH deploy key
-```
-
-## @runner
-
-```
-runnerTag      ::= "@runner" TEXT
-```
-
-**Examples:**
-
-```
-@runner ubuntu-latest
-@runner self-hosted
-```
-
-## @cache
-
-```
-cacheTag       ::= "@cache" IDENTIFIER { IDENTIFIER "=" STRING }
-```
-
-**Examples:**
-
-```
-@cache npm key="package-lock.json"
-@cache npm key="package-lock.json" path="~/.npm"
-```
-
-## @artifact
-
-```
-artifactTag    ::= "@artifact" IDENTIFIER { IDENTIFIER "=" ( STRING | INTEGER ) }
-```
-
-**Examples:**
-
-```
-@artifact dist path="dist/" retention=5
-@artifact coverage path="coverage/"
-```
-
-## @environment
-
-```
-environmentTag ::= "@environment" IDENTIFIER { IDENTIFIER "=" ( STRING | INTEGER ) }
-```
-
-**Examples:**
-
-```
-@environment production url="https://app.example.com" reviewers=2
-@environment staging
-```
-
-## @matrix
-
-```
-matrixTag      ::= "@matrix" [ "include" | "exclude" ] { IDENTIFIER "=" STRING }
-```
-
-Without a prefix, each key-value pair declares a dimension with comma-separated values. With `include` or `exclude`, it adds or removes a specific combination.
-
-**Examples:**
-
-```
-@matrix node="18,20,22" os="ubuntu-latest,macos-latest"
-@matrix include node="22" os="windows-latest"
-@matrix exclude node="18" os="macos-latest"
-```
-
-## @service
-
-```
-serviceTag     ::= "@service" IDENTIFIER { IDENTIFIER "=" STRING }
-```
-
-**Examples:**
-
-```
-@service postgres image="postgres:16" env="POSTGRES_PASSWORD=test" ports="5432:5432"
-@service redis image="redis:7" ports="6379:6379"
-```
-
-## @concurrency
-
-```
-concurrencyTag ::= "@concurrency" IDENTIFIER [ "cancel-in-progress=" ( "true" | "false" ) ]
-```
-
-**Examples:**
-
-```
-@concurrency deploy cancel-in-progress=true
-@concurrency ci-main
-```
-
-## @job
-
-Configures per-job settings. The name must match a `[job: "name"]` attribute used on `@node` declarations.
-
-```
-jobTag         ::= "@job" IDENTIFIER { IDENTIFIER "=" ( STRING | IDENTIFIER | INTEGER ) }
-```
-
-Recognized keys: `retry` (number), `allow_failure` (boolean), `timeout` (string), `runner` (string), `tags` (comma-list), `coverage` (string), `reports` (comma-list of type=path), `rules` (string), `when` (rule modifier), `changes` (rule modifier, comma-list), `extends` (string), `before_script` (comma-list), `variables` (comma-list of KEY=VALUE).
-
-The `when` and `changes` keys are rule modifiers: they apply to the most recently declared `rules` entry for that job. If no `rules` entry exists yet, one is created automatically.
-
-**Examples:**
-
-```
-@job build retry=2 timeout="10m"
-@job test-unit coverage='/Coverage: (\d+)%/' reports="junit=test-results.xml"
-@job deploy allow_failure=true rules="$CI_COMMIT_BRANCH == main"
-@job deploy rules="$CI_COMMIT_BRANCH == main" when=manual
-@job deploy rules="$CI_COMMIT_TAG" changes="src/**,lib/**"
-@job lint tags="docker,linux" extends=".base-lint"
-```
-
-## @stage
-
-Declares a pipeline stage for GitLab CI grouping. Multiple `@stage` annotations define stage ordering.
-
-```
-stageTag       ::= "@stage" IDENTIFIER
-```
-
-**Examples:**
-
-```
-@stage test
-@stage build
-@stage deploy
-```
-
-## @variables
-
-Sets workflow-level environment variables. Applied as defaults to all jobs.
-
-```
-variablesTag   ::= "@variables" { IDENTIFIER "=" ( STRING | IDENTIFIER ) }
-```
-
-**Examples:**
-
-```
-@variables NODE_ENV="production" CI="true"
-```
-
-## @before_script
-
-Sets workflow-level setup commands. Applied as defaults to all jobs.
-
-```
-beforeScriptTag ::= "@before_script" ( STRING | TEXT )
-```
-
-**Examples:**
-
-```
-@before_script "npm ci"
-@before_script npm ci
-```
-
-## @tags
-
-Sets workflow-level runner tags. Applied as defaults to all jobs.
-
-```
-tagsTag        ::= "@tags" { IDENTIFIER }
-```
-
-Tags can be space-separated or comma-separated.
-
-**Examples:**
-
-```
-@tags docker linux
-@tags docker,linux,arm64
-```
-
-## @includes
-
-Declares external configuration files to include (GitLab CI). Ignored for GitHub Actions.
-
-```
-includesTag    ::= "@includes" ( "local" | "template" | "remote" | "project" ) "=" STRING
-                   [ "file=" STRING ] [ "ref=" STRING ]
-```
-
-**Examples:**
-
-```
-@includes local="ci/shared-templates.yml"
-@includes template="Auto-DevOps.gitlab-ci.yml"
-@includes remote="https://example.com/ci.yml"
-@includes project="other-group/other-project" file="ci/shared.yml" ref="main"
-```
-
----
-
-# Pattern Tags
-
-A `@flowWeaver pattern` block defines a reusable partial workflow with boundary ports:
-
-```
-patternBlock   ::= "@flowWeaver pattern"
-                   [ "@name" TEXT ]
-                   [ "@description" TEXT ]
-                   { nodeTag }
-                   { positionTag }
-                   { connectTag }
-                   { portTag }
-
-portTag        ::= "@port" ( "IN" | "OUT" ) "." IDENTIFIER [ "-" TEXT ]
-```
-
-Pattern ports define the boundary connections (IN for inputs, OUT for outputs) that are wired when the pattern is applied to a workflow.
-
-**Examples:**
-
-```
-@port IN.data - Input data to process
-@port OUT.result - Processed result
-@port IN.config - Configuration object
-@port OUT.error - Error output
-```
-
----
-
 # Terminals
 
 <!-- AUTO:START terminals -->
@@ -727,7 +483,6 @@ IDENTIFIER supports `/` and `-` to accommodate npm package naming conventions (e
 # Related Topics
 
 - `advanced-annotations` — Conceptual explanations and examples for pull execution, execution strategies, merge strategies, auto-connect, strict types, path/map sugar, and node attributes
-- `cicd` — CI/CD pipeline export with annotation examples and validation rules
-- `compilation` — How annotations affect code generation, Inngest target details for @trigger/@cancelOn/@retries/@timeout/@throttle
+- `compilation` — How annotations affect code generation and pack targets for @trigger/@cancelOn/@retries/@timeout/@throttle
 - `concepts` — Core workflow fundamentals and quick reference
 - `error-codes` — Validation errors and warnings for annotation issues