← v0.6 spec

Capsule format · v0.6 · File layout

File Layout

Canonical source. This page is rendered from spec/format.md. The markdown file is the canonical authority. View raw: /protocol/v0.6/format.md.

A .capsule is a deterministic ZIP archive. The container is standard ZIP; the determinism comes from canonical file ordering and fixed timestamps inside the archive.

Plain (unencrypted) capsule

example.capsule
├── manifest.json
├── program.md
├── agents.md
├── chain/
│   └── events.jsonl
├── skills/
│   └── <skill_id>/
│       ├── skill.json
│       └── SKILL.md
├── payload/
│   └── ...arbitrary files...
└── provenance/
    └── envelope.json

Encrypted capsule (outer layer)

The outer archive is plaintext metadata; the inner capsule is encrypted as one blob.

example.capsule
├── manifest.json                       outer manifest, encryption-aware
├── content.enc                         encrypted inner ZIP
├── skills/
│   └── decryption/
│       └── decryption.json             cipher, nonce, recipient bundles
└── provenance/
    └── envelope.json                   signs the encrypted-blob hash

The decrypted inner content is a normal capsule layout (the "Plain" shape above) parsed by the same reader.

Required files

Every capsule has:

  • manifest.json
  • program.md
  • chain/events.jsonl
  • provenance/envelope.json

Optional but conventional:

  • agents.md — recommended whenever more than one actor participates
  • skills/<id>/skill.json and/or skills/<id>/SKILL.md — see trust.md for trust tiers
  • payload/... — arbitrary (where the fun happens)

For encrypted capsules, the inner shape contains the required files; the outer shape replaces them with content.enc plus decryption metadata.

Files that are not part of v0.6

The following files appeared in the prior format and are not part of v0.6:

  • surface.md — replaced by program.md
  • handoff.md — folded into program.md as a "Continuation" section
  • state/state.json — state is a projection of the chain; not stored
  • plan.md — folded into program.md as a "Plan" section
  • skills_used_in_this_capsule.md — computed at read
  • surface-citations.md convention — ordinary markdown links

A reader that encounters these files in an old capsule should ignore them (they are not authoritative under v0.6) but should not error.

Container properties

  • File entries are sorted by path, ASCII order.
  • Internal ZIP timestamps are fixed at 1980-01-01T00:00:00Z (the ZIP epoch) so identical content produces identical bytes.
  • Compression: STORED (no compression). This makes archive bytes a function of content only, not of compression-library version.
  • Symlinks, hardlinks, and out-of-tree paths (.., absolute paths, NULs) are rejected by readers as ZIP-slip protection.
  • File-count and total-uncompressed-size limits are configurable on the reader; defaults are 10,000 entries and 1 GiB. Exceeding either is a rejection.

Determinism boundary

Determinism is a write-time property of one implementation, not a protocol guarantee across implementations. Two implementations producing "the same" capsule are not required to produce byte-identical archives; they are required to produce archives whose content_index (per-file hashes) match, and whose canonical envelope payload matches.

This is the right boundary because it is what an auditor actually checks.