results-cli 0.1.0__py3-none-any.whl

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.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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+results/__init__.py,sha256=quPt6si4TzPx3vsWIdqxTKZy9hnQYlWqEb5Q66t_3No,122
+results/cli.py,sha256=H8cGnttpljtrHmti01dcnd-Ct4DzR3TwDfXr3MovVOA,8919
+results/ledger.py,sha256=apzy1v6NGOp5Uy5hW51xBk_6VtIEoaJ-V-rwJU9YD2M,2366
+results_cli-0.1.0.dist-info/METADATA,sha256=lJBuE-UMNqpAvIxMv1xxQjxWBUUkCMuuMW0lVPpZkBw,3135
+results_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+results_cli-0.1.0.dist-info/entry_points.txt,sha256=IKJM5z5zKmfR1JLm5wze8zXDYnbOrpp1SKg8JQ3Ifsk,45
+results_cli-0.1.0.dist-info/licenses/LICENSE,sha256=-C2xzeJxZAl5nBr-WFxtiYY3521mIQjxI0-_5GEpFCQ,1069
+results_cli-0.1.0.dist-info/RECORD,,

results_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

results_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+results = results.cli:main

results_cli-0.1.0.dist-info/licenses/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.