receipt/ledger.py
Typeset an archive of fragletc receipts (fraglet-receipt/2) as a ledger: one row per run with its tool, memo key, params, inputs and outputs by content hash, and exit code, in run order. Where a run's input hash is an earlier run's output hash the row says so, which makes the archive a provenance graph a reader can follow by hand. If the archive also carries blobs/<sha256 hex> files, every hash present in it is marked, so the reader knows which bytes travel with the ledger and which are hash-only. Emits an HTML fragment (default) or Markdown to stdout, for embedding in a page such as a Daily Fraglet edition.
Use when a bundle of receipts must be presented to a reader as evidence -- an appendix, a ledger page, a provenance table -- rather than handed over as raw JSON.
- the file
- receipt/ledger.py
- its skill
- receipt/SKILL.md (the whole receipt pack)
- as knowledge
- okf/receipt/ledger.md
- on GitHub
- receipt/ledger.py ↗
Run it
1. Once per machine: install fragletc (Docker must already be running).
curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh
2. Fetch the tool and print its contract.
curl -fsSLO https://tools.ofthemachine.com/receipt/ledger.py && chmod +x ledger.py && ./ledger.py --fraglet-help
3. Run it.
./ledger.py -p receipts="<receipts>" [-p format=html] [-p prefix=12]
Parameters
| name | type | requirement | description |
|---|---|---|---|
| receipts | file | required | tar/tar.gz/zip containing receipts/*.json and optionally blobs/<hex> |
| format | string | default html | html (a fragment with class="ledger") or md |
| prefix | string | default 12 | How many hex characters of each hash to print |
Outputs
stdout
Provenance
- image
- ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522
- reach
network=none— a run is a pure function of its inputs; results are safe to memoize.- procedure_hash
- sha256:7a3706383ac7cde41ce5a50776ddf5ea7ed0c7e58e84cf209028dc59796fef68
- receipt
- add
--receipt run.jsonto any run;receipt/attest.pyverifies it against this hash without re-running.
Source
ledger.py · 141 lines · sha256 7a3706383ac7…
#!/usr/bin/env -S fragletc --image ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522
#: d=Typeset an archive of fragletc receipts (fraglet-receipt/2) as a ledger: one row per run with its tool, memo key, params, inputs and outputs by content hash, and exit code, in run order. Where a run's input hash is an earlier run's output hash the row says so, which makes the archive a provenance graph a reader can follow by hand. If the archive also carries blobs/<sha256 hex> files, every hash present in it is marked, so the reader knows which bytes travel with the ledger and which are hash-only. Emits an HTML fragment (default) or Markdown to stdout, for embedding in a page such as a Daily Fraglet edition.
#: when=Use when a bundle of receipts must be presented to a reader as evidence -- an appendix, a ledger page, a provenance table -- rather than handed over as raw JSON.
#: network=none
#: stdin=none
#: param=receipts:required:file:d=tar/tar.gz/zip containing receipts/*.json and optionally blobs/<hex>
#: param=format:default=html:d=html (a fragment with class="ledger") or md
#: param=prefix:default=12:d=How many hex characters of each hash to print
import html
import io
import json
import os
import sys
import tarfile
import zipfile
archive = os.environ["RECEIPTS"]
fmt = os.environ.get("FORMAT", "html").strip().lower()
prefix = int(os.environ.get("PREFIX", "12"))
receipts = []
blobs = set()
def take(name, data):
base = os.path.basename(name)
if "/receipts/" in "/" + name and base.endswith(".json"):
try:
receipts.append((base, json.loads(data.decode("utf-8"))))
except (ValueError, UnicodeDecodeError) as e:
print(f"Error: {name}: {e}", file=sys.stderr)
sys.exit(2)
elif "/blobs/" in "/" + name:
blobs.add(base.replace("sha256_", "sha256:"))
if zipfile.is_zipfile(archive):
with zipfile.ZipFile(archive) as z:
for info in z.infolist():
if not info.is_dir():
take(info.filename, z.read(info))
else:
with tarfile.open(archive) as t:
for m in t.getmembers():
if m.isfile():
take(m.name, t.extractfile(m).read())
if not receipts:
print("Error: no receipts/*.json in the archive", file=sys.stderr)
sys.exit(2)
receipts.sort(key=lambda r: r[1].get("started", ""))
def short(h):
return h.split(":", 1)[-1][:prefix]
def tool_of(r):
return os.path.basename(r.get("procedure") or "inline")
def unbound(r):
why = []
if r.get("argv"):
why.append("argv")
if r.get("env"):
why.append("-e " + ",".join(r["env"]))
if r.get("stdin_mode") == "stream":
why.append("stdin streamed")
return why
def klass(r):
return "hermetic" if (not unbound(r) and "memo_key" in r and r.get("network") == "none" and "@sha256:" in r.get("image", "")) else "environmental"
# Every output hash, by the run (index) that produced it: the edges of the graph.
produced = {}
for i, (_, r) in enumerate(receipts):
for name, h in (r.get("outputs") or {}).items():
produced.setdefault(h, (i, name))
esc = html.escape
def cell_hashes(items, i, stdin_mode=""):
parts = []
for name, h in sorted(items.items()):
if i == "in" and name == "" and stdin_mode == "none":
continue # nothing was attached; the empty-input hash is implied by the mode
label = "stdin" if name == "" and i == "in" else ("stdout" if name == "" else name)
mark = "✓" if h in blobs else ""
src = ""
if i == "in" and h in produced:
j, oname = produced[h]
src = f' <span class="from">← run {j + 1} {esc(tool_of(receipts[j][1]))}</span>'
parts.append(f"<b>{esc(label)}</b> <code>{short(h)}</code>{mark}{src}")
return "<br>".join(parts) or "—"
if fmt == "md":
print("| # | Tool | Key | Class | Params | Inputs | Outputs | Exit |")
print("|---|---|---|---|---|---|---|---|")
for i, (fname, r) in enumerate(receipts):
key = short(r["memo_key"]) if "memo_key" in r else "unkeyed (" + ", ".join(unbound(r)) + ")"
# a pipe inside a value (jq filters, meme caption lines) would split the table cell
params = ", ".join(f"{k}={v.replace('|', chr(92) + '|')}" for k, v in sorted((r.get("params") or {}).items())) or "—"
ins = ", ".join(f"{k or 'stdin'}={short(h)}" for k, h in sorted((r.get("inputs") or {}).items()))
outs = ", ".join(f"{k or 'stdout'}={short(h)}" for k, h in sorted((r.get("outputs") or {}).items()))
print(f"| {i + 1} | {tool_of(r)} | `{key}` | {klass(r)} | {params} | {ins} | {outs} | {r.get('exit_code')} |")
sys.exit(0)
rows = []
for i, (fname, r) in enumerate(receipts):
if "memo_key" in r:
key = f"<code>{short(r['memo_key'])}</code>"
else:
key = "<i>unkeyed</i><br><span class=\"from\">" + esc(", ".join(unbound(r))) + "</span>"
params = "<br>".join(
f"<b>{esc(k)}</b> {esc(v if len(v) <= 48 else v[:45] + '…')}" for k, v in sorted((r.get("params") or {}).items())
) or "—"
started = r.get("started", "")[11:19] + "Z"
rows.append(
f"<tr><td>{i + 1}</td><td><b>{esc(tool_of(r))}</b><br><span class=\"from\">{started} · {esc(r.get('network') or 'undeclared')}"
f" · {esc(r.get('stdin_mode', ''))}</span></td><td>{key}<br><span class=\"from\">{klass(r)}</span></td>"
f"<td>{params}</td><td>{cell_hashes(r.get('inputs') or {}, 'in', r.get('stdin_mode', ''))}</td>"
f"<td>{cell_hashes(r.get('outputs') or {}, 'out')}</td><td>{r.get('exit_code')}</td></tr>"
)
hermetic = sum(1 for _, r in receipts if klass(r) == "hermetic")
keyed = sum(1 for _, r in receipts if "memo_key" in r)
edges = sum(1 for _, r in receipts for h in (r.get("inputs") or {}).values() if h in produced)
print(
f'<div class="ledger-summary">{len(receipts)} runs · {keyed} keyed · {hermetic} hermetic · '
f"{edges} input{'s' if edges != 1 else ''} traced to an earlier run's output · {len(blobs)} blob{'s' if len(blobs) != 1 else ''} in the bundle "
f"(✓ marks a hash whose bytes travel with this ledger)</div>"
)
print('<table class="ledger"><thead><tr><th>#</th><th>Run</th><th>Memo key</th><th>Params</th><th>Inputs</th><th>Outputs</th><th>Exit</th></tr></thead><tbody>')
print("\n".join(rows))
print("</tbody></table>")