results-cli 0.1.0__tar.gz

results_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install hatchling
+      - run: python -m hatchling build
+      - uses: pypa/gh-action-pypi-publish@release/v1

results_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.DS_Store
+*.egg-info/

results_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elliot Tower
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

results_cli-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: results-cli
+Version: 0.1.0
+Summary: Seal a run, record what it produced, and verify the chain
+Author-email: Elliot Tower <elliot@elliottower.ai>
+License: MIT
+License-File: LICENSE
+Keywords: open science,provenance,reproducibility,results
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# results
+
+Seal a run, record what it produced, and verify the chain.
+
+## Install
+
+```bash
+pip install results-cli
+```
+
+## Quick start
+
+```bash
+results init
+results seal prereg.md analysis.py data.csv --role input
+results access "read zenodo metadata" --level "metadata only"
+
+# run the computation, then record its outputs
+results run output.json --run-id exp_001 --note "ICC analysis"
+results claim "ICC = 0.42" --run-id exp_001 --confirmatory --location "Table 2"
+results verify --files
+```
+
+```
+chain intact: 5 events
+
+  access       1
+  claim        1
+  init         1
+  run          1
+  seal         1
+
+file hashes:
+  ok         prereg.md
+  ok         analysis.py
+  ok         data.csv
+  ok         output.json
+
+all checks passed.
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `results init` | Start tracking results here |
+| `results seal <file>...` | Hash inputs before a run |
+| `results access <note>` | Record a data-access event |
+| `results run <file>...` | Record outputs after a run |
+| `results claim <text>` | Bind a manuscript claim to a run |
+| `results verify` | Check the ledger chain and every hash it names |
+
+## The chain
+
+A number in a manuscript names a claim. The claim names a run. The run names its outputs. The
+outputs were hashed when they were recorded. The inputs were hashed before the run started.
+
+```
+manuscript  →  claim  →  run  →  output file  →  sha256
+                                  input files  →  sha256
+```
+
+`results verify --files` walks the whole thing and tells you what moved.
+
+## Data-access levels
+
+The access timeline is what makes the confirmatory/exploratory distinction verifiable.
+
+| Level | Meaning |
+|-------|---------|
+| `nothing seen` | No target data touched |
+| `metadata only` | Structure, region names, sample sizes — not outcomes |
+| `structure seen` | Data shape and distributions, not the target variable |
+| `outcomes seen` | The dependent variable was observed |
+
+An analysis registered after `outcomes seen` is retrospective.
+
+## Verify output
+
+| Result | Meaning |
+|--------|---------|
+| `chain intact` | Every event's prev_hash matches the line before it |
+| `CHAIN BROKEN` | The ledger was edited after it was written |
+| `ok` | File matches its recorded hash |
+| `CHANGED` | File was modified since it was recorded |
+| `MISSING` | File no longer exists |
+
+## The ledger
+
+Append-only JSONL in `.results/ledger.jsonl`. Each line is hash-chained to the previous — editing
+or inserting a line breaks the chain. `git diff` shows what changed; `results verify` checks
+whether it should have.
+
+## Claude Code
+
+`plugin/` is a Claude Code plugin that tells Claude when to reach for the CLI.
+
+```bash
+/plugin marketplace add elliottower/results
+/plugin install results@results
+```
+
+MIT licensed.

results_cli-0.1.0/README.md

@@ -0,0 +1,103 @@
+# results
+
+Seal a run, record what it produced, and verify the chain.
+
+## Install
+
+```bash
+pip install results-cli
+```
+
+## Quick start
+
+```bash
+results init
+results seal prereg.md analysis.py data.csv --role input
+results access "read zenodo metadata" --level "metadata only"
+
+# run the computation, then record its outputs
+results run output.json --run-id exp_001 --note "ICC analysis"
+results claim "ICC = 0.42" --run-id exp_001 --confirmatory --location "Table 2"
+results verify --files
+```
+
+```
+chain intact: 5 events
+
+  access       1
+  claim        1
+  init         1
+  run          1
+  seal         1
+
+file hashes:
+  ok         prereg.md
+  ok         analysis.py
+  ok         data.csv
+  ok         output.json
+
+all checks passed.
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `results init` | Start tracking results here |
+| `results seal <file>...` | Hash inputs before a run |
+| `results access <note>` | Record a data-access event |
+| `results run <file>...` | Record outputs after a run |
+| `results claim <text>` | Bind a manuscript claim to a run |
+| `results verify` | Check the ledger chain and every hash it names |
+
+## The chain
+
+A number in a manuscript names a claim. The claim names a run. The run names its outputs. The
+outputs were hashed when they were recorded. The inputs were hashed before the run started.
+
+```
+manuscript  →  claim  →  run  →  output file  →  sha256
+                                  input files  →  sha256
+```
+
+`results verify --files` walks the whole thing and tells you what moved.
+
+## Data-access levels
+
+The access timeline is what makes the confirmatory/exploratory distinction verifiable.
+
+| Level | Meaning |
+|-------|---------|
+| `nothing seen` | No target data touched |
+| `metadata only` | Structure, region names, sample sizes — not outcomes |
+| `structure seen` | Data shape and distributions, not the target variable |
+| `outcomes seen` | The dependent variable was observed |
+
+An analysis registered after `outcomes seen` is retrospective.
+
+## Verify output
+
+| Result | Meaning |
+|--------|---------|
+| `chain intact` | Every event's prev_hash matches the line before it |
+| `CHAIN BROKEN` | The ledger was edited after it was written |
+| `ok` | File matches its recorded hash |
+| `CHANGED` | File was modified since it was recorded |
+| `MISSING` | File no longer exists |
+
+## The ledger
+
+Append-only JSONL in `.results/ledger.jsonl`. Each line is hash-chained to the previous — editing
+or inserting a line breaks the chain. `git diff` shows what changed; `results verify` checks
+whether it should have.
+
+## Claude Code
+
+`plugin/` is a Claude Code plugin that tells Claude when to reach for the CLI.
+
+```bash
+/plugin marketplace add elliottower/results
+/plugin install results@results
+```
+
+MIT licensed.

