Capsule format · v0.6 · SDKs

One format, several reference implementations.

The v0.6 format specification is the contract; the SDKs are reference implementations that all build against the same canonical test vectors. New implementations are welcome, and the test vectors are the conformance gate: an implementation is Capsule-compliant when its hashes match the JS reference on the published vectors.

Read the spec See the latest conformance report

Conformance · verified 2026-05-12 · view report · machine-readable

v0.6 open format test-vector conformance Apache-2.0

Section 01

Status at a glance

One row per implementation. Status labels below the table are deliberately blunt: shipped is shipped, in flight is in flight, PoC is PoC.

Language Package Version Status Maintainer
JavaScript @capsule/sdk-v0.6-prototype 0.6.0-prototype.1 Shipped (prototype) · last verified 2026-05-12 (20/20 tests pass, 209ms) Virion.ai
Python (TBD) upgrading to v0.6 In flight Virion.ai
Rust (TBD) verifier only In flight Virion.ai
Swift (extracted from Prescribe.chat) preview PoC Virion.ai
Kotlin (extracted from Prescribe.chat) preview PoC Virion.ai

Status legend

  • Shipped (prototype): builds, signs, verifies, round-trips the v0.6 test vectors. API not stable; expect breakage before v1.0.
  • In flight: actively being implemented against v0.6; not yet test-vector-clean.
  • PoC: a working implementation has been used inside a vertical product (Prescribe.chat), but has not been extracted into a public SDK yet.

Section 02 · Test vectors are the contract

Conformance

Every SDK in the matrix above is tested against the v0.6 test vectors via a single harness. The public report records exit codes, durations, parsed test counts, and produced capsule sizes for each run, so anyone can audit what passed and how long it took.

git clone https://github.com/virionai/capsules-protocol
cd capsules-protocol/new-design
npm install
node tools/run-conformance.mjs

Latest run: 7 of 7 targets pass · 1397ms total · generated 2026-05-12 02:38 UTC.

What's verified

  • sdk-js: @capsule/sdk-v0.6-prototype (sdk) · 209ms
  • example-symptom-tracker: symptom-tracker (example) · 166ms
  • example-medical-journal: medical-journal (example) · 169ms
  • example-tamper-detection: tamper-detection (example) · 294ms
  • example-business-dr: business-dr (example) · 196ms
  • example-family-dr: family-dr (example) · 175ms
  • example-town-dr: town-dr (example) · 180ms

Reports are archived at /conformance/ with one dated copy per public release.

Section 03

JavaScript (Shipped)

The reference SDK. Builder, reader, verifier, the canonical-JSON and Ed25519 primitives, and the deterministic-ZIP container live in a single npm package. The exported surface includes CapsuleBuilder, CapsuleReader, verifyCapsule, plus the lower-level buildChainEvents, hashEvent, verifyChain, buildEnvelope, signEnvelope, verifyEnvelopeSignatures, buildManifest, computeCapsuleId, packZip, unpackZip, and the JCS / SHA-256 helpers (jcs, sha256, sha256Hex). Two dependencies: canonicalize (RFC 8785 JCS) and jszip (deterministic ZIP). Node 20 or newer; runs unmodified in browsers via a bundler.

npm install @capsule/sdk-v0.6-prototype
import { CapsuleReader, verifyCapsule } from "@capsule/sdk-v0.6-prototype";

const bytes = await fetch("/examples/medical-journal/sample.capsule")
  .then((r) => r.arrayBuffer());
const reader = await CapsuleReader.fromBytes(new Uint8Array(bytes));
const result = await verifyCapsule(reader, { allowlist: [] });
console.log(result.ok, result.level, result.envelope.signers);

Source: github.com/virionai/capsules-protocol/tree/main/new-design/sdk.

Browser-only reference builds without a bundler are demonstrated in examples/medical-journal/: the clinician reader loads the SDK in a single offline HTML file.

Section 04

Python (In flight)

Capsule started as a Python codebase. The Python implementation is being upgraded to v0.6 in the open, on the same crypto primitives as the JS SDK (SHA-256, JCS RFC 8785, Ed25519 raw-byte signing, ChaCha20-Poly1305 + X25519 + HKDF-SHA256 for encrypted capsules) and the same deterministic ZIP rules. It is expected to ship parity against the JS reference test vectors as the second independent implementation.

This is the format-stewardship signal. A second implementation completing test-vector parity is the milestone that locks v0.6; it is the kill criterion against which milestone 1 of the project roadmap is measured (see ROADMAP.md). Until that lands, the spec is a single-implementation spec, and "Capsule" is a JS library.

