# module: flow-engine

职责:      flow 范式:步序声明的装载与静态检查、四种步型的执行、条件跳步、
           重试与声明给定的兜底、异步步的监听登记与事件续跑、步序位置的持久
不负责:    任务生命周期与终态裁定(见 task)、放行与落地(见 release)、
           复杂路由(**不得在 flow 内表达** —— 上升为流程层网关或改用 loop)

公开出口:  index.ts
  - 类型:`FlowEngineService` `FlowPosition` `StepRuntime` `AdvanceOutcome` `FailureAction` `NextAction`
  - 错误:`FlowDeclarationInvalidError`
  - 端口类型:`FlowStateStore` `PredicateEvaluator` `TaskDataGateway` `ToolStepInvoker`
          `LlmStepGateway` `CardGateway` `ListenerRegistrar` `MemoryRecorder` `TaskContext`
  - 用例工厂:`createFlowRunner(deps): FlowEngineService`
  - 纯函数:`nextAction` `markStep` `failureAction` `checkDeclaration` `initialPosition`
          `lastStepIsAcceptance` `parallelGroupComplete`
  - adapter:`createFlowStateStore`;Drizzle 表:`flowStateTable`

层级:      L5(编码规范 §4)
依赖:      @contracts;@shared/db;skill-engine(L4,步引用结晶片段);
           port 注入:ledger / toolbox / llm / human-tool / event / memory
被依赖:    task

不变量(AM 05 / 12.3):
  - **零临场调度**:下一步由 `nextAction` 从声明算出,LLM 只以「被调用的工具」出现
  - **条件必谓词**:跳步条件经 `PredicateEvaluator`(@sfeel)确定性求值,零 LLM
  - **失败路径声明给定**:`failureAction` 只从声明读重试次数与兜底,不临场发明
  - **异步步 = 监听**:人类工具步登记人事件监听,**时限必配**,无死等
  - **出参落草稿层**:步的产出是草稿态,放行前不落事实
  - **写类工具登记为动作意向**:flow 里同样不即时触达世界(除契约显式预授权)
  - **谱全程可静态检查**:`checkDeclaration` 不过即 `FlowDeclarationInvalidError`,不得上架
  - 步序位置持久于 `flowStateTable` —— 断点续跑的三份持久状态之一