v0.11 item 4: one chain, five receipt schema versions, walked end to end

.github/workflows/ci.yml

@@ -133,7 +133,7 @@ jobs:
           set -eu
           echo "authority: $AUTHORITY ($AUTHORITY_NA not applicable)"
           echo "templates: $TEMPLATES ($TEMPLATES_NA not applicable)"
-          test "$AUTHORITY" = "verified 24/24"
+          test "$AUTHORITY" = "verified 25/25"
           # G13 is N/A on SQLite, the action's default store: SQLite has no clock of its own
           # to diverge from; G15 is N/A because neither document declares `max_attempts`.
           # G16 is graded on both: verify brings its own precondition provider (SPEC-v0.7 §8.9).
@@ -148,7 +148,11 @@ jobs:
           # grants name no task, which the templates example's do not. The authority example
           # binds one, so its count is unchanged and its passing total moved 19 to 20 instead.
           test "$AUTHORITY_NA" = "3"
-          test "$TEMPLATES" = "verified 11/11"
+          #
+          # SPEC-v0.11 §8 moved the templates count again: G31 needs only an action to
+          # build a chain from, so it is graded wherever any guarantee is, and both
+          # examples gained one passing row when item 4 landed.
+          test "$TEMPLATES" = "verified 12/12"
           test "$TEMPLATES_NA" = "16"
           test -s verify-badge.json
           test -s verify-report.json

CHANGELOG.md

@@ -42,6 +42,28 @@ any change to one appears here.
   trusted. Found by review; the tests that missed it all tampered with a row's *content*, and
   `{}` and a float among the controls are both valid JSON.
 
+- **One chain, five receipt schema versions, walked end to end** (`SPEC-v0.11.md` §6). A store
+  kept since v0.6 holds five: `v3` (0.6), `v4` (0.7), `v5` (0.8), `v6` (0.9), `v7` (0.10).
+  **No new field**: `schema` has existed since `SPEC-v0.3.md` §12.2. What is new is the proof
+  that `verify_chain` walks such a chain hash by hash, **each row hashed by the rule its own
+  version wrote**. v0.10's release pass proved the `v6`/`v7` boundary against the released 0.9.0
+  and stopped there.
+
+  `scripts/five_schema_chain.py` builds the chain from the **released wheels** rather than from
+  fixtures: five environments, `pip install ctrlrun==0.6.1`, `0.7.0`, `0.8.0`, `0.9.0`, `0.10.0`,
+  one store, then this build verifies across the whole thing. A fixture is this build's opinion
+  of what 0.6 wrote; the wheel is what it wrote.
+
+  And a receipt whose schema label this binary does **not** know is named, not reported as a
+  break: `SPEC-v0.6.md` §3.2's distinction, and the difference between *this evidence is from a
+  future version* and *this evidence is tampered with*. Relabelling a stored row without
+  rehashing it is still `content_altered`, because that is somebody editing evidence.
+
+- **`G31`, five receipt schemas verify**, and `ctrlrun.guarantees/v6` becomes **`v7`**, moved
+  once. `G28` to `G30` and `G32` are not in the catalogue yet: `SPEC-v0.11.md` §8 assigns ids in
+  item order so that splitting the milestone renumbers nothing, and a row whose check does not
+  exist would report something before it could.
+
 ### Changed
 
 - **`StateStore.receipts()` returns `tuple[Receipt | UnreadableReceipt, ...]`**, amending

scripts/five_schema_chain.py

