Using it in CI¶
The commands are headless and deterministic enough for a pipeline. This page lists what to rely on. The longer guide is headless and CI use.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | ok |
| 1 | the stored ledger does not verify |
| 2 | the operation was rejected (bad input, or the new entry would break a rule); nothing was written |
| 3 | I/O or environment error, for example no ledger at the store path, or the lock timed out |
A minimal verification job¶
protocolith verify-ledger --store .protocolith
Fails the job with code 1 if any rule R1 to R11 is violated, and with code 3 if the ledger is missing. A missing ledger is never an empty pass.
Machine-readable output¶
Every command except mcp accepts --json and prints canonical JSON on stdout:
protocolith verify-ledger --json
{"codes":[],"count":3,"head":{"hash":"...","seq":2},"ok":true,"violations":[]}
On failure the error text goes to stderr and, with --json, a canonical JSON error object goes to stdout.
Pitfalls¶
- The clock is the machine clock. Timestamps never decrease within a ledger; an append whose time is earlier
than the last entry is rejected with
TS_REGRESSION. Do not append from several machines to a copy of the same file. - The store uses an advisory lock with a 30 s timeout, so parallel jobs on the same file serialise.
- CI is the wrong place to be the only copy of a ledger; keep it as an artifact or in git, and compare the head with an anchored value (anchoring).
- To detect a removed tail or a replaced ledger, compare with an anchored head:
protocolith verify-ledger --expect-head SEQ:HASHexits with 1 andHEAD_MISMATCHif the entry atSEQhas another hash or does not exist.