Task 生命周期

• 以 task 为中心：状态共享、读缓存、超时都锚定到 task。
• 单 Worker 执行：一个 task 只在一个 Worker 上跑，Worker 不感知 Coordinator，只暴露 RequestTaskSlot / SubmitTask。
• task 内 call 全并行：call 之间没有顺序依赖，由 dispatcher 按窗口逐步放量。
• 同一 task 函数版本固定：激活时 pin 住一个 taskCodeEpoch（TaskContext.TaskCodeEpoch），期间的代码更新只影响后续 task。
• 函数只读：用户函数不直接写库，所有写入走 Writer Plugin。
• 不做 task 级自动重试：Worker 只对单个 call 做有界 attempt 重试（CallRetryPolicy），是否重投 task 由 Client 看 TaskResult.executeResult.retryable 决定。
• 不支持取消：只有 task 超时（taskTimeoutMs）和可选的 Watch 断连回收。

​

Task 模型

{
  "task_id": "3f2b1c9e-8a4d-4c1e-9b0a-6f7e5d4c3b2a",
  "functionCallConfig": {
    "type": "CallListCallConfig",
    "config": {
      "function": "hello_world",
      "callList": [["ct2"], ["blockx"]]
    }
  },
  "resultHandler": {
    "type": "ReturnValueResultHandler",
    "config": {}
  },
  "taskTimeoutMs": 30000
}

// TaskCtx carries the immutable context injected when a task is activated.
type TaskCtx struct {
	TaskInput

	Stage Stage `json:"stage"`
	DebugMode bool `json:"debugMode,omitempty"`
	Deadline time.Time          `json:"deadline"`
	Ctx      context.Context    `json:"-"`
	Cancel   context.CancelFunc `json:"-"`
}

​

端到端时序

​

slot 与准入

• RequestTaskSlot(task_id, ttl_ms) 只占位，不执行。ttl_ms 必须为正（<= 0 返回 InvalidArgument），只控制 ALLOCATED 的自动回收，与 task 超时无关。TickTimers 每 500ms 扫一次 ExpiredSlots，过期 slot 由 HandleSlotLeaseExpired 回收，同时清掉还停在 Preparing 的 task 记录。
• SubmitTask(task, slot_id?)：带 slot_id 时必须命中一条 ALLOCATED 且绑定同一 taskId 的记录，否则 InvalidSlot；不带时 Worker 用 DefaultTTLMs 内联申请一次，没容量返回 NoSlot。
• 幂等：同一 taskId 处于 ALLOCATED / RUNNING 时，RequestTaskSlot 返回同一个 slot_id；已进入 RUNNING 或结果仍在保留窗口内时，SubmitTask 返回稳定的当前状态，不会再启动一次执行。旧执行结束且结果过期后，同一 taskId 可以重新分配 slot。
• 没有 release 接口：拿到 slot 后放弃提交只能等 TTL 回收。

​

三个阶段

• 每个阶段等准入时如果 task ctx 被取消（例如已超时收敛），以 CANCELLED 失败；进入 Calls 前还会先检查 deadline，已过期直接按 TIMED_OUT 收敛，不再占 executorSem。
• Calls 阶段成功后 core 总是输出 StartWriterPhase；ResultHandler 为空时 runWriterPhase 仍会取 pluginSem，只是不执行插件、pluginResults 为空。
• 流式 Builder（StreamingCallBuilder，仅 BlockBundleCallConfig，StreamBuildConfig.Enabled 默认关闭）把 Builder 阶段缩成 PrepareStream，扫描放到 Calls 阶段由 scanSem（ScanSlots = 8）约束；生产中途失败会导致部分 call 已执行。
• 超时由 TickTimers 扫 TimedOutTasks 后调 HandleTaskTimedOut 强制收敛为 TIMED_OUT（retryable=true），不强求立即中断 Executor 里正在跑的 call；in-flight call 会收到 CancelCall。

​

结果与查询

{
  "success": false,
  "executeResult": {
    "failureCode": "PLUGIN_FAILED",
    "retryable": true,
    "pluginResults": [
      {
        "pluginName": "BlockWriteResultHandler",
        "success": false,
        "failureCode": "PLUGIN_FAILED",
        "failureMsg": "..."
      }
    ]
  }
}

• 终态由 state 字段（SUCCEEDED / FAILED）表达，不需要 Client 从 success 推断；TIMED_OUT、WATCH_DISCONNECTED 等都是 FAILED 下的 failureCode，不是独立终态。
• 代码里出现的 failureCode：ACTIVATION_FAILED、IO_SCOPE_FAILED、SLOT_LOST、BUILDER_NOT_FOUND、BUILDER_FAILED、CALL_FAILED、OUTPUT_BYTES_EXCEEDED、PLUGIN_NOT_FOUND、PLUGIN_FAILED、CANCELLED、TIMED_OUT、WATCH_DISCONNECTED（定义在 internal/worker/core/worker.go、internal/worker/adapters/orchestrator_phases.go、internal/worker/core/dispatcher_internal.go）。
• ReturnValueResultHandler 把 call 输出数组放进 pluginResults[i].result（gRPC 上是 JSON bytes）。
• gRPC PluginResult 只有 plugin_name / success / failure_code / result 四个字段；Go 类型里的 FailureMsg、Retryable 不上 wire（taskResultToPB）。

• GetTaskResult(task_id)：WorkerCore.HandleGetTaskResult。活动 task 返回 RUNNING；只预占未提交返回 ALLOCATED；终态且未过期返回 state + result；否则 NotFound。
• WatchTasks(task_ids) -> stream TaskUpdate：SubscriptionManager.WatchTasks。先对每个 task_id 发一次当前快照（未知的 task_id 发 is_terminal=true, error="not_found"，不让整批失败），再对仍在跑的 task 各推一次终态；所有 task 终态后 stream 自行关闭。TaskUpdate 含 task_id / state / is_terminal / worker_addr / timestamp_ms / result / error。没有单独的取消订阅方法，取消订阅靠关闭 stream。

​

时间语义速查

​

不适用场景

• 依赖同一张表大量行的计算：大范围聚合、窗口统计、K 线。
• 需要任意时间窗口状态或大规模有状态计算。
• 强依赖流式引擎 Exactly Once 状态恢复。
• 普通在线表的任意增量流式计算。

​

相关文档

• docs/specs/architecture.md：§2 任务模型、§3 主链路、§4.3 结果与协议、§5 不适用场景。
• docs/specs/worker.md：§2 对外协议、§3 本地状态模型、§4 执行流程、§8 失败语义。
• docs/specs/task-resource-coordinator.md：选址、不确定态重试、熔断。
• docs/specs/call-execution-subsystem.md：dispatcher、Executor、子函数调用。
• docs/specs/plugin-system.md：Call Builder 与 Writer Plugin 的声明结构。

• 架构总览：系统架构总览。
• 协议与接口：gRPC / UDS / etcd 协议细节。
• Worker：slot 表、WorkerCore 事件与命令、配置。
• Coordinator：ReserveWorkerSlot 处理链。
• Call 执行子系统：Calls 阶段内部。
• Plugin 系统：Builder 与 Writer Plugin 扩展。
• IO 访问子系统：TaskIOScope、retry scope、backend admission。