@@ -0,0 +1,216 @@
+# SPDX-FileCopyrightText: 2026 The CTRLRun contributors
+# SPDX-License-Identifier: Apache-2.0
+"""Build one receipt chain with five RELEASED ctrlrun wheels, then verify it with this build.
+
+`SPEC-v0.11.md` §6.1. A store kept since v0.6 holds five receipt schema versions: `v3` (0.6),
+`v4` (0.7), `v5` (0.8), `v6` (0.9), `v7` (0.10). Nothing proved that `verify` walks such a chain
+end to end, hash by hash, **each row hashed by the rule its own version wrote**. v0.10's release
+pass proved the `v6`/`v7` boundary against the released 0.9.0 and stopped there.
+
+**The chain is written by the released wheels and not by fixtures this build produces**, because
+a fixture is this build's opinion of what 0.6 wrote and the wheel is what it actually wrote.
+v0.10's upgrade check did this and it is the reason it found anything.
+
+This needs a network and five virtual environments, so it is a script an operator or a release
+pass runs rather than a test the ordinary suite runs. `tests/test_five_schema_versions.py` keeps
+the invariant checkable without a network, and `G31` grades the walk.
+
+    python scripts/five_schema_chain.py            # build and verify, print the transcript
+    python scripts/five_schema_chain.py --keep DIR # leave the store behind to poke at
+
+The transcript it printed on 2026-09-14, against this build, is in that test file's docstring.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import venv
+from pathlib import Path
+
+#: One release per receipt schema version a store kept since v0.6 can hold. 0.6.1 rather than
+#: 0.6.0 because it is the last 0.6, and `v3` is what both wrote.
+RELEASES: tuple[tuple[str, str], ...] = (
+    ("0.6.1", "ctrlrun.receipt/v3"),
+    ("0.7.0", "ctrlrun.receipt/v4"),
+    ("0.8.0", "ctrlrun.receipt/v5"),
+    ("0.9.0", "ctrlrun.receipt/v6"),
+    ("0.10.0", "ctrlrun.receipt/v7"),
+)
+
+#: `ctrlrun.policy/v1`, which every release from 0.6 on still reads: the rule since
+#: `SPEC-v0.3.md` §12.2 is that every reader upgrades before any writer switches, and a document
+#: only the newest binary parses would make this script test the policy loader instead of the
+#: chain.
+POLICY = "schema: ctrlrun.policy/v1\nactions:\n  stripe.refund:\n    decision: allow\n"
+
+#: Run by each wheel inside its own environment. It must use only what 0.6.1 already had, so
+#: nothing here touches `Receipt.schema`: that attribute does not exist in 0.6.1, and an earlier
+#: version of this script raised `AttributeError` out of its own reporting line **after** the
+#: writes had landed, which reads as a failed write and is not one.
+WRITER = """
+import sys
+from ctrlrun import Control, Policy, SQLiteStateStore
+from ctrlrun.action import Action, Principal
+
+database, tag, policy = sys.argv[1], sys.argv[2], sys.argv[3]
+store = SQLiteStateStore(database)
+control = Control(Policy.from_yaml(policy), store)
+for index in range(2):
+    control.execute(
+        Action(
+            name="stripe.refund",
+            arguments={"payment_id": "%s-%d" % (tag, index), "amount": 2000},
+            principal=Principal(agent="chain-agent"),
+        ),
+        lambda: {"ok": True},
+        "refund:%s-%d" % (tag, index),
+    )
+print(len(store.receipts()))
+store.close()
+"""
+
+
+#: The environment every subprocess gets: this one, with anything that could put **this**
+#: build's source onto a released wheel's `sys.path` removed.
+#:
+#: **This is the whole methodology and it was wrong first.** Run as `PYTHONPATH=src python
+#: scripts/five_schema_chain.py`, which is how anyone runs a script against an uninstalled
+#: checkout, the variable is inherited by every child -- so each "released wheel" imported this
+#: build's `src/ctrlrun` instead of the wheel just installed beside it. The script printed a
+#: chain of ten receipts that verified perfectly and reported **one** schema version, because
+#: all five writers were this binary. A run that checked nothing looked exactly like a pass.
+def _clean_environment() -> dict[str, str]:
+    environment = dict(os.environ)
+    for leak in ("PYTHONPATH", "PYTHONHOME", "PYTHONSTARTUP"):
+        environment.pop(leak, None)
+    return environment
+
+
+def _require_wrote_as(python: Path, version: str, schema: str) -> None:
+    """Fail loudly if the wheel that just ran was not the released one.
+
+    The positive control for `_clean_environment`, and it is not optional: the only symptom of a
+    leaked `sys.path` is a schema count, which is the number this script exists to produce. A
+    check that can be fooled by the bug it checks for is not a check.
+    """
+    seen = subprocess.run(
+        [
+            str(python),
+            "-c",
+            "import ctrlrun, ctrlrun.receipt as r;"
+            "print(ctrlrun.__file__);print(getattr(r, 'RECEIPT_SCHEMA', 'none'))",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+        env=_clean_environment(),
+    ).stdout.split()
+    if f"venv-{version}" not in seen[0]:
+        raise SystemExit(
+            f"{version} ran from {seen[0]}, which is not its own environment: something put "
+            "another ctrlrun on its sys.path, so this run proves nothing"
+        )
+    if seen[1] != schema:
+        raise SystemExit(
+            f"{version} writes {seen[1]}, and this script says it writes {schema}. One of the "
+            "two is wrong, and RELEASES is the thing to fix"
+        )
+
+
+def _environment(root: Path, version: str) -> Path:
+    """A scratch environment with exactly one released ctrlrun in it."""
+    target = root / f"venv-{version}"
+    venv.EnvBuilder(with_pip=True).create(target)
+    python = target / "bin" / "python"
+    subprocess.run(
+        [
+            str(python),
+            "-m",
+            "pip",
+            "install",
+            "-q",
+            "--disable-pip-version-check",
+            f"ctrlrun=={version}",
+        ],
+        check=True,
+        env=_clean_environment(),
+    )
+    return python
+
+
+def build(root: Path) -> Path:
+    """Write two receipts with each release, oldest first, into one store."""
+    database = root / "chain.db"
+    writer = root / "writer.py"
+    writer.write_text(WRITER, encoding="utf-8")
+    for version, schema in RELEASES:
+        python = _environment(root, version)
+        done = subprocess.run(
+            [str(python), str(writer), str(database), f"v{version}", POLICY],
+            check=True,
+            capture_output=True,
+            text=True,
+            env=_clean_environment(),
+        )
+        _require_wrote_as(python, version, schema)
+        print(
+            f"  {version:<7} wrote 2 receipts under {schema}; store now holds {done.stdout.strip()}"
+        )
+    return database
+
+
+def verify(database: Path) -> int:
+    """Verify the whole chain with THIS build, and report what it walked."""
+    from ctrlrun.receipt import verify_chain
+    from ctrlrun.state import SQLiteStateStore
+
+    store = SQLiteStateStore(str(database))
+    try:
+        rows = store.receipts()
+        schemas = sorted({row.schema for row in rows})
+        report = verify_chain(store)
+    finally:
+        store.close()
+
+    print()
+    print(f"  receipts:              {len(rows)}")
+    print(f"  schemas in ONE chain:  {len(schemas)}")
+    for schema in schemas:
+        at = [row.seq for row in rows if row.schema == schema]
+        print(f"    {schema:<22} at seq {at}")
+    print(
+        f"  verify_chain:          ok={report.ok} verified={report.verified} "
+        f"chained={report.chained} unchained={report.unchained}"
+    )
+    print(f"  breaks:                {[(b.name, b.seq) for b in report.breaks] or 'none'}")
+
+    expected = {schema for _, schema in RELEASES}
+    if set(schemas) != expected:
+        print(f"\nFAIL: expected {sorted(expected)}, walked {schemas}")
+        return 1
+    if not report.ok or report.verified != len(rows):
+        print("\nFAIL: the chain did not verify end to end")
+        return 1
+    print(f"\nOK: one chain, {len(schemas)} receipt schema versions, verified end to end")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--keep", type=Path, help="build in this directory and leave it behind")
+    arguments = parser.parse_args()
+
+    print(f"Building one chain with {len(RELEASES)} released wheels from PyPI:")
+    if arguments.keep:
+        arguments.keep.mkdir(parents=True, exist_ok=True)
+        return verify(build(arguments.keep))
+    with tempfile.TemporaryDirectory() as scratch:
+        return verify(build(Path(scratch)))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/ctrlrun/verify/guarantees.py

@@ -31,7 +31,11 @@
 #: SPEC-v0.9 §8: `v5` was G1 to G24, and it moved once, with G24. G22 and G23 joined it with
 #: their items. No stub rows: a guarantee that reports anything before its check exists is a
 #: false green, which is what 0.6.1 had to fix and what G17 shipped as in v0.8.
-CATALOGUE: Final = "ctrlrun.guarantees/v6"
+#: SPEC-v0.11 §8: `v7` is G1 to G32, and it moves once, here, with item 4's G31. G28 (item 2),
+#: G29, G30 and G32 (item 3) join it with their items, and the release item asserts every row
+#: present before the release. No stub rows: a guarantee that reports anything before its check
+#: exists is a false green.
+CATALOGUE: Final = "ctrlrun.guarantees/v7"
 
 
 @dataclass(frozen=True)
@@ -209,6 +213,15 @@ class Guarantee:
         "a swapped upstream is denied",
         ("v0.10 §4.3", "v0.10 §4.7 T490", "v0.10 §4.7 T493"),
     ),
+    Guarantee(
+        "G31",
+        # 27 characters against `report._TITLE_WIDTH`'s 32. It grades **the walk**, not the
+        # field: `schema` has existed since v0.3 and `SPEC-v0.11 §6` adds no field. What was
+        # never proved is that `verify_chain` walks a chain holding more than one of them,
+        # hash by hash, each row hashed by the rule its own version wrote.
+        "five receipt schemas verify",
+        ("v0.11 §6", "v0.11 §6.1 T521", "v0.11 §6.2 T523"),
+    ),
 )
 
 #: By id, for `--only` and for the report. Insertion order is catalogue order.