clay-borg/tools/trials.py

#!/usr/bin/env python3
"""trials — what the players said, and where (CB-WP-0027 T04).

**Surfacing is the deliverable, not storage.** ADR-0014 D6: a commentary
feature that stores comments and shows them nowhere would be this
project's signature failure in a new medium — after the message that sat
unread for four days and the ten rulings that arrived and were never
collected.

So this reports every note from every trial log, with its position and its
age, and flags the ones whose position can no longer be reached.

Reuses `design.py`'s parsing shape because the trial log deliberately
reuses `FindingRegister.md`'s idiom: a table between HTML-comment markers
inside a readable Markdown file.
"""

import os, re, sys, glob, datetime

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
TRIALS = os.path.join(ROOT, "trials")

BEGIN = "<!-- trial-log:begin -->"
END = "<!-- trial-log:end -->"

# GameDesign §3.1's figure, shared rather than reinvented: a note that
# cannot expire ages into an apparent finding.
NOTE_EXPIRY_DAYS = 30


def parse(text):
    """Rows between the markers. A log without the block is an error, not
    an empty log — silently reporting zero notes for a file full of them
    is precisely the failure this tool exists to prevent."""
    if BEGIN not in text or END not in text:
        raise ValueError("no trial-log block")
    block = text.split(BEGIN)[1].split(END)[0]
    rows = []
    for line in block.splitlines():
        line = line.strip()
        if not line.startswith("|") or line.startswith("|---"):
            continue
        cells = [c.strip() for c in line.strip("|").split("|")]
        if len(cells) != 5 or cells[0] == "n":
            continue
        rows.append(dict(zip(("n", "round", "step", "state_hash", "comment"), cells)))
    return rows


def logs(root=TRIALS):
    """Every trial log, with its recording beside it if there is one."""
    out = []
    for path in sorted(glob.glob(os.path.join(root, "*.md"))):
        try:
            rows = parse(open(path).read())
        except ValueError:
            print(f"  WARN {os.path.basename(path)}: no trial-log block — not a trial log?")
            continue
        recording = os.path.splitext(path)[0] + ".yaml"
        out.append((path, rows, recording if os.path.exists(recording) else None))
    return out


def reachability(row, recording):
    """Can this note's position be reached? One of three answers.

    **"No recording" and "the hash is not in the recording" are different
    states and must not be one number.** A note written mid-game is
    pending — the recording is only written when the game ends — while a
    note whose hash is absent from a recording that *exists* means the
    position moved. Collapsing them makes every live session report
    orphans, and a metric that cries wolf is one nobody reads, which is
    the failure this whole pass is about.

    Orphans are reported, never deleted (ADR-0014 D3): a moved position is
    worth knowing, by the same reasoning that rewrote `gr-e01` rather than
    retiring it.
    """
    if not recording:
        return "pending"
    return "ok" if row["state_hash"] in open(recording).read() else "orphan"


def age_days(path, today):
    """Dated from the log's filename (`YYYY-MM-DD-slug.md`), falling back
    to mtime — the name is the intent, the mtime is what happened."""
    m = re.match(r"(\d{4}-\d{2}-\d{2})", os.path.basename(path))
    if m:
        try:
            return (today - datetime.date.fromisoformat(m.group(1))).days
        except ValueError:
            pass
    return (today - datetime.date.fromtimestamp(os.path.getmtime(path))).days


