Skip to content

Local experiment workflow

A complete pass through one experiment, including the awkward cases. It assumes the quickstart works for you.

1. Before the run

Write the protocol and freeze it.

protocolith freeze protocol.json

Check the entry with protocolith log. If you later realise the protocol was wrong, do not edit the file and freeze again under the same version: that is rejected. Freeze a new version.

2. Run, outside Protocolith

Run your script. Keep what it produced where your normal data handling puts it. Protocolith stores hashes of sources, not their content.

3. Hash the inputs

protocolith hash results.txt

The output is <sha256> <path>. Use the 64-character hash in sources:

"sources": [{"id": "results.txt", "sha256": "60ff5e00..."}]

4. A deviation, if there was one

If the run did not follow the protocol (a source moved, a step was skipped), record it first:

{"protocol_sha256": "802a1675...", "kind": "source_change", "description": "The source file was re-exported."}
protocolith deviation deviation.json
# deviation source_change seq=3 hash=...

Then list its seq in the record: "deviations": [3]. A deviation must belong to the same protocol as the record that lists it, otherwise verification reports DANGLING_REF. Listing a deviation is how a reader sees it next to the result; a deviation that is never listed is still in the ledger.

5. Record

protocolith record record.json

If the clock of the machine moved backwards since the last entry, the record is rejected with TS_REGRESSION (exit 2). Fix the clock; do not edit the ledger.

6. Verify and issue

protocolith verify-ledger
protocolith issue SEQ

7. Share

What you share is your decision: the ledger file, the card, or only the head. A reader who has the ledger can verify it with the same command. A reader who has only the card can see its protocol_sha256 and ledger_record_seq but cannot verify the history.

Several runs of one protocol

Record each run with its own run_id. Record failed and blocked runs too. Nothing stops you from recording many runs against one frozen protocol; nothing hides them either.