ato

Docs/Capsule

更新于 2026-10-23

Capsule

Capsule（封装体）是计算中一个被封存、不可变、可寻址的点。它是一个持久打开着的延续：工作仍然保留，但这个点本身可以被命名、保存、分享、恢复、组合和分叉，而与产生它的进程无关。

seal(C42)      → Capsule C42
resume(C42)    → Run
fork(C42)      → RunA, RunB

“打开”表示这个延续还没有结束。“持久”表示这个点在最初的运行结束后仍然存在。

身份与物化

Capsule 不是传输它的文件，也不是重建它的机制。

Capsule identity  !=  bundle bytes
Capsule identity  !=  materialization inventory

计算根 wire v2 使用 ComputationRef，Portable Application wire v3/v4 使用 ContractRef；两者不能互换。详见 Portable Capsules（英文）。

主机可以对 Capsule 做什么，取决于该主机上有哪些可用的物化方式。这种可用性决定主机能否以及如何恢复这个点，而不决定 Capsule 是什么。

Run、Record 与分支

  • Run（运行）是从 Capsule 恢复的活动求值。Run 会向前推进；封存当前点会生成另一个 Capsule。
  • Record（记录）是观察到的一次交互的证据。Record 让重放可以在别处重建一个点；它们不是那个点本身。
  • 分支名称和谱系有助于定位和关联各个点。它们不会改变这些点的身份。

Capsule 不是什么

Capsule != Snapshot
Capsule != VM
Capsule != Container
Capsule != Replay Log
Capsule != capsule.toml

快照、虚拟机或容器可以实现一个 Capsule。重放日志可以携带重建它所需的证据。capsule.toml 描述一个项目如何被记录。它们都不是延续本身。

.capsule 文件

以下说明和示例仅适用于 computation-root wire v2。

可移植的 .capsule 文件是一个传输包。它包含被封存计算的根引用、该根所需的经过验证的对象闭包，以及可选的物化描述符。

导出不会改变该点的身份：

ato encap demo@main --materialize ato.replay@1 -o demo.capsule
ato run demo.capsule

ato run 以临时方式使用该包；它恢复的 Capsule 是这个包所指向的点，而不是文件本身。

关于生成和使用这些文件的命令，请继续阅读 CLI 快速上手。