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 快速上手。