Execution Lifecycle

LightFlow currently implements a manual lifecycle instead of a full scheduler. This gives CLI, scripts, agents, and future HTTP handlers a stable path.

1. Discover

assets workflows|nodes|compositions|models scans project assets and built-in assets:

cargo run -- assets workflows

Discovery returns an AssetRecord:

• metadata
• source path
• built-in flag

This is the first boundary between authoring and execution. Clients should receive normalized records instead of reading Rust source files themselves.

2. Preview

cargo run -- run preview workflow.text_plan --inputs '{"prompt":"Plan a migration"}'

Preview parses the workflow, validates references, plans CortexFS paths, and renders request templates without writing state.

Preview returns:

• planned run id
• workflow asset record
• workflow definition
• validation issues
• planned CortexFS paths
• rendered request body when a template is available

This is the right self-check for an agent after editing workflow assets. It catches missing models, missing nodes, missing compositions, and request-template problems before a run directory is created.

3. Create

cargo run -- run create workflow.text_plan --id run-001 --inputs '{"prompt":"Plan a migration"}'

Create writes the original request, resolved workflow, event stream, and manifest under XDG state.

The write order is intentionally conservative:

1. Reject an existing run directory.
2. Write request.json.
3. Write resolved_workflow.json.
4. Append a run.created event.
5. Atomically write manifest.json.

If the run directory already exists, LightFlow refuses to overwrite it even when the manifest is missing. That prevents a crash recovery path from silently replacing partial state.

4. Submit

cargo run -- run submit run-001 draft

Submit requires the step to be planned. It writes *.tmp, syncs it, renames it to *.req.json, and records the submission.

Submit checks:

• the run exists
• the step exists
• the step status is planned
• a request body was provided, or the step has a request template

After commit:

• the step status becomes submitted
• step.submitted is appended
• cortex.request.committed is appended
• the manifest points to the committed CortexFS request path

5. Refresh

cargo run -- run refresh run-001

Refresh observes CortexFS response or error files and updates step status, fingerprint, route metadata, events, and trace.

When a response is observed:

• the step status becomes succeeded
• the response path is recorded
• the response fingerprint is recorded
• route metadata is parsed when present
• step.succeeded is appended
• cortex.response.observed is appended

When an error is observed:

• the step status becomes failed
• the error path is recorded
• the error fingerprint is recorded
• step.failed is appended
• cortex.error.observed is appended

6. Inspect

The visible inspection surface is:

cargo run -- run status run-001
cargo run -- run events run-001
cargo run -- run trace run-001

events.jsonl is meant for humans and UIs. trace.jsonl is meant for debugging, audit correlation, and lower-level execution evidence.

Scheduler Direction

A future scheduler should automate preview, create, submit, and refresh. It should not bypass the run store or CortexFS file semantics, because those are the system boundaries the CLI, API, and future UI all need to share.