Local experiments¶
Protocolith does not run anything. You run the experiment with your own scripts and use three small JSON files around it. The loop is the same for every experiment.
The loop¶
- Write
protocol.json: the question, the data you will use, the exact gate, how a failed run is reported. Keep it small; anything you want to be unable to change later belongs here. protocolith freeze protocol.json. Do this before the first run. From now on the protocol is identified by its hash.- Run your experiment. Keep raw outputs outside the repository or ignored by git; Protocolith never stores raw payloads, only hashes.
- Hash each input the run used (
protocolith hash FILE, orshasum -a 256, orGet-FileHashon Windows) and writerecord.jsonwith the outcome, the source hashes and aclaim_boundarythat says where the claim stops. protocolith record record.json, thenprotocolith verify-ledger.- Optional:
protocolith issue SEQto produce a card.
Where the store lives¶
By default .protocolith/ in the current directory. Use --store DIR or the environment variable
PROTOCOLITH_STORE to keep one ledger per project or to keep the store outside the working tree:
export PROTOCOLITH_STORE="$HOME/experiments/ledgers/my-project"
Whether to commit .protocolith/ledger.jsonl to git is your decision. Committing it gives you history and a
way to compare against an earlier copy; it is not a replacement for anchoring the head
(guide). Add .protocolith/lock to .gitignore.
If the run does not go to plan¶
- The source changed or is unavailable: record
BLOCKED_SOURCEwith ablock_reason, orSOURCE_DRIFTwith adrift_reason. Do not swap the source after seeing a result. - Too little data for the gate:
INSUFFICIENT_COVERAGE. - You had to do something the protocol did not allow: record a
deviationfirst, then list itsseqin the record'sdeviations. - The protocol itself was wrong: freeze a new version with
--supersedes; the old record keeps pointing at the old hash. - The gate was not met: record
NEGATIVE_RESULT_UNDER_PROTOCOL. A failed run is a result, not an error.
Absence of evidence is not a negative result; use the blocked or coverage statuses for it. See result statuses and the worked examples.
One ledger or many¶
A ledger can hold many protocols and many runs; verification checks each record against the protocol it names. Separate ledgers make sense when you want to anchor, share or delete them independently.