results_cli-0.1.0/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "results",
+  "description": "Seal a run's inputs, record what it produced, bind claims to outputs, and verify the chain",
+  "version": "0.1.0",
+  "author": { "name": "Elliot Tower", "email": "elliot@elliottower.ai" },
+  "repository": "https://github.com/elliottower/results",
+  "license": "MIT",
+  "keywords": ["results", "provenance", "reproducibility", "open science"]
+}

results_cli-0.1.0/plugin/README.md

@@ -0,0 +1,31 @@
+# The Claude Code plugin
+
+Tells Claude the `results` CLI exists and when to reach for it. The CLI does the work; this
+adds nothing the CLI cannot do.
+
+## Install
+
+```bash
+/plugin marketplace add elliottower/results
+/plugin install results@results
+```
+
+The plugin ships instructions, not binaries. Install the tool too:
+
+```bash
+uv tool install results-cli
+```
+
+For development against a checkout:
+
+```bash
+/plugin marketplace add ~/Documents/GitHub/results
+/plugin install results@results
+```
+
+## What it changes
+
+Claude will seal inputs before running a computation rather than after, record outputs with their
+hashes, and bind manuscript claims to specific runs instead of leaving numbers untraced. It will
+also record data-access events so the distinction between confirmatory and exploratory analysis
+is verifiable from the timeline, not from a self-report.

