omakit 0.5.1 → 0.6.1

package/tests/lab/run/report.py

@@ -0,0 +1,217 @@
+# The Run lab suite's reader: every run under <out>/runs into one document,
+# <out>/runlab.json, and the gate, asserted. Every figure says how it was
+# read: time to end is the harness's own clock from start() to the result
+# (to the destroy event for destroy, to the last of ten results for
+# concurrency); Pss is /proc/<quickshell pid>/smaps_rollup sampled every
+# 100 ms by suite.sh, before = the last sample before the start event, peak
+# = the maximum until the end, after = the last sample at least 1.5 s after
+# the end; survivors are counted two seconds after the end by pgid and by
+# the scope's cgroup; a signal to an empty group is the supervisor's
+# os.killpg raising ProcessLookupError; shadow hits are the lines the
+# hostile scenario's shadow tools wrote.
+import hashlib
+import json
+import os
+import platform
+import re
+import statistics
+import sys
+import time
+
+# What each scenario must show. deadline and grace are the harness's values,
+# so the bound "within deadline plus grace" is checked from them; 500 ms of
+# slack covers the harness's own clock and one supervisor start.
+EXPECT = {
+    "producer": {"deadline": 60000, "grace": 1000, "state": "overflow"},
+    "producer-stream": {"deadline": 120000, "grace": 1000, "state": "ok", "outBytes": 1073741824},
+    "holder": {"deadline": 10000, "grace": 1000, "state": "ok"},
+    "stubborn": {"deadline": 2000, "grace": 1000, "state": "timeout", "kill": True},
+    "hostile": {"deadline": 5000, "grace": 1000, "state": "ok", "stdout": ["PATH=/usr/bin\n", "BASH_ENV=unset\n", "PYTHONPATH=unset\n"]},
+    "destroy": {"deadline": 10000, "grace": 1000, "state": None},
+    "cancel": {"deadline": 10000, "grace": 1000, "state": "cancelled"},
+    "supersede": {"deadline": 10000, "grace": 1000, "states": ["cancelled", "ok"]},
+    "shell-string": {"deadline": 5000, "grace": 1000, "state": "spawn-failed", "reason": "shell string"},
+    "relative": {"deadline": 5000, "grace": 1000, "state": "spawn-failed", "reason": "not an absolute path"},
+    "missing": {"deadline": 5000, "grace": 1000, "state": "spawn-failed", "reason": "No such file"},
+    "controls": {"deadline": 5000, "grace": 1000, "state": "ok", "stdout": ["a[31mbcde\tf\ng\n"], "stderr": ["stderr]0;titleline\n"]},
+    "concurrency": {"deadline": 30000, "grace": 1000, "state": "ok", "count": 10, "outBytes": 1048576},
+    # 0.2.0: the review of 2026-09-18 (docs/evidence/blocks/2026-09-18-review.json)
+    "forge": {"deadline": 5000, "grace": 1000, "state": "supervisor-lost", "reason": "detached reaper", "notStdout": ["forged"], "notPgid": 4194303},
+    "orphan": {"deadline": 5000, "grace": 1000, "state": "supervisor-lost", "reason": "detached reaper"},
+    "stalled-supersede": {"deadline": 2000, "grace": 500, "states": ["supervisor-lost", "ok"], "bound": 2000 + 500 + 3000 + 6000},
+    "destroy-early": {"deadline": 10000, "grace": 1000, "state": None},
+    "shell-string-option": {"deadline": 5000, "grace": 1000, "state": "spawn-failed", "reason": "shell string"},
+    "shell-string-wrapper": {"deadline": 5000, "grace": 1000, "state": "spawn-failed", "reason": "shell string"},
+}
+CONTROL = re.compile("[\\x00-\\x08\\x0b-\\x1f\\x7f-\\x9f\\u061c\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069]")
+SLACK_MS = 500
+
+
+def events(log):
+    found = []
+    for line in open(log, errors="replace"):
+        match = re.search(r"RUNLAB (\{.*\})", line)
+        if match:
+            try:
+                found.append(json.loads(match.group(1)))
+            except ValueError:
+                pass
+    return found
+
+
+def meta_of(path):
+    lines = [line.rstrip("\n") for line in open(path)]
+    pairs = dict(line.split("=", 1) for line in lines if "=" in line and not line.startswith("survivor"))
+    survivors = [line for line in lines if line.startswith("survivor")]
+    return pairs, survivors
+
+
+def pss_of(path, start, end):
+    samples = [tuple(map(int, line.split())) for line in open(path) if line.strip()]
+    before = [p for t, p in samples if t < start]
+    during = [p for t, p in samples if start <= t <= end + 200]
+    after = [p for t, p in samples if t >= end + 1500]
+    return {"before": before[-1] if before else None, "peak": max(during) if during else None, "after": after[-1] if after else None}
+
+
+def read_run(runs_dir, scen, index):
+    base = os.path.join(runs_dir, "%s-%d" % (scen, index))
+    evs = events(base + ".log")
+    start = next((e["t"] for e in evs if e.get("ev") == "start"), None)
+    results = [e for e in evs if e.get("ev") == "result"]
+    destroy = next((e for e in evs if e.get("ev") == "destroy"), None)
+    done = next((e for e in evs if e.get("ev") == "all-finished"), None)
+    pairs, survivors = meta_of(base + ".meta")
+    end_wall = int(pairs.get("end_wall", start or 0))
+    pss = pss_of(base + ".pss", start or 0, end_wall)
+    if scen == "concurrency" and done and start:
+        ms = done["t"] - start
+    elif scen in ("destroy", "destroy-early") and destroy and start:
+        ms = destroy["t"] - start
+    else:
+        ms = results[-1]["ms"] if results else None
+    signals = [s for r in results for s in r.get("signals", [])]
+    return {"scenario": scen, "run": index, "start": start, "ms": ms,
+            "states": [r.get("state") for r in results], "results": results,
+            "pssBefore": pss["before"], "pssPeak": pss["peak"], "pssAfter": pss["after"],
+            "survivors": len(survivors), "survivorLines": survivors,
+            "signals": ["%s@%s" % (s["sig"], s["atMs"]) for s in signals],
+            "toEmptyGroup": sum(1 for s in signals if s.get("esrch")),
+            "shadowHits": int(pairs.get("shadow_hits", 0)), "destroyed": destroy is not None}
+
+
+def check_states(row, want, problems):
+    if "states" in want:
+        if row["states"] != want["states"]:
+            problems.append("states %s, expected %s" % (row["states"], want["states"]))
+        return
+    count = want.get("count", 1)
+    if want["state"] is None:
+        if row["states"]:
+            problems.append("a result after destruction: %s" % row["states"])
+        return
+    if row["states"] != [want["state"]] * count:
+        problems.append("states %s, expected %s x%d" % (row["states"], want["state"], count))
+
+
+def check_results(row, want, problems):
+    for result in row["results"]:
+        if "outBytes" in want and result.get("outBytes") != want["outBytes"]:
+            problems.append("outBytes %s, expected %s" % (result.get("outBytes"), want["outBytes"]))
+        if "reason" in want and want["reason"] not in str(result.get("reason", "")):
+            problems.append("reason %r does not say %r" % (result.get("reason"), want["reason"]))
+        for piece in want.get("notStdout", []):
+            if piece in str(result.get("stdout", "")):
+                problems.append("stdout carries the forged %r" % piece)
+        if "notPgid" in want and result.get("pgid") == want["notPgid"]:
+            problems.append("pgid is the forged %d" % want["notPgid"])
+        for key in ("stdout", "stderr"):
+            text = result.get(key, "")
+            if CONTROL.search(text):
+                problems.append("%s carries a control character" % key)
+            for piece in want.get(key, []):
+                if piece not in text:
+                    problems.append("%s lacks %r" % (key, piece))
+        if result.get("survivors", 0):
+            problems.append("the supervisor reported %d survivors" % result["survivors"])
+    if want.get("kill") and not any(s.startswith("KILL@") for s in row["signals"]):
+        problems.append("no KILL was sent")
+
+
+def check(row):
+    want = EXPECT[row["scenario"]]
+    problems = []
+    if row["start"] is None:
+        return ["no start event"]
+    check_states(row, want, problems)
+    check_results(row, want, problems)
+    bound = want.get("bound", want["deadline"] + want["grace"]) + SLACK_MS
+    if row["ms"] is None:
+        problems.append("no end")
+    elif row["ms"] > bound:
+        problems.append("ended at %d ms, over deadline plus grace (%d)" % (row["ms"], bound))
+    if row["survivors"]:
+        problems.append("%d survivor(s): %s" % (row["survivors"], "; ".join(row["survivorLines"])))
+    if row["toEmptyGroup"]:
+        problems.append("%d signal(s) to an empty group" % row["toEmptyGroup"])
+    if row["shadowHits"]:
+        problems.append("%d shadow hit(s)" % row["shadowHits"])
+    if row["scenario"] in ("destroy", "destroy-early") and not row["destroyed"]:
+        problems.append("no destroy event")
+    return problems
+
+
+def rng(values):
+    values = [v for v in values if v is not None]
+    if not values:
+        return None
+    return {"median": statistics.median(values), "min": min(values), "max": max(values), "n": len(values)}
+
+
+def summarise(rows):
+    out = {}
+    for scen in EXPECT:
+        mine = [r for r in rows if r["scenario"] == scen]
+        if not mine:
+            continue
+        out[scen] = {"runs": len(mine), "ms": rng([r["ms"] for r in mine]),
+                     "pssPeakMinusBeforeKb": rng([r["pssPeak"] - r["pssBefore"] for r in mine if r["pssPeak"] and r["pssBefore"]]),
+                     "pssAfterMinusBeforeKb": rng([r["pssAfter"] - r["pssBefore"] for r in mine if r["pssAfter"] and r["pssBefore"]]),
+                     "survivors": sum(r["survivors"] for r in mine), "toEmptyGroup": sum(r["toEmptyGroup"] for r in mine),
+                     "shadowHits": sum(r["shadowHits"] for r in mine), "problems": [p for r in mine for p in r["problems"]]}
+    return out
+
+
+def sha256(path):
+    return hashlib.sha256(open(path, "rb").read()).hexdigest()
+
+
+def main(out, blocks):
+    runs_dir = os.path.join(out, "runs")
+    names = sorted(f[:-4] for f in os.listdir(runs_dir) if f.endswith(".log"))
+    rows = []
+    for name in names:
+        scen, index = name.rsplit("-", 1)
+        row = read_run(runs_dir, scen, int(index))
+        row["problems"] = check(row)
+        rows.append(row)
+    summary = summarise(rows)
+    failed = [scen for scen, entry in summary.items() if entry["problems"]]
+    document = {"id": "runlab", "measured": time.strftime("%Y-%m-%d"), "host": platform.node(), "kernel": platform.release(),
+                "blocks": {name: sha256(os.path.join(blocks, name)) for name in ("Run.qml", "run-supervisor.py")},
+                "method": open(__file__).read().split("import hashlib")[0].replace("# ", "").replace("#", "").strip(),
+                "runs": [{k: v for k, v in r.items() if k != "results"} for r in rows], "summary": summary, "ok": not failed}
+    with open(os.path.join(out, "runlab.json"), "w") as handle:
+        json.dump(document, handle, indent=1)
+    for scen, entry in summary.items():
+        ms = entry["ms"] or {}
+        print("%s - %s: %d run(s), end %s ms (%s-%s), Pss after-before %s kB, survivors %d, to empty group %d, shadow hits %d%s" % (
+            "not ok" if entry["problems"] else "ok", scen, entry["runs"], ms.get("median"), ms.get("min"), ms.get("max"),
+            (entry["pssAfterMinusBeforeKb"] or {}).get("median"), entry["survivors"], entry["toEmptyGroup"], entry["shadowHits"],
+            "; " + "; ".join(entry["problems"]) if entry["problems"] else ""))
+    print("%s - Run lab suite: %d scenarios, %d runs, document at %s" % ("not ok" if failed else "ok", len(summary), len(rows), os.path.join(out, "runlab.json")))
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1], sys.argv[2]))

