results-cli 0.4.2__tar.gz → 0.5.0__tar.gz

{results_cli-0.4.2 → results_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: results-cli
-Version: 0.4.2
+Version: 0.5.0
 Summary: Seal a run, record what it produced, and verify the chain
 Project-URL: Changelog, https://github.com/elliottower/reproducible-science/blob/main/CHANGELOG.md
 Project-URL: Homepage, https://github.com/elliottower/reproducible-science
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
-Requires-Dist: provenance-core<0.5,>=0.4
+Requires-Dist: provenance-core[anchor]<0.6,>=0.5
 Description-Content-Type: text/markdown
 
 # results
@@ -77,6 +77,7 @@ all checks passed.
 | `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 |
+| `results timestamp` | Date the ledger's head outside the repository, and check earlier dates |
 
 ## The chain
 
@@ -119,6 +120,31 @@ Append-only JSONL in `.results/ledger.jsonl`. Each line is hash-chained to the p
 or inserting a line breaks the chain. `git diff` shows what changed; `results verify` checks
 whether it should have.
 
+`results init` writes a `.results/.gitignore` that ignores only the lock files, so the ledger and
+its anchor are committed with the project. A ledger on one disk is a record nobody else can
+check. What is committed is public with the repository, so a run's `note` is written as a commit
+message would be.
+
+## Timestamp
+
+The chain catches a line edited by hand. It cannot catch the ledger and its anchor rewritten
+together, because whoever can write one can write the other. `results timestamp` sends the head
+to the [OpenTimestamps](https://opentimestamps.org) calendars, which commit it into a Bitcoin
+block within a few hours, and keeps the proof under `.results/timestamps/`. Each line names the
+hash of the one before it, so a proof of the head dates every earlier event too.
+
+```text
+events 1–153 existed by Bitcoin block 915004, 2026-10-03 16:12 UTC
+```
+
+`results verify` reads the proofs with no network. A proof whose head no longer matches the
+chain at its length means the ledger was rewritten after it was stamped:
+
+```text
+TIMESTAMP CONTRADICTS THE CHAIN — the ledger was rewritten after it was stamped
+  000153-3f9c2a1b7d4e5f60.ots dates event 153 as 3f9c2a1b7d4e5f60…, and the ledger's event 153 is 81d0…
+```
+
 ## Claude Code
 
 `plugin/` is a Claude Code plugin. Three surfaces, because each catches a different failure:

{results_cli-0.4.2 → results_cli-0.5.0}/README.md

@@ -56,6 +56,7 @@ all checks passed.
 | `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 |
+| `results timestamp` | Date the ledger's head outside the repository, and check earlier dates |
 
 ## The chain
 
@@ -98,6 +99,31 @@ Append-only JSONL in `.results/ledger.jsonl`. Each line is hash-chained to the p
 or inserting a line breaks the chain. `git diff` shows what changed; `results verify` checks
 whether it should have.
 
+`results init` writes a `.results/.gitignore` that ignores only the lock files, so the ledger and
+its anchor are committed with the project. A ledger on one disk is a record nobody else can
+check. What is committed is public with the repository, so a run's `note` is written as a commit
+message would be.
+
+## Timestamp
+
+The chain catches a line edited by hand. It cannot catch the ledger and its anchor rewritten
+together, because whoever can write one can write the other. `results timestamp` sends the head
+to the [OpenTimestamps](https://opentimestamps.org) calendars, which commit it into a Bitcoin
+block within a few hours, and keeps the proof under `.results/timestamps/`. Each line names the
+hash of the one before it, so a proof of the head dates every earlier event too.
+
+```text
+events 1–153 existed by Bitcoin block 915004, 2026-10-03 16:12 UTC
+```
+
+`results verify` reads the proofs with no network. A proof whose head no longer matches the
+chain at its length means the ledger was rewritten after it was stamped:
+
+```text
+TIMESTAMP CONTRADICTS THE CHAIN — the ledger was rewritten after it was stamped
+  000153-3f9c2a1b7d4e5f60.ots dates event 153 as 3f9c2a1b7d4e5f60…, and the ledger's event 153 is 81d0…
+```
+
 ## Claude Code
 
 `plugin/` is a Claude Code plugin. Three surfaces, because each catches a different failure:

{results_cli-0.4.2 → results_cli-0.5.0}/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "results",
   "description": "Seal a run's inputs, record what it produced, bind every number in a manuscript to the run behind it as it is written, and verify the chain",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "author": {
     "name": "Elliot Tower",
     "email": "elliot@elliottower.ai"

{results_cli-0.4.2 → results_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "results-cli"
-version = "0.4.2"
+version = "0.5.0"
 description = "Seal a run, record what it produced, and verify the chain"
 readme = "README.md"
 keywords = [ "open science", "provenance", "reproducibility", "results" ]
@@ -18,7 +18,7 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-dependencies = [ "provenance-core>=0.4,<0.5" ]
+dependencies = [ "provenance-core[anchor]>=0.5,<0.6" ]
 urls.Changelog = "https://github.com/elliottower/reproducible-science/blob/main/CHANGELOG.md"
 urls.Homepage = "https://github.com/elliottower/reproducible-science"
 urls.Issues = "https://github.com/elliottower/reproducible-science/issues"

{results_cli-0.4.2 → results_cli-0.5.0}/src/results/audit.py

@@ -15,9 +15,9 @@ from __future__ import annotations
 
 import pathlib
 
-from provenance_core import sha256_of_tree, try_run
+from provenance_core import anchor, sha256_of_tree, try_run
 
-from results import ledger, manuscript
+from results import ledger, manuscript, stamps
 from results.paths import ledger_path, require_root
 from results.timeline import first_outcomes_seen, first_run_timestamp, precedes
 
@@ -132,6 +132,37 @@ def reanchor() -> int:
     return 0
 
 
+def timestamp() -> int:
+    """Stamp the current head, complete every pending proof, and check the complete ones."""
+    root = require_root()
+    lp = ledger_path(root)
+    try:
+        made = stamps.stamp_head(lp)
+    except anchor.AnchorError as e:
+        print(f"not timestamped: {e}")
+        return 1
+    if made is not None:
+        print(f"stamped      {made.relative_to(root.parent)}")
+    try:
+        found = stamps.complete(lp)
+    except anchor.AnchorError as e:
+        print(f"TIMESTAMP    {e}")
+        return 1
+    dated = [(s, block) for s, block in found if block is not None]
+    if dated:
+        stamp, block = max(dated, key=lambda pair: pair[0].count)
+        print(
+            f"events 1–{stamp.count} existed by Bitcoin block {block.height}, "
+            f"{block.time:%Y-%m-%d %H:%M} UTC"
+        )
+    waiting = [s for s, block in found if block is None]
+    if waiting:
+        latest = max(waiting, key=lambda s: s.count)
+        print(f"events 1–{latest.count} pending; Bitcoin usually confirms within hours.")
+    print("Commit .results/timestamps/ with the ledger.")
+    return 0
+
+
 def verify(check_files: bool) -> int:
     root = require_root()
     lp = ledger_path(root)
@@ -166,6 +197,28 @@ def verify(check_files: bool) -> int:
     if state := in_history(lp):
         print(f"  the ledger {state}. A record is evidence once it is in history.\n")
 
+    reading = stamps.read(lp)
+    if reading.contradictions:
+        # The chain verifies against its own anchor and not against a proof held outside it, so
+        # the chain and the anchor were rewritten together after that proof was made.
+        print("TIMESTAMP CONTRADICTS THE CHAIN — the ledger was rewritten after it was stamped")
+        for problem in reading.contradictions:
+            print(f"  {problem}")
+        return 1
+    if reading.dated:
+        print(
+            f"  events 1–{reading.dated.count} dated by Bitcoin block "
+            f"{reading.dated.status.blocks[0]}. `results timestamp` checks the block."
+        )
+    if reading.pending and (not reading.dated or reading.pending.count > reading.dated.count):
+        print(
+            f"  events 1–{reading.pending.count} stamped, pending at "
+            f"{len(reading.pending.status.pending)} calendars."
+        )
+    if not reading.dated and not reading.pending:
+        print("  no outside timestamp. `results timestamp` makes one.")
+    print()
+
     counts = {}
     for e in events:
         t = e.get("event", "?")

{results_cli-0.4.2 → results_cli-0.5.0}/src/results/cli.py

@@ -8,6 +8,7 @@ results claim <text>      bind a manuscript claim to a run's output
 results coverage <paper>  how many of a manuscript's numbers are bound to a run
 results verify            check the ledger chain and every hash it names
 results reanchor          record the ledger's current length as authoritative
+results timestamp         date the ledger's head outside the repository, and check earlier dates
 
 This module parses arguments. Each handler unpacks the namespace argparse built and calls into
 `results.record` or `results.audit`, where the command's logic and its refusals live.
@@ -76,6 +77,10 @@ def cmd_verify(a) -> int:
     return audit.verify(a.files)
 
 
+def cmd_timestamp(a) -> int:
+    return audit.timestamp()
+
+
 def main(argv: list[str] | None = None) -> int:
     code = _main(argv)
     # After the work, never before it, and never instead of it: the note is about how this
@@ -165,6 +170,11 @@ def _main(argv: list[str] | None = None) -> int:
     ra = sub.add_parser("reanchor", help="record the ledger's current length as authoritative")
     ra.set_defaults(fn=cmd_reanchor)
 
+    ts = sub.add_parser(
+        "timestamp", help="date the ledger's head outside the repository, and check earlier dates"
+    )
+    ts.set_defaults(fn=cmd_timestamp)
+
     a = ap.parse_args(argv)
     if not a.cmd:
         ap.print_help()

{results_cli-0.4.2 → results_cli-0.5.0}/src/results/ledger.py

@@ -3,9 +3,9 @@
 **Threat model.** The chain detects accidental damage and casual editing: a crashed write, a
 bad sync, a file opened in an editor, a line changed by hand. It does not defend against an
 adversary who can write to the directory, because such an adversary can rewrite the anchor as
-readily as the ledger. Defending against that needs an external anchor -- a git note, an
-OSF registration, a timestamp authority -- and the head digest here is what you would publish
-to one.
+readily as the ledger. Defending against that needs an external anchor, and the head digest here
+is what is published to one: `results timestamp` sends it to the OpenTimestamps calendars, and
+`results.stamps` reads the proofs back against the chain.
 
 Saying this plainly matters more than the mechanism. A hash chain is often read as proof of
 tamper-resistance when it delivers tamper-*evidence*, and only against a party who does not
@@ -25,13 +25,12 @@ import enum
 import json
 import os
 import pathlib
-import tempfile
 
 # Re-exported under the names this module has always used: `ledger.sha256_of_file` and
 # `ledger.ZERO` are its surface, and callers should not have to know where they moved.
 from provenance_core import ZERO as ZERO
+from provenance_core import atomic_write, exclusive_lock, sha256_of_text, shared_lock
 from provenance_core import sha256_of_file as sha256_of_file
-from provenance_core import sha256_of_text
 
 LEDGER = "ledger.jsonl"
 ANCHOR = "ledger.head"
@@ -130,6 +129,11 @@ def last_hash(ledger: pathlib.Path) -> str:
     return sha256_of_str(lines[-1]) if lines else ZERO
 
 
+def line_hashes(ledger: pathlib.Path) -> list[str]:
+    """The digest of each line as stored: entry `n` is the head the anchor records at `n + 1`."""
+    return [sha256_of_str(line) for line in _lines(ledger)] if ledger.exists() else []
+
+
 def read_ledger(ledger: pathlib.Path) -> list[dict]:
     """Every event, or raise `ChainError` naming the line that is not one."""
     if not ledger.exists():
@@ -168,29 +172,29 @@ def write_anchor(ledger: pathlib.Path, count: int, head: str) -> dict:
     it, which would report a complete ledger as truncated.
     """
     anchor = {"canon_version": CANON_VERSION, "count": count, "head": head, "updated": now_iso()}
-    _atomic_write(anchor_path(ledger), json.dumps(anchor, indent=2, sort_keys=True) + "\n")
+    atomic_write(anchor_path(ledger), json.dumps(anchor, indent=2, sort_keys=True) + "\n")
     return anchor
 
 
-def _atomic_write(path: pathlib.Path, text: str) -> None:
-    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=path.name, suffix=".tmp")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            f.write(text)
-            f.flush()
-            os.fsync(f.fileno())
-        os.replace(tmp, path)
-    except BaseException:
-        pathlib.Path(tmp).unlink(missing_ok=True)
-        raise
-
-
 # --------------------------------------------------------------------------------- writing
 
 
 def append_event(ledger: pathlib.Path, event: dict) -> dict:
     """Write one event and advance the anchor. Returns a new event; the argument is not
-    mutated, so the object a caller holds cannot drift from the line on disk."""
+    mutated, so the object a caller holds cannot drift from the line on disk.
+
+    An event's position and `prev_hash` come from the lines already on disk, so two callers that
+    read the same tail write two lines claiming one position. The chain then reports `edited`,
+    and `reanchor` refuses an edited chain, which leaves no way back: the damage is permanent and
+    a pipeline running two skills at once is enough to cause it. The lock covers the read as well
+    as the write, because reading early is what makes the second line wrong.
+    """
+    with exclusive_lock(ledger):
+        return _append_locked(ledger, event)
+
+
+def _append_locked(ledger: pathlib.Path, event: dict) -> dict:
+    """The append itself. Assumes the caller holds the lock for `ledger`."""
     lines = _lines(ledger) if ledger.exists() else []
 
     # The anchor is the only witness to the last line, and appending overwrites it. An edited
@@ -233,7 +237,18 @@ def verify(ledger: pathlib.Path) -> tuple[ChainStatus, list[str]]:
 
     Reports the first structural fault as the status, because a chain that was edited and then
     truncated is edited: the earlier fault explains the later one.
+
+    Read under a shared lock. An append writes its line and then its anchor, so a reader arriving
+    between the two counted one more event than the anchor records and reported `extended` -- true
+    of the bytes, wrong about the cause, and gone on a re-run. A verify that fails only while
+    something else is writing teaches people to re-run it until it passes.
     """
+    with shared_lock(ledger):
+        return _verify_locked(ledger)
+
+
+def _verify_locked(ledger: pathlib.Path) -> tuple[ChainStatus, list[str]]:
+    """The verification itself. Assumes the caller holds a lock for `ledger`."""
     if not ledger.exists():
         return ChainStatus.ABSENT, [f"{ledger} does not exist"]
 
@@ -314,6 +329,10 @@ def reanchor(ledger: pathlib.Path) -> dict:
     For a ledger written before anchoring, and for repairing an under-count after a crash.
     It cannot recover a truncated ledger: re-anchoring a shortened chain records the shortened
     chain, which is why it is a separate deliberate call and not something verification does.
+
+    Taken under the lock, so it cannot record a length that an append is in the middle of
+    changing and leave the anchor describing neither state.
     """
-    lines = _lines(ledger) if ledger.exists() else []
-    return write_anchor(ledger, len(lines), sha256_of_str(lines[-1]) if lines else ZERO)
+    with exclusive_lock(ledger):
+        lines = _lines(ledger) if ledger.exists() else []
+        return write_anchor(ledger, len(lines), sha256_of_str(lines[-1]) if lines else ZERO)

{results_cli-0.4.2 → results_cli-0.5.0}/src/results/record.py

@@ -25,6 +25,20 @@ ACCESS_LEVELS = [
 ]
 
 
+#: Written into `.results/` so the ledger is tracked without anyone editing the project's own
+#: ignore file. The ledger and its anchor are the record a claim appeals to, and one that exists
+#: on a single disk cannot be appealed to by anyone else; only the lock sidecars are ignored.
+GITIGNORE = """\
+# Commit ledger.jsonl and ledger.head: a record is evidence once it is in history.
+# Everything in the ledger becomes public with the repository, notes included.
+
+# Lock sidecars. They hold nothing; the kernel releases a lock when its holder exits.
+*.lock
+*.provenance-lock
+*.provenance-tmp
+"""
+
+
 def init() -> int:
     d = pathlib.Path.cwd() / RESULTS_DIR
     if d.exists():
@@ -34,8 +48,10 @@ def init() -> int:
     lp = d / ledger.LEDGER
     lp.touch()
     ledger.append_event(lp, {"event": "init"})
+    (d / ".gitignore").write_text(GITIGNORE)
     print(f"created {RESULTS_DIR}/")
     print(f"  {ledger.LEDGER}   append-only event log")
+    print("  .gitignore     ignores the lock files only, so the ledger is committed")
     print("\nseal your inputs before running: `results seal prereg.md script.py data.csv`")
     return 0
 

results_cli-0.5.0/src/results/stamps.py

@@ -0,0 +1,125 @@
+"""Outside timestamps of the ledger's head, and what they prove about the chain.
+
+The anchor file records how long the chain is and where it ends, and whoever can write the ledger
+can write the anchor. A timestamp of the head is held by the OpenTimestamps calendars and then by
+a Bitcoin block, so it says that a ledger of exactly this length and this last line existed by
+the block's date. Every earlier line is covered too, because each line names the hash of the one
+before it.
+
+Proofs live under `.results/timestamps/`, one per stamped head, named by the length and the head
+so a reader can see what each covers without opening it: `000153-3f9c2a…ots` covers events 1 to
+153. They are only ever added. A proof whose head does not match the chain at its length means the
+chain was rewritten after it was stamped, which is the one thing a stamp exists to catch.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+from dataclasses import dataclass
+
+from provenance_core import anchor, atomic_write_bytes
+
+from results import ledger
+
+STAMPS = "timestamps"
+NAME = re.compile(r"^(\d{6})-([0-9a-f]{16})\.ots$")
+
+
+@dataclass(frozen=True)
+class Stamp:
+    path: pathlib.Path
+    count: int
+    head: str
+    status: anchor.Status
+
+
+@dataclass(frozen=True)
+class Reading:
+    """What the proofs under `.results/timestamps/` say about this chain, read with no network."""
+
+    dated: Stamp | None
+    """The longest stretch of the chain a complete proof covers."""
+    pending: Stamp | None
+    """The longest stretch a proof covers that Bitcoin has not confirmed yet."""
+    contradictions: list[str]
+
+
+def stamps_dir(lp: pathlib.Path) -> pathlib.Path:
+    return lp.parent / STAMPS
+
+
+def _proofs(lp: pathlib.Path) -> list[tuple[pathlib.Path, int, str]]:
+    found = []
+    for path in sorted(stamps_dir(lp).glob("*.ots")):
+        m = NAME.match(path.name)
+        if m:
+            found.append((path, int(m.group(1)), m.group(2)))
+    return found
+
+
+def read(lp: pathlib.Path) -> Reading:
+    hashes = ledger.line_hashes(lp)
+    dated = pending = None
+    contradictions = []
+    for path, count, short in _proofs(lp):
+        if count > len(hashes):
+            contradictions.append(
+                f"{path.name} dates a chain of {count} events, and the ledger holds {len(hashes)}"
+            )
+            continue
+        head = hashes[count - 1]
+        if not head.startswith(short):
+            contradictions.append(
+                f"{path.name} dates event {count} as {short}…, and the ledger's event {count} "
+                f"is {head[:16]}…"
+            )
+            continue
+        try:
+            found = Stamp(path, count, head, anchor.status(path.read_bytes(), head))
+        except anchor.AnchorError as e:
+            contradictions.append(f"{path.name}: {e}")
+            continue
+        if found.status.is_complete:
+            dated = found if dated is None or count > dated.count else dated
+        else:
+            pending = found if pending is None or count > pending.count else pending
+    return Reading(dated, pending, contradictions)
+
+
+def stamp_head(lp: pathlib.Path) -> pathlib.Path | None:
+    """Stamp the head the anchor records, or None where that head is already stamped.
+
+    Refused on a chain that does not verify: a stamp would date the damage.
+    """
+    status, problems = ledger.verify(lp)
+    if status is not ledger.ChainStatus.INTACT:
+        raise ledger.ChainError(
+            lp,
+            f"refusing to timestamp a chain reported as {status.value}: {'; '.join(problems)}",
+        )
+    recorded = ledger.read_anchor(lp) or {}
+    count, head = recorded["count"], recorded["head"]
+    path = stamps_dir(lp) / f"{count:06d}-{head[:16]}.ots"
+    if path.exists():
+        return None
+    path.parent.mkdir(exist_ok=True)
+    atomic_write_bytes(path, anchor.stamp(head))
+    return path
+
+
+def complete(lp: pathlib.Path) -> list[tuple[Stamp, anchor.Confirmation | None]]:
+    """Fetch the rest of every pending proof, and check every complete one against Bitcoin."""
+    hashes = ledger.line_hashes(lp)
+    out = []
+    for path, count, short in _proofs(lp):
+        if count > len(hashes) or not hashes[count - 1].startswith(short):
+            continue
+        head = hashes[count - 1]
+        data = anchor.upgrade(path.read_bytes(), head)
+        if data != path.read_bytes():
+            atomic_write_bytes(path, data)
+        found = anchor.status(data, head)
+        block = anchor.confirm(data, head) if found.is_complete else None
+        out.append((Stamp(path, count, head, found), block))
+    return out

{results_cli-0.4.2 → results_cli-0.5.0}/tests/test_cli.py

@@ -28,6 +28,28 @@ def test_init_creates_results_dir(tmp_path):
     assert events[0]["event"] == "init"
 
 
+def test_a_new_ledger_is_tracked_by_git_and_its_lock_files_are_not(tmp_path):
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True, env=clean_env())
+    run_cli("init", cwd=tmp_path)
+    (tmp_path / "script.py").write_text("print('hello')\n")
+    run_cli("seal", "script.py", cwd=tmp_path)
+    (tmp_path / ".results" / "ledger.jsonl.lock").touch()
+    (tmp_path / ".results" / "ledger.jsonl.provenance-lock").touch()
+
+    def ignored(name):
+        return (
+            subprocess.run(
+                ["git", "check-ignore", "-q", f".results/{name}"], cwd=tmp_path, env=clean_env()
+            ).returncode
+            == 0
+        )
+
+    assert not ignored("ledger.jsonl")
+    assert not ignored("ledger.head")
+    assert ignored("ledger.jsonl.lock")
+    assert ignored("ledger.jsonl.provenance-lock")
+
+
 def test_init_twice_fails(tmp_path):
     run_cli("init", cwd=tmp_path)
     r = run_cli("init", cwd=tmp_path)

results_cli-0.5.0/tests/test_concurrency.py

@@ -0,0 +1,148 @@
+"""Concurrent appends to one ledger.
+
+Two callers that read the same tail compute the same `seq` and the same `prev_hash`, so the chain
+takes two lines claiming one position. Verification reports `edited`, and `reanchor` refuses an
+edited chain, which leaves the ledger permanently unrepairable. An orchestrator running two
+analyses at once is enough to cause it, so these assert the chain survives contention rather than
+that the lock exists.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from results import ledger
+
+
+def _append_from_threads(lp, threads: int, per_thread: int) -> list[BaseException]:
+    failures: list[BaseException] = []
+    barrier = threading.Barrier(threads)
+
+    def worker(n: int) -> None:
+        barrier.wait(timeout=30)
+        for i in range(per_thread):
+            try:
+                ledger.append_event(lp, {"event": "run", "thread": n, "i": i})
+            except BaseException as e:
+                failures.append(e)
+
+    workers = [threading.Thread(target=worker, args=(n,)) for n in range(threads)]
+    for w in workers:
+        w.start()
+    for w in workers:
+        w.join(timeout=60)
+    return failures
+
+
+def test_concurrent_appends_leave_an_intact_chain(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    threads, per_thread = 16, 8
+
+    failures = _append_from_threads(lp, threads, per_thread)
+
+    assert failures == []
+    status, problems = ledger.verify(lp)
+    assert (status, problems) == (ledger.ChainStatus.INTACT, [])
+
+
+def test_concurrent_appends_lose_no_event(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    threads, per_thread = 16, 8
+
+    _append_from_threads(lp, threads, per_thread)
+
+    events = ledger.read_ledger(lp)
+    assert len(events) == threads * per_thread
+    assert [e["seq"] for e in events] == list(range(threads * per_thread))
+
+
+def test_every_concurrent_event_is_recorded_once(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    threads, per_thread = 16, 8
+
+    _append_from_threads(lp, threads, per_thread)
+
+    events = ledger.read_ledger(lp)
+    written = sorted((e["thread"], e["i"]) for e in events)
+    expected = sorted((n, i) for n in range(threads) for i in range(per_thread))
+    assert written == expected
+
+
+def test_the_anchor_matches_the_ledger_after_contention(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+
+    _append_from_threads(lp, 12, 6)
+
+    anchor = ledger.read_anchor(lp)
+    lines = lp.read_text(encoding="utf-8").splitlines()
+    assert anchor["count"] == len(lines)
+    assert anchor["head"] == ledger.sha256_of_str(lines[-1])
+
+
+def test_a_reanchor_racing_appends_leaves_the_chain_verifiable(tmp_path):
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    ledger.append_event(lp, {"event": "init"})
+    stop = threading.Event()
+
+    def reanchor_repeatedly() -> None:
+        while not stop.is_set():
+            ledger.reanchor(lp)
+
+    spinner = threading.Thread(target=reanchor_repeatedly, daemon=True)
+    spinner.start()
+    try:
+        _append_from_threads(lp, 8, 6)
+    finally:
+        stop.set()
+        spinner.join(timeout=10)
+
+    ledger.reanchor(lp)
+    status, problems = ledger.verify(lp)
+    assert (status, problems) == (ledger.ChainStatus.INTACT, [])
+
+
+APPEND_IN_CHILD = """
+import sys
+from pathlib import Path
+from results import ledger
+
+lp, n = Path(sys.argv[1]), int(sys.argv[2])
+for i in range(n):
+    ledger.append_event(lp, {"event": "run", "proc": sys.argv[3], "i": i})
+"""
+
+
+def test_separate_processes_appending_leave_an_intact_chain(tmp_path):
+    # The case this guards against is two processes, not two threads: an orchestrator running two
+    # skills, or a rerun started before the last one finished. `flock` is held per open file
+    # description, so a threaded test exercises the same exclusion -- but only a process test
+    # shows it holding across the interpreter boundary the real failure crosses.
+    import subprocess
+    import sys
+
+    lp = tmp_path / "ledger.jsonl"
+    lp.touch()
+    script = tmp_path / "append.py"
+    script.write_text(APPEND_IN_CHILD)
+    per_process, processes = 6, 6
+
+    running = [
+        subprocess.Popen(
+            [sys.executable, str(script), str(lp), str(per_process), f"p{n}"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        for n in range(processes)
+    ]
+    for proc in running:
+        _, err = proc.communicate(timeout=120)
+        assert proc.returncode == 0, err.decode()[-2000:]
+
+    status, problems = ledger.verify(lp)
+    assert (status, problems) == (ledger.ChainStatus.INTACT, [])
+    assert len(ledger.read_ledger(lp)) == per_process * processes

results_cli-0.5.0/tests/test_timestamp.py

@@ -0,0 +1,142 @@
+"""A stamped head catches what the anchor cannot: the ledger and its anchor rewritten together."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from opentimestamps.core.notary import BitcoinBlockHeaderAttestation, PendingAttestation
+from opentimestamps.core.op import OpSHA256
+from opentimestamps.core.timestamp import Timestamp
+from provenance_core import anchor
+from results import cli, ledger
+
+ALICE = "https://alice.btc.calendar.opentimestamps.org"
+BOB = "https://bob.btc.calendar.opentimestamps.org"
+
+
+class Calendars:
+    """Both calendars. Each accepts a commitment; `mine(height)` makes them complete it."""
+
+    def __init__(self):
+        self.height: int | None = None
+        self.roots: dict[int, str] = {}
+
+    def mine(self, height: int) -> None:
+        self.height = height
+
+    def __call__(self, url: str):
+        calendars = self
+
+        class One:
+            def __init__(self):
+                self.url = url
+
+            def submit(self, digest, timeout=None):
+                timestamp = Timestamp(digest)
+                timestamp.attestations.add(PendingAttestation(url))
+                return timestamp
+
+            def get_timestamp(self, commitment, timeout=None):
+                if calendars.height is None:
+                    raise anchor.CommitmentNotFoundError("not yet")
+                timestamp = Timestamp(commitment)
+                root = timestamp.ops.add(OpSHA256())
+                root.attestations.add(BitcoinBlockHeaderAttestation(calendars.height))
+                calendars.roots[calendars.height] = root.msg[::-1].hex()
+                return timestamp
+
+        return One()
+
+    def explorer(self, url: str) -> bytes:
+        if "/block-height/" in url:
+            return f"hash{url.rsplit('/', 1)[1]}".encode()
+        height = int(url.rsplit("hash", 1)[1])
+        return json.dumps({"merkle_root": self.roots[height], "timestamp": 1_759_500_000}).encode()
+
+
+@pytest.fixture
+def calendars(monkeypatch) -> Calendars:
+    fake = Calendars()
+    monkeypatch.setenv(anchor.CALENDARS_ENV, f"{ALICE},{BOB}")
+    monkeypatch.setattr(anchor, "remote", fake)
+    monkeypatch.setattr(anchor, "_get", fake.explorer)
+    return fake
+
+
+@pytest.fixture
+def project(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "data.csv").write_text("a,b\n1,2\n")
+    assert cli.main(["init"]) == 0
+    assert cli.main(["seal", "data.csv"]) == 0
+    return tmp_path / ".results" / "ledger.jsonl"
+
+
+def test_a_stamp_is_pending_until_mined_and_then_dates_the_whole_chain(project, calendars, capsys):
+    assert cli.main(["timestamp"]) == 0
+    capsys.readouterr()
+    cli.main(["verify"])
+    assert "events 1–2 stamped, pending at 2 calendars" in capsys.readouterr().out
+
+    calendars.mine(915_000)
+    assert cli.main(["timestamp"]) == 0
+    assert "events 1–2 existed by Bitcoin block 915000" in capsys.readouterr().out
+    assert cli.main(["verify"]) == 0
+    assert "events 1–2 dated by Bitcoin block 915000" in capsys.readouterr().out
+
+
+def test_stamping_the_same_head_twice_makes_one_proof(project, calendars):
+    cli.main(["timestamp"])
+    cli.main(["timestamp"])
+
+    assert len(list((project.parent / "timestamps").glob("*.ots"))) == 1
+
+
+def test_a_ledger_rewritten_with_its_anchor_after_a_stamp_is_reported(project, calendars, capsys):
+    cli.main(["timestamp"])
+    # The owner's rewrite: same length, a different second event, chain and anchor both
+    # consistent. `results verify` alone passes this.
+    project.unlink()
+    ledger.anchor_path(project).unlink()
+    (project.parent.parent / "data.csv").write_text("a,b\n9,9\n")
+    ledger.append_event(project, {"event": "init"})
+    ledger.append_event(project, {"event": "seal", "files": []})
+    capsys.readouterr()
+
+    assert cli.main(["verify"]) == 1
+    out = capsys.readouterr().out
+    assert "TIMESTAMP CONTRADICTS THE CHAIN" in out
+    assert "000002-" in out
+
+
+def test_a_ledger_truncated_and_reanchored_after_a_stamp_is_reported(project, calendars, capsys):
+    (project.parent.parent / "more.csv").write_text("x\n")
+    cli.main(["seal", "more.csv"])
+    cli.main(["timestamp"])
+    lines = project.read_text().splitlines(keepends=True)
+    project.write_text("".join(lines[:-1]))
+    ledger.anchor_path(project).unlink()
+    assert cli.main(["reanchor"]) == 0
+    capsys.readouterr()
+
+    assert cli.main(["verify"]) == 1
+    assert "dates a chain of 3 events, and the ledger holds 2" in capsys.readouterr().out
+
+
+def test_a_damaged_chain_is_not_stamped(project, calendars, capsys):
+    project.write_text(project.read_text().replace('"seal"', '"sealed"'))
+
+    assert cli.main(["timestamp"]) == 2
+    assert not (project.parent / "timestamps").exists()
+
+
+def test_with_no_calendar_reachable_nothing_is_written_and_verify_says_there_is_no_date(
+    project, monkeypatch, capsys
+):
+    monkeypatch.setenv(anchor.CALENDARS_ENV, "")
+
+    assert cli.main(["timestamp"]) == 1
+    capsys.readouterr()
+    cli.main(["verify"])
+    assert "no outside timestamp" in capsys.readouterr().out