results_cli-0.1.0/plugin/skills/results/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: results
+description: Seal a run's inputs before computing, record outputs after, bind manuscript claims to specific runs, and verify the hash chain. Use before launching any computation whose output will appear in a paper, after a run completes, when a number in a manuscript needs tracing to its source, or when asked whether results are still what they were. Requires the `results` CLI (`uv tool install results-cli`).
+---
+
+# results
+
+Seal a run, record what it produced, and verify the chain.
+
+## The rule that matters
+
+**Seal before you run. Claim after you verify.**
+
+A number in a manuscript is trustworthy when it names the run that produced it, the run names the
+inputs that were sealed before it started, and the chain from input to claim has not been broken.
+Every way this fails is a version of the result moving without a trace — a script edited after
+the seal, an output overwritten between the run and the claim, a claim attached to a run that
+no longer exists.
+
+## Commands
+
+```bash
+results init                            # start tracking results here
+results seal <file>... [--role input]   # hash inputs before a run
+results access <note> [--level ...]     # record a data-access event
+results run <file>... --run-id <id>     # record outputs after a run
+results claim <text> --run-id <id>      # bind a manuscript claim to a run
+results verify [--files]                # check the chain and every hash it names
+```
+
+## The workflow, in order
+
+1. **`results init`** in the experiment directory.
+2. **`results seal prereg.md script.py data.csv`** — hash every input before computing.
+3. **`results access "downloaded zenodo metadata" --level "metadata only"`** — record what
+   was seen and when. This is the data-access taint the chain uses to distinguish confirmatory
+   from exploratory.
+4. **Run the computation.**
+5. **`results run output.json --run-id exp_001`** — hash the outputs.
+6. **`results claim "ICC = 0.42" --run-id exp_001 --confirmatory --location "Table 2"`** —
+   bind the manuscript claim to the run.
+7. **`results verify --files`** — check everything.
+
+## Data-access levels
+
+Four levels, in order of exposure:
+
+| level | meaning |
+|---|---|
+| `nothing seen` | no target data touched |
+| `metadata only` | structure, region names, sample sizes — not outcomes |
+| `structure seen` | data shape and distributions, but not the target variable |
+| `outcomes seen` | the dependent variable was observed |
+
+An analysis registered after `outcomes seen` is retrospective, not confirmatory. The level is
+recorded, not judged — log the honest one even when it is the damaging one.
+
+## Reading `results verify`
+
+The chain check is pass/fail:
+
+| | |
+|---|---|
+| `chain intact` | every event's prev_hash matches the hash of the line before it |
+| `CHAIN BROKEN` | a line was edited, inserted, or deleted after it was written |
+
+With `--files`, every sealed input and recorded output is re-hashed against its current state:
+
+| | |
+|---|---|
+| `ok` | file matches its recorded hash |
+| `CHANGED` | file was modified since it was sealed or recorded |
+| `MISSING` | file no longer exists at the recorded path |
+
+**`CHAIN BROKEN` means the ledger was tampered with.** It does not mean the results are wrong —
+it means the evidence that they are right was damaged. Restore from git history.
+
+## Claims
+
+A claim names a run. A run names its outputs. The outputs were hashed when they were recorded.
+This is the whole chain: manuscript → claim → run → output file → hash. `verify` walks it.
+
+`--confirmatory` marks the claim as backed by a pre-registered hypothesis. Without it, the claim
+is exploratory. The distinction is recorded, not enforced — the access timeline is what makes it
+verifiable.
+
+## When to reach for this
+
+- Before launching any computation whose output will be reported
+- After a run completes, to record what it produced
+- When a number in a manuscript needs tracing to its source run
+- When asked whether results are still what they were
+- In CI, as `results verify --files`
+
+## What it will not do
+
+It cannot prove the computation was correct. A sealed script that produces the wrong answer
+passes every check here. It also cannot prove the access timeline is honest — the events are
+self-reported, and the tool records them without questioning. The chain is evidence, not proof.

results_cli-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "results-cli"
+version = "0.1.0"
+description = "Seal a run, record what it produced, and verify the chain"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Elliot Tower", email = "elliot@elliottower.ai" }]
+keywords = ["reproducibility", "provenance", "open science", "results"]
+dependencies = []
+
+[project.scripts]
+results = "results.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/results"]

results_cli-0.1.0/src/results/__init__.py

@@ -0,0 +1,3 @@
+"""Seal a run, record what it produced, and verify the chain."""
+from __future__ import annotations
+__version__ = "0.1.0"

results_cli-0.1.0/src/results/cli.py

