Start `flow.start`

The start node defines how a top-level graph is identified and entered. Keep exactly one in every executable workflow and do not connect an incoming control edge to it. The next port passes control to the first business node. The input port exposes start data after it has been checked against the declared input shape. Container scopes use their own internal entry markers instead of another start node.

Identity and runtime entry

workflow_name is long-lived business identity, while workflow_version distinguishes incompatible definitions. runtime_kind, entrypoint, and export_name tell the host where to load the workflow function. Before publication, verify that the entry exists in the built artifact, that the export name matches, and that a worker capable of serving that version is available. Existing runs may still require the previous entry and build route after a new version is deployed.

input_schema should declare only fields the workflow reads. A permissive object is useful while prototyping, but a production release should identify required properties, types, and nested structures before bad data can reach a durable task. run_id_expression can derive identity from stable input such as an order or job number. When it resolves to no value, the host allocates an ID. When it resolves to a stable value, repeated start requests can address the same run.

Wiring and release checks

Start normally connects to a condition, task, or container. Connect control from next to the target in port and data from input only to a compatible JSON input. Title and canvas position can change freely, but node ID, workflow name, and version should remain stable after runs exist. Test valid and invalid input, duplicate starts, a missing runtime entry, old-worker routing, and an unconnected first edge before releasing the graph.

Every executable graph enters through this node. It pins workflow identity, input shape, and runtime entry, then exposes the start input to downstream nodes.

Runtime behavior

The start node is validated at publication time and emits no runtime command. A run ID expression lets the host retry a start request with the same business identity.

Node contract

Type: flow.start
Role: Entry
Runtime binding: Host compilation
Durable identity: Defined by graph structure

Configuration properties

Property	Type and control	Default	Rules
`workflow_name`Workflow ID	`str`StrInput	`workflow.main`	Permanent identifier for this workflow. Do not change it after runs exist.Required
`workflow_version`Version	`str`StrInput	`0.1.0`	Use a new version when workflow logic changes incompatibly.Required
`input_schema`Accepted input	`dict`A3SFlowSchemaInput	`{"type":"object","additionalProperties":true}`	Fields accepted when this workflow starts.Required
`runtime_kind`Execution runtime	`tab`TabInput	`native_ts`	Runtime that executes the workflow logic.Required · Advanced · Allowed values native_ts, rust_embedded
`entrypoint`Runtime entry	`str`StrInput	`workflows/main.ts`	TypeScript source path or embedded runtime key.Required · Advanced
`export_name`Workflow function	`str`StrInput	`main`	Function exported by the selected runtime entry.Required · Advanced
`run_id_expression`Run ID (optional)	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":null}}`	Build an ID from stable input to prevent duplicate starts, or let the host create one.Optional · Advanced

Ports

Direction	Port ID	Kind	Value types
Output	`next`Next	control	`FlowControl`
Output	`input`Workflow input	data	`JsonValue`

Node JSON example

The CLI creates the same structure from manifest defaults. Canvas position, title, and selection are presentation data.

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-start",
  "data": {
    "workflow_name": "workflow.main",
    "workflow_version": "0.1.0",
    "input_schema": {
      "type": "object",
      "additionalProperties": true
    },
    "runtime_kind": "native_ts",
    "entrypoint": "workflows/main.ts",
    "export_name": "main",
    "run_id_expression": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": null
      }
    },
    "type": "flow.start"
  }
}

CLI usage

Inspect the installed manifest first, then create the node and validate the complete workflow. Every command emits JSON.

Terminal

a3s-flow node flow.start --pretty
a3s-flow new flow.start --id example-flow-start --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill usage

The package includes the a3s-flow Skill. It queries the CLI catalog before creating, validating, compiling, and digesting a workflow.

Prompt

Use $a3s-flow to add the "flow.start" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

Keep one start node in a top-level graph.
Do not change workflow identity for existing runs.
Declare only input fields that workflow code actually reads.

#Start flow.start

#Identity and runtime entry

#Wiring and release checks