@oomol-lab/open-flow 0.1.0-beta.65 → 0.1.0-beta.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.65",
+  "version": "0.1.0-beta.66",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,6 +29,10 @@
       "types": "./dist/common/openapi.d.ts",
       "import": "./dist/common/openapi.js"
     },
+    "./workflow": {
+      "types": "./dist/common/workflow.d.ts",
+      "import": "./dist/common/workflow.js"
+    },
     "./connector-action": {
       "types": "./dist/common/connector-action.d.ts",
       "import": "./dist/common/connector-action.js"

package/skills/open-flow/references/flow-authoring.md

@@ -106,7 +106,7 @@ Absence, explicit null, an unset binding and an inherited default are distinct.
 
 ### Connect execution and data
 
-This complete edit adds a Manual Trigger, a calculation, and a formatter. It
+This complete edit adds a Start node, a calculation, and a formatter. It
 needs no Connector or model. `total` is a business output; `amount` is a named
 input whose binding reads it. Both execution edges and data bindings are visible.
 
@@ -115,7 +115,7 @@ input whose binding reads it. Both execution edges and data bindings are visible
   "baseRevision": "REVISION",
   "requestId": "example-code-and-data",
   "edits": [
-    { "op": "node.add", "as": "start", "type": "manual", "name": "Start" },
+    { "op": "node.add", "as": "start", "type": "start", "name": "Start" },
     {
       "op": "node.add",
       "as": "calculate",
@@ -151,6 +151,13 @@ Common sources are `{"kind":"value","value":...}`,
 `{"kind":"variable","name":"VARIABLE"}`. An output source may omit `port`
 when there is one output, or select a nested `field`. Each node schema advertises
 supported sources. A Trigger cannot read downstream results before the Run starts.
+
+For workflow business outputs, add one `outputs` node with `config.outputDefs` as a named schema/nullable/description map. Set sources with `node.add.inputs` or `input.set` and connect execution predecessors. Outputs owns its definitions and mappings; deleting it removes both. Node details expose definitions and inputs. Run results expose business `outputs` separately from node logs. A `workflow` node with `config: { "flowId": "TARGET_FLOW_ID" }` calls the target's current enabled Live with Start. Published interface snapshots supply its ports. A changed Revision with the same interface remains callable; changed interfaces require `node.refresh`. Snapshot comparison ignores descriptions and port ordering, but preserves schema, nullability and node-presence differences.
+
+Workflow target selection may retain an owned unpublished or disabled Flow. Without a loaded interface,
+the call stores an empty source revision; checks report the target problem or missing interface.
+After the target becomes available, `node.refresh` loads its current Live contract. Selection and
+workflow-call checks do not validate Start presence. Start remains required at actual Live invocation.
 Schema `{}` accepts dynamic JSON; it does not convert objects or arrays into text.
 
 ### Change one prompt rule
@@ -282,15 +289,16 @@ unavailable action and an action lacking an active Connection are different
 problems. Actions marked `authenticated: false` need no account. Connection
 selection rules come from the selected node contract.
 
-| Capability                      | Relevant schema and configuration                                                                                       |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| Provider read or write          | `connector`: discovered `action`, optional `connectionId`, named input bindings.                                        |
-| Provider event                  | `poll` or `integration`: discovered `key`, Connection and any static inputs; polling also has a schedule.               |
-| Manual, HTTP or scheduled entry | `manual`, `webhook`, `cron`: business payload fields or schedule. A Manual Trigger has no output parameters.            |
-| Workflow failure handler        | `error`: published upstream Flows' automatic Run failures; not a node-level catch or a handler for manual Run failures. |
-| Fixed HTTP operation            | `openapi`: an OpenAPI source, path and method; resolved authentication choices and ports appear in node details.        |
-| Reusable constants              | `value`: named JSON values and optional output constraints.                                                             |
-| Durable interaction             | `wait`, `approval`: prompt and named inputs; resume through the Run's Wait ID.                                          |
+| Capability                      | Relevant schema and configuration                                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Provider read or write          | `connector`: discovered `action`, optional `connectionId`, named input bindings.                                                   |
+| Provider event                  | `poll` or `integration`: discovered `key`, Connection and any static inputs; polling also has a schedule.                          |
+| Manual, HTTP or scheduled entry | `start`, `webhook`, `cron`: workflow `inputDefs`, HTTP body fields, or schedule.                                                   |
+| Workflow failure handler        | `error`: published upstream Flows' automatic Run failures; not a node-level catch or a handler for manual Run failures.            |
+| Call another workflow           | `workflow`: select an owned published Flow ID; inputs and outputs derive from its saved contract. Use `node.refresh` to update it. |
+| Fixed HTTP operation            | `openapi`: an OpenAPI source, path and method; resolved authentication choices and ports appear in node details.                   |
+| Reusable constants              | `value`: named JSON values and optional output constraints.                                                                        |
+| Durable interaction             | `wait`, `approval`: prompt and named inputs; resume through the Run's Wait ID.                                                     |
 
 Connector and LLM services are configured on the Server. Missing capabilities
 should be described in terms of the required operation or event, without silently
@@ -311,14 +319,16 @@ and `validation`. A Draft may save with diagnostics. `valid`, `invalid` and
 Use the edit's validation or request a check of a specific Revision. Structural
 validity does not demonstrate business behavior, model quality or runtime account
 access. An authorized test Run can exercise meaningful input cases. Draft Run
-readiness concerns the selected Trigger's path and dependencies; publishing and
-Live Runs require the complete Flow to be ready.
+readiness concerns the selected Trigger's path and dependencies. Publishing and
+Live Runs require the complete Flow to be ready. Explicit Live Runs must select a Start node. Other Triggers can be simulated only in Draft Runs; their Live Runs originate from their event sources.
 
-A sole Manual Trigger is selected automatically; otherwise specify `--trigger`.
-`--outputs` supplies named Trigger outputs. `--input` supplies per-node input
+The Start node is selected automatically even when other Triggers exist; use `--trigger` to choose another entry for a Draft test. A sole legacy Manual Trigger remains supported for Draft tests.
+`--outputs` supplies named Start parameters or other Trigger outputs. Required Start parameters must be present, omitted nullable parameters become null, and unknown parameters are rejected. Start parameters have no defaults. `--input` supplies per-node input
 overrides; command help gives their shape. Live Runs use `--source live` and
 `--expected-publication` instead of `--expected-revision`.
 
+Declare parameters on Start: `{"op":"node.add","as":"start","type":"start","name":"Start","config":{"inputDefs":{"message":{"schema":{"type":"string"},"nullable":false},"note":{"schema":{"type":"string"},"nullable":true}}}}`. Read definitions in Start node details at `config.inputDefs`; `flow_live.inputDefs` remains a derived view of the published Start. Update with `node.update set.config.inputDefs`, and clear node-relative paths such as `["config","inputDefs","message","description"]`. Downstream nodes bind `{ "kind": "output", "node": "$start", "port": "message" }` with separate execution edges. Call with `--outputs '{"message":"Hello"}'`; note becomes null. REST and MCP use `trigger.outputs`. Deleting Start removes its configuration; undo restores it, while a new Start has empty definitions.
+
 ### Inspect or continue an existing Run
 
 ```bash
@@ -384,7 +394,7 @@ commands when relevant.
 belongs to the host. An open Workbench receives Revision notifications, so a CLI
 edit does not require a page reload.
 
-`live` includes Manual entry nodes without a runtime binding. `trigger search`
+`live` includes Start and legacy Manual entry nodes without a runtime binding. `trigger search`
 and `trigger show` discover provider definitions; `live` inspects the Flow's
 current online entries. The MCP equivalent is `flow_live({ flowId })`.