package/tests/lab/run/suite.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/bash
+# The lab suite for the Run block: the spike's scenarios made repeatable,
+# on whatever machine runs it (the desktop, or the 4.0.3 guest through
+# `omakit lab prove run`). Never touches the running omarchy-shell: every
+# scenario starts its own `quickshell -p <harness>` in a transient user
+# scope (systemd-run --user --scope -p MemoryMax=768M; setsid when the
+# user manager is not reachable), samples that instance's Pss from
+# /proc/<pid>/smaps_rollup every 100 ms, waits for the harness's result
+# lines, counts survivors two seconds later by pgid and by scope, and stops
+# the scope. tests/lab/run/report.py turns the runs into one document and
+# asserts the gate: every run ends within deadline plus grace, no survivor,
+# no signal to an empty group, no shadow hit, the state the scenario expects.
+#
+#   bash tests/lab/run/suite.sh [out-dir] [runs]     default: /tmp/omakit-runlab, 1 run per scenario
+#   RUNLAB_BLOCKS=<dir>                              the block files to test; default blocks/run of this checkout
+set -u
+here="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo="$(cd -- "$here/../../.." && pwd)"
+blocks="${RUNLAB_BLOCKS:-$repo/blocks/run}"
+out="${1:-/tmp/omakit-runlab}"
+runs="${2:-1}"
+scenarios=(producer producer-stream holder stubborn hostile destroy cancel supersede shell-string relative missing controls concurrency forge orphan stalled-supersede destroy-early shell-string-option shell-string-wrapper)
+
+for tool in /usr/bin/python3 /usr/bin/quickshell /usr/bin/setsid /usr/bin/kill; do
+  [[ -x $tool ]] || { echo "not ok - $tool is missing" >&2; exit 1; }
+done
+[[ -n ${WAYLAND_DISPLAY:-} ]] || { echo "not ok - no WAYLAND_DISPLAY; quickshell needs the session" >&2; exit 1; }
+[[ -f $blocks/Run.qml && -f $blocks/run-supervisor.py ]] || { echo "not ok - no block files at $blocks" >&2; exit 1; }
+[[ $runs =~ ^[1-9][0-9]*$ ]] || { echo "not ok - runs must be a positive integer" >&2; exit 1; }
+
+rm -rf "$out" && mkdir -p "$out/runs" "$out/harness/omakit" "$out/shadow/pypath" || exit 1
+cp "$here/harness/shell.qml" "$out/harness/" && cp -r "$here/harness/scenarios" "$out/harness/" || exit 1
+cp "$blocks/Run.qml" "$blocks/run-supervisor.py" "$out/harness/omakit/" || exit 1
+# The shadow directory for the hostile scenario: copies first in PATH that
+# log a hit and exec the real tool; BASH_ENV and a json.py in PYTHONPATH.
+for b in kill setsid python3 bash sh head sleep env sort sed wc; do
+  printf '#!/usr/bin/bash\nprintf "shadow %%s ppid=%%s\\n" "%s" "$PPID" >> %s/shadow/hits.log\nexec /usr/bin/%s "$@"\n' "$b" "$out" "$b" > "$out/shadow/$b"
+  chmod +x "$out/shadow/$b"
+done
+printf 'printf "BASH_ENV sourced by pid=%%s\\n" "$$" >> %s/shadow/hits.log\n' "$out" > "$out/shadow/bash_env.sh"
+printf 'open("%s/shadow/hits.log","a").write("PYTHONPATH json.py imported\\n")\nraise SystemExit(99)\n' "$out" > "$out/shadow/pypath/json.py"
+
+scope_ok=0
+systemd-run --user --scope --quiet -p MemoryMax=768M -- /usr/bin/true >/dev/null 2>&1 && scope_ok=1
+echo "# scope: $([[ $scope_ok == 1 ]] && echo systemd-run || echo setsid)"
+
+ev() { grep -o 'RUNLAB {.*}' "$log" | sed 's/^RUNLAB //' | grep "\"ev\":\"$1\"" | head -1; }
+count_ev() { grep -o 'RUNLAB {.*}' "$log" | grep -c "\"ev\":\"$1\""; }
+waitev() { local n=0; while [[ $(count_ev "$1") -lt $2 ]]; do sleep 0.05; n=$((n+1)); [[ $n -gt $(( $3 * 20 )) ]] && return 1; done; return 0; }
+
+one() {
+  local scen=$1 index=$2 tag=$1-$2
+  log=$out/runs/$tag.log; local pss=$out/runs/$tag.pss meta=$out/runs/$tag.meta
+  : > "$out/shadow/hits.log"; : > "$log"; : > "$pss"; : > "$meta"
+  local -a env=(RUNLAB_SCENARIO="$scen" RUNLAB_BASE="$out/harness" RUNLAB_KEEP="${RUNLAB_KEEP:-65536}")
+  [[ $scen == hostile ]] && env+=(PATH="$out/shadow:$PATH" BASH_ENV="$out/shadow/bash_env.sh" PYTHONPATH="$out/shadow/pypath")
+  local unit=runlab-$tag-$$
+  if [[ $scope_ok == 1 ]]; then
+    systemd-run --user --scope --quiet -p MemoryMax=768M --unit="$unit" -- /usr/bin/env "${env[@]}" /usr/bin/quickshell -p "$out/harness" >"$log" 2>&1 &
+  else
+    /usr/bin/setsid /usr/bin/env "${env[@]}" /usr/bin/quickshell -p "$out/harness" >"$log" 2>&1 < /dev/null &
+  fi
+  local runner=$!
+  waitev ready 1 30 || { echo "no ready line" >>"$meta"; kill -KILL -- -"$runner" 2>/dev/null; systemctl --user stop "$unit.scope" 2>/dev/null; return 1; }
+  local qspid; qspid=$(ev ready | /usr/bin/python3 -c 'import json,sys; print(json.load(sys.stdin)["pid"])')
+  local cg; cg=$(cut -d: -f3 /proc/$qspid/cgroup 2>/dev/null)
+  printf 'qspid=%s\nunit=%s\ncgroup=%s\n' "$qspid" "$unit" "$cg" >>"$meta"
+  ( while [[ -r /proc/$qspid/smaps_rollup ]]; do
+      p=$(awk '/^Pss:/{print $2}' /proc/$qspid/smaps_rollup 2>/dev/null) || break
+      printf '%s %s\n' "$(date +%s%3N)" "$p" >>"$pss"; sleep 0.1; done ) &
+  local sampler=$!
+  local want=1 limit=200
+  [[ $scen == concurrency ]] && want=10
+  [[ $scen == supersede || $scen == stalled-supersede ]] && want=2
+  if [[ $scen == destroy || $scen == destroy-early ]]; then waitev destroy 1 30 || echo "no destroy line" >>"$meta"; else waitev result "$want" "$limit" || echo "no result within $limit s" >>"$meta"; fi
+  echo "end_wall=$(date +%s%3N)" >>"$meta"
+  sleep 2
+  local pgids; pgids=$(grep -o 'RUNLAB {.*}' "$log" | sed 's/^RUNLAB //' | /usr/bin/python3 -c '
+import json,sys
+seen=set()
+for line in sys.stdin:
+    try: o=json.loads(line)
+    except Exception: continue
+    if o.get("pgid"): seen.add(o["pgid"])
+print(" ".join(str(p) for p in sorted(seen)))')
+  echo "pgids=$pgids" >>"$meta"
+  for g in $pgids; do ps -eo pid=,pgid=,stat=,comm= | awk -v g="$g" '$2==g' | sed 's/^/survivor-by-pgid: /' >>"$meta"; done
+  if [[ -n $cg && -r /sys/fs/cgroup$cg/cgroup.procs ]]; then
+    for p in $(cat /sys/fs/cgroup$cg/cgroup.procs); do [[ $p == "$qspid" ]] && continue; echo "survivor-in-scope: $p $(cat /proc/$p/comm 2>/dev/null)" >>"$meta"; done
+  fi
+  echo "shadow_hits=$(grep -c . "$out/shadow/hits.log")" >>"$meta"
+  cp "$out/shadow/hits.log" "$out/runs/$tag.hits"
+  kill "$sampler" 2>/dev/null; wait "$sampler" 2>/dev/null
+  if [[ $scope_ok == 1 ]]; then systemctl --user stop "$unit.scope" 2>/dev/null; else kill -KILL -- -"$runner" 2>/dev/null; fi
+  wait "$runner" 2>/dev/null
+  echo "stopped=$(date +%s%3N)" >>"$meta"
+}
+
+for index in $(seq 1 "$runs"); do
+  for scen in "${scenarios[@]}"; do
+    one "$scen" "$index" || { echo "not ok - $scen run $index did not produce a ready line" >&2; }
+    echo "# done $scen $index $(grep -o '"state":"[a-z-]*"' "$out/runs/$scen-$index.log" | head -3 | tr '\n' ' ')"
+  done
+done
+
+/usr/bin/python3 "$here/report.py" "$out" "$blocks"

package/tests/lab/store/harness/shell.qml

@@ -0,0 +1,73 @@
+// The lab harness for the Store block: a throwaway Quickshell configuration
+// that loads Store (and Run, which it uses) from ./omakit, copied there by
+// suite.sh from blocks/, and runs one scenario named by STORELAB_SCENARIO
+// against the HOME the driver prepared, logging JSON events with a STORELAB
+// prefix. Never loaded into omarchy-shell.
+import QtQuick
+import Quickshell
+import "omakit"
+
+ShellRoot {
+    id: root
+    property string scenario: Quickshell.env("STORELAB_SCENARIO")
+    property string pluginId: "lab.store.fixture"
+    property var results: []
+    property int expected: 0
+    readonly property var schema: ({ type: "object", required: ["version", "themes"], properties: { version: { type: "integer", minimum: 1 }, themes: { type: "object", maxProperties: 64 } }, additionalProperties: false })
+
+    function log(o) { console.log("STORELAB " + JSON.stringify(o)) }
+    function collect(result) {
+        root.results = root.results.concat([result])
+        root.log(Object.assign({ ev: "result", t: Date.now() }, result))
+        if (root.results.length === root.expected) root.log({ ev: "all-done", t: Date.now() })
+    }
+
+    Store { id: state; pluginId: root.pluginId; name: "memory.json"; schema: root.schema; onFinished: function(result) { root.collect(result) } }
+    Store { id: cache; pluginId: root.pluginId; name: "catalog.json"; kind: "cache"; maxBytes: 1048576; onFinished: function(result) { root.collect(result) } }
+    Store { id: loose; pluginId: root.pluginId; name: "memory.json"; onFinished: function(result) { root.collect(result) } }
+
+    property Component writerComponent: Component { Store { pluginId: root.pluginId; name: "memory.json"; schema: root.schema; onFinished: function(result) { root.collect(result) } } }
+
+    property Timer starter: Timer {
+        interval: 1500; running: true
+        onTriggered: {
+            root.log({ ev: "start", scenario: root.scenario, t: Date.now() })
+            const value = { version: 1, themes: { a: { wallpaper: "/x" } } }
+            switch (root.scenario) {
+            case "plain":
+                root.expected = 4; state.write(value); state.read(); state.remove(); state.read(); break
+            case "symlink-directory":
+            case "symlink-parent":
+            case "outside-home":
+            case "group-writable":
+            case "foreign-owner":
+                root.expected = 2; state.read(); state.write(value); break
+            case "symlink-file":
+                root.expected = 3; state.read(); state.write(value); state.read(); break
+            case "swap":
+                root.expected = 40
+                for (let i = 0; i < 20; i++) { state.read(); state.write({ version: i + 1, themes: {} }) }
+                break
+            case "oversized":
+                root.expected = 3; cache.read(); state.write({ version: 1, themes: { big: "x".repeat(70000) } }); state.read(); break
+            case "invalid":
+                root.expected = 2; state.read(); loose.read(); break
+            case "crash":
+                root.expected = 2; state.read(); state.write(value); break
+            case "fifo":
+                root.expected = 3; state.read(); state.write(value); state.read(); break
+            case "short-write":
+                root.expected = 3; state.read(); state.write({ version: 2, themes: { big: "x".repeat(9000) } }); state.read(); break
+            case "non-ascii":
+                root.expected = 1; cache.read(); break
+            case "concurrent":
+                root.expected = 10
+                for (let i = 0; i < 10; i++) root.writerComponent.createObject(root).write({ version: i + 1, themes: {} })
+                break
+            default:
+                root.log({ ev: "unknown-scenario" })
+            }
+        }
+    }
+    Component.onCompleted: log({ ev: "ready", pid: Quickshell.processId, scenario: scenario, home: Quickshell.env("HOME") })
+}

package/tests/lab/store/report.py

@@ -0,0 +1,133 @@
+# The Store lab suite's reader: every scenario's results under <out>/runs
+# into <out>/storelab.json, and the gate, asserted. A result is the state
+# the block reported for one operation; the facts after the run come from
+# suite.sh's stat of the throwaway HOME (the victim file's content, the
+# directory and file modes, the staging files left). Every expectation
+# below names the contract line it holds (docs/BLOCKS.md, Store).
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+
+MIB = 1048576
+
+# Per scenario: the states expected in order (None: any of a set), and
+# the facts. `victim` untouched means the planted link led nowhere.
+EXPECT = {
+    "plain": {"states": ["ok", "ok", "ok", "missing"], "file_mode": None, "dir_mode": "700", "written_mode": "600"},
+    "symlink-directory": {"states": ["refused", "refused"], "reason": "symbolic link", "victim": "untouched", "victim_dir_unchanged": True},
+    "symlink-parent": {"states": ["refused", "refused"], "reason": "symbolic link", "victim": "untouched"},
+    "symlink-file": {"states": ["refused", "ok", "ok"], "reason": "symbolic link", "victim": "untouched", "file_type": "regular file"},
+    "swap": {"any_of": {"ok", "missing", "refused", "invalid"}, "count": 40, "victim": "untouched"},
+    "oversized": {"multiset": ["overflow", "overflow", "missing"], "reason": "over"},
+    "group-writable": {"states": ["refused", "ok"], "reason": "writable by the group", "written_mode": "600"},
+    "foreign-owner": {"states": ["refused", "ok"], "reason": "not owned", "simulated_only": True, "written_mode": "600"},
+    "invalid": {"multiset": ["invalid", "ok"], "reason": "is not an integer"},
+    "crash": {"states": ["ok", "ok"], "staging_left": 1, "file_content": '{"themes":{"a":{"wallpaper":"/x"}},"version":1}'},
+    "concurrent": {"any_of": {"ok"}, "count": 10, "staging_left": 0, "content_one_of": ['{"themes":{},"version":%d}' % i for i in range(1, 11)]},
+    "outside-home": {"states": ["refused", "refused"], "reason": "not inside HOME", "victim_dir_unchanged": True},
+    # 0.2.0: the review of 2026-09-18 (docs/evidence/blocks/2026-09-18-review.json)
+    "fifo": {"states": ["refused", "ok", "ok"], "reason": "not a regular file", "file_type": "regular file"},
+    "short-write": {"states": ["ok", "failed", "ok"], "reason": "File too large", "staging_left": 0, "file_content": '{"version":1,"themes":{}}'},
+    "non-ascii": {"states": ["ok"], "value_bytes_over": 700000},
+}
+
+
+def events(log):
+    found = []
+    for line in open(log, errors="replace"):
+        match = re.search(r"STORELAB (\{.*\})", line)
+        if match:
+            try:
+                found.append(json.loads(match.group(1)))
+            except ValueError:
+                pass
+    return found
+
+
+def meta_of(path):
+    return dict(line.rstrip("\n").split("=", 1) for line in open(path) if "=" in line)
+
+
+def check_states(results, want, problems):
+    states = [r.get("state") for r in results]
+    if "states" in want and states != want["states"]:
+        problems.append("states %s, expected %s" % (states, want["states"]))
+    if "multiset" in want and sorted(states) != sorted(want["multiset"]):
+        problems.append("states %s, expected %s in any order (two queues)" % (states, want["multiset"]))
+    if "any_of" in want:
+        if len(states) != want["count"]:
+            problems.append("%d results, expected %d" % (len(states), want["count"]))
+        bad = [s for s in states if s not in want["any_of"]]
+        if bad:
+            problems.append("states outside %s: %s" % (sorted(want["any_of"]), bad))
+    if "reason" in want:
+        reasons = [r.get("reason", "") for r in results if r.get("state") not in ("ok", "missing")]
+        if not reasons or not all(want["reason"] in reason for reason in reasons):
+            problems.append("reasons %s do not all say %r" % (reasons, want["reason"]))
+    if "value_bytes_over" in want and not any(r.get("bytes", 0) > want["value_bytes_over"] and isinstance(r.get("value"), dict) for r in results):
+            problems.append("no ok read carried a value of over %d bytes" % want["value_bytes_over"])
+
+
+def check_facts(meta, want, problems):
+    for key in ("victim", "dir_mode", "file_type"):
+        if key in want and meta.get(key) != want[key]:
+            problems.append("%s is %r, expected %r" % (key, meta.get(key), want[key]))
+    if want.get("victim_dir_unchanged") and meta.get("victim_dir_before") != meta.get("victim_dir_after"):
+        problems.append("the victim directory went from %s to %s entries: something landed there" % (meta.get("victim_dir_before"), meta.get("victim_dir_after")))
+    if "written_mode" in want and meta.get("file_mode") not in (None, want["written_mode"]):
+        problems.append("the written file's mode is %s, expected %s" % (meta.get("file_mode"), want["written_mode"]))
+    if "staging_left" in want and int(meta.get("staging_left", -1)) != want["staging_left"]:
+        problems.append("%s staging files left, expected %d" % (meta.get("staging_left"), want["staging_left"]))
+    if "file_content" in want and meta.get("file_content") != want["file_content"]:
+        problems.append("file content %r, expected %r" % (meta.get("file_content"), want["file_content"]))
+    if "content_one_of" in want and meta.get("file_content") not in want["content_one_of"]:
+        problems.append("file content %r is not one whole write" % meta.get("file_content"))
+
+
+def check(scen, results, meta):
+    want = EXPECT[scen]
+    if want.get("simulated_only") and meta.get("foreign_owner") == "not-simulated":
+        return [], "not simulated here: no sudo for a foreign owner; the mode check stands in (group-writable)"
+    problems = []
+    check_states(results, want, problems)
+    check_facts(meta, want, problems)
+    return problems, None
+
+
+def main(out, blocks):
+    runs_dir = os.path.join(out, "runs")
+    rows = []
+    for name in sorted(EXPECT):
+        log = os.path.join(runs_dir, name + ".log")
+        if not os.path.exists(log):
+            rows.append({"scenario": name, "problems": ["no log"], "results": [], "meta": {}, "msToLast": None, "skipped": None})
+            continue
+        evs = events(log)
+        results = [e for e in evs if e.get("ev") == "result"]
+        start = next((e["t"] for e in evs if e.get("ev") == "start"), None)
+        meta = meta_of(os.path.join(runs_dir, name + ".meta"))
+        problems, skipped = check(name, results, meta)
+        # ms: the harness's clock from the scenario's start to each result.
+        timed = [{k: v for k, v in r.items() if k not in ("value", "t")} | {"ms": (r["t"] - start) if start and "t" in r else None} for r in results]
+        rows.append({"scenario": name, "results": timed, "msToLast": (results[-1]["t"] - start) if results and start and "t" in results[-1] else None, "meta": meta, "problems": problems, "skipped": skipped})
+    failed = [r["scenario"] for r in rows if r["problems"]]
+    document = {"id": "storelab", "measured": time.strftime("%Y-%m-%d"), "kernel": os.uname().release,
+                "blocks": {name: hashlib.sha256(open(os.path.join(blocks, name), "rb").read()).hexdigest() for name in ("store/Store.qml", "store/store-helper.py", "run/Run.qml", "run/run-supervisor.py")},
+                "method": open(__file__).read().split("import hashlib")[0].replace("# ", "").replace("#", "").strip(),
+                "scenarios": rows, "ok": not failed}
+    with open(os.path.join(out, "storelab.json"), "w") as handle:
+        json.dump(document, handle, indent=1)
+    for row in rows:
+        states = [r.get("state") for r in row["results"]]
+        summary = ", ".join("%s x%d" % (s, states.count(s)) for s in dict.fromkeys(states)) if states else "no result"
+        note = row.get("skipped") or ("; ".join(row["problems"]) if row["problems"] else "")
+        print("%s - %s: %s, %s ms to the last result%s" % ("not ok" if row["problems"] else "ok", row["scenario"], summary, row["msToLast"], " (" + note + ")" if note else ""))
+    print("%s - Store lab suite: %d scenarios, document at %s" % ("not ok" if failed else "ok", len(rows), os.path.join(out, "storelab.json")))
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1], sys.argv[2]))