@@ -0,0 +1,277 @@
+"""Seal a run, record what it produced, and verify the chain.
+
+    results init              start tracking results here
+    results seal <file>...    hash inputs before a run (prereg, script, data)
+    results access <note>     record a data-access event (what you looked at, when)
+    results run <file>...     record outputs after a run completes
+    results claim <text>      bind a manuscript claim to a run's output
+    results verify            check the ledger chain and every hash it names
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import pathlib
+import sys
+
+from results import ledger
+
+
+RESULTS_DIR = ".results"
+
+
+def find_root(start: pathlib.Path | None = None) -> pathlib.Path | None:
+    here = (start or pathlib.Path.cwd()).resolve()
+    for d in [here, *here.parents]:
+        if (d / RESULTS_DIR).is_dir():
+            return d / RESULTS_DIR
+    return None
+
+
+def require_root() -> pathlib.Path:
+    root = find_root()
+    if root is None:
+        print(f"no {RESULTS_DIR}/ here or above. `results init` makes one.")
+        sys.exit(2)
+    return root
+
+
+def ledger_path(root: pathlib.Path) -> pathlib.Path:
+    return root / ledger.LEDGER
+
+
+def cmd_init(a) -> int:
+    d = pathlib.Path.cwd() / RESULTS_DIR
+    if d.exists():
+        print(f"{d} already exists.")
+        return 1
+    d.mkdir()
+    lp = d / ledger.LEDGER
+    lp.touch()
+    ledger.append_event(lp, {"event": "init"})
+    print(f"created {RESULTS_DIR}/")
+    print(f"  {ledger.LEDGER}   append-only event log")
+    print("\nseal your inputs before running: `results seal prereg.md script.py data.csv`")
+    return 0
+
+
+def cmd_seal(a) -> int:
+    root = require_root()
+    lp = ledger_path(root)
+    sealed = []
+    for name in a.files:
+        p = pathlib.Path(name).resolve()
+        if not p.is_file():
+            print(f"not a file: {name}")
+            return 1
+        digest = ledger.sha256_of_file(p)
+        sealed.append({"path": os.path.relpath(p), "sha256": digest})
+    ev = ledger.append_event(lp, {
+        "event": "seal",
+        "role": a.role,
+        "files": sealed,
+    })
+    print(f"sealed {len(sealed)} file(s) as {a.role}")
+    for s in sealed:
+        print(f"  {s['sha256'][:16]}…  {s['path']}")
+    return 0
+
+
+def cmd_access(a) -> int:
+    root = require_root()
+    lp = ledger_path(root)
+    if a.level not in ACCESS_LEVELS:
+        print(f"level must be one of: {', '.join(ACCESS_LEVELS)}")
+        return 1
+    ev = ledger.append_event(lp, {
+        "event": "access",
+        "level": a.level,
+        "note": a.note,
+    })
+    print(f"recorded: {a.level} — {a.note}")
+    if a.level == "outcomes seen":
+        print("\nany analysis registered after this is retrospective, not confirmatory.")
+    return 0
+
+
+def cmd_run(a) -> int:
+    root = require_root()
+    lp = ledger_path(root)
+    existing = ledger.read_ledger(lp)
+    existing_ids = {e["run_id"] for e in existing if e.get("event") == "run"}
+    if a.run_id in existing_ids:
+        print(f"warning: run id '{a.run_id}' already exists in the ledger.")
+        print("the new run will be recorded alongside the old one.")
+    outputs = []
+    for name in a.files:
+        p = pathlib.Path(name).resolve()
+        if not p.is_file():
+            print(f"not a file: {name}")
+            return 1
+        digest = ledger.sha256_of_file(p)
+        outputs.append({"path": os.path.relpath(p), "sha256": digest})
+    ev = ledger.append_event(lp, {
+        "event": "run",
+        "run_id": a.run_id,
+        "outputs": outputs,
+        "note": a.note or "",
+    })
+    print(f"run {a.run_id}: {len(outputs)} output(s)")
+    for o in outputs:
+        print(f"  {o['sha256'][:16]}…  {o['path']}")
+    return 0
+
+
+def cmd_claim(a) -> int:
+    root = require_root()
+    lp = ledger_path(root)
+
+    events = ledger.read_ledger(lp)
+    run_ids = {e["run_id"] for e in events if e.get("event") == "run"}
+    if a.run_id not in run_ids:
+        print(f"no run with id '{a.run_id}' in the ledger.")
+        print(f"known runs: {', '.join(sorted(run_ids)) or '(none)'}")
+        return 1
+
+    ev = ledger.append_event(lp, {
+        "event": "claim",
+        "claim": a.text,
+        "run_id": a.run_id,
+        "confirmatory": a.confirmatory,
+        "location": a.location or "",
+    })
+    status = "confirmatory" if a.confirmatory else "exploratory"
+    print(f"claim ({status}): {a.text[:72]}")
+    print(f"  backed by run: {a.run_id}")
+    if a.location:
+        print(f"  appears in: {a.location}")
+    return 0
+
+
+def cmd_verify(a) -> int:
+    root = require_root()
+    lp = ledger_path(root)
+
+    ok, problems = ledger.verify_chain(lp)
+    if not ok:
+        print("CHAIN BROKEN")
+        for p in problems:
+            print(f"  {p}")
+        return 1
+
+    events = ledger.read_ledger(lp)
+    print(f"chain intact: {len(events)} events\n")
+
+    counts = {}
+    for e in events:
+        t = e.get("event", "?")
+        counts[t] = counts.get(t, 0) + 1
+    for t, n in sorted(counts.items()):
+        print(f"  {t:<12}{n:>5}")
+
+    drift = 0
+    if a.files:
+        print("\nfile hashes:")
+        file_hashes = {}
+        for e in events:
+            for f in e.get("files", []) + e.get("outputs", []):
+                file_hashes[f["path"]] = f["sha256"]
+        for path, expected in sorted(file_hashes.items()):
+            p = pathlib.Path(path)
+            if not p.exists():
+                print(f"  MISSING    {path}")
+                drift += 1
+            else:
+                actual = ledger.sha256_of_file(p)
+                if actual == expected:
+                    print(f"  ok         {path}")
+                else:
+                    print(f"  CHANGED    {path}")
+                    print(f"    sealed   {expected[:16]}…")
+                    print(f"    now      {actual[:16]}…")
+                    drift += 1
+        if drift:
+            print(f"\n{drift} file(s) changed or missing since they were recorded.")
+            return 1
+
+    access_events = [e for e in events if e.get("event") == "access"]
+    if access_events:
+        print("\ndata access timeline:")
+        for e in access_events:
+            print(f"  {e['timestamp'][:19]}  {e['level']:<20}  {e.get('note', '')}")
+
+    claims = [e for e in events if e.get("event") == "claim"]
+    if claims:
+        unlinked = []
+        for c in claims:
+            run_events = [e for e in events
+                          if e.get("event") == "run" and e.get("run_id") == c.get("run_id")]
+            if not run_events:
+                unlinked.append(c)
+        if unlinked:
+            print(f"\n{len(unlinked)} claim(s) reference missing runs:")
+            for c in unlinked:
+                print(f"  {c['claim'][:60]}  (run: {c.get('run_id')})")
+
+    print()
+    if ok and not (a.files and drift):
+        print("all checks passed.")
+    return 0
+
+
+ACCESS_LEVELS = [
+    "nothing seen",
+    "metadata only",
+    "structure seen",
+    "outcomes seen",
+]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="results", description=__doc__.split("\n")[0])
+    sub = ap.add_subparsers(dest="cmd")
+
+    sub.add_parser("init", help="start tracking results here")
+
+    s = sub.add_parser("seal", help="hash inputs before a run")
+    s.add_argument("files", nargs="+")
+    s.add_argument("--role", default="input",
+                   help="what these files are: input, prereg, script, data")
+    s.set_defaults(fn=cmd_seal)
+
+    ac = sub.add_parser("access", help="record a data-access event")
+    ac.add_argument("note", help="what was accessed and why")
+    ac.add_argument("--level", default="metadata only",
+                    help=f"one of: {', '.join(ACCESS_LEVELS)}")
+    ac.set_defaults(fn=cmd_access)
+
+    r = sub.add_parser("run", help="record outputs after a run")
+    r.add_argument("files", nargs="+")
+    r.add_argument("--run-id", required=True, help="a name for this run")
+    r.add_argument("--note", help="what this run computed")
+    r.set_defaults(fn=cmd_run)
+
+    cl = sub.add_parser("claim", help="bind a manuscript claim to a run")
+    cl.add_argument("text", help="the claim, as it appears in the manuscript")
+    cl.add_argument("--run-id", required=True, help="which run backs this claim")
+    cl.add_argument("--confirmatory", action="store_true",
+                    help="mark as confirmatory (default: exploratory)")
+    cl.add_argument("--location", help="where in the manuscript: Table 2, Section 4.1, etc.")
+    cl.set_defaults(fn=cmd_claim)
+
+    v = sub.add_parser("verify", help="check the ledger and every hash it names")
+    v.add_argument("--files", action="store_true",
+                   help="also check that sealed/output files still match their hashes")
+    v.set_defaults(fn=cmd_verify)
+
+    a = ap.parse_args()
+    if not a.cmd:
+        ap.print_help()
+        return 0
+    if a.cmd == "init":
+        return cmd_init(a)
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

results_cli-0.1.0/src/results/ledger.py

@@ -0,0 +1,78 @@
+"""Append-only JSONL ledger: every event is one line, hash-chained to the previous."""
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+import pathlib
+
+
+LEDGER = "ledger.jsonl"
+
+
+def sha256_of_file(path: pathlib.Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 16), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def sha256_of_str(s: str) -> str:
+    return hashlib.sha256(s.encode()).hexdigest()
+
+
+def now_iso() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+def last_hash(ledger: pathlib.Path) -> str:
+    """The hash of the last line as stored, or a zero hash if the ledger is empty."""
+    if not ledger.exists() or ledger.stat().st_size == 0:
+        return "0" * 64
+    with open(ledger, "rb") as f:
+        last = b""
+        for line in f:
+            if line.strip():
+                last = line
+    return sha256_of_str(last.decode().strip())
+
+
+def append_event(ledger: pathlib.Path, event: dict) -> dict:
+    """Write one event to the ledger. Returns the event with chain fields added."""
+    event["timestamp"] = now_iso()
+    event["prev_hash"] = last_hash(ledger)
+    line = json.dumps(event, separators=(",", ":"), sort_keys=True)
+    with open(ledger, "a") as f:
+        f.write(line + "\n")
+    return event
+
+
+def read_ledger(ledger: pathlib.Path) -> list[dict]:
+    if not ledger.exists():
+        return []
+    events = []
+    for line in ledger.read_text().splitlines():
+        line = line.strip()
+        if line:
+            events.append(json.loads(line))
+    return events
+
+
+def verify_chain(ledger: pathlib.Path) -> tuple[bool, list[str]]:
+    """Check that every line's prev_hash matches the hash of the previous line as stored."""
+    if not ledger.exists():
+        return True, []
+    lines = [ln.strip() for ln in ledger.read_text().splitlines() if ln.strip()]
+    if not lines:
+        return True, []
+    problems = []
+    prev = "0" * 64
+    for i, raw in enumerate(lines):
+        ev = json.loads(raw)
+        if ev.get("prev_hash") != prev:
+            problems.append(
+                f"line {i + 1}: prev_hash mismatch — expected {prev[:16]}…, "
+                f"got {ev.get('prev_hash', '???')[:16]}…")
+        prev = sha256_of_str(raw)
+    return len(problems) == 0, problems

