ato

Docs/Capsule

Atualizado em 2026-10-23

Capsule

Um Capsule(uma cápsula) é um ponto selado, imutável e endereçável em um Computation(computação). É uma continuação aberta e persistente: ainda resta trabalho, mas o ponto em si pode ser nomeado, guardado, compartilhado, retomado, composto e bifurcado independentemente do processo que o produziu.

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

"Aberto" significa que a continuação não terminou. "Persistente" significa que o ponto sobrevive à execução original.

Identidade e materialização

Um Capsule não é o arquivo que o transporta nem o mecanismo que o reconstrói.

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

O wire v2 com raiz Computation usa ComputationRef; Portable Application wire v3/v4 usa ContractRef. As referências não são intercambiáveis. Consulte Portable Capsules (inglês).

O que um host pode fazer com um Capsule depende de quais Materializations estão disponíveis ali. Essa disponibilidade decide se e como o host pode retomar o ponto, não o que o Capsule é.

Run, Record e ramificações

  • Um Run(uma execução) é uma avaliação ativa retomada de um Capsule. Runs avançam; selar o ponto atual produz outro Capsule.
  • Um Record(um registro) é evidência de uma interação observada. Records permitem que Replay(reprodução) reconstrua um ponto em outro lugar; eles não são o ponto.
  • Nomes de ramificação e linhagem ajudam a localizar e relacionar pontos. Eles não mudam a identidade desses pontos.

O que um Capsule não é

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

Um snapshot, uma VM ou um contêiner pode realizar um Capsule. Um log de Replay pode carregar a evidência necessária para reconstruir um. capsule.toml descreve como um projeto é registrado. Nenhum deles é a continuação em si.

O arquivo .capsule

A descrição e o exemplo a seguir se aplicam apenas ao wire v2 com raiz Computation.

Um arquivo .capsule portátil é um pacote de transporte. Ele contém a referência raiz do Computation selado, o fechamento de objetos verificado de que a raiz precisa e descritores de Materialization opcionais.

Exportar não altera a identidade do ponto:

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

ato run consome o pacote de forma efêmera; o Capsule que ele retoma é o ponto ao qual o pacote se refere, não o arquivo.

Para os comandos que produzem e consomem esses arquivos, siga para o Início rápido da CLI.