beeverforge 0.1.0__py3-none-any.whl

beeverforge/namespace.py

@@ -0,0 +1,278 @@
+"""The directory this platform claims inside a CLIENT's repository, and the branches it mints there.
+
+The product is BeeverForge and the folder it writes into a client's repository is `.beeverforge/`
+(the product owner, 2026-08-07: everything lives under `.beeverforge`). The folder used to carry an
+acronym, and for a while this module was a MIGRATION: readers answered to both names, writers
+emitted only the new one. That code left on 2026-08-25, with the decision that the public
+repository has no old installation to migrate — the one deployment that ran under the former name
+renamed its own files.
+
+WHAT REMAINS OF THE OLD NAME IS A REFUSAL, NOT A READ. A repository that still carries the retired
+directory and nothing under the new one is refused BY NAME, with the sentence saying what to rename.
+The alternative — a reader that simply does not look there — would report "no manifest" to a
+repository that plainly has one, and the person reading that would go looking for a typo in a file
+the platform never opened. That is the absence-read-as-compliance class, and a rename is exactly
+where it breeds.
+
+AN EXPLICIT PATH IS NEVER OVERRIDDEN. `Project.manifest_path` exists so a client can put the file
+where their conventions say; the refusal below applies only to OUR default location, because the
+retired name has a twin only there.
+
+…AND THE ONE EXCEPTION IS A PULL REQUEST, which is written here because it is the exception to the
+paragraph above (GitHub issue #259). READING honours a `manifest_path` outside the repository,
+through the very same `root / relative` join — an absolute value wins it, which is exactly what
+makes setup, the gates, `box prove`, `doctor` and `conformance` work against a manifest the client
+keeps elsewhere.
+PROPOSING one cannot: a pull request carries only files that live in the repository it is opened
+on. So `env apply --pr` and `onboard` refuse such a row BY NAME, before they clone and before they
+write — they used to take the same join, write the manifest over the real file outside the
+throwaway clone, and only then be refused by `git add` with git's words about a path the platform
+had composed. `propose_manifest.leaves_the_repository` is that one rule, asked once.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+log = logging.getLogger("beeverforge.namespace")
+
+#: The directory this platform claims inside a client's repository.
+DIR = ".beeverforge"
+
+#: The prefix of every branch this platform mints in a client's repository — the job branches
+#: (`beeverforge/<ticket>`), the onboarding proposal, the environment rehearsal, the box proof.
+#: The most visible name the product has: it is born in EVERY pull request on the client's own
+#: repository, which is why it carries the product's name and not an acronym the client never
+#: chose (#106 item 5).
+BRANCH_PREFIX = "beeverforge"
+
+
+def job_branch(ticket_id: str, change: int = 0) -> str:
+    """The branch a job for `ticket_id` works on — the one name every job is known by.
+
+    Recalculated from the ticket id on every entry, so a repair or a resume finds the branch the
+    open pull request tracks without anybody storing it.
+
+    `change` IS WHICH CHANGE OF THE CARD THIS IS (#448 slice 4): 0 the first, and one more each
+    time its requester said "not yet" at the last gate — after the first change had MERGED. Every
+    change had this one name, and the box pushes with `--force` (`publish_branch`), so a second
+    change would have been pushed over the branch of the merged one. The first change keeps the
+    name it always had; a later one is `<prefix>/<id>-<n>`, n counting changes from 2 — a sibling
+    name, never `<prefix>/<id>/…`, which git refuses beside an existing `<prefix>/<id>`. It is
+    recalculated like the rest, from the change number the job carries (`JobParams.change`)."""
+    bare = str(ticket_id).lstrip('#')
+    return f"{BRANCH_PREFIX}/{bare}-{change + 1}" if change > 0 else f"{BRANCH_PREFIX}/{bare}"
+
+
+#: The two files that live in it, as the defaults every caller starts from.
+MANIFEST = f"{DIR}/project.yaml"
+PRODUCT_MANIFEST = f"{DIR}/product.yaml"
+
+#: The directory's RETIRED name. Named here, once, for one purpose: to refuse a repository still
+#: on it with a sentence, instead of reporting "no manifest" to somebody looking at one. Nothing
+#: reads under it; the guard in `tests/test_the_namespace_is_the_products_name.py` holds this to
+#: be the only module that spells it.
+RETIRED_DIR = ".sdlc"
+
+
+class RetiredNamespace(FileNotFoundError):
+    """A repository still on the retired directory name, and nothing under the current one.
+
+    A `FileNotFoundError` on purpose: to every caller that already handles a missing manifest, this
+    IS a missing manifest — the only difference is that the sentence says what to rename, which is
+    the difference between a client fixing it in a minute and hunting a typo in a file the platform
+    never opened."""
+
+
+def _retired_twin(relative: str) -> str:
+    """The same path under the retired directory name, or `""` when it is not one of ours."""
+    # `removeprefix("./")`, NOT `lstrip("./")`. `lstrip` takes a SET of characters and eats every
+    # leading `.` or `/` there is — `.beeverforge/project.yaml` became `beeverforge/…`, matched
+    # nothing, and every project fell through to "no manifest" (34 tests red, the day the rename
+    # landed). Kept as a comment because the two names still differ by a leading dot.
+    rel = str(relative).replace("\\", "/").removeprefix("./")
+    if rel == DIR or rel.startswith(f"{DIR}/"):
+        return RETIRED_DIR + rel[len(DIR):]
+    return ""
+
+
+def resolve(root: Path, relative: str, *, project: str = "") -> Path:
+    """The path to read — and a refusal, by name, when only the retired twin is there.
+
+    Returns `root / relative` whether or not it exists: "missing" is then reported in the name we
+    use, and a client reading the error is told what to create. The one thing this never does is
+    answer with the retired path or pretend it did not see it.
+    """
+    new = root / relative
+    if new.exists():
+        return new
+    old_rel = _retired_twin(relative)
+    if old_rel and (root / old_rel).exists():
+        raise RetiredNamespace(
+            f"project {project or root.name!r} has no manifest at {new} — it has one at "
+            f"`{old_rel}`, which is this platform's former name and is not read. Rename the "
+            f"directory `{RETIRED_DIR}/` to `{DIR}/` in that repository; nothing under "
+            f"`{RETIRED_DIR}/` is read.")
+    return new
+
+
+def operator_path(filename: str) -> Path:
+    """The operator's file under `~/.beeverforge/` — the registry, the approver store, the resume
+    handles.
+
+    Called from the composition points that resolve these paths (`ProjectRegistry.__init__`,
+    `approvals.store_path`), never at import — the house has paid for import-time side effects
+    before. An explicit override (env var, argument) bypasses this entirely: an explicit path is
+    never second-guessed."""
+    return Path.home() / DIR / filename
+
+
+#: Where a process leaves the build it runs from, for the OTHER halves of the deployment to read
+#: (#135). One file per ROLE — `build-worker.json`, `build-panel.json`.
+#:
+#: HALF A STACK CAN BE STALE AND NOTHING SAYS SO. `build_stamp()` answers "which code am I", and
+#: every surface that prints it prints its OWN — so the worker's doctor line said one build while
+#: the panel served a page from a build twenty-eight hours older, and the operator read the old
+#: page reporting the old state with no way to tell (pilot, 2026-08-17: I had told him to rebuild
+#: only the worker, and the fix he was looking for lived in the panel).
+#:
+#: PER ROLE, AND SYMMETRIC, because the stale half is whichever one you did not rebuild — naming a
+#: file after the role that happened to be fresh in the first episode would bake this deployment's
+#: accident into the product. Every process that serves a surface announces; every surface can name
+#: the ones that disagree with it, including roles that do not exist yet.
+BUILD_FILE = "build-{role}.json"
+
+
+def announce_build(role: str, *, where: str = "") -> str:
+    """Record THIS process's build under `role`, in the shared state directory. Returns the stamp.
+
+    Best-effort: a deployment whose state directory is read-only still boots — it simply cannot say
+    what it is running, which is where this started, so the failure is logged rather than raised."""
+    import json
+
+    stamp, built = build_stamp()
+    if not stamp:
+        # NOT A BUILT IMAGE — a checkout, where the code on disk IS the code running and there are
+        # no separate halves to disagree. Announcing here would mean creating
+        # `/var/lib/beeverforge` on somebody's laptop (or logging a permission warning on every
+        # boot when that fails) to record that we are nothing in particular.
+        return ""
+    root = _state_dir(where)
+    try:
+        root.mkdir(parents=True, exist_ok=True)
+        (root / BUILD_FILE.format(role=role)).write_text(
+            json.dumps({"stamp": stamp, "built_at": built}), encoding="utf-8")
+    except OSError as exc:
+        log.warning("could not record this %s's build for the rest of the deployment to read (%s) "
+                    "— a stale half beside a fresh one will stay invisible", role, exc)
+        return ""
+    return stamp
+
+
+def announced_builds(*, where: str = "") -> dict[str, tuple[str, str]]:
+    """`{role: (stamp, built_at)}` for every half that has announced. Empty when none has.
+
+    EMPTY IS NOT A DISAGREEMENT. A deployment whose other half predates this, or whose halves do
+    not share a state directory, has told us nothing — and nothing is what a caller must be able to
+    distinguish from "told us, and it differs"."""
+    import json
+
+    found: dict[str, tuple[str, str]] = {}
+    root = _state_dir(where)
+    try:
+        files = sorted(root.glob(BUILD_FILE.format(role="*")))
+    except OSError:
+        return found
+    prefix, suffix = BUILD_FILE.split("{role}")
+    for f in files:
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue  # a half-written file is one we have not been told about yet
+        role = f.name[len(prefix):-len(suffix)] if suffix else f.name[len(prefix):]
+        found[role] = (str(data.get("stamp") or ""), str(data.get("built_at") or ""))
+    return found
+
+
+def _state_dir(where: str = "") -> Path:
+    """The directory the halves of this deployment share. Compose mounts it into both."""
+    return Path(where or os.environ.get("BEEVERFORGE_STATE_DIR") or "/var/lib/beeverforge")
+
+
+def build_disagreement(role: str, *, where: str = "") -> dict[str, tuple[str, str]]:
+    """The halves whose build differs from THIS process's, `{role: (stamp, built_at)}`.
+
+    Empty means either "everybody agrees" or "there is nothing to compare" — callers that need to
+    tell those apart (the panel's banner does; it must not cry wolf) check `build_stamp()` and
+    `announced_builds()` themselves."""
+    mine, _ = build_stamp()
+    if not mine:
+        return {}
+    return {r: v for r, v in announced_builds(where=where).items()
+            if r != role and v[0] and v[0] != mine}
+
+
+def build_stamp() -> tuple[str, str]:
+    """`(code-hash, built-at)` for the image this process runs from — `("", "")` outside one.
+
+    THE QUESTION NOBODY COULD ANSWER (2026-08-14). The compose worker BAKES the package, so
+    `git pull && docker compose up -d` restarts the previous build and every command inside
+    keeps answering from it — silently, indistinguishably. The pilot operator ran the same
+    diagnostic three times against fixes that were on his disk and not in his worker, and
+    neither he nor I could tell from the output; I had told him the rebuild was optional, which
+    was wrong. A running deployment must be able to say WHICH code it is.
+
+    Read from a file the image writes at build time (`docker/worker.Dockerfile`). Absent means
+    "not a built image" — a laptop checkout, where the code on disk IS the code running — and
+    that is reported as such rather than invented."""
+    import json
+    from pathlib import Path
+
+    try:
+        data = json.loads(Path("/etc/beeverforge/build.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return "", ""
+    return str(data.get("code") or ""), str(data.get("built_at") or "")
+
+
+# ── whether the halves of this deployment agree, as a REPORT ─────────────────────────────────
+#
+# MOVED OUT OF `api/app.py` (#144). Which code each half runs is a fact about the deployment,
+# not about the web layer — the floor's ladder, the CLI and any channel need the same answer,
+# and a second copy is how two surfaces come to disagree about what is even running.
+def build_agreement(role: str = "panel") -> dict:
+    """Which code each half of this deployment runs, and whether they agree (#135).
+
+    A COMPOSE STACK IS TWO IMAGES, and both BAKE the package. `docker compose up -d --build worker`
+    leaves the panel serving whatever it was built from — so on 2026-08-17 the pilot rebuilt,
+    pressed
+    F5, and read a page from an image twenty-eight hours older, reporting the older world. `docker
+    ps`
+    said `Up 28 hours` beside `Up 2 minutes`, and nothing on the screen he was actually looking at
+    could say it. He spent the round believing a fix had not worked.
+
+    Each process could only ever print its OWN stamp, which is why this needs the state volume both
+    of them mount: the worker WRITES its build there at boot, and the panel reads it back here.
+
+    THREE ANSWERS, and the third is not a failure:
+
+        agree = True    both halves report the same build
+        agree = False   they differ — PROVEN, and the panel says so in the loudest place it has
+        agree = None    it cannot be established, and no claim is made. Either this is not a built
+                        image at all (a checkout: one tree, no halves to disagree) or the worker
+                        has not announced — an older worker, or a deployment whose halves do not
+                        share a state directory. Silence beats a false alarm on a working stack,
+                        and beats a false all-clear on a split one.
+    """
+    mine, mine_at = build_stamp()
+    others = {r: v for r, v in announced_builds().items() if r != role and v[0]}
+    if not mine or not others:
+        agree: bool | None = None
+    else:
+        agree = all(stamp == mine for stamp, _ in others.values())
+    return {
+        "role": role, "stamp": mine, "built_at": mine_at, "agree": agree,
+        "others": {r: {"stamp": s, "built_at": b} for r, (s, b) in sorted(others.items())},
+    }

beeverforge/observability/__init__.py

@@ -0,0 +1,23 @@
+from beeverforge.observability.events import (
+    EventKind,
+    EventSink,
+    FileEventSink,
+    InMemoryEventSink,
+    JobEvent,
+    NullEventSink,
+    StdoutEventSink,
+    TeeEventSink,
+    now_iso,
+)
+
+__all__ = [
+    "EventKind",
+    "EventSink",
+    "FileEventSink",
+    "InMemoryEventSink",
+    "JobEvent",
+    "NullEventSink",
+    "StdoutEventSink",
+    "TeeEventSink",
+    "now_iso",
+]

beeverforge/observability/autonomy.py

@@ -0,0 +1,233 @@
+"""Autonomy, as a number read off the card's record (#85, hole 4).
+
+THE FACTS EXISTED AND NOTHING READ THEM. Every pass a job makes is an `agent_run` row tagged with
+its role (`orchestrator/machine.py::_count`), and since ADR-0055 every card's life is a record of
+transitions (`lifecycle/record.py`). Whether a card reached its merge on the factory's first try —
+or took three repairs, a park and a person's adjustment — was in those rows for every card, and
+"is the factory getting better?" was answered by opening twenty job pages. This reads them once.
+
+A CARD IS MEASURED ONLY WHEN THE RECORD HOLDS ITS START. A measured card's record holds `promoted`
+before its first `merged`: the moment the factory was handed the card, and the moment it landed.
+Cards only carry `promoted` since #414 (2026-10-04), so every card merged before that — and any
+card whose promotion the record does not hold — is counted on its own, by name, as BEFORE THE
+RECORD, and never enters a rate. A yield over cards whose start nobody recorded is a yield over
+whichever of them happened to be recorded.
+
+THE DEFINITIONS, one decision each:
+
+    first-pass      a measured merged card with NO repair-role pass and no `parked`, `resumed` or
+                    `adjusted` between its promotion and its merge. `question_asked` and
+                    `accepted` are gates the design puts in the road, not somebody stepping in.
+    yield           first-pass cards over measured merged cards — `None` when there are none,
+                    never 0: a factory that merged nothing did not fail every card
+    rework rate     code-writing passes (the executor and the five repair roles) per measured
+                    merged card; 1 is one pass each. The planner and the reviewer write no code
+                    and are not rework
+    repair depth    how many measured merged cards took 0, 1, 2 and 3+ repair passes
+    park reasons    every `parked` row, read into the tech-lead's own taxonomy
+                    (`techlead/classify.py`) from the note it recorded — said as "classified from
+                    the recorded note", because the park did not declare its class (a park that
+                    records one is a follow-up). A note nobody can read is `unknown`, never
+                    `transient`: guessing "it passes on its own" is how a broken thing looks fine
+
+A PASS BELONGS TO ITS CARD, NOT TO A WINDOW. The `agent_run` rows are written when the job ends,
+which on the attended driver is AFTER the merge it handed back went through the door
+(`cli._run_and_record`), so bounding them by the merge's time would drop every pass of a card the
+job merged itself. Every pass recorded for the card counts; the record's sequence, not a clock,
+bounds the interventions.
+
+THE RECORD WINS OVER THE JOB'S ROW. A job row is written once, at the job's end, and says how far
+THAT job got — `pr_open`, while the merge a person made an hour later is in the record. A job row
+past the merge is read only to name a card BEFORE THE RECORD that the record never saw merge.
+
+READ-ONLY AND PURE. Rows in, a dict out: it reads no store, writes nothing, calls no door and
+starts nothing that spends. The CLI hands it `scan_all_or_raise`'s rows and the cost dashboard
+the rows it already scanned, so `beeverforge autonomy --json` and `/api/metrics`'s `autonomy`
+block are one function's answer and cannot disagree.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterable
+from datetime import UTC, datetime
+
+#: The pass that writes the code the first time (`machine.py::_count(…, "executor")`).
+EXECUTOR = "executor"
+
+#: The passes that write code AGAIN because what was written did not hold — each tagged where it
+#: runs: a validation that failed (`repair`), a suppression the gate refused, a review's findings,
+#: a red CI, and a box that died mid-pass (`recovery`). Any one of them on a card means the card
+#: did not land on the factory's first try.
+REPAIR_ROLES = frozenset({"repair", "suppression_repair", "review_repair", "ci_repair",
+                          "recovery"})
+
+#: What counts as rework: every pass that writes code. The planner plans and the reviewer reads;
+#: counting them would make a project that turned review on look like it repairs more.
+WRITES_CODE = frozenset({EXECUTOR, *REPAIR_ROLES})
+
+#: Somebody stepping in between the promotion and the merge: a park, its resumption, and the
+#: release manager's adjustment. `question_asked` and `accepted` are not here — the design asks
+#: them, and a card that waited at a gate it was meant to wait at did not need rescuing.
+INTERVENTIONS = frozenset({"parked", "resumed", "adjusted"})
+
+PROMOTED, MERGED, PARKED = "promoted", "merged", "parked"
+
+#: The repair-depth buckets, in the order the table reads.
+DEPTHS = ("0", "1", "2", "3+")
+
+
+def _said(key: str, language: str | None, **params: object) -> str:
+    from beeverforge.techlead import voice
+
+    return voice.say(voice.AUTONOMY, key, language, **params)
+
+
+def _moment(value: object) -> datetime | None:
+    """A row's time, as a moment — `None` for one that does not parse. A naive time is UTC: every
+    writer here stamps an offset, and a test or a hand-written row that did not means UTC."""
+    if isinstance(value, datetime):
+        found = value
+    else:
+        try:
+            found = datetime.fromisoformat(str(value or "").strip())
+        except ValueError:
+            return None
+    return found if found.tzinfo else found.replace(tzinfo=UTC)
+
+
+def _within(ts: object, start: datetime | None) -> bool:
+    """Whether a row's time is in the window. With no window, every row is; with one, a row whose
+    time does not parse is NOT — a card cannot be claimed for a week nobody can place it in."""
+    if start is None:
+        return True
+    when = _moment(ts)
+    return when is not None and when >= start
+
+
+def _project_of(row: dict) -> str:
+    return str(row.get("pk") or row.get("project") or "")
+
+
+def _decimal(value: float, language: str | None) -> str:
+    """A rate as a person in that language writes one: `1.67`, `1,67`."""
+    text = f"{value:.2f}".rstrip("0").rstrip(".")
+    return text.replace(".", ",") if (language or "").lower().startswith("pt") else text
+
+
+def _labels(language: str | None) -> dict:
+    keys = ("title", "yield", "rework", "measured", "before", "depth", "repairs", "cards",
+            "parks", "cause", "count")
+    return {k: _said(f"label.{k}", language) for k in keys}
+
+
+def autonomy(records: Iterable[dict], project: str, *, since: object = None,
+             language: str | None = None) -> dict:
+    """The autonomy block for `project`, from `records` — the store's rows as a scan returns them,
+    every project and every kind (it keeps its own).
+
+    `since` (a moment, or an ISO time) narrows it to the cards whose first merge — and the parks —
+    happened from then on; `None` is the whole record. `language` is the project's: the numbers
+    are numbers, and every sentence and label beside them is in it."""
+    from beeverforge.contracts.refs import canonical_ref, ref_sort_key
+    from beeverforge.contracts.state import PAST_THE_MERGE
+    from beeverforge.lifecycle import record
+    from beeverforge.techlead.classify import CLASSES, classify
+
+    start = _moment(since) if since is not None else None
+    mine = [r for r in records if _project_of(r) == project]
+    histories = record.histories([r for r in mine if r.get("kind") == record.KIND])
+
+    # EVERY PASS ON ITS CARD, joined by the ref's one spelling: `#12` and `12` are one card, and
+    # `DAR-12` is a card too — never reduced to a number that would drop it or meet another's
+    roles: dict[str, list[str]] = {}
+    job_merged: dict[str, str] = {}
+    for row in mine:
+        ticket = canonical_ref(row.get("ticket"))
+        if row.get("kind") == "agent_run":
+            roles.setdefault(ticket, []).append(str(row.get("role") or ""))
+        elif row.get("kind") == "job" and str(row.get("state") or "") in PAST_THE_MERGE:
+            ts = str(row.get("ts") or "")
+            job_merged[ticket] = min(job_merged.get(ticket, ts), ts)
+
+    measured: list[tuple[int, int, bool]] = []   # (repair passes, code passes, first-pass)
+    before: list[str] = []
+    reasons: Counter[str] = Counter()
+    for card, history in histories.items():
+        for row in history.rows:
+            if row.event == PARKED and _within(row.ts, start):
+                facts = row.facts or {}
+                text = str(facts.get("note") or facts.get("reason") or row.why or "")
+                state = str(facts.get("job_state") or "")
+                reasons[classify(text, state=state).cause] += 1
+        merged = next((r for r in history.rows if r.event == MERGED), None)
+        if merged is None or not _within(merged.ts, start):
+            continue
+        promoted = next((r.seq for r in history.rows
+                         if r.event == PROMOTED and r.seq < merged.seq), None)
+        if promoted is None:
+            before.append(card)
+            continue
+        stepped_in = any(r.event in INTERVENTIONS for r in history.rows
+                         if promoted < r.seq < merged.seq)
+        passes = roles.get(canonical_ref(card), [])
+        repairs = sum(1 for role in passes if role in REPAIR_ROLES)
+        code = sum(1 for role in passes if role in WRITES_CODE)
+        measured.append((repairs, code, not repairs and not stepped_in))
+    for card, ts in job_merged.items():
+        held = histories.get(card)
+        if held is not None and any(r.event == MERGED for r in held.rows):
+            continue   # the record saw it merge, and the record has spoken above
+        if _within(ts, start):
+            before.append(card)
+
+    n = len(measured)
+    clean = sum(1 for _, _, first in measured if first)
+    code_passes = sum(code for _, code, _ in measured)
+    depth = Counter(DEPTHS[min(repairs, 3)] for repairs, _, _ in measured)
+    window = (_said("window", language, day=start.date().isoformat()) if start is not None
+              else "")
+    rate = round(code_passes / n, 4) if n else None
+    parks = sum(reasons.values())
+    block = {
+        "project": project,
+        "readable": True,
+        "since": start.isoformat() if start is not None else None,
+        "measured": n,
+        "first_pass": clean,
+        "yield": round(clean / n, 4) if n else None,
+        "code_passes": code_passes,
+        "rework_rate": rate,
+        "repair_depth": {d: depth.get(d, 0) for d in DEPTHS},
+        "before_the_record": sorted(set(before), key=ref_sort_key),
+        "parks": parks,
+        "park_reasons": dict(sorted(reasons.items(), key=lambda kv: (-kv[1], kv[0]))),
+    }
+    block["said"] = {
+        "title": _said("title", language, project=project),
+        "headline": (_said("yield", language, clean=clean, merged=n, window=window,
+                           pct=round(clean / n * 100)) if n
+                     else _said("none", language, window=window)),
+        "rework": (_said("rework", language, passes=code_passes, rate=_decimal(rate, language))
+                   if rate is not None else ""),
+        "before_the_record": (_said("before", language, count=len(block["before_the_record"]))
+                              if block["before_the_record"] else ""),
+        "scope": _said("scope", language),
+        "parks": (_said("parks", language, count=parks, window=window) if parks
+                  else _said("parks.none", language, window=window)),
+        "labels": _labels(language),
+        # EVERY CLASS THE CLASSIFIER HAS, each a word in the phrasebook — read from it, never a
+        # copy, so the table never shows a class it cannot name (review of #545)
+        "causes": {c: _said(f"cause.{c}", language) for c in CLASSES},
+    }
+    return block
+
+
+def unread(project: str, cause: object, *, language: str | None = None) -> dict:
+    """The block when the store would not answer: no number at all, and the sentence that says
+    why and what to check. NEVER the empty record's block — "no card measured yet" from a store
+    nobody could read is the factory claiming a fact it did not look at (#126)."""
+    return {"project": project, "readable": False,
+            "said": {"title": _said("title", language, project=project),
+                     "headline": _said("unread", language, cause=str(cause).rstrip(".")),
+                     "labels": _labels(language)}}