results_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,133 @@
+"""Tests for the results CLI commands."""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from results import ledger
+
+
+def run_cli(*args, cwd=None):
+    return subprocess.run(
+        [sys.executable, "-m", "results.cli", *args],
+        cwd=cwd, capture_output=True, text=True,
+    )
+
+
+def test_init_creates_results_dir(tmp_path):
+    r = run_cli("init", cwd=tmp_path)
+    assert r.returncode == 0
+    assert (tmp_path / ".results" / "ledger.jsonl").exists()
+    events = ledger.read_ledger(tmp_path / ".results" / "ledger.jsonl")
+    assert len(events) == 1
+    assert events[0]["event"] == "init"
+
+
+def test_init_twice_fails(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    r = run_cli("init", cwd=tmp_path)
+    assert r.returncode == 1
+
+
+def test_seal_records_file_hashes(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "script.py").write_text("print('hello')\n")
+    (tmp_path / "data.csv").write_text("a,b\n1,2\n")
+    r = run_cli("seal", "script.py", "data.csv", "--role", "input", cwd=tmp_path)
+    assert r.returncode == 0
+    events = ledger.read_ledger(tmp_path / ".results" / "ledger.jsonl")
+    seal = [e for e in events if e["event"] == "seal"]
+    assert len(seal) == 1
+    assert len(seal[0]["files"]) == 2
+
+
+def test_access_records_event(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    r = run_cli("access", "read zenodo metadata", "--level", "metadata only", cwd=tmp_path)
+    assert r.returncode == 0
+    events = ledger.read_ledger(tmp_path / ".results" / "ledger.jsonl")
+    access = [e for e in events if e["event"] == "access"]
+    assert len(access) == 1
+    assert access[0]["level"] == "metadata only"
+
+
+def test_access_rejects_invalid_level(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    r = run_cli("access", "whatever", "--level", "banana", cwd=tmp_path)
+    assert r.returncode == 1
+    assert "level must be" in r.stdout
+
+
+def test_run_records_outputs(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "results.json").write_text('{"icc": 0.42}\n')
+    r = run_cli("run", "results.json", "--run-id", "run_001", cwd=tmp_path)
+    assert r.returncode == 0
+    events = ledger.read_ledger(tmp_path / ".results" / "ledger.jsonl")
+    runs = [e for e in events if e["event"] == "run"]
+    assert len(runs) == 1
+    assert runs[0]["run_id"] == "run_001"
+
+
+def test_run_warns_on_duplicate_id(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "out1.json").write_text('{"a": 1}\n')
+    (tmp_path / "out2.json").write_text('{"a": 2}\n')
+    run_cli("run", "out1.json", "--run-id", "exp_001", cwd=tmp_path)
+    r = run_cli("run", "out2.json", "--run-id", "exp_001", cwd=tmp_path)
+    assert r.returncode == 0
+    assert "already exists" in r.stdout
+
+
+def test_claim_requires_existing_run(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    r = run_cli("claim", "ICC = 0.42", "--run-id", "run_001", cwd=tmp_path)
+    assert r.returncode == 1
+    assert "no run" in r.stdout
+
+
+def test_claim_succeeds_after_run(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "results.json").write_text('{"icc": 0.42}\n')
+    run_cli("run", "results.json", "--run-id", "run_001", cwd=tmp_path)
+    r = run_cli("claim", "ICC = 0.42", "--run-id", "run_001",
+                "--confirmatory", "--location", "Table 2", cwd=tmp_path)
+    assert r.returncode == 0
+    events = ledger.read_ledger(tmp_path / ".results" / "ledger.jsonl")
+    claims = [e for e in events if e["event"] == "claim"]
+    assert len(claims) == 1
+    assert claims[0]["confirmatory"] is True
+    assert claims[0]["location"] == "Table 2"
+
+
+def test_verify_passes_on_clean_ledger(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    r = run_cli("verify", cwd=tmp_path)
+    assert r.returncode == 0
+    assert "chain intact" in r.stdout
+
+
+def test_verify_files_catches_drift(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "data.csv").write_text("a,b\n1,2\n")
+    run_cli("seal", "data.csv", cwd=tmp_path)
+    (tmp_path / "data.csv").write_text("a,b\n1,2\n3,4\n")
+    r = run_cli("verify", "--files", cwd=tmp_path)
+    assert r.returncode == 1
+    assert "CHANGED" in r.stdout
+
+
+def test_full_workflow(tmp_path):
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "prereg.md").write_text("# My prereg\n")
+    (tmp_path / "script.py").write_text("import json\n")
+    run_cli("seal", "prereg.md", "script.py", "--role", "prereg", cwd=tmp_path)
+    run_cli("access", "downloaded zenodo metadata", "--level", "metadata only", cwd=tmp_path)
+    (tmp_path / "out.json").write_text('{"result": 42}\n')
+    run_cli("run", "out.json", "--run-id", "exp_001", "--note", "first analysis", cwd=tmp_path)
+    run_cli("claim", "the answer is 42", "--run-id", "exp_001",
+            "--confirmatory", "--location", "Section 3", cwd=tmp_path)
+    r = run_cli("verify", "--files", cwd=tmp_path)
+    assert r.returncode == 0
+    assert "chain intact" in r.stdout
+    assert "all checks passed" in r.stdout

results_cli-0.1.0/tests/test_ledger.py

@@ -0,0 +1,89 @@
+"""Tests for the append-only hash-chained ledger."""
+from __future__ import annotations
+
+import json
+
+from results import ledger
+
+
+def test_empty_ledger_has_zero_hash(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    assert ledger.last_hash(lp) == "0" * 64
+
+
+def test_append_and_read_round_trips(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    ledger.append_event(lp, {"event": "init"})
+    ledger.append_event(lp, {"event": "seal", "files": [{"path": "x.py", "sha256": "abc"}]})
+    events = ledger.read_ledger(lp)
+    assert len(events) == 2
+    assert events[0]["event"] == "init"
+    assert events[1]["event"] == "seal"
+
+
+def test_chain_verification_passes_on_clean_ledger(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    for i in range(5):
+        ledger.append_event(lp, {"event": "test", "i": i})
+    ok, problems = ledger.verify_chain(lp)
+    assert ok
+    assert problems == []
+
+
+def test_chain_verification_catches_tampering(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    ledger.append_event(lp, {"event": "init"})
+    ledger.append_event(lp, {"event": "seal"})
+    ledger.append_event(lp, {"event": "run"})
+
+    lines = lp.read_text().splitlines()
+    tampered = json.loads(lines[1])
+    tampered["event"] = "TAMPERED"
+    lines[1] = json.dumps(tampered, separators=(",", ":"), sort_keys=True)
+    lp.write_text("\n".join(lines) + "\n")
+
+    ok, problems = ledger.verify_chain(lp)
+    assert not ok
+    assert len(problems) >= 1
+
+
+def test_sha256_of_file_is_deterministic(tmp_path):
+    f = tmp_path / "data.txt"
+    f.write_text("hello world\n")
+    h1 = ledger.sha256_of_file(f)
+    h2 = ledger.sha256_of_file(f)
+    assert h1 == h2
+    assert len(h1) == 64
+
+
+def test_first_event_prev_hash_is_zero(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    ev = ledger.append_event(lp, {"event": "init"})
+    assert ev["prev_hash"] == "0" * 64
+
+
+def test_second_event_prev_hash_chains_to_first(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    ledger.append_event(lp, {"event": "first"})
+    ev2 = ledger.append_event(lp, {"event": "second"})
+    first_line = lp.read_text().splitlines()[0].strip()
+    assert ev2["prev_hash"] == ledger.sha256_of_str(first_line)
+
+
+def test_verify_catches_inserted_line(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    ledger.append_event(lp, {"event": "first"})
+    ledger.append_event(lp, {"event": "second"})
+    lines = lp.read_text().splitlines()
+    injected = '{"event":"injected","prev_hash":"fake","timestamp":"2026-01-01T00:00:00+00:00"}'
+    lines.insert(1, injected)
+    lp.write_text("\n".join(lines) + "\n")
+    ok, problems = ledger.verify_chain(lp)
+    assert not ok