feat(blaze): capture sandbox checkpoints

docs/user-guide/en/runtime/blaze.md

@@ -93,7 +93,10 @@ responds.
 Blaze exposes sandbox lifecycle and guest operations under `/v1/sandboxes`.
 Clients use this namespace to list, create, inspect, and delete sandboxes and
 to execute commands, read files, and write files inside them. Sandbox
-destruction uses `DELETE /v1/sandboxes/{id}`.
+destruction uses `DELETE /v1/sandboxes/{id}`. Checkpoint capture and history
+use
+`POST /v1/sandboxes/{id}/checkpoint` and
+`GET /v1/sandboxes/{id}/checkpoints`.
 
 ## Host Integration Boundary
 
@@ -211,6 +214,78 @@ The lifecycle invariants behind these compatibility responses are recorded in
 the
 [lifecycle state consistency and compatibility design](../../../../src/blaze/docs/design/lifecycle-state-consistency.md).
 
+## Checkpoint Capture and History
+
+Blaze captures a running sandbox through
+`POST /v1/sandboxes/{id}/checkpoint`.
+
+Capture requires both the selected backend and the storage provider to
+advertise full-checkpoint support. The built-in file provider captures the
+writable root filesystem, and the built-in mock backend supplies a complete
+development implementation. Firecracker, Bubblewrap, and the other process
+backends do not advertise capture support in this release. An unsupported
+combination returns HTTP 501 before the sandbox is paused or its lifecycle
+record is changed.
+
+For a supported running sandbox, Blaze holds the sandbox operation lock,
+validates its current checkpoint parent, pauses the backend, and captures three
+self-contained files: `vmstate.snap`, `memory.snap`, and `rootfs.snap`. It
+synchronizes and hashes those files, publishes the manifest, atomically updates
+the sandbox checkpoint HEAD, and resumes the backend. Guest operations and
+other lifecycle changes wait for the same operation lock while capture is in
+progress.
+
+A successful response contains the complete published manifest. The existing
+`checkpoint_id` and `instance_id` fields identify the same checkpoint and
+sandbox as `id` and `sandbox_id`:
+
+```json
+{
+  "checkpoint_id": "ckpt-11111111-1111-4111-8111-111111111111",
+  "instance_id": "22222222-2222-4222-8222-222222222222",
+  "format_version": 1,
+  "id": "ckpt-11111111-1111-4111-8111-111111111111",
+  "parent": null,
+  "sandbox_id": "22222222-2222-4222-8222-222222222222",
+  "policy_name": "agent-tool",
+  "image_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+  "backend": "mock",
+  "backend_version": "mock-v1",
+  "created_at": "2026-08-14T00:00:00Z",
+  "snapshot_kind": "full",
+  "artifacts": [
+    {
+      "name": "vmstate.snap",
+      "size_bytes": 4096,
+      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    {
+      "name": "memory.snap",
+      "size_bytes": 8192,
+      "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    },
+    {
+      "name": "rootfs.snap",
+      "size_bytes": 8589934592,
+      "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    }
+  ]
+}
+```
+
+Use `GET /v1/sandboxes/{id}/checkpoints` to list committed history. Each list
+entry contains `id`, `parent`, `created_at`, total logical `size_bytes`,
+`is_head`, and `on_head_chain`. The list is a summary and does not repeat the
+complete artifact manifest returned by capture.
+
+A failure known to occur before publication removes its temporary data,
+resumes the backend, and leaves the sandbox running. If Blaze cannot prove the
+publication, HEAD update, persistence, or backend-resume outcome, it retains
+the durable record and reports `RecoveryRequired`; do not retry capture until
+the sandbox has been reconciled or destroyed. A committed checkpoint that did
+not become HEAD can still appear in history with `is_head: false`. This release
+does not provide checkpoint restore, deletion, or pruning APIs.
+
 ## Storage Artifact Synchronization
 
 Blaze can periodically persist the already-written host artifacts and directory

docs/user-guide/zh/runtime/blaze.md

