Skip to content

File formats

Store layout

.protocolith/           (or --store / PROTOCOLITH_STORE)
  ledger.jsonl          the ledger
  lock                  advisory lock file, created on the first write
  cards/                issued cards (default of `issue`)
    PLITH-<protocol_id>-<date>-<seq>.json
    PLITH-<protocol_id>-<date>-<seq>.svg

Paths are handled with pathlib; files are written in binary mode so newlines are always \n.

Ledger line

One canonical JSON object per line, ending with \n:

{"body":{},"hash":"64 hex","prev":"64 hex","seq":0,"ts":"2026-11-14T16:00:00Z","type":"freeze","v":1}

Exactly these seven keys. A line is at most 1,048,576 bytes without the newline.

Bodies

Bodies are closed: unknown keys are rejected with BAD_ENTRY.

freeze

Key Type Notes
protocol_id string [A-Za-z0-9][A-Za-z0-9._-]*, at most 128 characters
version string [A-Za-z0-9][A-Za-z0-9._+-]*, at most 64 characters
protocol object must contain the same protocol_id and version
protocol_sha256 hash SHA-256 of the canonical protocol
supersedes hash or null hash of the replaced version

record

Key Type Notes
protocol_sha256 hash a protocol frozen at an earlier seq
run_id non-empty string
status string one of the result statuses
outcome object free content, no floats
sources list of {id, sha256} id non-empty, sha256 a 64-hex hash
reproduction_level non-empty string the card values are listed in result statuses
claim_boundary non-empty string where the claim stops
deviations list of integers seq of earlier deviations of the same protocol
block_reason string, optional required for BLOCKED_SOURCE
drift_reason string, optional required for SOURCE_DRIFT
card object, optional extra evidence-card fields, used by issue

The outcome object is free-form (no floats). protocolith capture prints a fragment with environment and inputs (relative path, size and sha256 of input files) that you can paste into it.

deviation

protocol_sha256 (a frozen protocol), kind (non-empty string), description (non-empty string).

issue

record_seq (integer), format (evidence-card-json-svg), card_sha256 (hash).

Hash

Lowercase 64-character hexadecimal, SHA-256 of the canonical bytes.

Timestamp

YYYY-MM-DDTHH:MM:SSZ, UTC, whole seconds, a valid calendar date and time.

Card JSON

The canonical bytes of the evidence card, no trailing newline. Fields derived from the record are claim_boundary, created_at (the record's ts), evidence_id (PLITH-<protocol_id>-<date>-<seq>, seq being the record's ledger seq in 6 digits, so every record has its own card), ledger_record_seq, protocol_id, protocol_sha256, protocol_version, raw_payload_committed (always false), reproduction_level, result_status, sources, and block_reason or drift_reason when present. Defaults that card may override: last_verified_date, record_type (evidence_result), registry_sequence (record seq + 1). The remaining fields come from card; see EVIDENCE_CARD.

The normative text is in the core specification.