Record progress `flow.progress`

A progress node writes an inspectable milestone, count, and short message to event history. It is useful for batch counts, import stages, and long operations whose confirmed progress should appear before completion. Progress is observational data. It does not replace business state needed for branching and it does not invoke a host task.

Progress fields

progress_id is stable identity for one update and normally follows the graph node ID. completed is the confirmed amount. total is optional and, when present, cannot be below completed. message describes the milestone briefly, while details holds small structured data or an object reference. Every expression should read committed values so replay cannot produce different content for the same update.

After commit, control continues through recorded. Do not write conflicting content under one progress ID. For several milestones, use separate stable nodes or include explicit iteration identity in a controlled loop design. High-frequency telemetry belongs in a metrics system. Recording every byte, model token, or polling tick as a workflow event creates unnecessary history and operational load.

Presentation and validation

An interface should state that progress comes from the latest committed event and distinguish running, waiting, failed, and terminal states. Test an unknown total, zero, completed greater than total, duplicate submission, process recovery, and oversized details. Before release, define retention, permissions, and localized units so operators can connect every displayed number to the real business measurement.

Use it to write inspectable milestones, counts, and short operator messages. Progress does not call a host task and is not a substitute for business state.

Runtime behavior

The node ID identifies the command and progress_id identifies the update. After commit, the run replays immediately and continues through recorded.

Node contract

Type: flow.progress
Role: Durable runtime command
Runtime binding: record_progress
Durable identity: Graph node ID

Configuration properties

Property	Type and control	Default	Rules
`progress_id`Progress ID	`str`StrInput	`progress`	Replay-stable progress identity. The graph node ID is the recommended value.Required
`completed`Completed	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":0}}`	Completed units as a fixed value or workflow field.Required
`total`Total	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":null}}`	Optional total units.Optional · Advanced
`message`Message	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":""}}`	Optional progress message.Optional · Advanced
`details`Details	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":null}}`	Optional JSON details exposed by inspection APIs.Optional · Advanced

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Output	`recorded`Recorded	control	`FlowControl`

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-progress",
  "data": {
    "progress_id": "progress",
    "completed": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": 0
      }
    },
    "total": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": null
      }
    },
    "message": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": ""
      }
    },
    "details": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": null
      }
    },
    "type": "flow.progress"
  }
}

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.progress --pretty
a3s-flow new flow.progress --id example-flow-progress --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.progress" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

Do not reuse one progress_id for changed content.
When present, total must not be lower than completed.
Keep details to small structured data or object references.

#Record progress flow.progress

#Progress fields

#Presentation and validation