@@ -78,7 +78,9 @@ ID。Blaze 会保留被拒绝的记录。修复或恢复该记录后，重新启
 
 Blaze 通过 `/v1/sandboxes` 提供沙箱生命周期和客户机操作。客户端使用该
 命名空间列出、创建、查看和删除沙箱，以及在沙箱内执行命令、读取文件和写入
-文件。销毁沙箱使用 `DELETE /v1/sandboxes/{id}`。
+文件。销毁沙箱使用 `DELETE /v1/sandboxes/{id}`。检查点捕获与历史查询分别使用
+`POST /v1/sandboxes/{id}/checkpoint` 和
+`GET /v1/sandboxes/{id}/checkpoints`。
 
 ## 主机集成边界
 
@@ -179,6 +181,68 @@ Blaze 仍可读取旧版本写入的 `Reset`、`Warm` 和 `start_path = "warm"`
 [生命周期状态一致性与兼容性设计](../../../../src/blaze/docs/design/lifecycle-state-consistency_zh.md)
 中。
 
+## 检查点捕获与历史
+
+Blaze 通过 `POST /v1/sandboxes/{id}/checkpoint` 捕获运行中的 sandbox。
+
+所选后端和存储提供程序必须同时声明支持完整检查点捕获。内置文件存储提供程序
+负责捕获可写根文件系统，内置 `mock` 后端提供完整的开发环境实现。当前版本的
+Firecracker、Bubblewrap 和其他进程后端尚未声明支持捕获。不支持的组合会在暂停
+sandbox 或修改其生命周期记录前返回 HTTP 501。
+
+对于受支持且正在运行的 sandbox，Blaze 会持有该 sandbox 的操作锁，验证当前
+检查点的父项，暂停后端，并捕获三个自包含文件：`vmstate.snap`、`memory.snap`
+和 `rootfs.snap`。随后会同步文件、计算摘要、发布清单、原子更新该 sandbox 的
+检查点 HEAD，再恢复后端。捕获期间，对虚拟机内部执行的命令和文件操作，以及
+其他生命周期变更都会等待同一把操作锁。
+
+成功响应包含已发布的完整清单。现有 `checkpoint_id` 和 `instance_id` 字段与
+`id` 和 `sandbox_id` 分别指向同一个检查点和 sandbox：
+
+```json
+{
+  "checkpoint_id": "ckpt-11111111-1111-4111-8111-111111111111",
+  "instance_id": "22222222-2222-4222-8222-222222222222",
+  "format_version": 1,
+  "id": "ckpt-11111111-1111-4111-8111-111111111111",
+  "parent": null,
+  "sandbox_id": "22222222-2222-4222-8222-222222222222",
+  "policy_name": "agent-tool",
+  "image_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+  "backend": "mock",
+  "backend_version": "mock-v1",
+  "created_at": "2026-08-14T00:00:00Z",
+  "snapshot_kind": "full",
+  "artifacts": [
+    {
+      "name": "vmstate.snap",
+      "size_bytes": 4096,
+      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    {
+      "name": "memory.snap",
+      "size_bytes": 8192,
+      "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    },
+    {
+      "name": "rootfs.snap",
+      "size_bytes": 8589934592,
+      "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    }
+  ]
+}
+```
+
+可以通过 `GET /v1/sandboxes/{id}/checkpoints` 查询已提交的历史。每个列表项
+包含 `id`、`parent`、`created_at`、总逻辑大小 `size_bytes`、`is_head` 和
+`on_head_chain`。该列表只提供摘要，不会重复捕获响应中的完整制品清单。
+
+能够确认发生在发布前的失败会删除临时数据、恢复后端，并让 sandbox 保持运行。
+如果 Blaze 无法确认发布、HEAD 更新、持久化或后端恢复的结果，则会保留持久记录并
+报告 `RecoveryRequired`；在 sandbox 完成恢复处理或销毁前，不应重试捕获。已经提交但
+未成为 HEAD 的检查点仍可能出现在历史列表中，其 `is_head` 为 `false`。当前版本
+不提供检查点恢复、删除或清理接口。
+
 ## 存储制品同步
 
 Blaze 可以定期持久化 running sandbox 中已经写入的宿主机制品和目录元数据。

