From 1d2c1e9b8b0a5b66d0c8870bd55e0de516e7fac3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 06:01:43 +0000
Subject: [PATCH] runs: build_record, record_json, done_status for hosts that
 write their own run record

A host that makes its run-record folder itself (owner marker when the run
starts) and must never prune had to copy runs.record. Three pure functions
now carry what it needs: build_record (the content of run.json, exactly what
record writes; run_id and started_utc only when given), record_json (its
text) and done_status (the .lc-done.json status, SPEC 3.2: a crash after
Cancel is cancelled). record uses them; the CLI's record is unchanged except
that a crash after Cancel is cancelled, a case the CLI cannot produce.

No features id (an additive helper of the Python package); hosts require the
first Tools release after 0.2.0rc1. Documented in PROTOCOL.md and
OPERATIONS.md, with tests, sabotage rows and a ledger row.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2SN8SuEakTdiWy3F2WUqN
---
 docs/OPERATIONS.md               |   1 +
 docs/PROTOCOL.md                 |   7 +
 docs/REGRESSION_LEDGER.md        |   1 +
 labconstrictor_tools/runs.py     |  90 ++++++++---
 tests/test_run_record_builder.py | 252 +++++++++++++++++++++++++++++++
 tests/test_sabotage.py           | 119 ++++++++++++++-
 6 files changed, 446 insertions(+), 24 deletions(-)
 create mode 100644 tests/test_run_record_builder.py

diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 2637738..7f7e369 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -60,6 +60,7 @@ Files that must change in the apps (the template-repository change is a later ta
 * `labconstrictor-tools run` without `--out` writes its results to `<LC_HOME>/results/<time>_<app>_<tool>` (the newest 20 finished ones are kept by `labconstrictor-tools prune`, which the hosts start after a run; Napari and Fiji use their own temporary folders and remove them). `prune` removes only folders that carry LabConstrictor's own marker files (`.lc-owner.json` and `.lc-done.json`): a folder you made yourself, or one from an older version without markers, is never touched. Look first with `labconstrictor-tools prune --dry-run`; the rules are in [PROTOCOL.md](PROTOCOL.md#result-folders-and-run-records-retention).
 * Every run writes `<LC_HOME>/runs/<time>_<app>_<tool>/run.json` (parameters as file paths and values, never pixel data; status,
   error, traceback, interpreter, worker output). Napari's *Details...* button shows it; attach it to bug reports. The newest 50 finished records are kept (`prune`, same rules).
+  A Python host that makes its own record folder (Napari) builds the content with `labconstrictor_tools.runs.build_record`, writes it with `runs.record_json` and picks the done status with `runs.done_status` (a crash after Cancel is `cancelled`); none of them prunes, the host starts `labconstrictor-tools prune` itself ([PROTOCOL.md](PROTOCOL.md#result-folders-and-run-records-retention)). They exist from the first release after 0.2.0rc1 (same release as `retention_prune`): when you cut it, write its number in that PROTOCOL.md paragraph so hosts can use it as their minimum, and tell the host repositories. There is no feature id for them.
 * First run slow? Imports dominate (a repeat run in a kept worker is ~10x faster). Napari keeps the worker for 10 minutes by default.
 * Tool hangs on Windows? Please report with the run record; two such hangs (numpy/scipy imports vs a pending stdin read) were found
   and fixed during development.
diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index 6878ca0..607bcab 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -80,6 +80,13 @@ Under `<LC_HOME>` two folders hold what runs leave behind: `results/<YYYYMMDDTHH
 * **What `prune` removes**: the oldest folders beyond the newest 20 (`results`) or 50 (`runs`), counted over eligible folders only. Eligible = a real directory (not a symlink, junction or other reparse point) that is a direct child of the root, with a name of `A-Za-z0-9_.-`, a valid owner marker whose `name` is the folder's own name and whose `kind` matches the root, and a done marker. Foreign folders, legacy folders without a marker, folders with no done marker (active or crashed), links and files are never touched and never use up the quota. Order is the marker's `created`, then the name.
 * **How**: one non-blocking lock on `<LC_HOME>/.retention.lock` (if it cannot be taken, `prune` exits 0 and deletes nothing); a folder is renamed to `.lc-deleting-<token>` inside the root, then removed without following links; a leftover of an interrupted removal is finished by the next `prune`. `--dry-run` lists exactly what a real run would remove and changes nothing. Exit code: 0, also when the lock is held; 1 when a folder that should go could not be removed (the report says which and why). `--out` folders, `state`, `logs` and everything outside the two roots are never touched.
 
+* **A Python host that writes its own run record** (Napari). `runs.record` is for the CLI and the Python client: it makes the folder when the run is over, writes `.lc-owner.json`, `run.json` and `.lc-done.json`, and then prunes. A host makes its folder when the run *starts* (owner marker first, so a crash leaves an owned, unfinished folder that nobody removes) and must never prune, so it uses three functions that create, delete and prune nothing, instead of copying them:
+  * `runs.build_record(app, tool_id, inputs, task, seconds, stderr="", *, run_id=None, started_utc=None, finished_utc=None) -> dict`: the content of `run.json`, the same dict `runs.record` writes (the host-owned `_job_dir` and `matrix_yx` are left out, the stderr tail is cut to `runs.STDERR_TAIL_CHARS`, `finished_utc` defaults to now). With `run_id` and `started_utc` the record also carries them (`run_id` first, `started_utc` after `tool`); without them it has neither key, which is what the CLI writes.
+  * `runs.record_json(content) -> str`: the text to put in `run.json` (indented, anything that is not JSON written as text).
+  * `runs.done_status(task_status, cancel_requested=False) -> str`: the status for `.lc-done.json` ([SPEC_WRONG_SCIENCE.md](SPEC_WRONG_SCIENCE.md) 3.2): `COMPLETE` is `ok`, `CANCELED` is `cancelled`, `FAILED` is `failed`, and `CRASHED` is `cancelled` when the person pressed Cancel (`Task.cancel_requested`) and `failed` when not.
+
+  The host writes the owner marker with `retention.write_owner(folder, "run", "<host>")`, `run.json` with the text above, the done marker with `retention.write_done(folder, runs.done_status(...))`, and then starts `labconstrictor-tools prune` in a subprocess (compatibility rule 6 above). **Version:** the three functions arrive in the first Tools release after 0.2.0rc1, the release that also lists `retention_prune`; they are not in 0.2.0rc1. A host that calls them requires that release as its `min_tools_version` (the number is written here when the release is tagged; until then it checks `hasattr(runs, "build_record")`). **There is no `features` id for them**: an id says a worker or CLI behaviour exists, which a host in any language can check in the schema, and these are additive functions of the Python package that only a Python host imports; a version minimum says the same thing without a second list. `runs.record` and the CLI behave as before, except that a crash after Cancel now gets `cancelled` (the CLI cannot produce that case: it never calls `Task.cancel`).
+
 ## Reserved inputs
 A request's `inputs` may carry fields that are not tool parameters. Their names start with an underscore and belong to the protocol; a tool cannot declare a parameter with one of these names (declaration error). **A worker accepts every name that starts with an underscore and ignores the ones it does not know**: a newer host may send a field an older worker predates, and that must never fail the task. Tools never see reserved inputs. The list (`labconstrictor_tools.protocol.RESERVED_INPUTS`, tested against this table):
 
diff --git a/docs/REGRESSION_LEDGER.md b/docs/REGRESSION_LEDGER.md
index e20ea47..7d33834 100644
--- a/docs/REGRESSION_LEDGER.md
+++ b/docs/REGRESSION_LEDGER.md
@@ -36,6 +36,7 @@ How to add one: [TESTING.md](TESTING.md#the-ledger).
 | 2026-10-12 | An app registered with a relative `--prefix` or `--pythonpath` disappeared from `list` / loaded other code when a host started from another folder | `registry.register` stored the paths as typed, and hosts read them relative to their own working directory | [#102](https://github.com/CellMigrationLab/LabConstrictor-Tools/pull/102) | `test_roundtrip_registration_paths.py::RelativeRegistration.test_a_relative_prefix_and_pythonpath_still_work_from_another_folder` |
 | 2026-10-12 | Found in the versioning plan, before any user saw it: enforcing issue #51 (reject undeclared inputs) would have refused the reserved fields `_calibration` and `_axes` that new hosts send, so every task from a new host would fail on an old or a strict worker | Only `_job_dir` was known to the worker; "reserved" was a convention, not a list that the input check consults | this PR: `protocol.RESERVED_INPUTS` (documented in PROTOCOL.md), every other leading-underscore name accepted and ignored, `convert.undeclared_inputs` is the single check #51 must use, a tool cannot declare a reserved name | `tests/test_reserved_inputs.py::ReservedList.test_load_inputs_consults_the_reserved_list`, `tests/test_reserved_inputs.py::WorkerAcceptsThem.test_a_real_worker_ignores_reserved_inputs_it_knows_and_those_it_does_not`, `tests/test_reserved_inputs.py::ReservedList.test_the_documented_list_is_the_code_list` |
 | 2026-10-12 | Found in the versioning plan: a host could not tell which Tools wrote a cached schema or whether a rule exists, so a host that needs a newer rule would misbehave silently on an app with an old Tools | Schema and registry entry recorded neither a Tools version nor features | this PR: `tools_version` and `features` in schema and entry (additive, protocol 1), `compat.check_schema` (ok/warn/refuse), CI job `compat` against the last tag with frozen 0.1/0.2 schema fixtures | `tests/test_compat.py::Rules.test_every_rule`, `tests/test_tools_features.py::RegistryAndDoctor.test_register_writes_them_into_the_entry_and_the_cached_schema`, `tests/test_compat_matrix.py::Script.test_every_check_of_the_matrix_passes_against_itself` |
+| 2026-10-13 | Found by Napari phase 2 (LabConstrictor-napari #51): a host that makes its own run-record folder and must never prune had no way to write the record except by copying `runs.record` (the content of `run.json` and the status mapping), so its copy could drift from the CLI's, and a task that crashed after the person pressed Cancel was recorded `failed` | `runs.record` did everything in one function (folder, owner marker, content, done marker, prune) and mapped only `CANCELED` to `cancelled` | this PR: `runs.build_record`, `runs.record_json` and `runs.done_status` (pure, no folder, no prune); `runs.record` uses them and its behaviour is unchanged except that a crash after Cancel is `cancelled` (SPEC 3.2) | `test_run_record_builder.py::BuildRecord.test_the_content_is_what_a_run_record_holds_and_nothing_else`, `test_run_record_builder.py::BuildRecord.test_it_writes_nothing_and_prunes_nothing`, `test_run_record_builder.py::BuildRecord.test_record_writes_the_same_content`, `test_run_record_builder.py::DoneStatus.test_every_way_a_task_ends`, `test_run_record_builder.py::HostFlow.test_a_host_record_is_finished_without_a_prune_and_pruned_later_by_tools_only` |
 
 ## Found by the round-trip matrix, fix PRs pending
 
diff --git a/labconstrictor_tools/runs.py b/labconstrictor_tools/runs.py
index 48b6d40..a52256c 100644
--- a/labconstrictor_tools/runs.py
+++ b/labconstrictor_tools/runs.py
@@ -3,6 +3,11 @@
 One folder per run under <LC_HOME>/runs/, carrying the owner and done markers of docs/SPEC_WRONG_SCIENCE.md section 3;
 `retention.prune` keeps the newest 50 finished ones and never touches a folder it did not make. Everything stays on the local machine. A record holds
 file *paths* and parameter values you passed, never image or table contents.
+
+`record` is what the CLI and the Python client use: it makes the folder, writes everything and prunes. A host that makes its own
+folder (owner marker when the run starts, so a crash leaves an owned, unfinished folder) and must never prune uses the pieces
+instead: `build_record` (the content of `run.json`), `record_json` (its text) and `done_status` (the status for `.lc-done.json`),
+then `retention.write_done`, then starts `labconstrictor-tools prune` itself (docs/PROTOCOL.md, "Result folders and run records").
 """
 
 import json
@@ -23,6 +28,65 @@ def runs_dir() -> Path:
     return registry.home() / "runs"
 
 
+def done_status(task_status: str, cancel_requested: bool = False) -> str:
+    """The `.lc-done.json` status of a task that ended as `task_status` (docs/SPEC_WRONG_SCIENCE.md 3.2, decided 13 Oct).
+
+    COMPLETE is ok, CANCELED is cancelled, FAILED is failed; a CRASHED task is cancelled when the person had pressed Cancel
+    (`Task.cancel_requested`: the worker was killed because the tool did not stop) and failed otherwise. Any other status is failed.
+    """
+    if task_status == "CRASHED" and cancel_requested:
+        return "cancelled"
+    return _DONE_STATUS.get(task_status, "failed")
+
+
+def build_record(
+    app: str,
+    tool_id: str,
+    inputs: dict[str, Any],
+    task: Any,
+    seconds: float,
+    stderr: str = "",
+    *,
+    run_id: str | None = None,
+    started_utc: str | None = None,
+    finished_utc: str | None = None,
+) -> dict[str, Any]:
+    """The content of `run.json` for one finished task, exactly what `record` writes; no folder, no marker, no pruning.
+
+    `finished_utc` defaults to now (UTC, ISO-8601). A host that knows its own `run_id` and the time the run started passes them and
+    gets `run_id` and `started_utc` in the record; without them the record has no such keys (the CLI's record is unchanged).
+    It reads the registry for the app's version and writes nothing. Write the text with `record_json`.
+    """
+    entry: Mapping[str, Any] = registry.load_all().get(app) or {}
+    return {
+        **({"run_id": run_id} if run_id is not None else {}),
+        "app": app,
+        "app_version": entry.get("version"),
+        "tool": tool_id,
+        **({"started_utc": started_utc} if started_utc is not None else {}),
+        "finished_utc": finished_utc or datetime.now(timezone.utc).isoformat(),
+        "seconds": round(seconds, 2),
+        "status": task.status,
+        "error": task.error,
+        "code": task.code,
+        "traceback": task.traceback,
+        "inputs": {
+            k: v for k, v in inputs.items() if k != JOB_DIR_KEY
+        },  # the host-owned folder is not a user input
+        "results": [
+            {k: v for k, v in r.items() if k != "matrix_yx"} for r in task.outputs.get("results", [])
+        ],
+        "timings": task.outputs.get("timings"),
+        "interpreter": task.outputs.get("diagnostics"),
+        "stderr_tail": stderr[-STDERR_TAIL_CHARS:],
+    }
+
+
+def record_json(content: Mapping[str, Any]) -> str:
+    """The text of `run.json` for `content` (what `record` writes: indented, anything that is not JSON written as text)."""
+    return json.dumps(content, indent=2, default=str)
+
+
 def record(
     app: str, tool_id: str, inputs: dict[str, Any], task: Any, seconds: float, stderr: str = ""
 ) -> Path | None:
@@ -33,29 +97,9 @@ def record(
         runs_dir().mkdir(parents=True, exist_ok=True)
         folder.mkdir()  # never an existing folder: it would be marked as ours
         retention.write_owner(folder, "run", "cli")
-        entry: Mapping[str, Any] = registry.load_all().get(app) or {}
-        content = {
-            "app": app,
-            "app_version": entry.get("version"),
-            "tool": tool_id,
-            "finished_utc": started.isoformat(),
-            "seconds": round(seconds, 2),
-            "status": task.status,
-            "error": task.error,
-            "code": task.code,
-            "traceback": task.traceback,
-            "inputs": {
-                k: v for k, v in inputs.items() if k != JOB_DIR_KEY
-            },  # the host-owned folder is not a user input
-            "results": [
-                {k: v for k, v in r.items() if k != "matrix_yx"} for r in task.outputs.get("results", [])
-            ],
-            "timings": task.outputs.get("timings"),
-            "interpreter": task.outputs.get("diagnostics"),
-            "stderr_tail": stderr[-STDERR_TAIL_CHARS:],
-        }
-        (folder / "run.json").write_text(json.dumps(content, indent=2, default=str), encoding="utf-8")
-        retention.write_done(folder, _DONE_STATUS.get(task.status, "failed"))
+        content = build_record(app, tool_id, inputs, task, seconds, stderr, finished_utc=started.isoformat())
+        (folder / "run.json").write_text(record_json(content), encoding="utf-8")
+        retention.write_done(folder, done_status(task.status, getattr(task, "cancel_requested", False)))
         retention.prune("runs")
         return folder
     except (
diff --git a/tests/test_run_record_builder.py b/tests/test_run_record_builder.py
new file mode 100644
index 0000000..ac0c977
--- /dev/null
+++ b/tests/test_run_record_builder.py
@@ -0,0 +1,252 @@
+"""`runs.build_record`, `runs.record_json` and `runs.done_status`: what a Python host uses to write its own run record without
+pruning (docs/PROTOCOL.md, "Result folders and run records"; docs/SPEC_WRONG_SCIENCE.md 3.2).
+
+`runs.record` (the CLI and the Python client) must write exactly what it always did. Expected values are written out by hand.
+"""
+
+import json
+import os
+import re
+import tempfile
+import types
+import unittest
+from datetime import datetime
+from pathlib import Path
+from unittest import mock
+
+import _paths  # noqa: F401  (must come first)
+from _paths import ROOT
+
+from labconstrictor_tools import retention, runs
+
+
+def task(status="COMPLETE", **extra):
+    values = {
+        "status": status,
+        "error": None,
+        "code": None,
+        "traceback": None,
+        "outputs": {
+            "results": [
+                {
+                    "name": "mask",
+                    "type": "labels",
+                    "path": "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/r/mask.tif",
+                    "matrix_yx": [[1, 0, 0], [0, 1, 0]],
+                },
+                {"name": "n", "type": "values", "value": 3},
+            ],
+            "timings": {"run_wall_s": 1.5},
+            "diagnostics": {"python": "3.12"},
+        },
+    }
+    values.update(extra)
+    return types.SimpleNamespace(**values)
+
+
+INPUTS = {"image": "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/data/a.tif", "sigma": 2.0, "_job_dir": "/home/x/results/r1"}
+EXPECTED = {
+    "app": "synthetic",
+    "app_version": "0.0",
+    "tool": "blur",
+    "finished_utc": "2026-10-13T08:00:00+00:00",
+    "seconds": 1.23,
+    "status": "COMPLETE",
+    "error": None,
+    "code": None,
+    "traceback": None,
+    "inputs": {"image": "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/data/a.tif", "sigma": 2.0},
+    "results": [
+        {"name": "mask", "type": "labels", "path": "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/r/mask.tif"},
+        {"name": "n", "type": "values", "value": 3},
+    ],
+    "timings": {"run_wall_s": 1.5},
+    "interpreter": {"python": "3.12"},
+    "stderr_tail": "oops",
+}
+
+
+class Home(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="lc_runrec_")
+        self.addCleanup(self._tmp.cleanup)
+        self.home = Path(self._tmp.name) / "home"
+        self.home.mkdir()
+        _paths.register_synthetic(self.home)  # the app version comes from the registry entry
+        patcher = mock.patch.dict(os.environ, {"LC_HOME": str(self.home)})
+        patcher.start()
+        self.addCleanup(patcher.stop)
+
+    def build(self, **extra):
+        return runs.build_record(
+            "synthetic",
+            "blur",
+            INPUTS,
+            task(),
+            1.2345,
+            "oops",
+            finished_utc="2026-10-13T08:00:00+00:00",
+            **extra,
+        )
+
+
+class BuildRecord(Home):
+    def test_the_content_is_what_a_run_record_holds_and_nothing_else(self):
+        self.assertEqual(self.build(), EXPECTED)
+        self.assertEqual(list(self.build()), list(EXPECTED))  # the same keys in the same order
+
+    def test_it_writes_nothing_and_prunes_nothing(self):
+        with (
+            mock.patch.object(retention, "prune") as prune,
+            mock.patch.object(retention, "write_owner") as owner,
+        ):
+            self.build()
+        prune.assert_not_called()
+        owner.assert_not_called()
+        self.assertEqual(sorted(p.name for p in self.home.iterdir() if p.name != "apps"), [])
+
+    def test_record_writes_the_same_content(self):
+        folder = runs.record("synthetic", "blur", INPUTS, task(), 1.2345, "oops")
+        written = json.loads((folder / "run.json").read_text(encoding="utf-8"))
+        finished = written.pop("finished_utc")
+        self.assertTrue(re.fullmatch(r"\d{4}-\d\d-\d\dT[\d:.]+\+00:00", finished), finished)
+        expected = dict(EXPECTED)
+        expected.pop("finished_utc")
+        self.assertEqual(written, expected)
+        self.assertNotIn("run_id", written)  # the CLI's record has no run_id and no started_utc
+        self.assertNotIn("started_utc", written)
+
+    def test_the_text_is_what_record_writes(self):
+        content = self.build()
+        with mock.patch.object(runs, "build_record", return_value=content):
+            folder = runs.record("synthetic", "blur", INPUTS, task(), 1.2345, "oops")
+        self.assertEqual((folder / "run.json").read_text(encoding="utf-8"), runs.record_json(content))
+        self.assertEqual(runs.record_json(content), json.dumps(content, indent=2, default=str))
+        self.assertEqual(json.loads(runs.record_json(content)), content)
+
+    def test_a_host_gets_its_run_id_and_start_in_the_record(self):
+        content = self.build(run_id="3f2a9c", started_utc="2026-10-13T07:59:58+00:00")
+        self.assertEqual(list(content)[:5], ["run_id", "app", "app_version", "tool", "started_utc"])
+        self.assertEqual((content["run_id"], content["started_utc"]), ("3f2a9c", "2026-10-13T07:59:58+00:00"))
+        rest = {k: v for k, v in content.items() if k not in ("run_id", "started_utc")}
+        self.assertEqual(rest, EXPECTED)
+
+    def test_without_finished_utc_it_is_now_in_utc(self):
+        content = runs.build_record("synthetic", "blur", INPUTS, task(), 1.0)
+        finished = datetime.fromisoformat(content["finished_utc"])
+        self.assertEqual(finished.utcoffset().total_seconds(), 0)
+        self.assertLess(abs((datetime.now(finished.tzinfo) - finished).total_seconds()), 60)
+
+    def test_the_stderr_tail_is_cut_and_the_input_dict_is_left_alone(self):
+        inputs = dict(INPUTS)
+        content = runs.build_record("synthetic", "blur", inputs, task(), 1.0, "x" * 9000 + "end")
+        self.assertEqual(len(content["stderr_tail"]), runs.STDERR_TAIL_CHARS)
+        self.assertTrue(content["stderr_tail"].endswith("xend"))
+        self.assertEqual(inputs, INPUTS)
+        self.assertIn("_job_dir", inputs)
+
+    def test_an_app_that_is_not_registered_has_no_version(self):
+        self.assertIsNone(runs.build_record("nobody", "t", {}, task(), 1.0)["app_version"])
+
+    def test_values_that_are_not_json_are_written_as_text(self):
+        content = runs.build_record("synthetic", "blur", {"folder": Path("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/data/x")}, task(), 1.0)
+        self.assertEqual(json.loads(runs.record_json(content))["inputs"], {"folder": str(Path("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/data/x"))})
+
+
+class DoneStatus(unittest.TestCase):
+    def test_every_way_a_task_ends(self):
+        table = {
+            ("COMPLETE", False): "ok",
+            ("COMPLETE", True): "ok",
+            ("CANCELED", False): "cancelled",
+            ("CANCELED", True): "cancelled",
+            ("FAILED", False): "failed",
+            ("FAILED", True): "failed",  # the tool raised: failed, whether or not Cancel was pressed
+            ("CRASHED", False): "failed",
+            ("CRASHED", True): "cancelled",  # the person asked for the stop (HOST_PARITY J08)
+            ("RUNNING", False): "failed",
+            ("SOMETHING_NEW", True): "failed",
+        }
+        for (status, cancelled), expected in table.items():
+            with self.subTest(status=status, cancel_requested=cancelled):
+                self.assertEqual(runs.done_status(status, cancelled), expected)
+        self.assertEqual(runs.done_status("CRASHED"), "failed")  # no Cancel unless said so
+
+    def test_every_answer_is_a_status_a_done_marker_may_hold(self):
+        for status in ("COMPLETE", "CANCELED", "FAILED", "CRASHED", "RUNNING"):
+            for cancelled in (False, True):
+                self.assertIn(runs.done_status(status, cancelled), retention.STATUSES)
+
+
+class RecordKeepsItsBehaviour(Home):
+    def test_every_status_gets_the_done_status_it_always_had(self):
+        for status, expected in (
+            ("COMPLETE", "ok"),
+            ("CANCELED", "cancelled"),
+            ("CRASHED", "failed"),
+            ("FAILED", "failed"),
+        ):
+            folder = runs.record("synthetic", "blur", {}, task(status), 1.0)
+            self.assertEqual(json.loads((folder / ".lc-done.json").read_text())["status"], expected, status)
+            self.assertEqual(json.loads((folder / ".lc-owner.json").read_text())["host"], "cli")
+
+    def test_a_crash_after_cancel_is_cancelled_in_the_record_folder_too(self):
+        folder = runs.record("synthetic", "blur", {}, task("CRASHED", cancel_requested=True), 1.0)
+        self.assertEqual(json.loads((folder / ".lc-done.json").read_text())["status"], "cancelled")
+        folder = runs.record("synthetic", "blur", {}, task("CRASHED", cancel_requested=False), 1.0)
+        self.assertEqual(json.loads((folder / ".lc-done.json").read_text())["status"], "failed")
+
+    def test_record_still_prunes_and_still_never_raises(self):
+        with mock.patch.object(retention, "prune") as prune:
+            runs.record("synthetic", "blur", {}, task(), 1.0)
+        prune.assert_called_once_with("runs")
+        with mock.patch.object(retention, "write_owner", side_effect=OSError("disk full")):
+            self.assertIsNone(runs.record("synthetic", "blur", {}, task(), 1.0))
+
+
+class HostFlow(Home):
+    """What Napari does, with the three functions: the folder exists from the start, the host finishes it, nothing is pruned."""
+
+    def make_old_records(self, count):
+        for index in range(count):
+            folder = self.home / "runs" / ("20260101T0000%02d_old_tool" % index)
+            folder.mkdir(parents=True, exist_ok=True)
+            retention.write_owner(folder, "run", "napari")
+            retention.write_done(folder, "ok")
+
+    def test_a_host_record_is_finished_without_a_prune_and_pruned_later_by_tools_only(self):
+        self.make_old_records(55)
+        folder = self.home / "runs" / "20261013T080000000000_synthetic_blur"
+        folder.mkdir()
+        retention.write_owner(folder, "run", "napari")
+        self.assertFalse((folder / ".lc-done.json").exists())  # started, not finished: nobody may remove it
+        content = runs.build_record(
+            "synthetic", "blur", INPUTS, task("CRASHED", cancel_requested=True), 2.0, run_id="r1"
+        )
+        (folder / "run.json").write_text(runs.record_json(content), encoding="utf-8")
+        retention.write_done(folder, runs.done_status("CRASHED", True))
+        self.assertEqual(json.loads((folder / ".lc-done.json").read_text())["status"], "cancelled")
+        self.assertEqual(json.loads((folder / "run.json").read_text())["run_id"], "r1")
+        self.assertEqual(len(list((self.home / "runs").iterdir())), 56)  # nothing was removed on the way
+        retention.prune("runs")  # the host's subprocess, run here
+        remaining = sorted(p.name for p in (self.home / "runs").iterdir())
+        self.assertEqual(len(remaining), retention.RUN_RECORDS_KEPT)
+        self.assertIn(folder.name, remaining)  # the newest is kept
+
+
+class Documented(unittest.TestCase):
+    def test_protocol_and_operations_describe_the_three_functions_and_the_version(self):
+        protocol = (ROOT / "docs" / "PROTOCOL.md").read_text(encoding="utf-8")
+        operations = (ROOT / "docs" / "OPERATIONS.md").read_text(encoding="utf-8")
+        for name in ("runs.build_record(", "runs.record_json(", "runs.done_status("):
+            self.assertIn(name, protocol)
+        for name in ("runs.build_record", "runs.record_json", "runs.done_status"):
+            self.assertIn(name, operations)
+        self.assertIn("not in 0.2.0rc1", protocol)
+        self.assertIn("There is no `features` id for them", protocol)
+        self.assertIn("There is no feature id for them", operations)
+
+    def test_there_is_no_feature_id_for_them(self):
+        from labconstrictor_tools import features
+
+        self.assertEqual(sorted(features.FEATURES), ["reserved_inputs_v1", "retention_prune"])
diff --git a/tests/test_sabotage.py b/tests/test_sabotage.py
index 44c453f..6b656e4 100644
--- a/tests/test_sabotage.py
+++ b/tests/test_sabotage.py
@@ -630,7 +630,7 @@ class Break:
     Break(
         "runs: a run record is not marked done",
         "runs.py",
-        '        retention.write_done(folder, _DONE_STATUS.get(task.status, "failed"))\n',
+        '        retention.write_done(folder, done_status(task.status, getattr(task, "cancel_requested", False)))\n',
         "        pass\n",
         unittest_slice(
             "test_retention.CliCreatesOwnedFolders.test_a_run_record_has_markers_and_old_records_are_pruned_without_touching_foreign_ones"
@@ -645,6 +645,123 @@ class Break:
             "test_retention.CliCreatesOwnedFolders.test_a_cancelled_or_crashed_run_record_says_so"
         ),
     ),
+    # ---- the run record without pruning, for hosts (docs/PROTOCOL.md; SPEC_WRONG_SCIENCE 3.2)
+    Break(
+        "runs: a crash after Cancel is recorded as failed",
+        "runs.py",
+        '    if task_status == "CRASHED" and cancel_requested:\n',
+        "    if False:\n",
+        unittest_slice("test_run_record_builder.DoneStatus.test_every_way_a_task_ends"),
+    ),
+    Break(
+        "runs: a crash with no Cancel is recorded as cancelled",
+        "runs.py",
+        '    if task_status == "CRASHED" and cancel_requested:\n',
+        '    if task_status == "CRASHED":\n',
+        unittest_slice("test_run_record_builder.DoneStatus.test_every_way_a_task_ends"),
+    ),
+    Break(
+        "runs: a failed task after Cancel is recorded as cancelled",
+        "runs.py",
+        '    return _DONE_STATUS.get(task_status, "failed")\n',
+        '    return "cancelled" if cancel_requested else _DONE_STATUS.get(task_status, "failed")\n',
+        unittest_slice("test_run_record_builder.DoneStatus.test_every_way_a_task_ends"),
+    ),
+    Break(
+        "runs: record does not read the Cancel flag of the task",
+        "runs.py",
+        'getattr(task, "cancel_requested", False)',
+        "False",
+        unittest_slice(
+            "test_run_record_builder.RecordKeepsItsBehaviour.test_a_crash_after_cancel_is_cancelled_in_the_record_folder_too"
+        ),
+    ),
+    Break(
+        "runs: record no longer prunes",
+        "runs.py",
+        '        retention.prune("runs")\n        return folder\n',
+        "        return folder\n",
+        unittest_slice(
+            "test_run_record_builder.RecordKeepsItsBehaviour.test_record_still_prunes_and_still_never_raises"
+        ),
+    ),
+    Break(
+        "runs: build_record always carries a run_id",
+        "runs.py",
+        '        **({"run_id": run_id} if run_id is not None else {}),\n',
+        '        "run_id": run_id,\n',
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_the_content_is_what_a_run_record_holds_and_nothing_else"
+        ),
+    ),
+    Break(
+        "runs: build_record always carries started_utc",
+        "runs.py",
+        '        **({"started_utc": started_utc} if started_utc is not None else {}),\n',
+        '        "started_utc": started_utc,\n',
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_the_content_is_what_a_run_record_holds_and_nothing_else"
+        ),
+    ),
+    Break(
+        "runs: build_record ignores the finished_utc it is given",
+        "runs.py",
+        "finished_utc or datetime.now(timezone.utc).isoformat()",
+        "datetime.now(timezone.utc).isoformat()",
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_the_content_is_what_a_run_record_holds_and_nothing_else"
+        ),
+    ),
+    Break(
+        "runs: build_record keeps the host-owned folder in the inputs",
+        "runs.py",
+        "if k != JOB_DIR_KEY",
+        "if True",
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_the_content_is_what_a_run_record_holds_and_nothing_else"
+        ),
+    ),
+    Break(
+        "runs: build_record keeps the matrix of a result",
+        "runs.py",
+        'if k != "matrix_yx"',
+        "if True",
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_the_content_is_what_a_run_record_holds_and_nothing_else"
+        ),
+    ),
+    Break(
+        "runs: build_record keeps the whole stderr",
+        "runs.py",
+        "stderr[-STDERR_TAIL_CHARS:]",
+        "stderr",
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_the_stderr_tail_is_cut_and_the_input_dict_is_left_alone"
+        ),
+    ),
+    Break(
+        "runs: build_record prunes",
+        "runs.py",
+        "    entry: Mapping[str, Any] = registry.load_all().get(app) or {}\n    return {\n",
+        '    entry: Mapping[str, Any] = registry.load_all().get(app) or {}\n    retention.prune("runs")\n    return {\n',
+        unittest_slice("test_run_record_builder.BuildRecord.test_it_writes_nothing_and_prunes_nothing"),
+    ),
+    Break(
+        "runs: record_json is not indented",
+        "runs.py",
+        "json.dumps(content, indent=2, default=str)",
+        "json.dumps(content, default=str)",
+        unittest_slice("test_run_record_builder.BuildRecord.test_the_text_is_what_record_writes"),
+    ),
+    Break(
+        "runs: record_json cannot write a value that is not JSON",
+        "runs.py",
+        "json.dumps(content, indent=2, default=str)",
+        "json.dumps(content, indent=2)",
+        unittest_slice(
+            "test_run_record_builder.BuildRecord.test_values_that_are_not_json_are_written_as_text"
+        ),
+    ),
     # ---- the conformance loader and its schema (docs/CONFORMANCE.md)
     Break(
         "conformance: a limit with an unknown status is valid",