def report(root=TRIALS, today=None):
    today = today or datetime.date.today()
    if not os.path.isdir(root):
        print("trials — no trials/ directory yet\n")
        print("  Play one:  cb-play --serve 0 --record trials/<date>-<slug>.yaml \\")
        print("                     --trial trials/<date>-<slug>.md")
        return 0

    found = logs(root)
    print("trials — what the players said, and where\n")
    total, orphans, pending, expired = 0, 0, 0, 0
    for path, rows, recording in found:
        name = os.path.basename(path)
        age = age_days(path, today)
        print(f"  {name}  ({len(rows)} note(s), {age}d"
              f"{', recording not written yet' if not recording else ''})")
        for r in rows:
            total += 1
            state = reachability(r, recording)
            orphans += state == "orphan"
            pending += state == "pending"
            expired += age > NOTE_EXPIRY_DAYS
            mark = {"orphan": "orphan", "pending": "  ..  ", "ok": "      "}[state]
            print(f"    {mark}  r{r['round']:<2} {r['step']:<8} {r['state_hash']:<12} "
                  f"{r['comment'][:70]}")
        print()

    print(f"  trial logs             {len(found)}")
    print(f"  notes                  {total}")
    print(f"  positions unreachable  {orphans}   target 0"
          + ("   <-- the recording exists but the position moved" if orphans else ""))
    if pending:
        print(f"  awaiting a recording   {pending}"
              "   (normal during a live session; the recording lands at game end)")
    print(f"  notes past {NOTE_EXPIRY_DAYS} days     {expired}   target 0")
    if total and not orphans:
        print("\n  Every note points at a position a reader can reach.")
    print("\n  Raw notes stay in this repo (ADR-0014 D4). A note reaches"
          "\n  ground-game only by being promoted to a register finding, by a"
          "\n  human, with the wording chosen then.")
    return 0


def self_test():
    """Positive controls, including for the REPORTING path.

    `design-baseline.py` had a green self-test and an unexercised
    reporting path, and the reporting path is where it rotted (ADR-0012
    D8). So this runs `report` against a fixture and checks what it says.
    """
    import tempfile, io, contextlib

    ok = True

    def check(name, cond, detail=""):
        nonlocal ok
        ok = ok and bool(cond)
        print(f"  [{'ok ' if cond else 'FAIL'}] {name}" + (f"  — {detail}" if detail else ""))

    good = (f"# Trial log\n\n{BEGIN}\n\n"
            "| n | round | step | state_hash | comment |\n|---|---|---|---|---|\n"
            "| 1 | 3 | Select | abc123def456 | why is SOLVE doing nothing |\n"
            f"\n{END}\n")
    check("a trial log parses", len(parse(good)) == 1)
    check("the header row is not a note", all(r["n"] != "n" for r in parse(good)))

    try:
        parse("# Trial log\n\nno block here\n")
        check("a file with no block is an error, not an empty log", False)
    except ValueError:
        check("a file with no block is an error, not an empty log", True,
              "silently reporting zero is the failure this tool prevents")

    with tempfile.TemporaryDirectory() as d:
        open(os.path.join(d, "2026-08-06-x.md"), "w").write(good)
        # No .yaml beside it → the position cannot be reached.
        rows = parse(good)
        check("a note with no recording is PENDING, not orphaned",
              reachability(rows[0], None) == "pending",
              "a live session must not report orphans")
        rec = os.path.join(d, "2026-08-06-x.yaml")
        open(rec, "w").write("state_hash: abc123def456\n")
        check("a note whose hash is in the recording is reachable",
              reachability(rows[0], rec) == "ok",
              "without this the check could always say orphan")
        open(rec, "w").write("state_hash: something-else\n")
        check("a note whose hash is absent from a REAL recording is an orphan",
              reachability(rows[0], rec) == "orphan",
              "the position moved \u2014 the case the flag exists for")

        # THE control design-baseline.py lacked: exercise the reporting
        # path and assert on what it printed.
        buf = io.StringIO()
        with contextlib.redirect_stdout(buf):
            report(d, datetime.date(2026, 8, 6))
        out = buf.getvalue()
        check("the reporting path runs and names the note",
              "why is SOLVE doing nothing" in out, "not just the parser")
        check("the reporting path counts", "notes                  1" in out)

    print("trials self-test (positive control)")
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(self_test() if "--self-test" in sys.argv else report())