src/blaze/Cargo.toml

@@ -45,6 +45,7 @@ chrono = { version = "0.4", default-features = false, features = ["std", "clock"
 semver = "1.0"
 base64 = "0.22"
 rustix = { version = "1.1", features = ["fs"] }
+sha2 = "0.10"
 
 # Internal crates
 blaze-core = { path = "crates/blaze-core" }

src/blaze/README.md

@@ -14,6 +14,9 @@ Designed as the per-host agent for E2B-style orchestrator platforms.
 - **HTTP API** — Unix domain socket (`/run/blaze/api.sock`) + TCP (`:14159`)
 - **Policy-driven backend selection** — workload class → backend priority list
 - **Lifecycle state machine** — durable state with restart recovery
+- **Checkpoint capture** — full VM state, guest memory, and writable root
+  filesystem capture with queryable history for supported backends and storage
+  providers
 - **Guest operations** — bounded command execution and file transfer for
   running backends that expose a guest endpoint
 - **Template catalog** — bounded import and atomic publication of reusable artifacts
@@ -148,6 +151,8 @@ Blaze exposes sandbox lifecycle and guest operations through `/v1/sandboxes`.
 | POST | `/v1/sandboxes/{id}/exec` | Execute a guest command |
 | POST | `/v1/sandboxes/{id}/read` | Read a guest file |
 | POST | `/v1/sandboxes/{id}/write` | Replace a guest file |
+| POST | `/v1/sandboxes/{id}/checkpoint` | Capture a full checkpoint |
+| GET | `/v1/sandboxes/{id}/checkpoints` | List committed checkpoint history |
 | GET | `/v1/pools` | Reserved; returns `501` |
 | GET | `/v1/pools/{backend}/{class}` | Reserved; returns `501` |
 | POST | `/v1/pools/{backend}/{class}/drain` | Reserved; returns `501` |
@@ -233,13 +238,29 @@ See the
 for writer coordination, inventory publication, reset rejection, legacy-state
 cleanup, and failure boundaries.
 
-The operation journal records the operation and start time, not completion of
-each resource step. An interrupted create is cleaned up rather than resumed,
-and an existing backend process is not adopted after restart. Failed recovery
-does not run in a background retry loop. Checkpoint capture and restore are not
-available in this change. Reset remains unavailable until runtime and storage
-can be reset together; this recovery flow does not add backend snapshot,
-capture, or restore operations.
+The operation journal records create and destroy operations and the durable
+phase reached by checkpoint capture. An interrupted create is cleaned up rather
+than resumed, and an existing backend process is not adopted after restart.
+Startup recovery destroys an interrupted sandbox instead of restoring its
+checkpoint. Failed recovery does not run in a background retry loop. Reset
+remains unavailable and does not restore a checkpoint.
+
+### Checkpoint capture and history
+
+`POST /v1/sandboxes/{id}/checkpoint` captures a running sandbox when both its
+backend and storage provider advertise full-capture support. A successful
+request pauses the backend, captures VM state, guest memory, and the writable
+root filesystem, publishes a self-contained integrity manifest, moves the
+sandbox checkpoint HEAD, and resumes the backend. The response includes the
+complete manifest plus the `checkpoint_id` and `instance_id` fields.
+Unsupported backend or storage combinations return HTTP 501 before changing
+sandbox state.
+
+`GET /v1/sandboxes/{id}/checkpoints` returns committed history summaries,
+including parentage, logical size, current-HEAD status, and HEAD reachability.
+This release does not provide checkpoint restore or deletion.
+See the [checkpoint capture user guide](../../docs/user-guide/en/runtime/blaze.md#checkpoint-capture-and-history)
+for response fields, current backend support, and failure handling.
 
 ### Guest operations