Minimal Work Core v0.1 契约冻结与检查点工作流验证报告

日期：2026-08-21
实验分支：spike/checkpoint-workflow-contract
性质：正式生产实现前的最终设计收敛；不包含正式代码重构、数据库迁移或产品行为变更。

结论

Verdict：A. CONTRACT FROZEN — ready for production implementation。

“ready”只表示后续生产实现已有经过三轮证伪的输入规范；不意味着本实验分支应该合并，也不授权立即修改 Agent-Box 正式架构。

三轮证据链

第一轮离线证伪验证 Work-first/execution-pluggable：Harness、Workflow、Human、CI、Security Scanner 能以独立 Execution provider 接入；Work 不保存 workflow state，Core schema/source mutation 为 0。

第二轮真实 provider 兼容性使用真实 Codex CLI 0.149.0（通过 Agent-Box codex-main profile launch）与真实长运行 subprocess。Codex thread/session identity 可跨 CLI turn 以 exec resume THREAD_ID 延续；subprocess 则以 PID 为非可恢复 native instance。结果推翻 single status：Execution projection 必须表达 terminality、outcome、resumability 与 observation freshness。

第三轮使用真实 LangGraph 1.2.11 和 SQLite checkpointer 3.1.1。依赖仅安装在 spikes/minimal_work_core/.checkpoint-venv/，未修改 pyproject.toml、锁文件或全局 Python。

真实 Checkpoint 实验

真实 graph 路径为：

research → interrupt/checkpoint → client/process boundary → Command(resume) → finalize

第一次 client 执行到 LangGraph interrupt，SQLite 存储 durable checkpoint。随后销毁第一 client/saver，创建新的 saver 与 graph client，使用相同 LangGraph thread_id 执行 Command(resume="approved")，成功得到 finalized: approved。恢复前后 checkpoint ID 不同。

结论：checkpoint、node、step、poll 和 client process 都不定义 Execution identity。稳定、provider-authoritative 的 workflow instance（LangGraph thread_id）才定义 identity。因此：

情况	Execution 结论
Codex 同一 thread resume	同一个
LangGraph 同一 thread 从 checkpoint resume	同一个
workflow 内部 retry node	同一个，Core 不感知
旧 workflow instance abandoned 后新 thread 重启	新 Execution、同一 Work
同一 graph definition 但新 native thread	新 Execution、同一 Work
checkpoint fork 成新 thread	若跨 provider federation，则新 Execution；否则 provider-native

冻结的最小边界

Domain 只保留 Work、Execution。

Runtime 保留 ExecutionProvider、ExecutionProjection、typed Ref、material-fact EventLedger、ExtensionRegistry。

Work

Work 拥有稳定 identity、objective/intended outcome、最小 open/completed/(optional abandoned) lifecycle、显式 closure/reopen 和 Execution relation。

Work 永不拥有 native session、transcript、workflow graph/checkpoint/retry/DAG、scheduler、PID、credential、workspace/artifact bytes 或详细 permission policy。

Execution failed/cancelled/succeeded 都不自动改变 Work；host、user 或显式 policy extension 才可关闭或 reopen Work。

Execution

Execution 是某次可追踪的 Work 推进实例，拥有 execution/work/provider identity、native refs、projection、input/output refs 与 provenance/time。

Execution 不拥有 transcript、checkpoint、workflow state、retry logic、process internals 或 scheduler state。

Projection 与 capabilities

冻结 projection：

字段	含义
phase	active / terminal / unknown
outcome	terminal 时的 succeeded / failed / cancelled / abandoned
resumable_now	当前 native instance 是否实际可继续
freshness	observed / stale / unreachable

不添加公共 waiting。human waiting、queue、checkpoint pause、rate-limit、retry 都是 provider detail。

provider-level supports_resume 是 capability；resumable_now 是某个 Execution 的当前 projection。前者不能替代后者。observe() 查询失败必须给出 unknown/unreachable，绝不能伪造成功或失败。

Ref、Event 和 ownership

Ref 使用统一结构加 registered semantic type：SessionRef、WorkflowInstanceRef、RunRef、WorkspaceRef、ArtifactRef。只允许 type/provider/native_id/可选 URI/小型字符串 metadata。

禁止 transcript、checkpoint blob、workflow graph、artifact bytes、command output 或任意嵌套 provider payload。

Event ledger 仅保存 Agent-Box 有权声明的 cross-system facts：Work lifecycle、Execution 创建/dispatch/native-ref/start、material projection change、terminal transition 和 Ref attachment。它不是 event-sourcing runtime，不复制 Codex JSONL 或 LangGraph checkpoint history。

Concern	Authoritative owner
Work identity/objective/closure	Work Core 与 host closure policy
Execution identity/projection	Execution Core，基于 provider observation
Codex thread/transcript	Codex provider
workflow state/checkpoint/retry	Workflow provider
workspace/artifact bytes	各自 external authority
scheduling/orchestration/notification	Host 或 extension
credentials/permissions	provider 与 host security authority

Mutation 和 Freeze Gate

Spike	Schema/source	Semantic/API	Naming
Offline	0	0	0
Real provider	0	1（structured projection）	1（SessionRef/RunRef）
Checkpoint workflow	0	0	0

Freeze gate 全部通过：Work 无 provider state；Codex 和 workflow resume identity 有稳定规则；projection 在 Codex/subprocess/LangGraph 三类 runtime 有意义；Ref 未退化；ledger 不复制 telemetry；provider 不需要 Core 分支；workflow state opaque；Execution lifecycle 与 Work lifecycle 独立；未新增 Workflow/Scheduler primitive。

验证

spikes/minimal_work_core/.checkpoint-venv/bin/python -m pytest \
  spikes/minimal_work_core/tests \
  spikes/minimal_work_core/real_providers/tests -q

结果：11 passed，包括真实 LangGraph SQLite checkpoint/resume。

后续建议

可将以下 spike 文件作为后续生产实现设计输入，但必须另开并经用户授权：

• spikes/minimal_work_core/contracts/v0_1/CORE_CONTRACT_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/WORK_CONTRACT_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/EXECUTION_CONTRACT_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/EXECUTION_IDENTITY_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/EXECUTION_PROJECTION_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/EXECUTION_PROVIDER_CONTRACT_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/REF_GOVERNANCE_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/EVENT_LEDGER_CONTRACT_V0_1.md
• spikes/minimal_work_core/contracts/v0_1/OWNERSHIP_MATRIX_V0_1.md

当前不建议直接搬迁 spike code、修改正式 Work service/CLI/GUI、迁移数据库或合并实验分支。