Section 05

Rust (In flight, verifier-only)

A Rust implementation is in flight. Verifier-only for the launch window: the natural shape for clinic-side ingestion pipelines (capsule verify file.capsule, exit 0 on pass, exit 1 on fail) and for any server-side workflow that needs typed errors, fast batch verification, and a small static binary with no runtime.

Verifier-first is the right first scope because the verifier is the contract any consumer needs; the builder is what producers need. Verifier-first lets the format gain credibility in the consuming environment (auditor, clinic, downstream platform) before the production tooling is in flight.

Section 06

Swift & Kotlin (PoC via Prescribe.chat)

Swift

A working Capsule signing and verifying flow exists inside the Prescribe.chat iOS app. Ed25519 keypair generation, deterministic ZIP packing, JCS canonicalization, envelope signing, and round-trip verification have all run against real capsules on-device. This implementation will be extracted into a public capsules-swift package, marked "preview, extracted from Prescribe.chat, not yet API-stable," before the v0.7 stabilization wave. Today it is not a public SDK; it is application code that proves the format runs natively on iOS.

Kotlin

Same pattern, Android side. A Kotlin implementation of the same builder + verifier surface is in the Prescribe.chat Android codepath and will be extracted on the same timeline as Swift. Both Swift and Kotlin target native mobile-app integrations where Edge Gallery's WebView model is not appropriate: a clinic intake app, a journaling app that wants Capsule as a backing format, an agentic tool exporting its work product as a portable, signed file.

PoC is PoC. The Swift code signs and verifies a real capsule; the Kotlin code signs and verifies a real capsule; neither is a public SDK yet. We are not promising a release date and we are not promising parity surface; the description above is what exists today, and what is planned is extraction, not new feature work.

Section 07

How conformance works

Conformance is test-vector parity. A new implementation is Capsule-compliant when it produces capsules whose content_index_hash matches the JS reference, and whose canonical envelope payload signs and verifies bit-identically against the published test vectors. Every hash that ships in provenance/envelope.json (capsule_id, first_event_hash, entry_hash, manifest_hash, content_index_hash, envelope_signature) is checkable byte-for-byte.

Conformance is not enforced by anything except those test vectors. There is no certification program, no registry of approved implementations, no "Capsule Foundation" issuing logos. The test vectors are the conformance program: if the hashes match, the implementation is compliant; if they don't, it isn't.

The spec lives at /protocol/v0.6/: five files (format, manifest, chain, envelope, trust), roughly 5 KB of text in total. The latest conformance results, including the per-target breakdown, are published at /conformance/latest.md.

Section 08

Building a new implementation

What an implementer should know before starting:

  • Format anchor. /protocol/v0.6/ is the canonical spec. Five spec files (format, manifest, chain, envelope, trust), roughly 5 KB of text total. Read these first; everything else is an artifact of them.
  • Crypto primitives required. SHA-256, JCS RFC 8785, Ed25519 (raw-byte signing: sign the bytes, not a hex string), and for encrypted capsules ChaCha20-Poly1305 + X25519 + HKDF-SHA256.
  • ZIP primitives required. For writing: a deterministic ZIP_STORED writer with fixed timestamps and sorted paths. For reading: any compliant ZIP parser.
  • Test vectors. Drop the new SDK against the published vectors; if the hashes match, it's compliant. The capsule vectors verify <vectors.json> CLI is the single line a CI matrix can run across JS, Rust, Python, Swift, Kotlin to prove the implementations agree.
  • No second-class implementations. Partial implementations are explicitly welcome: verifier-only Rust, builder-only Python, mobile SDKs scoped to read-only. The roadmap rewards completed shapes over comprehensive coverage. A clean verifier with test-vector parity is a stronger contribution than a half-finished builder.

Open an issue at github.com/virionai/capsules-protocol/issues to coordinate.

Section 09

Roadmap

  • v0.6 locks when a second independent implementation round-trips signed test vectors. This is milestone 1 of the project roadmap; until it lands, every version commitment is debt.
  • Once locked, the Capsule spec gets a versioned release tag and the JS SDK rebases from 0.6.0-prototype.x to 0.6.0. The "prototype" suffix is the visible signal that the format has not yet been independently validated.
  • v0.7 plans: AES-256-GCM cipher support, encrypted-capsule extension (multi-recipient envelope), and RFC 3161 / Rekor temporal anchoring. All three are parking-lot today, blocked on adoption signal, not on engineering.

See the full roadmap for kill criteria. The operating principle is: do not add infrastructure before the capsule file proves its value.