运行与状态

Run 是 LightFlow 对一次 workflow 请求的本地记录。它不替代 CortexFS audit，而是保存 workflow 结构和 step 与 CortexFS 文件的对应关系。

XDG state layout

真实 run state 放在：

$XDG_STATE_HOME/lightflow/runs/<run_id>/

目录中包含：

manifest.json
request.json
resolved_workflow.json
events.jsonl
trace.jsonl
outputs/

Manifest

manifest.json 是 LightFlow-owned summary。它保存：

• run_id
• workflow_asset_id
• 每个 step 的 step_id
• node 或 composition id
• CortexFS inbox/outbox path
• step status
• submitted request path
• response path 或 error path
• provider、model、route decision
• fingerprint
• output artifact path

Status model

Step 当前有四种状态：

planned
submitted
succeeded
failed

Run status 是从所有 step 推导出来的：

• 任一 step failed，则 run failed。
• 所有 step succeeded，则 run succeeded。
• 至少一个 step submitted 或 succeeded，则 run running。
• 否则 run planned。

Preview 与 create 的差别

Preview：

• 解析 workflow。
• 验证引用。
• 规划 CortexFS path。
• 尝试渲染 request template。
• 不写任何 XDG state。

Create：

• 做同样的解析和验证。
• 写入 run 目录。
• 保存原始 request。
• 保存 resolved workflow。
• 写入 manifest 和 event stream。

Submit 与 refresh

Submit step：

cargo run -- run submit run-001 draft

如果 workflow step 有 request template，可以不传 body。否则需要显式传 JSON：

cargo run -- run submit run-001 draft '{"messages":[{"role":"user","content":"Draft a plan"}]}'

Refresh run：

cargo run -- run refresh run-001

Refresh 会读取 CortexFS outbox，更新 manifest，并在首次观察到结果时追加 event 和 trace。

Event 与 trace

events.jsonl 是面向用户的事件流，例如：

run.created
step.submitted
step.succeeded
step.failed

trace.jsonl 是技术流，用来记录 CortexFS request commit、response observed、error observed 等细节。

这两个文件保持普通 JSONL 格式，方便 tail、jq 和 shell pipeline 使用。