#!/usr/bin/env python3
"""tools/restruct.py — the struct/declaration rewrite engine (Phase 37 T3, 2026-09-12; the T2 probe form kept inside it).

    tools/restruct.py --plan --rung S|D|L [--batch N] [--headers] [--only X …]        # what the next batch would touch (no writes)
    tools/restruct.py --apply --rung S|D|L --batch N --label <lbl> [--headers] [--only X …] [-j N]
                                                                                       # judge every unit of the batch's files, KEEP the winning
                                                                                       # texts in place (the outer gate — R22 — follows), ledger every site
      (rung D with `--redraw KEY`: lifted decl units with no lying declaration left get a superseding DECL-NONE row; --plan reports them, P3.39 T1)
    tools/restruct.py --apply --rung D --callee F --signature "void F(s32 a)" --label <lbl>   # a definition-side signature change: the definition's
                                                                                       # TU + every TU declaring F, one judged unit (the 24 parked patches)
    tools/restruct.py --restore                                                        # every in-flight file back from inflight.json (never git checkout, R102)
    tools/restruct.py --status                                                         # the ledger's totals per rung
    tools/restruct.py --status --rung L --only <CanonType> …                           # the HEAD-FOLD rows (latest per unit): verdict -> cause -> units
      (rung L with `--only <CanonType> …` = HEAD-FOLD mode, P38 T4: same-size other-layout definitions -> `typedef <Canon> <Local>;` + renames)
    tools/restruct.py --check-ledger                                                   # every MEMBER site still a leaf of its (current) canonical type
    tools/restruct.py --rung S --residue --label <lbl> [--only X …] [--forms P,X]      # T3.c7: a no-edit RESIDUAL(<cause>) row per body with uncovered
                                                                                       # sites (ledger only); T10.c1: a body with a latest S row gets a
                                                                                       # MERGED copy of it + one RESIDUAL entry per uncovered site
    tools/restruct.py --check-residue [--only X …] [--forms P,X]                       # census sites (default ov_*, forms P,X; I,M accepted) not covered
                                                                                       # per site (form, normalised base, off; multiset) by a RESIDUAL
                                                                                       # entry of the body's latest S row; exit 1 if any
      residue causes: FILE-SCOPE, NO-TYPE-IN-MAP, TYPE-NOT-CANONICAL, TYPE-NOT-VISIBLE, else site_class's (MISALIGNED, NO-EDIT, …);
      I/M forms add ABS-ADDR (bclass abs: a fixed address), GADDR (bclass gaddr: `&D_x` reinterpreted) and GLOBAL (bclass global: a
      global's storage reinterpreted)
    tools/restruct.py --plan|--apply --rung S --forms I,M [--only X …] --batch N --label <lbl>   # T5.c2: ONLY the bodies with uncovered
                                                                                       # I/M sites on a global base (gaddr/global); the R ladder
                                                                                       # on them (no struct spelling); the body's latest S row merged
      I/M ladder causes (RESIDUAL(<Rn-CAUSE>), the most specific refusal): R1/R2/R3-NOT-GLOBAL, R3-NOT-CARVED, R<n>-STILL-RAW (the cast
      respelled, not removed), R2-HEADER-EXTERN (no extern in the TU), R2/R3-NO-SCALAR-EXTERN, R3-NO-BODY, R2-MISALIGNED, R2-WIDTH
      (the site's width != the extern's), R3-NOT-CONTIGUOUS, R<n>-NO-EDIT, R<n>-REKEYS (another raw/macro site's key would move),
      R<n>-<verdict> (judged: DIFFERS, COMPILE-ERROR …)
    tools/restruct.py --audit-types                                                    # the naming invariant over the canonical type files (struct_layout.audit_definition)
    tools/restruct.py --write-types --top N | --type NAME … [--space ov]               # the WRITER: canonical definitions rendered from the struct map (a preview)
    tools/restruct.py --selftest [--real]                                              # the fixture (a stub oracle); --real adds the calibration + known-true controls
    tools/restruct.py --try TU FN [--base bclass:name] [--recipes]                     # T2's rung 1 on one body (local P37S_ type) + S2 + S+A [+ the R recipes]
    tools/restruct.py --probe | --probe-decls | --probe-defs | --audit-layouts | --fanout-cost   # the T2 probes (unchanged)

THE RUNGS (deterministic first; every verdict on the bytes through tools/delever_oracle.py — whole-object equality against the fleet run's
snapshot, then the LINKED mode when only the relocation spelling moved — R110):
  S    struct spelling on EVERY typed base of a body: `*(u16 *)(a0 + 0x3C)` -> `((Unkstruct_X *)a0)->unk3C` (or `a0->unk3C` when a0 is
       already declared `Unkstruct_X *`; `D_x.unk3C` when the global is declared with the type). The type comes from the struct map and
       must be a CANONICAL definition visible to the TU (`--apply`); `--try` builds T2's body-local `P37S_<hash>` type from the map's layout.
       A site the type cannot hold is SKIPPED and counted (no-field / width / sign / index / negative / pointee / overlap) — T5's authoring residue.
  S2   the member spelling DIFFERS -> the minimal set of sites that must stay casts (leave-one-out, then cumulative revert in source order,
       then minimise — delever's rung-B shape, <= 2n+1 compiles); the kept casts are ledgered KEPT with their residual and a pass HINT (X).
  S+A  a lever-bearing body: the struct-spelled text run through delever's ladder (rung A strip-all, rung B greedy) — the struct hypothesis;
       survivors keep/receive their `// !FAKE:` marker attributed `(P37 S+A <label>)` and a row in delever's ledger too (one lever record).
  X    the residual of a DIFFERS candidate, classified (delever_search.classify: REG / COUNT / ORDER / MIXED) and named by the pass it
       most resembles: SCHED-ALIAS (a load hoisted over a `/s` store), CSE-KILL (a reload added/removed), WIDTH (andi/sll-sra), ADDRESS-FOLD
       (an addend moved), ALIGNMENT (lwl/lwr), REGALLOC, OTHER. A hint for the readings (R65 needs the dump line), never a verdict.
  R    recipes for a KEPT cast — the shapes the record already proves: R1 the pointer global read as a struct member (§458: both sides `/s`),
       R2 a scalar global declared `extern T X[]` (a18: the MEM_IN_STRUCT alias escape), R3 consecutive carved words walked through one
       pointer (f3; relocation spelling -> the linked oracle). A registry (RECIPES) with a fixture each; T7's harvest -> toolify adds to it.
  D    declarations: EVERY declaration of a callee in a TU replaced by the canonical prototype — the DEFINITION's ANSI signature, else its
       width-promoted form (`s16 a` -> `s32 a`: what a K&R call passes), else kept `()` with `// K&R: n of m args (P37 rung D <label>)` when
       the TU's calls pass another count (the byte-proven K&R sites, counted apart). Ladder per TU: all callees at once, else one at a time.
       `--callee/--signature`: a DEFINITION-side change judged on the definition's TU and every TU that declares it (one unit, all IDENTICAL).
  L    definition folds: a TU's file-scope duplicate of a canonical type (same layout; tier 1 same-named -> deleted when the text is identical,
       tier 2 opaque -> `typedef <Canon> <Local>;` with the TU's member accesses renamed by the offset map — REFUSED when a local member name
       is also a member of another type visible in the TU (a textual rename could hit the other)).

THE ENGINE PATTERN (tools/delever.py's, R43/R48/R102/R111/R114): positional token-exact edits on the raw text (the census's records re-walked
on the CURRENT file — positions are never cached); the FILE is the write unit and its final compile through every recipe (a twin's object,
every includer of a header) is the proof — IDENTICAL or the file is restored and REFUSED loudly (COMBINATION-FAILED); every original text is
in .run/P37/restruct/inflight.json before the first write and --restore reads it; the ledger .run/P37/restruct/ledger.jsonl keys a unit by
(rung, tu, unit, body hash before/after) — "done" is per body, never by text alone; workers own whole TUs; headers run serially after the
TUs and are judged on every includer, a fan-out COMPILE-ERROR retried once (T2 (h)); the batch's touched files are left in place for the
outer gate (the clean fleet run, R22) which tools/restruct_cycle.sh runs before the commit.
"""
import argparse
import collections
import contextlib
import difflib
import fcntl
import fnmatch
import hashlib
import json
import os
import pathlib
import random
import re
import subprocess
import sys
import threading
import time
from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor

sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
import share_census as sc          # noqa: E402
import type_census as tc           # noqa: E402
import struct_layout as sl         # noqa: E402
import delever as dl               # noqa: E402
import delever_oracle as oracle    # noqa: E402
import delever_search as ds        # noqa: E402
import lever_census as lc          # noqa: E402
import masked_diff as md           # noqa: E402
from struct_layout import field_offsets   # noqa: E402,F401  (the T2 audit's helper; lives in struct_layout since T3)

REPO = pathlib.Path(__file__).resolve().parent.parent
CENSUS = REPO / ".run/P37/census"
PROBE = REPO / ".run/P37/probe"
RUN = REPO / ".run/P37/restruct"
LEDGER = RUN / "ledger.jsonl"
INFLIGHT = RUN / "inflight.json"
RAW_FORMS = ("P", "I", "X", "M")
TYPE_OF = sl.TYPE_OF
CANON_HEADERS = tc.CANON_HEADERS
KR_MARK = "// K&R:"
_LOCK = threading.Lock()
_APPLY_LOCK_F = None               # the --apply process lock's open file (held for the process's life)


class Refuse(Exception):
    pass

# ----------------------------------------------------------------------------------------------------------------------
# the census's view of a body
# ----------------------------------------------------------------------------------------------------------------------
_map_cache = None

def struct_map():
    global _map_cache
    if _map_cache is None:
        p = CENSUS / "struct_map.json"
        if not p.exists():
            sys.exit("restruct: no struct map — run `tools/type_census.py -j 16 --sites` first")
        _map_cache = {t["name"]: t for t in json.loads(p.read_text())["types"]}
    return _map_cache

def body_sites(tu, fn):
    """The census's site records for one body, RE-WALKED on the current file (positions on the raw text via a same-length mask)."""
    raw = (REPO / tu).read_text(errors="surrogateescape")
    masked = dl.same_len_mask(raw)
    line_of = lambda idx: masked.count("\n", 0, idx) + 1
    recs = sc.scan_text(raw, tu, shared_defs=None)
    defs = [r for r in recs if r["form"] == "def"]
    span_of_line = {}
    for d in defs:
        for ln in range(d["line"], d["end"] + 1):
            span_of_line[ln] = d
    params_of = {}
    for d in defs:
        head_start = dl.line_starts(masked)[d["line"] - 1]
        brace = masked.find("{", head_start)
        head = masked[head_start:brace] if brace != -1 else ""
        m = re.search(r"\b" + re.escape(d["name"]) + r"\s*\(", head)
        if not m:      # an alias-named def (`f_impl(…) __asm__("f")`): the first ident( — the census's rule (T3.c4: was local:param_N)
            m = re.search(r"\b(" + tc.NAME + r")\s*\((?=[^;]*\))", head)
        if m:
            inner, close = tc._paren_body(head, m.end() - 1)
            params_of[d["name"]] = tc._param_names(inner or "", head[close + 1:] if close != -1 else "")
    sites, _ = tc.find_sites(masked, tu, span_of_line, line_of, params_of)
    d = next((x for x in defs if x["name"] == fn), None)
    return raw, masked, d, [s for s in sites if s.get("fn") == fn]

def field_type(w, sg, ctypes):
    if sg == "p":
        # a pointer field: the sites' pointee when they agree, else void *
        pt = collections.Counter(c.rstrip("* ").strip() + " *" for c in ctypes if c and c.count("*") >= 2)
        return pt.most_common(1)[0][0] if len(pt) == 1 else "void *"
    return TYPE_OF.get((w, sg))

def build_type(tname, layout, ctypes_by_off):
    """The struct text for a cluster's layout [(off, w, sign, n)]: fields at their offsets, pads between, overlaps skipped.
    Returns (text, fields{off: (w, sign, name)}, skipped)."""
    fields, skipped, lines, cur = {}, [], [], 0
    for (off, w, sg, n) in sorted(layout, key=lambda x: (x[0], -x[3])):
        if off < cur or w is None or w == 0:
            skipped.append((off, w, sg))
            continue
        if off % (8 if w == 8 else min(w, 4)) != 0:
            # an access at an offset its width cannot be aligned to (an `lh` at +0x79): not a field of THIS base — a cross-base
            # contamination of the cluster, or an unaligned lwl/lwr pair; gcc would realign it and shift every later field
            skipped.append((off, w, "misaligned"))
            continue
        t = field_type(w, sg, ctypes_by_off.get(off, []))
        if t is None:
            skipped.append((off, w, sg))
            continue
        if off > cur:
            lines.append(f"    /* {cur:#06x} */ u8 pad{cur:X}[{off - cur:#x}];")
        name = f"unk{off:X}"
        lines.append(f"    /* {off:#06x} */ {t} {name};")
        fields[off] = (w, sg, name, t)
        cur = off + w
    text = f"typedef struct {{\n" + "\n".join(lines) + f"\n}} {tname}; /* P37 rung 1 — from the struct map (size >= {cur:#x}) */\n"
    return text, fields, skipped

def rung1_edits(raw, d, sites, tname, fields, base_key):
    """The positional edits of rung 1 for one body/base: [(pos, end, replacement, site)], skips{reason: n}."""
    edits, skips = [], collections.Counter()
    bcls, bname = base_key.split(":", 1)
    for s in sites:
        if s["form"] not in RAW_FORMS or s.get("bclass") != bcls or str(s.get("base")) != bname:
            continue
        if s.get("index") is not None or s.get("refused"):
            skips["index"] += 1
            continue
        off = s.get("off") or 0
        if off < 0:
            skips["negative-offset"] += 1
            continue
        f = fields.get(off)
        if f is None:
            skips["no-field"] += 1
            continue
        w, sg, name, ftype = f
        if s.get("width") != w:
            skips["width"] += 1
            continue
        if s.get("sign") != sg and not (s.get("access") in ("store",) and {s.get("sign"), sg} <= {"s", "u"}):
            skips["sign"] += 1
            continue
        if sg == "p":
            # a pointer field: the site's pointee must be the field's (a `void *` field cannot be indexed or dereferenced at the site)
            site_pointee = (s.get("ctype") or "").rstrip("* ").strip() + " *"
            if site_pointee != ftype:
                skips["pointee"] += 1
                continue
        base_expr = ("&" + bname) if bcls == "gaddr" else bname
        edits.append((s["pos"], s["end"], f"(({tname} *){base_expr})->{name}", s))
    edits.sort(key=lambda e: e[0])
    kept, last = [], 0
    for e in edits:
        if e[0] < last:
            skips["overlap"] += 1       # a nested site's inner span inside an outer's — the outer was skipped as `nested`
            continue
        kept.append(e); last = e[1]
    return kept, skips

def splice(raw, d, tname, edits):
    """The TU text with the given edits applied and the typedef inserted before the function (file scope)."""
    out, last = [], 0
    for (a, b, rep, _) in sorted(edits, key=lambda e: e[0]):
        out.append(raw[last:a]); out.append(rep); last = b
    out.append(raw[last:])
    text = "".join(out)
    ins = dl.line_starts(raw)[d["line"] - 1]
    return text[:ins] + _typedef_cache[tname] + text[ins:]

def rung1_text(raw, d, sites, tname, fields, base_key):
    edits, skips = rung1_edits(raw, d, sites, tname, fields, base_key)
    if not edits:
        return None, 0, skips
    return splice(raw, d, tname, edits), len(edits), skips

def greedy_casts(tu, raw, d, tname, edits, tag):
    """Rung S2: the member spelling DIFFERS — find a minimal set of sites that must stay casts (delever's rung B shape):
    leave-one-out first (n compiles), else cumulative revert in source order until IDENTICAL, then drop every revert not needed.
    Returns (kept_sites[list of site dicts], compiles, verdict) — verdict IDENTICAL when a set was found."""
    n = len(edits)
    compiles = 0
    for i in range(n):
        sub = edits[:i] + edits[i + 1:]
        v, _, _, _ = judge_text(tu, splice(raw, d, tname, sub), tag)
        compiles += 1
        if v == "IDENTICAL":
            return [edits[i][3]], compiles, "IDENTICAL"
    K = []
    for i in range(n):
        K.append(i)
        sub = [e for j, e in enumerate(edits) if j not in K]
        v, _, _, _ = judge_text(tu, splice(raw, d, tname, sub), tag)
        compiles += 1
        if v == "IDENTICAL":
            break
    else:
        return [], compiles, "NO-SET"          # even every site reverted differs: the typedef alone or the mask moved bytes — a tool defect
    # minimise
    for j in list(K):
        trial = [k for k in K if k != j]
        sub = [e for i2, e in enumerate(edits) if i2 not in trial]
        v, _, _, _ = judge_text(tu, splice(raw, d, tname, sub), tag)
        compiles += 1
        if v == "IDENTICAL":
            K = trial
    return [edits[i][3] for i in K], compiles, "IDENTICAL"

_typedef_cache = {}

# ----------------------------------------------------------------------------------------------------------------------
# the oracle wrapper (in place, restored)
# ----------------------------------------------------------------------------------------------------------------------

# ======================================================================================================================
# THE ENGINE (T3)
# ======================================================================================================================
# ----------------------------------------------------------------------------------------------------------------------
# the judge: a multi-file job through the oracle (whole-object, then linked when only the relocation spelling moved)
# ----------------------------------------------------------------------------------------------------------------------
_recipes = None
_by_src = None
_inc = None
_tu_headers = None
JUDGE_STUB = None        # the selftest installs a callable(files, tag) -> (verdict, err) here; None = the real oracle


def recipes():
    global _recipes, _by_src, _inc
    if _recipes is None:
        _recipes = oracle.load_recipes()["recipes"]
        _by_src = oracle.recipes_by_src(_recipes)
        _inc = dl.includers()
    return _recipes, _by_src, _inc


def recs_for(tu):
    _, by_src, inc = recipes()
    return ds.recs_for(tu, by_src, inc)


def headers_of(tu):
    """The headers a TU sees (transitively) — the inverse of delever.includers()."""
    global _tu_headers
    if _tu_headers is None:
        _, _, inc = recipes()
        m = collections.defaultdict(set)
        for h, tus in inc.items():
            for t in tus:
                m[t].add(h)
        _tu_headers = m
    return _tu_headers.get(tu, set())


def judge_files(files, tag, reloc=False, pool=None, retry=True):
    """files = {rel: candidate text}. Every file written IN PLACE (snapshotted first), every recipe of every file compiled (a header's
    includers' recipes), the objects compared with the snapshot baseline; a DIFFERS falls to the LINKED judgement when the job is
    flagged relocation-spelling (`reloc`) or the .text words agree modulo relocation operands. Every file restored (R102).
    Returns dict(verdict, seconds, err, compiles, linked=[objs judged IDENTICAL only linked], cand0=first recipe's candidate bytes)."""
    if JUDGE_STUB is not None:
        v, err = JUDGE_STUB(files, tag)
        return dict(verdict=v, seconds=0.0, err=err, compiles=1, linked=[], cand0=None)
    recs, seen = [], set()
    for rel in files:
        for r in recs_for(rel):
            if r["obj"] not in seen:
                seen.add(r["obj"]); recs.append(r)
    if not recs:
        return dict(verdict="NO-RECIPE", seconds=0.0, err=f"no recipe compiles {sorted(files)}", compiles=0, linked=[], cand0=None)
    snaps = {}
    for rel in files:
        p = REPO / rel
        snaps[rel] = (p.read_text(errors="surrogateescape"), p.stat())
    out = dict(verdict="IDENTICAL", seconds=0.0, err="", compiles=0, linked=[], cand0=None)
    try:
        for rel, text in files.items():
            (REPO / rel).write_text(text, errors="surrogateescape")

        def one(r):
            base = oracle.baseline_bytes(r["obj"])
            if base is None:
                return r, "NO-BASELINE", 0.0, "", None
            data, dt, err = oracle.compile_obj(r, None, tag=tag)
            if data is None and retry and not err.startswith("CRASH:"):
                data, dt2, err = oracle.compile_obj(r, None, tag=tag)          # a fan-out transient (T2 (h)): one retry
                dt += dt2
            if data is None:
                return r, ("COMPILE-CRASH" if err.startswith("CRASH:") else "COMPILE-ERROR"), dt, err, None
            if data == base:
                return r, "IDENTICAL", dt, "", data
            if reloc or oracle.reloc_only_diff(data, oracle.baseline_path(r["obj"]), tag=tag):
                lv, dt2, lerr = oracle.judge_linked(r, data, tag=tag)
                if lv == "IDENTICAL":
                    return r, "IDENTICAL-LINKED", dt + dt2, "", data
                return r, "DIFFERS", dt + dt2, ("linked: " + lerr if lerr else ""), data
            return r, "DIFFERS", dt, "", data
        if pool is not None and len(recs) > 2:
            results = list(pool.map(one, recs))
        else:
            results = [one(r) for r in recs]
        first = None
        for i, (r, v, dt, err, data) in enumerate(results):
            out["seconds"] += dt
            out["compiles"] += 1
            if i == 0:
                out["cand0"] = data
            if v == "IDENTICAL-LINKED":
                out["linked"].append(r["obj"])
                continue
            if v != "IDENTICAL" and first is None:
                first = (v, err, r["obj"])
        if first:
            out["verdict"], out["err"] = first[0], (first[1] + f" [{first[2]}]" if first[1] else f"[{first[2]}]")
        return out
    finally:
        for rel, (raw, st) in snaps.items():
            dl.restore_file(REPO / rel, raw, st)


def judge_text(tu, text, tag):
    """T2's single-file form: (verdict, seconds, err, candidate_object_bytes_of_first_recipe)."""
    r = judge_files({tu: text}, tag)
    return r["verdict"], r["seconds"], r["err"], r["cand0"]


# ----------------------------------------------------------------------------------------------------------------------
# the ledger (R48/R114: a unit is (rung, tu, unit, body hash); the latest row per unit is the verdict, R70) and the in-flight snapshot
# ----------------------------------------------------------------------------------------------------------------------
DONE_VERDICTS = {"IDENTICAL", "MEMBERS", "S2", "S+A", "UNCHANGED", "NO-SITE", "REFUSED", "KEPT-ALL", "DECL-CANON", "DECL-PROMOTED",
                 "DECL-KEPT", "DECL-NONE", "ALIAS-TYPED", "ALIAS-KEPT", "BUILTIN-ABS", "BUILTIN-KEPT", "UNALIAS-DONE", "UNALIAS-KEPT", "UNALIAS-REFUSED",
                 "FOLDED", "FOLD-REFUSED", "NO-EDIT", "TYPE-NOT-CANONICAL", "TYPE-NOT-VISIBLE"}
REDRAW_VERDICTS = {"COMBINATION-FAILED", "NO-RECIPE", "TOOL-ERROR"}


def load_ledger():
    rows = []
    if LEDGER.exists():
        for l in LEDGER.read_text().splitlines():
            if l.strip():
                rows.append(json.loads(l))
    return rows


def ledger_append(rows):
    RUN.mkdir(parents=True, exist_ok=True)
    with _LOCK, open(LEDGER, "a") as f:
        for r in rows:
            f.write(json.dumps(r) + "\n")


def ledger_latest(rows):
    """{(rung, tu, unit): row} — the LATEST row per unit (R70: the last row is the verdict). The one latest-row filter; its callers read
    verdict/cause from the row (ledger_index, settled_units, type_census --check-structs)."""
    latest = {}
    for r in rows:
        latest[(r.get("rung"), r["tu"], r["unit"])] = r
    return latest


def ledger_index(rows):
    """done: {(rung, tu, unit, nhash_after)}; latest: {(rung, tu, unit): verdict}."""
    done = set()
    for r in rows:
        if r.get("verdict") in DONE_VERDICTS and r.get("nhash_after") and (r.get("rung") != "S" or s_judged(r)):
            done.add((r.get("rung"), r["tu"], r["unit"], r["nhash_after"]))
    return done, {k: r.get("verdict") for k, r in ledger_latest(rows).items()}


def s_judged(r):
    """A rung-S row judged at least one base (CANONICAL/LOCAL). T3.c3: t3_S6..S14, S16..S18 ledgered every pinned base NO-TYPE-IN-MAP
    (no compile): those rows are not judgements — neither done (ledger_index) nor finished (s_finished)."""
    return any(b.get("status") in ("CANONICAL", "LOCAL") for b in r.get("bases") or [])


def body_nhash(masked, d):
    ls = dl.line_starts(masked)
    s0 = ls[d["line"] - 1]
    s1 = ls[d["end"]] - 1 if d["end"] < len(ls) else len(masked)
    return lc.norm_hash(masked[s0:s1])


@contextlib.contextmanager
def _inflight_lock(path=None, shared=False):
    """inflight.json is read and written only under this lock: the thread lock (workers of one process) AND an fcntl lock on
    <path>.lock (other processes). T4.c2: batch t38_4L1 ran twice concurrently under one label; one process's plain write_text
    (truncate, then write) was read EMPTY by the other's workers — 5 file-level TOOL-ERROR JSONDecodeError."""
    path = path or INFLIGHT
    path.parent.mkdir(parents=True, exist_ok=True)
    with _LOCK, open(path.with_name(path.name + ".lock"), "a") as lf:
        fcntl.flock(lf, fcntl.LOCK_SH if shared else fcntl.LOCK_EX)
        try:
            yield
        finally:
            fcntl.flock(lf, fcntl.LOCK_UN)


def _inflight_write(d, path=None):
    """Atomic: a tmp file beside it, then os.replace (a reader sees the old or the new record, never a truncated one). Caller holds
    _inflight_lock."""
    path = path or INFLIGHT
    tmp = path.with_name(f"{path.name}.tmp{os.getpid()}")
    tmp.write_text(json.dumps(d))
    os.replace(tmp, path)


def inflight_update(fn, path=None):
    """Read-modify-write of inflight.json, serialised across threads and processes; fn(d) mutates d in place."""
    path = path or INFLIGHT
    with _inflight_lock(path):
        d = json.loads(path.read_text())
        fn(d)
        _inflight_write(d, path)


def load_inflight(path=None):
    path = path or INFLIGHT
    if not path.exists():
        return None, "no inflight.json — nothing was in flight"
    with _inflight_lock(path, shared=True):
        raw = path.read_text() if path.exists() else ""
    if not raw.strip():
        return None, "inflight.json is EMPTY (a kill landed mid-write): reconcile every dirty file with the oracle (IDENTICAL = a bank, DIFFERS = a leftover)"
    try:
        return json.loads(raw), "ok"
    except json.JSONDecodeError as ex:
        return None, f"inflight.json is TORN ({ex}): same reconciliation as for an empty one"


def restore():
    """Every in-flight file back from inflight.json; the killed batch's ledger rows dropped (kept in ledger.jsonl.killed_<label>)."""
    d, why = load_inflight()
    if d is None:
        sys.exit(f"restruct --restore: {why}")
    label, files = d.get("label"), d.get("files", {})
    n = 0
    for tu, text in files.items():
        p = REPO / tu
        if p.read_text(errors="surrogateescape") != text:
            p.write_text(text, errors="surrogateescape")
            n += 1
    dropped = 0
    if label and LEDGER.exists():
        rows = LEDGER.read_text().splitlines()
        keep = [l for l in rows if l.strip() and json.loads(l).get("label") != label]
        dropped = len([l for l in rows if l.strip()]) - len(keep)
        if dropped:
            (RUN / f"ledger.jsonl.killed_{label}").write_text("\n".join(rows) + "\n")
            LEDGER.write_text("".join(l + "\n" for l in keep))
    INFLIGHT.unlink()
    clean, dirty = dl.src_clean()
    print(f"restruct --restore: {n} of {len(files)} files restored from inflight.json (batch {label or '?'}); {dropped} ledger rows of that "
          f"batch dropped; src {'clean' if clean else 'STILL DIRTY:'}\n{'' if clean else dirty[:400]}")
    return 0 if clean else 1


def status():
    rows = load_ledger()
    by = collections.Counter((r.get("rung"), r.get("verdict")) for r in rows)
    sites = collections.Counter()
    for r in rows:
        for s in r.get("sites", []):
            sites[(r.get("rung"), s.get("verdict", "").split("(")[0])] += 1
    print(f"restruct --status: {len(rows)} ledger rows")
    for (rung, v), n in sorted(by.items(), key=lambda x: (str(x[0][0]), -x[1])):
        print(f"   {rung or '?':4s} {v:22s} {n}")
    if sites:
        print("   sites: " + ", ".join(f"{r}/{v} {n}" for (r, v), n in sorted(sites.items(), key=lambda x: (str(x[0][0]), -x[1]))))
    return 0


# ----------------------------------------------------------------------------------------------------------------------
# the shared ladder: all units at once, else cumulative greedy in order (delever's rung-B shape: n compiles, the last accepted
# candidate IS the final text — no extra combination compile)
# ----------------------------------------------------------------------------------------------------------------------
def ladder_units(units, compose, judge, tag, log=None):
    """units: [unit] in source order; compose(accepted_units) -> {rel: text}; judge(files, tag) -> result dict.
    Returns (accepted[list of units], per_unit{idx: (verdict, err)}, compiles, seconds, rung) with rung 'A' (all at once) or 'B'."""
    per, compiles, secs = {}, 0, 0.0
    if not units:
        return [], per, 0, 0.0, None

    def safe(acc, t):
        try:
            return judge(compose(acc), t)
        except Refuse as ex:                 # two units' edits overlap: the combination is REFUSED, never a file-level TOOL-ERROR (R43)
            return dict(verdict="REFUSED", seconds=0.0, err=f"overlapping edits: {ex}", compiles=0, linked=[], cand0=None)
    r = safe(units, tag + "A")
    compiles += r["compiles"]; secs += r["seconds"]
    if r["verdict"] == "IDENTICAL":
        for i in range(len(units)):
            per[i] = ("IDENTICAL", "", r["linked"])
        return list(units), per, compiles, secs, "A"
    if len(units) == 1:
        per[0] = (r["verdict"], r["err"], r["linked"])
        return [], per, compiles, secs, "A"
    accepted = []
    for i, u in enumerate(units):
        r2 = safe(accepted + [u], tag + f"B{i}")
        compiles += r2["compiles"]; secs += r2["seconds"]
        if r2["verdict"] == "IDENTICAL":
            accepted.append(u)
            per[i] = ("IDENTICAL", "", r2["linked"])
        else:
            per[i] = (r2["verdict"], r2["err"], r2["linked"])
            if log:
                log(f"    unit {i}: {r2['verdict']} {r2['err'].replace(chr(10), ' | ')[:140]}")
    return accepted, per, compiles, secs, "B"


# ----------------------------------------------------------------------------------------------------------------------
# rung X: the residual named by the pass it most resembles (a HINT for the readings; R65 wants the dump line before a verdict)
# ----------------------------------------------------------------------------------------------------------------------
LOADS = ("lw", "lh", "lhu", "lb", "lbu", "lwl", "lwr", "lui")
STORES = ("sw", "sh", "sb", "swl", "swr")


def pass_hint(residual):
    if not residual or residual.get("kind") in (None, "UNSCORED"):
        return "UNSCORED"
    kind = residual["kind"]
    # `pairs` = the aligned differing rows (k, "<word> <mnem …>" | "--", same) from classify_residual; a register-pair row
    # (x, y, count — delever_search.classify's `pairs`, what classify_residual emitted before T3.c3: `.split()` on an int crashed)
    # carries no mnemonic and is skipped here (T3.c3)
    rows = [p for p in residual.get("pairs", []) if len(p) == 3 and isinstance(p[1], str) and isinstance(p[2], str)]
    mn = [(p[1].split()[1] if len(p[1].split()) > 1 else "") for p in rows if p[1] != "--"]
    tg = [(p[2].split()[1] if len(p[2].split()) > 1 else "") for p in rows if p[2] != "--"]
    words = set(mn) | set(tg)
    if words & {"lwl", "lwr", "swl", "swr"}:
        return "ALIGNMENT"
    if kind == "ORDER" and (words & set(LOADS)) and (words & set(STORES)):
        return "SCHED-ALIAS"
    if kind == "ORDER":
        return "SCHED-ORDER"
    if kind == "COUNT" and (words & {"lui", "lw", "addiu", "la"}):
        return "CSE-KILL"
    if words & {"andi", "sll", "sra", "srl", "seb", "seh"}:
        return "WIDTH"
    if kind == "COUNT":
        return "COUNT-OTHER"
    if kind == "REG":
        return "REGALLOC"
    ims = [p for p in rows if p[1] != "--" and p[2] != "--" and p[1].split()[1:2] == p[2].split()[1:2]]
    if ims and all(x[1].split()[1] in ("addiu", "lui", "ori") for x in ims):
        return "ADDRESS-FOLD"
    return "OTHER"


# ----------------------------------------------------------------------------------------------------------------------
# rung S (engine form): every typed base of a body, canonical types, the declared-type-aware spelling
# ----------------------------------------------------------------------------------------------------------------------
_canon = None


def canon_types():
    """{name: (definition record, Resolver, field_map)} for every canonical type file's struct/union definitions (T5 adds files to
    tc.CANON_HEADERS; the writer appends definitions). Re-read per process."""
    global _canon
    if _canon is None:
        defs = {}
        recs = []
        for h in CANON_HEADERS:
            if not (REPO / h).exists():
                continue
            w = tc._walk_worker(h)
            for d in w["definitions"]:
                recs.append(d)
                for n in d["names"] + ([d["tag"]] if d["tag"] else []):
                    defs.setdefault(n, d)
            for al in w["typedef_aliases"]:
                defs.setdefault(al["name"], dict(kind="alias", alias_of=al["alias_of"], alias_stars=al["alias_stars"], alias_dims=al["alias_dims"]))
        res = sl.Resolver(dict(defs))
        out = {}
        for d in recs:
            if d["kind"] == "enum" or not d["fields"]:
                continue
            fm = sl.field_map(res, d)
            for n in d["names"]:
                out[n] = (d, res, fm)
        _canon = out
    return _canon


def type_visible(tu, tname):
    """Is the canonical type's file visible to the TU (the file itself, or one of its transitive headers)?"""
    d = canon_types().get(tname)
    if not d:
        return False
    if VISIBLE_OVERRIDE:
        return True
    f = d[0]["file"]
    return tu == f or f in headers_of(tu)


PARAM_DECL = re.compile(r"^\s*((?:(?:const|volatile|unsigned|signed|struct|union)\s+)*[A-Za-z_]\w*)\s*(\**)\s*([A-Za-z_]\w*)\s*$")


def declared_type(masked, d, base, bclass, fn_head_inner):
    """The declared type text of a base as the TU spells it ('Unkstruct_X *' / 's32' / None): a parameter from the definition's head,
    a local from its declaration line in the body, a global from `extern T D_x;` in the TU."""
    if bclass == "param" and fn_head_inner:
        for part in sl._split_top(fn_head_inner, ","):
            m = PARAM_DECL.match(part.strip())
            if m and m.group(3) == base:
                return sl._norm_type(m.group(1) + (" " + m.group(2) if m.group(2) else ""))
        return None
    ls = dl.line_starts(masked)
    if bclass == "local":
        s0, s1 = ls[d["line"] - 1], (ls[d["end"]] if d["end"] < len(ls) else len(masked))
        body = masked[s0:s1]
        m = re.search(r"(?<![\w.])((?:(?:const|volatile|unsigned|signed|struct|union|register)\s+)*[A-Za-z_]\w*)\s*(\**)\s*(?:[A-Za-z_]\w*\s*(?:=[^,;]*)?,\s*\**\s*)*" + re.escape(base) + r"\b\s*(?:=[^,;]*)?[,;]", body)
        if m and m.group(1) not in ("return", "goto", "case", "else"):
            return sl._norm_type(m.group(1) + (" " + m.group(2) if m.group(2) else ""))
        return None
    if bclass in ("global", "gaddr"):
        m = re.search(r"\bextern\s+((?:(?:const|volatile|unsigned|signed|struct|union)\s+)*[A-Za-z_]\w*)\s*(\**)\s*" + re.escape(base) + r"\s*((?:\[[^\]]*\])*)\s*;", masked)
        if m:
            return sl._norm_type(m.group(1) + (" " + m.group(2) if m.group(2) else "")) + ("[]" if m.group(3) else "")
    return None


def member_spelling(tname, base_expr, bclass, decl, fname):
    """The member access text for one site: typed base -> `base->f` / `D_x.f`; else the cast form."""
    want_ptr = tname + " *"
    if bclass in ("param", "local", "global") and decl == want_ptr:
        return f"{base_expr}->{fname}"
    if bclass == "gaddr" and decl == tname:
        return f"{base_expr.lstrip('&')}.{fname}"
    return f"(({tname} *){base_expr})->{fname}"


def s_edits(raw, masked, d, sites, tname, fields, base_key, fn_head_inner, allow_pointee_void=False, why=None):
    """Rung S's positional edits for one body/base with a FIELD MAP {off: dict(name,width,sign,type,stars,dims)}: [(pos, end, repl, site)],
    skips{reason: n}. The rules T2 fixed: width must match; a load's sign must match (a store may not care, R: a store's signedness
    leaves no byte); a pointer field's pointee must be the site's; indexed / negative / refused sites stay. `why` (P39 T3): a dict
    filled {id(site): skip reason} for the per-site class (s_site_rows)."""
    edits, skips = [], collections.Counter()
    bcls, bname = base_key.split(":", 1)
    decl = declared_type(masked, d, bname, bcls, fn_head_inner)
    for s in sites:
        if s["form"] not in RAW_FORMS or s.get("bclass") != bcls or str(s.get("base")) != bname:
            continue
        if s.get("index") is not None or s.get("refused"):
            skips["index"] += 1
            if why is not None:
                why[id(s)] = "index"
            continue
        off = s.get("off") or 0
        if off < 0:
            skips["negative-offset"] += 1
            if why is not None:
                why[id(s)] = "negative-offset"
            continue
        f = fields.get(off)
        if f is None:
            skips["no-field"] += 1
            if why is not None:
                why[id(s)] = "no-field"
            continue
        if f["sign"] == "agg":
            skips["aggregate-field"] += 1
            if why is not None:
                why[id(s)] = "aggregate-field"
            continue
        if s.get("width") != f["width"]:
            skips["width"] += 1
            if why is not None:
                why[id(s)] = "width"
            continue
        sg = f["sign"]
        if s.get("sign") != sg and not (s.get("access") == "store" and {s.get("sign"), sg} <= {"s", "u"}):
            skips["sign"] += 1
            if why is not None:
                why[id(s)] = "sign"
            continue
        if sg == "p":
            site_pointee = (s.get("ctype") or "").rstrip("* ").strip() + " *"
            ftype = sl._norm_type(f["type"]) + " " + "*" * f["stars"] if f["stars"] else sl._norm_type(f["type"])
            if site_pointee != ftype and not (allow_pointee_void and ftype == "void *"):
                skips["pointee"] += 1
                if why is not None:
                    why[id(s)] = "pointee"
                continue
        base_expr = ("&" + bname) if bcls == "gaddr" else bname
        edits.append((s["pos"], s["end"], member_spelling(tname, base_expr, bcls, decl, f["name"]), s))
    edits.sort(key=lambda e: e[0])
    kept, last = [], 0
    for e in edits:
        if e[0] < last:
            skips["overlap"] += 1
            if why is not None:
                why[id(e[3])] = "overlap"
            continue
        kept.append(e); last = e[1]
    return kept, skips


def compose_text(raw, edits, inserts=()):
    """raw with [(pos, end, repl, …)] edits spliced and [(pos, text)] insertions (file-scope typedefs) placed — insertions at a
    position inside no edit."""
    items = [(a, b, rep) for (a, b, rep, *_) in edits] + [(p, p, t) for (p, t) in inserts]
    out, last = [], 0
    for (a, b, rep) in sorted(items, key=lambda e: (e[0], e[1])):
        if a < last:
            raise Refuse(f"overlapping edits at {a}")
        out.append(raw[last:a]); out.append(rep); last = b
    out.append(raw[last:])
    return "".join(out)


def drop_overlaps(edits):
    """(kept, dropped) over one body's edits of ALL its bases: s_edits drops overlaps within one base, but a `nested:` base's site
    CONTAINS its parent base's site (`*(s16 *)(*(s32 *)(s0 + 0x20) + 0x18)` holds `*(s32 *)(s0 + 0x20)`, base param:s0). The
    earlier-starting edit stays (the longer one on a tie), the ones starting inside it drop — deterministic, source order.
    was: compose_text raised Refuse on them and the whole --try-file run crashed (T3.c3)."""
    kept, dropped, last = [], [], 0
    for e in sorted(edits, key=lambda e: (e[0], -e[1], e[2])):
        if e[0] < last:
            dropped.append(e)
            continue
        kept.append(e); last = e[1]
    return kept, dropped


def greedy_kept(judge_cands, edits, tag):
    """Rung S2 on an edit list: judge_cands(sub_edits, tag) -> verdict. leave-one-out (n), else cumulative revert in source order
    until IDENTICAL, then minimise. Returns (kept_edits, compiles, verdict)."""
    n = len(edits)
    compiles = 0
    for i in range(n):
        v = judge_cands(edits[:i] + edits[i + 1:], tag + f"l{i}")
        compiles += 1
        if v == "IDENTICAL":
            return [edits[i]], compiles, "IDENTICAL"
    K = []
    for i in range(n):
        K.append(i)
        v = judge_cands([e for j, e in enumerate(edits) if j not in K], tag + f"c{i}")
        compiles += 1
        if v == "IDENTICAL":
            break
    else:
        return [], compiles, "NO-SET"
    for j in list(K):
        trial = [k for k in K if k != j]
        v = judge_cands([e for i2, e in enumerate(edits) if i2 not in trial], tag + f"m{j}")
        compiles += 1
        if v == "IDENTICAL":
            K = trial
    return [edits[i] for i in K], compiles, "IDENTICAL"


def s_body_edits(tu, fn, raw, masked, d, sites, bases, allow_local, local_types, why=None):
    """Every typed base of the body: [(edits, skips, base_key, tname, canonical?)] + the inserts (local typedefs). `bases` =
    body_base_type.json's {base_key: {type, sites}}; `local_types` accumulates the file's local typedef texts (T2 form)."""
    fn_head_inner, _ = _head_parts(masked, d, fn)
    per_base, inserts = [], []
    for base_key, ent in sorted(bases.items(), key=lambda kv: -kv[1]["sites"]):
        tname = ent["type"]
        t = struct_map().get(tname)
        can = canon_types().get(tname)
        # T3.c3: a canonical type needs only its field map; the map lookup gates the LOCAL path alone (was: checked first — the
        # per-batch census drops the pinned names from struct_map.json, so t3_S6..S18 ledgered every pinned base NO-TYPE-IN-MAP)
        if not t and not can:
            per_base.append((base_key, tname, "NO-TYPE-IN-MAP", [], {}))
            continue
        if can and type_visible(tu, tname):
            fields = can[2] or {}
            edits, skips = s_edits(raw, masked, d, sites, tname, fields, base_key, fn_head_inner, why=why)
            per_base.append((base_key, tname, "CANONICAL", edits, skips))
        elif can:
            per_base.append((base_key, tname, "TYPE-NOT-VISIBLE", [], {}))
        elif allow_local and t:
            ctypes_by_off = collections.defaultdict(list)
            for s in sites:
                if s.get("bclass") + ":" + str(s.get("base")) == base_key and s.get("ctype"):
                    ctypes_by_off[s.get("off") or 0].append(s["ctype"])
            local_name = f"P37S_{hashlib.sha1(tname.encode()).hexdigest()[:8]}"
            ttext, fields_t2, skipped = build_type(local_name, t["layout"], ctypes_by_off)
            fields = {off: dict(name=nm, width=w, sign=sg, type=ft.rstrip("* ").strip(), stars=ft.count("*"), dims=[]) for off, (w, sg, nm, ft) in fields_t2.items()}
            edits, skips = s_edits(raw, masked, d, sites, local_name, fields, base_key, fn_head_inner, why=why)
            if edits and local_name not in local_types:
                local_types[local_name] = ttext
            per_base.append((base_key, local_name, "LOCAL", edits, skips))
        else:
            per_base.append((base_key, tname, "TYPE-NOT-CANONICAL", [], {}))
    return per_base


def lever_sites_in(text, tu, fn):
    """delever's body dict (its removable A/B sites) for one function of a CANDIDATE text — the census re-run on that text."""
    walk = lc.walk_file(text, tu, tu.endswith(".h"))
    sites = [s for s in walk["sites"] if s.get("fn") == fn]
    for s in sites:
        s.setdefault("aliases", []); s.setdefault("tu", tu); s.setdefault("header", tu.endswith(".h"))
    bodies = dl.bodies_from_sites(sites)
    return bodies.get((tu, fn))


def struct_plus_levers(tu, fn, text1, judge_one, label, log=None):
    """S+A: delever's ladder on the struct-spelled text. Returns (text2, res) — text2 = text1 when no lever came off; res = the
    ladder's result (verdict LEVER-FREE / RESIDUE / …, sites) or None when the body has no removable lever."""
    b = lever_sites_in(text1, tu, fn)
    if not b or not b["sites"]:
        return text1, None
    m1, ls1 = dl.same_len_mask(text1), dl.line_starts(text1)

    def judge(text, removed, tag):
        r = judge_one(text, tag)
        return r["verdict"], r["seconds"], r["err"]
    res = dl.ladder(b, text1, m1, ls1, judge, replay_from=None, log=log)
    accepted = res["accepted"]
    survivors = []
    for dd in res["sites"]:
        if dd["verdict"] in ("NEEDED", "REFUSED") and dd["ord"] >= 0:
            s = b["sites"][dd["ord"]]
            survivors.append((s, dd["verdict"], (dd["oracle"] if dd["verdict"] == "NEEDED" else dd["why"]) or ""))
    if not accepted:
        return text1, res
    markers = dl.marker_edits(text1, ls1, survivors, "S+A", label, phase="P37")
    text2 = dl.apply_edits(text1, accepted + markers)
    # the markers of the REMOVED sites are orphans now (the census's definition: no pin/asm site left on the line) — scrubbed here,
    # never left for a later --scrub (P36 left them and the census counted 0 orphans only after a sweep)
    removed_lines = {b["sites"][dd["ord"]]["line"] for dd in res["sites"] if dd["verdict"] in ("REMOVED", "REWRITTEN") and dd["ord"] >= 0}
    survivor_lines = {s_["line"] for (s_, _, _) in survivors}
    walk2 = lc.walk_file(text2, tu, tu.endswith(".h"))
    # a line keeps its marker only while a LEVER remains on it — a plain `gte_X()` (Sony's idiom, kind `gte`) is a site the census
    # counts but not a lever; the marker described the `_m` variant that just came off
    live_lines = {s_["line"] for s_ in walk2["sites"] if s_.get("fn") == fn and ((s_.get("cls"), s_.get("kind")) in dl.REMOVABLE or s_.get("kind") in dl.MARK_KINDS)}
    orphan = sorted(ln for ln in removed_lines if ln not in survivor_lines and ln not in live_lines)
    if orphan:
        # line numbers of text1 == text2 for the lever lines (a lever rewrite never adds or removes a line above the next lever)
        text2 = dl.apply_edits(text2, dl.scrub_edits(text2, orphan))
    return text2, res
def classify_residual(tu, fn, cand_bytes):
    """delever_search's classifier over the body's instructions: candidate object vs the baseline object of the first recipe."""
    recs = recs_for(tu)
    if not recs or cand_bytes is None:
        return None
    base = oracle.baseline_path(recs[0]["obj"])
    tmp = PROBE / "obj" / (hashlib.sha1((tu + fn).encode()).hexdigest()[:12] + ".o")
    tmp.parent.mkdir(parents=True, exist_ok=True)
    tmp.write_bytes(cand_bytes)
    try:
        mine = md.insns_from_object(str(tmp), fn)
        tgt = md.insns_from_object(str(base), fn)
    except Exception as e:      # noqa: BLE001
        return dict(kind="UNSCORED", err=str(e)[:80])
    finally:
        tmp.unlink(missing_ok=True)
    if not mine or not tgt:
        return dict(kind="UNSCORED", err="function not found in one object")
    c = ds.classify(mine, tgt)
    # pairs = the aligned differing rows pass_hint reads (k, "<word> <mnem>" | "--", …), delever_search --explain's alignment;
    # regs = classify's register pairs (x, y, n). was: pairs=c["pairs"][:4] (the register pairs — pass_hint crashed on the int, T3.c3)
    aa, bb = [ds.masked_word(i) for i in mine], [ds.masked_word(i) for i in tgt]
    rows = []
    for t, i1, i2, j1, j2 in difflib.SequenceMatcher(None, aa, bb, autojunk=False).get_opcodes():
        if t == "equal":
            continue
        for k in range(max(i2 - i1, j2 - j1)):
            m_ = f"{mine[i1 + k]['word']:08x} {mine[i1 + k]['mnem']}" if i1 + k < i2 else "--"
            t_ = f"{tgt[j1 + k]['word']:08x} {tgt[j1 + k]['mnem']}" if j1 + k < j2 else "--"
            rows.append((i1 + k, m_, t_))
    return dict(kind=c["kind"], score=c["score"], n_mine=c["n_mine"], n_tgt=c["n_tgt"], pairs=rows[:8], regs=c["pairs"][:4])

# ----------------------------------------------------------------------------------------------------------------------
# rung 1 on one body
# ----------------------------------------------------------------------------------------------------------------------
def try_body(tu, fn, base_key=None, tname_hint=None, tag="p37", want_sa=True, want_greedy=True, want_recipes=False):
    raw, masked, d, sites = body_sites(tu, fn)
    if d is None:
        return dict(tu=tu, fn=fn, verdict="NO-BODY")
    bbt = json.loads((CENSUS / "body_base_type.json").read_text()) if base_key is None or tname_hint is None else None
    if base_key is None:
        ent = (bbt or {}).get(tu + "|" + fn, {})
        if not ent:
            return dict(tu=tu, fn=fn, verdict="NO-TYPED-BASE")
        base_key = max(ent, key=lambda k: ent[k]["sites"])
    tname = tname_hint or (bbt or {}).get(tu + "|" + fn, {}).get(base_key, {}).get("type")
    if not tname:
        return dict(tu=tu, fn=fn, base=base_key, verdict="NO-TYPE")
    t = struct_map().get(tname)
    if not t:
        return dict(tu=tu, fn=fn, base=base_key, verdict="NO-TYPE-IN-MAP")
    ctypes_by_off = collections.defaultdict(list)
    for s in sites:
        if s.get("bclass") + ":" + str(s.get("base")) == base_key and s.get("ctype"):
            ctypes_by_off[s.get("off") or 0].append(s["ctype"])
    local_name = f"P37S_{hashlib.sha1(tname.encode()).hexdigest()[:8]}"
    ttext, fields, skipped = build_type(local_name, t["layout"], ctypes_by_off)
    _typedef_cache[local_name] = ttext
    edits, skips = rung1_edits(raw, d, sites, local_name, fields, base_key)
    n = len(edits)
    row = dict(tu=tu, fn=fn, base=base_key, type=tname, type_sites=t["sites"], type_bodies=t["bodies"], fields=len(fields),
               rewritten=n, skips=dict(skips), header=tu.endswith(".h"), levers=None)
    if not edits:
        row["verdict"] = "NO-SITE-CONVERTIBLE"
        return row
    text = splice(raw, d, local_name, edits)
    v, dt, err, cand = judge_text(tu, text, tag)
    row.update(verdict=v, seconds=round(dt, 2), err=err[:160])
    if v == "DIFFERS":
        row["residual"] = classify_residual(tu, fn, cand)
        if want_greedy:
            kept, compiles, gv = greedy_casts(tu, raw, d, local_name, edits, tag + "g")
            row["s2"] = dict(verdict=gv, kept=len(kept), compiles=compiles, members=n - len(kept),
                             kept_sites=[dict(off=k.get("off"), ctype=k.get("ctype"), access=k.get("access"), line=k.get("line")) for k in kept[:8]])
            row["hint"] = pass_hint(row.get("residual"))
            if want_recipes and kept and gv == "IDENTICAL":
                # the R recipes on the kept casts, over the S2 text (members everywhere but the kept sites)
                kept_ids = {id(k) for k in kept}
                s2_edits = [e for e in edits if id(e[3]) not in kept_ids]
                s2_text = splice(raw, d, local_name, s2_edits)
                kept_edits = [e for e in edits if id(e[3]) in kept_ids]
                row["recipes"] = run_recipes(tu, fn, s2_text, kept_edits, lambda text, tg, reloc=False: judge_files({tu: text}, tg, reloc=reloc), tag + "r")
                for hit in row["recipes"]:
                    hit.pop("text", None)
    # S+A: the body's marked levers stripped as well
    lever_sites = [s for s in ds.sites_by_body().get((tu, fn), []) if s.get("cls") in "AB" and s.get("kind") in ds.AB_KINDS]
    row["levers"] = len(lever_sites)
    if want_sa and lever_sites:
        try:
            free = ds.lever_free_body(tu, raw, fn, lever_sites)
        except ds.Unstrippable as u:
            row["sa"] = dict(verdict="UNSTRIPPABLE", why=str(u.args[0])[:120])
            return row
        # the lever-free TU: re-walk its sites (positions moved) and rewrite the same base
        m2 = dl.same_len_mask(free)
        recs2 = sc.scan_text(free, tu, shared_defs=None)
        defs2 = [r for r in recs2 if r["form"] == "def"]
        d2 = next((x for x in defs2 if x["name"] == fn), None)
        if d2 is None:
            row["sa"] = dict(verdict="NO-BODY-AFTER-STRIP")
            return row
        span2 = {}
        for x in defs2:
            for ln in range(x["line"], x["end"] + 1):
                span2[ln] = x
        line_of2 = lambda idx: m2.count("\n", 0, idx) + 1
        pnames = tc._param_names(*(lambda h: (h[0] or "", h[1]))(_head_parts(m2, d2, fn)))
        sites2, _ = tc.find_sites(m2, tu, span2, line_of2, {fn: pnames})
        sites2 = [s for s in sites2 if s.get("fn") == fn]
        text2, n2, skips2 = rung1_text(free, d2, sites2, local_name, fields, base_key)
        if text2 is None:
            row["sa"] = dict(verdict="NO-SITE-CONVERTIBLE")
            return row
        v2, dt2, err2, cand2 = judge_text(tu, text2, tag + "sa")
        row["sa"] = dict(verdict=v2, seconds=round(dt2, 2), rewritten=n2, err=err2[:120])
        if v2 == "DIFFERS":
            row["sa"]["residual"] = classify_residual(tu, fn, cand2)
        # the lever-free text ALONE (no struct): the control that says whether the struct did anything
        if v2 == "IDENTICAL":
            v3, _, _, _ = judge_text(tu, free, tag + "a")
            row["sa"]["levers_off_alone"] = v3
    return row

def _head_parts(masked, d, fn):
    ls = dl.line_starts(masked)
    head_start = ls[d["line"] - 1]
    brace = masked.find("{", head_start)
    head = masked[head_start:brace] if brace != -1 else ""
    m = re.search(r"\b" + re.escape(fn) + r"\s*\(", head)
    if not m:
        return "", ""
    inner, close = tc._paren_body(head, m.end() - 1)
    return inner, (head[close + 1:] if close != -1 else "")

# ----------------------------------------------------------------------------------------------------------------------
# rung S: one file (bottom-up over its bodies so positions stay valid; the last accepted candidate is the final text)
# ----------------------------------------------------------------------------------------------------------------------
def file_view(tu, text):
    """(masked, defs, span_of_line, params_of, sites) — the census's view of one text (T2's body_sites, once per file)."""
    masked = dl.same_len_mask(text)
    line_of = lambda idx: masked.count("\n", 0, idx) + 1
    recs = sc.scan_text(text, tu, shared_defs=None)
    defs = [r for r in recs if r["form"] == "def"]
    span_of_line = {}
    for d in defs:
        for ln in range(d["line"], d["end"] + 1):
            span_of_line[ln] = d
    params_of = {}
    ls = dl.line_starts(masked)
    for d in defs:
        head_start = ls[d["line"] - 1]
        brace = masked.find("{", head_start)
        head = masked[head_start:brace] if brace != -1 else ""
        m = re.search(r"\b" + re.escape(d["name"]) + r"\s*\(", head)
        if not m:      # an alias-named def (`f_impl(…) __asm__("f")`): the first ident( — the census's rule (T3.c4: was local:param_N)
            m = re.search(r"\b(" + tc.NAME + r")\s*\((?=[^;]*\))", head)
        if m:
            inner, close = tc._paren_body(head, m.end() - 1)
            params_of[d["name"]] = tc._param_names(inner or "", head[close + 1:] if close != -1 else "")
    sites, _ = tc.find_sites(masked, tu, span_of_line, line_of, params_of)
    return masked, defs, span_of_line, params_of, sites


def site_row(s, verdict, tname=None, field=None, cause=None):
    return dict(form=s.get("form"), line=s.get("line"), base=f"{s.get('bclass')}:{s.get('base')}", off=s.get("off"), width=s.get("width"),
                sign=s.get("sign"), access=s.get("access"), type=tname, field=field, verdict=verdict, cause=cause)


# P39 T3: every raw site of a drawn body gets its own class (was: the body's pass hint on its kept edits only). The five macro classes
# (type_census.KEPT_MACROS) are KEPT(<class>) and a KEPT P-form site is respelled with its macro (include/common.h, the identical cast);
# every other cause is RESIDUAL(<CAUSE>) and stays raw.
S_KEPT_MACRO = {"SCHED-ALIAS": "CAST_ALIAS", "SIGN": "CAST_SIGN", "WIDTH": "CAST_WIDTH", "MISALIGNED": "CAST_MISALIGNED",
                "NON-STRUCT": "CAST_NONSTRUCT"}
S_RESPELL_VERDICTS = ("MEMBERS", "S2", "KEPT-ALL", "KEPT")      # the body verdicts whose kept sites are respelled (type_census backs them)


def site_class(s, why=None, kept=False, typed=True):
    """The class of one non-member site, in the fixed order: off % width != 0 -> MISALIGNED; s_edits' sign skip -> SIGN; its width
    skip or an overlap loser -> WIDTH; a kept (S2 / KEPT-ALL) edit -> SCHED-ALIAS; a base with no struct type -> NON-STRUCT (an
    indexed / negative one -> INDEX / NEGATIVE-OFFSET); any other skip -> that reason uppercased (a residual)."""
    w, off = s.get("width"), s.get("off") or 0
    if w and off % w:
        return "MISALIGNED"
    if why == "sign":
        return "SIGN"
    if why in ("width", "overlap", "overlap-edit"):
        return "WIDTH"
    if kept:
        return "SCHED-ALIAS"
    if not typed:
        if s.get("index") is not None or s.get("refused"):
            return "INDEX"
        return "NEGATIVE-OFFSET" if off < 0 else "NON-STRUCT"
    return (why or "no-edit").upper()


_LOWER_PREC = re.compile(r"<<|>>|<|>|\||\^|\?|=|,|(?<=[\w\]])\s*&")


def respell_edit(raw, masked, s, cls):
    """(pos, end, `CAST_<X>(T, p, k)`, s) for a P-form site `*(T *)(p + k)` — the same expression tree (the macro expands to
    `(*(T *)((p) + (k)))`) — or None when the site is not that shape (no literal `+ k`, a lower-precedence operator in p, a comment
    inside, or p/k not reparsing to the site's base and offset)."""
    if s.get("form") != "P" or cls not in S_KEPT_MACRO:
        return None
    m = tc.FORM_P.match(masked, s["pos"])
    if not m:
        return None
    inner, close = tc._paren_body(masked, m.end() - 1)
    if inner is None or close + 1 != s["end"] or raw[m.end():close] != inner:
        return None
    sp = tc._split_plus(tc._strip_parens(inner))
    if not sp or sp[1] != "+":
        return None
    p, k = sp[0].strip(), tc._strip_parens(sp[2])
    kv = tc._int(k)
    top = re.sub(r"\([^()]*\)", "()", p)
    while top != (top2 := re.sub(r"\([^()]*\)", "()", top)):
        top = top2
    if kv is None or _LOWER_PREC.search(top.replace("->", "")):
        return None
    b = tc.parse_base(p)
    if str(b.get("base")) != str(s.get("base")) or (b.get("off") or 0) + kv != (s.get("off") or 0):
        return None
    T = re.sub(r"\s+", " ", m.group(1)) + (" " + "*" * (len(m.group(2)) - 1) if len(m.group(2)) > 1 else "")
    return (s["pos"], s["end"], f"{S_KEPT_MACRO[cls]}({T}, {p}, {k})", s)


def s_site_rows(raw, masked, bsites, per_base, why, edits, accepted, overlapped, kept_ok, refused, typed_other, respell, tname_of):
    """(site rows, respell edits) over EVERY raw site of one drawn body, in source order. kept_ok: the body is S2/KEPT-ALL (its
    unaccepted edits are kept casts); refused: its candidate did not build (edit sites stay REFUSED); typed_other {base_key: reason}:
    bases the struct map types but this run does not draw (type-not-canonical / type-not-visible); respell: write the KEPT P-form
    sites as their macros. The respell edits never overlap an accepted edit or each other (the outer one stays)."""
    acc = {id(e[3]) for e in accepted}
    ovl = {id(e[3]) for e in overlapped}
    edit_of = {id(e[3]): e for e in list(edits) + list(overlapped)}
    status_of = {bk: stt for (bk, _, stt, _, _) in per_base}
    type_of = {bk: tn_ for (bk, tn_, _, _, _) in per_base}           # T3.c5: every site carries its base's type (was: edit sites only)
    rows_, resp = [], []
    for s in sorted((x for x in bsites if x["form"] in RAW_FORMS), key=lambda x: x.get("pos", 0)):
        e = edit_of.get(id(s))
        tn = (tname_of.get(id(e)) if e is not None else None) or type_of.get(f"{s.get('bclass')}:{s.get('base')}")
        fld = e[2].rsplit("->", 1)[-1].rsplit(".", 1)[-1] if e is not None else None
        if id(s) in acc:
            rows_.append(site_row(s, "MEMBER", tn, fld, "MEMBER"))
            continue
        if e is not None and refused and id(s) not in ovl:
            rows_.append(site_row(s, "REFUSED", tn, fld, "REFUSED"))
            continue
        bk = f"{s.get('bclass')}:{s.get('base')}"
        reason = "overlap-edit" if id(s) in ovl else why.get(id(s))
        if reason is None and e is None:
            st_ = status_of.get(bk)
            reason = st_ if st_ not in (None, "CANONICAL", "LOCAL") else typed_other.get(bk)
        typed = bk in status_of or bk in typed_other
        c = site_class(s, reason, kept=(e is not None and kept_ok and id(s) not in ovl), typed=typed)
        if c in S_KEPT_MACRO:
            rows_.append(site_row(s, f"KEPT({c})", tn, fld, c))
            r_ = respell_edit(raw, masked, s, c) if respell else None
            if r_ is not None:
                resp.append(r_)
        else:
            rows_.append(site_row(s, f"RESIDUAL({c})", tn, fld, c))
    resp = [r_ for r_ in resp if not any(r_[0] < a[1] and a[0] < r_[1] for a in accepted)]
    resp, _ = drop_overlaps(resp)
    return rows_, resp


_bbt_cache = None


def typed_bases_of(tu, fn, bases):
    """{base_key: reason} — the bases body_base_type.json types for this body that `bases` (the drawn ones) leaves out.
    T3.c3: read through bbt() — the same pinned merge plan_S draws from (was: the live file, unpinned)."""
    global _bbt_cache
    if _bbt_cache is None:
        _bbt_cache = bbt() if (CENSUS / "body_base_type.json").exists() else {}
    out = {}
    for bk, ent in (_bbt_cache.get(f"{tu}|{fn}") or {}).items():
        if bk not in bases:
            out[bk] = "type-not-canonical" if ent.get("type") not in canon_types() else "type-not-visible"
    return out


S_PRIOR = None     # {(tu, fn): [rung-S ledger rows, oldest first]} — loaded once per process; the selftest installs its own


def s_prior_rows(tu, fn):
    global S_PRIOR
    with _LOCK:
        if S_PRIOR is None:
            idx = collections.defaultdict(list)
            for r in load_ledger():
                if r.get("rung") == "S":
                    idx[(r["tu"], r["unit"])].append(r)
            S_PRIOR = idx
    return S_PRIOR.get((tu, fn), [])


S_NO_EDIT_VERDICTS = ("NO-SITE", "TYPE-NOT-VISIBLE", "TYPE-NOT-CANONICAL")

_NB_DEREF = re.compile(r"\*\s*\(\s*[A-Za-z_][\w\s]*\*+\s*\)\s*\(\s*([^()]*?)\s*\+\s*0x([0-9A-Fa-f]+)\s*\)")
_NB_MEMBER = re.compile(r"\(\s*\(\s*[A-Za-z_]\w*\s*\*\s*\)\s*([^()]*?)\s*\)\s*->\s*unk([0-9A-Fa-f]+)")


def s_base_norm(key):
    """T3.c8: a site base key with its offset accesses spelling-normalised — `*(T *)(X + 0xNN)` and `((S *)X)->unkNN` both become
    `@[X+NN]` (innermost first) — so a KEPT entry keyed on the pre-respell text still matches the base the census spells after a
    respell of a nested base inside the macro (t3_S28 func_8017EA20: `*(s32 *)(param_1 + 0x64)` → `((Unkstruct_800B5CB8 *)param_1)->unk64`)."""
    hx = lambda m: f"@[{m.group(1).strip()}+{int(m.group(2), 16):x}]"
    prev = None
    while prev != key:
        prev, key = key, _NB_MEMBER.sub(hx, _NB_DEREF.sub(hx, key))
    return re.sub(r"\s+", "", key)


def s_macro_rows(tu, text, rows):
    """T3.c4: every kept-cast macro site (census form K) of a drawn body in the FINAL text gets its own KEPT(<class>) row in the
    census's key (base `<bclass>:<base>` and off parsed from the macro, type_census.check_casts_verdict) — the respell's row was keyed
    on the pre-respell text (a nested base respelled inside it changes) and a re-judged body's macro sites are not raw (no row: the
    latest row dropped the earlier backing). Backed only by a judgement: an entry KEPT(<class>) of this row or of an earlier rung-S
    row of the body with the same off and (the same base or the same line); REINTERP by line. `macro_of` = the backing row's label.
    A no-edit row (NO-SITE / TYPE-NOT-*) that carries one becomes KEPT (as a respelled-only body)."""
    _, _, _, _, sites = file_view(tu, text)
    by_fn = collections.defaultdict(list)
    for s in sites:
        if s.get("form") == "K" and s.get("fn"):
            by_fn[s["fn"]].append(s)
    for row in rows:
        ks = by_fn.get(row.get("fn"))
        if not ks or row.get("verdict") in ("TOOL-ERROR", "COMBINATION-FAILED"):
            continue
        cands = [(row.get("label"), e) for e in row.get("sites") or []]
        cands += [(r.get("label"), e) for r in reversed(s_prior_rows(tu, row["fn"])) for e in r.get("sites") or []]
        n = 0
        for s in ks:
            want, key = f"KEPT({s['cls']})", f"{s['bclass']}:{s['base']}"
            nkey = s_base_norm(key)                                # T3.c8: a respelled nested base still matches (was: exact base or line)
            src = next((lb for lb, e in cands if e.get("verdict") == want and (e.get("line") == s["line"] if s["cls"] == "REINTERP" else
                        e.get("off") == s["off"] and (e.get("base") == key or e.get("line") == s["line"]
                                                      or s_base_norm(e.get("base") or "") == nkey))), None)
            if src is None:
                continue
            e_ = site_row(s, want, tname=next((b.get("type") for b in row.get("bases") or [] if b.get("base") == key), None), cause=s["cls"])
            e_["macro_of"] = src
            row["sites"].append(e_)
            n += 1
        if n and row.get("verdict") in S_NO_EDIT_VERDICTS:
            row["verdict"] = "KEPT"


def work_file_S(tu, bodies, label, calib_id, log, pool=None, allow_local=False, want_sa=True, want_recipes=False, done=frozenset(), write=True,
                im_only=False, latest=None):
    """bodies = {fn: bases}. Returns dict(rows, written, final, compiles, seconds, …).
    T5.c2: want_recipes also runs im_recipe_pass on each body's I/M global-base sites; im_only (`--forms I,M`) runs ONLY that pass —
    no struct spelling, the done filter bypassed — and the body's row is a merged copy of its latest S row (`latest`; `im_of` = its
    label) or a new no-base row (verdict `R:<recipe>` / RESIDUAL)."""
    path = REPO / tu
    st = path.stat()
    raw = path.read_text(errors="surrogateescape")
    is_hdr = tu.endswith(".h")
    if not recs_for(tu) and JUDGE_STUB is None:
        return dict(tu=tu, rows=[dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="S", calib=calib_id, tu=tu, unit=fn, fn=fn,
                                      verdict="NO-RECIPE", sites=[]) for fn in bodies], written=False, final="NO-RECIPE", compiles=0, seconds=0.0,
                    members=0, kept=0, skipped=0, levers_off=0, bodies=len(bodies))
    short = hashlib.sha1(tu.encode()).hexdigest()[:6]
    text_acc = raw
    local_types, local_pos = {}, {}
    rows = []
    out = dict(tu=tu, rows=rows, written=False, final="", compiles=0, seconds=0.0, members=0, kept=0, skipped=0, levers_off=0,
               bodies=len(bodies), linked=0, respelled=0, im_drawn=0, im_residual=0)
    judge_r = lambda text, tag, reloc=False: judge_files({tu: text}, tag, pool=pool, reloc=reloc)

    def im_count(st):
        out["im_drawn"] += sum(st["drawn"].values())
        out["im_residual"] += sum(st["residual"].values())
    masked0, defs0, _, _, _ = file_view(tu, raw)
    order = sorted([d for d in defs0 if d["name"] in bodies], key=lambda d: -d["line"])           # bottom-up
    first_line = min((d["line"] for d in order), default=None)
    for d in order:
        fn = d["name"]
        masked, defs, span_of_line, params_of, sites = file_view(tu, text_acc)
        d2 = next((x for x in defs if x["name"] == fn), None)
        if d2 is None:
            rows.append(dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="S", calib=calib_id, tu=tu, unit=fn, fn=fn, verdict="TOOL-ERROR",
                             err="body not found in the accumulated text", sites=[]))
            continue
        nh0 = body_nhash(masked, d2)
        if im_only:                                                # T5.c2 `--forms I,M`: the recipe ladder only, the prior row merged
            text_acc, ents, ist = im_recipe_pass(tu, fn, text_acc, judge_r, f"{short}{d['line']}m")
            prior = (latest or {}).get(("S", tu, fn))
            now = time.strftime("%Y-%m-%d %H:%M:%S")
            if prior is not None:
                row = json.loads(json.dumps(prior))
                row.update(ts=now, label=label, calib=calib_id, im_of=prior.get("label"), nhash_before=nh0, nhash_after=nh0, compiles=0, seconds=0.0)
            else:
                row = dict(ts=now, label=label, rung="S", calib=calib_id, tu=tu, unit=fn, fn=fn, addr=dl.fn_addr(fn, tu), header=is_hdr,
                           nhash_before=nh0, nhash_after=nh0, bases=[], skips={}, sites=[], compiles=0, seconds=0.0, linked=0,
                           verdict=("R:" + sorted(ist["drawn"])[0]) if ist["drawn"] else "RESIDUAL")
            im_row_merge(row, ents, ist, fresh=prior is None)
            im_count(ist)
            rows.append(row)
            out["compiles"] += row["compiles"]; out["seconds"] += row["seconds"]
            continue
        if ("S", tu, fn, nh0) in done:
            continue
        bsites = [s for s in sites if s.get("fn") == fn]
        why = {}
        per_base = s_body_edits(tu, fn, text_acc, masked, d2, bsites, bodies[fn], allow_local, local_types, why=why)
        typed_other = typed_bases_of(tu, fn, bodies[fn])
        edits = [e for (_, _, status, es, _) in per_base for e in es]
        _, overlapped = drop_overlaps(edits)                       # a nested base's site holds its parent's (T3.c3)
        edits = [e for e in edits if not any(e is o for o in overlapped)]      # per_base order kept for the S2 search
        skips = collections.Counter()
        for (_, _, _, _, sk) in per_base:
            skips.update(sk)
        if overlapped:
            skips["overlap-edit"] += len(overlapped)
        row = dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="S", calib=calib_id, tu=tu, unit=fn, fn=fn, addr=dl.fn_addr(fn, tu),
                   header=is_hdr, nhash_before=nh0, nhash_after=nh0,
                   bases=[dict(base=bk, type=tn, status=stt, edits=len(es), skips=dict(sk)) for (bk, tn, stt, es, sk) in per_base],
                   skips=dict(skips), sites=[], compiles=0, seconds=0.0, linked=0)
        out["skipped"] += sum(skips.values())
        if not edits:
            statuses = {stt for (_, _, stt, _, _) in per_base}
            row["verdict"] = ("TYPE-NOT-VISIBLE" if statuses == {"TYPE-NOT-VISIBLE"} else "TYPE-NOT-CANONICAL" if "TYPE-NOT-CANONICAL" in statuses
                              and not statuses & {"CANONICAL", "LOCAL"} else "NO-SITE")
            row["sites"], resp = s_site_rows(text_acc, masked, bsites, per_base, why, [], [], [], False, False, typed_other,
                                             not want_recipes, {})
            if resp:                                               # kept-class sites only: the body is KEPT, its casts respelled (P39 T3)
                row["verdict"] = "KEPT"
                row["respelled"] = len(resp)
                text_acc = compose_text(text_acc, resp)
                out["respelled"] += len(resp)
            if want_recipes:                                       # T5.c2: the I/M global-base sites through the R ladder
                text_acc, ents, ist = im_recipe_pass(tu, fn, text_acc, judge_r, f"{short}{d['line']}m")
                if ents:
                    im_row_merge(row, ents, ist, fresh=True)
                    im_count(ist)
            rows.append(row)
            out["compiles"] += row["compiles"]; out["seconds"] += row["seconds"]     # T5.c2: 0 before the ladder (no judgement here)
            continue
        tname_of = {id(e): tn for (_, tn, _, es, _) in per_base for e in es}
        base_text = text_acc
        # a LOCAL type (try mode) travels with its body: its typedef is inserted at file scope right before this function; a
        # typedef already placed below (an earlier, lower body of the same type) is moved up so both bodies see it (bottom-up order)
        needed = {tn for (_, tn, stt, es, _) in per_base if stt == "LOCAL" and any(any(e is x for x in edits) for e in es)}   # was: `and es` (T3.c3)
        ls_acc = dl.line_starts(base_text)
        ins_pos = ls_acc[d2["line"] - 1]
        inserts = []
        for tn in sorted(needed):
            if tn in local_pos:
                old_at = local_pos[tn]
                inserts.append((old_at, old_at + len(local_types[tn]), ""))          # delete the lower copy
            inserts.append((ins_pos, ins_pos, local_types[tn]))

        def cands(sub, tag):
            return judge_files({tu: compose_text(base_text, list(sub) + inserts)}, tag, pool=pool)
        r = cands(edits, f"{short}{d['line']}")
        row["compiles"] += r["compiles"]; row["seconds"] += r["seconds"]; row["linked"] += len(r["linked"])
        accepted, kept = list(edits), []
        if r["verdict"] == "IDENTICAL":
            row["verdict"] = "MEMBERS"
        elif r["verdict"] == "DIFFERS":
            res = classify_residual(tu, fn, r["cand0"])
            row["residual"] = res
            row["hint"] = pass_hint(res)
            kept, n_c, gv = greedy_kept(lambda sub, tag: cands(sub, tag)["verdict"], edits, f"{short}{d['line']}g")
            row["compiles"] += n_c
            if gv == "IDENTICAL":
                keep_ids = {id(k) for k in kept}
                accepted = [e for e in edits if id(e) not in keep_ids]
                row["verdict"] = "S2" if accepted else "KEPT-ALL"
            else:
                accepted, kept = [], list(edits)
                row["verdict"] = "KEPT-ALL"
                row["err"] = "S2 found no kept-cast set (NO-SET): the typedef or the mask moved bytes — a tool question"
        else:
            row["verdict"] = "REFUSED"
            row["err"] = f"{r['verdict']}: {r['err'][:200]}"
            accepted, kept = [], list(edits)
        # every raw site its own class (P39 T3; was: the body hint on the kept edits, KEPT(overlap-edit) on the dropped nested ones)
        row["sites"], resp = s_site_rows(base_text, masked, bsites, per_base, why, edits, accepted, overlapped,
                                         row.get("verdict") in ("S2", "KEPT-ALL"), row.get("verdict") == "REFUSED", typed_other,
                                         row.get("verdict") in S_RESPELL_VERDICTS and not want_recipes, tname_of)
        if resp:
            row["respelled"] = len(resp)
            out["respelled"] += len(resp)
        out["members"] += len(accepted)
        out["kept"] += len(kept) + len(overlapped)
        if accepted:
            text_acc = compose_text(base_text, list(accepted) + resp + inserts)
            for tn in sorted(needed):
                local_pos[tn] = ins_pos + sum(len(local_types[t_]) for t_ in sorted(needed) if t_ < tn)
            # S+A: the struct hypothesis on a lever-bearing body
            if want_sa and (tu, fn) in ds.sites_by_body() and JUDGE_STUB is None:
                def judge_one(text, tag):
                    return judge_files({tu: text}, tag, pool=pool)
                text2, lres = struct_plus_levers(tu, fn, text_acc, judge_one, label, log=log)
                if lres is not None:
                    row["levers"] = dict(verdict=lres["verdict"], rung=lres.get("rung"), removed=sum(1 for x in lres["sites"] if x["verdict"] in ("REMOVED", "REWRITTEN")),
                                         needed=sum(1 for x in lres["sites"] if x["verdict"] == "NEEDED"), refused=lres.get("refused", 0),
                                         compiles=lres["compiles"])
                    row["compiles"] += lres["compiles"]; row["seconds"] += lres["seconds"]
                    if text2 != text_acc:
                        out["levers_off"] += row["levers"]["removed"]
                        text_acc = text2
                        row["verdict"] = "S+A"
                    if write and row["verdict"] == "S+A":
                        # one lever record: delever's ledger gets the row too (a dry run — write=False — leaves no trace, R66)
                        dl.ledger_append([dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=f"P37-{label}", rung="S+A", calib=calib_id, tu=tu, fn=fn,
                                               addr=dl.fn_addr(fn, tu), aliases=[], header=is_hdr, nhash_before=nh0, nhash_after=None,
                                               verdict=lres["verdict"], sites=lres["sites"], compiles=lres["compiles"], seconds=round(lres["seconds"], 3))])
        elif resp:                                                 # KEPT-ALL: only the respelled casts change (P39 T3)
            text_acc = compose_text(base_text, resp)
        if want_recipes and kept:
            row["recipes"] = run_recipes(tu, fn, text_acc, kept, lambda text, tag, reloc=False: judge_files({tu: text}, tag, pool=pool, reloc=reloc), f"{short}{d['line']}r")
            for hit in row["recipes"]:
                if hit["verdict"] == "IDENTICAL" and hit.get("adopt"):
                    text_acc = hit["text"]
                    hit.pop("text", None)
                    row["verdict"] = "R:" + hit["name"]
                    break
            for hit in row["recipes"]:
                hit.pop("text", None)
        if want_recipes:                                           # T5.c2: then every I/M global-base site through the R ladder
            text_acc, ents, ist = im_recipe_pass(tu, fn, text_acc, judge_r, f"{short}{d['line']}m")
            if ents:
                im_row_merge(row, ents, ist, fresh=True)
                im_count(ist)
        rows.append(row)
        out["compiles"] += row["compiles"]; out["seconds"] += row["seconds"]; out["linked"] += row["linked"]
    s_macro_rows(tu, text_acc, [r for r in rows if "im_of" not in r])   # T3.c4: the macro sites in the census's key (T5.c2: a merged
                                                                        # I/M row keeps its prior's macro entries as they are)
    if text_acc == raw:
        out["final"] = "UNCHANGED"
        return out
    fr = judge_files({tu: text_acc}, f"{short}F", pool=pool)
    out["compiles"] += fr["compiles"]; out["seconds"] += fr["seconds"]
    if fr["verdict"] != "IDENTICAL":
        dl.restore_file(path, raw, st)
        out["final"] = f"COMBINATION-FAILED ({fr['verdict']})"
        log(f"  {tu}: COMBINATION-FAILED ({fr['verdict']} {fr['err'][:120]}) — every body of this file REFUSED, the file restored")
        for row in rows:
            row["verdict"] = "COMBINATION-FAILED"
            row["nhash_after"] = None
        out["members"] = out["kept"] = out["levers_off"] = out["respelled"] = out["im_drawn"] = 0
        return out
    out["final"] = "IDENTICAL" + (" (linked)" if fr["linked"] else "")
    if JUDGE_STUB is None and write:
        path.write_text(text_acc, errors="surrogateescape")
    out["written"] = bool(write)
    out["final_text"] = text_acc
    # after-hashes from the final text
    try:
        masked_f, defs_f, _, _, _ = file_view(tu, text_acc)
        nh = {x["name"]: body_nhash(masked_f, x) for x in defs_f}
        for row in rows:
            row["nhash_after"] = nh.get(row["fn"], row.get("nhash_before"))
    except Exception as ex:      # noqa: BLE001
        log(f"  {tu}: after-hash walk failed ({ex}) — after-hash = before-hash")
    return out


# ----------------------------------------------------------------------------------------------------------------------
# rung R: recipes for a KEPT cast (the registry; each with a fixture in the selftest; T7's harvest adds here)
# ----------------------------------------------------------------------------------------------------------------------
NARROW_TYPES = {"s8", "u8", "s16", "u16", "char", "short", "unsigned char", "signed char", "unsigned short", "signed short"}


def _refuse(why, cause):
    """T5.c2: a recipe's refusal — the cause (`R<n>-<WHY>`) appended to `why` when the caller asks (the I/M ladder); always []."""
    if why is not None:
        why.append(cause)
    return []


def recipe_ptr_global_member(text, tu, fn, site, why=None):
    """R1 (§458): a KEPT site on a POINTER GLOBAL base read by value — the pointer's own read spelled as a struct member so both sides
    of the pair carry /s: `*(u16 *)(D_x + 0x34)` -> `((S *)(((struct { PT p; } *)&D_x)->p))->…` needs the member type; the recipe
    keeps the SITE's cast and only respells the base: `*(u16 *)((((struct { PT p; } *)&D_x)->p) + 0x34)`."""
    if site.get("bclass") != "global":
        return _refuse(why, "R1-NOT-GLOBAL")
    base = site["base"]
    m = re.search(r"\bextern\s+((?:(?:const|volatile|unsigned|signed|struct|union)\s+)*[A-Za-z_]\w*\s*\**)\s*" + re.escape(base) + r"\s*;", dl.same_len_mask(text))
    ptype = sl._norm_type(m.group(1)) if m else "void *"
    span = text[site["pos"]:site["end"]]
    new = re.sub(r"(?<![\w.])" + re.escape(base) + r"\b", f"(((struct {{ {ptype} p; }} *)&{base})->p)", span, count=1)
    if new == span:
        return _refuse(why, "R1-NO-EDIT")
    return [(text[:site["pos"]] + new + text[site["end"]:], f"R1 pointer global {base} read as a struct member ({ptype})", False)]


def recipe_extern_array(text, tu, fn, site, why=None):
    """R2 (a18): a KEPT site on a SCALAR GLOBAL base (`&D_x + k` / `D_x` by value): the TU's `extern T D_x;` becomes `extern T D_x[];`,
    every mention follows (`D_x` -> `D_x[0]`, `&D_x` -> `D_x`), the site becomes `D_x[k / w]` — the MEM_IN_STRUCT alias escape."""
    if site.get("bclass") not in ("gaddr", "global"):
        return _refuse(why, "R2-NOT-GLOBAL")
    base = site["base"]
    masked = dl.same_len_mask(text)
    dm = re.search(r"\bextern\s+((?:(?:const|volatile|unsigned|signed)\s+)*[A-Za-z_]\w*)\s+" + re.escape(base) + r"\s*;", masked)
    if not dm:      # no declaration in the TU: the symbol's extern is an included header's (not this TU's to respell)
        return _refuse(why, "R2-NO-SCALAR-EXTERN" if re.search(r"\bextern\b[^;{}]*(?<![\w.])" + re.escape(base) + r"\b", masked)
                       else "R2-HEADER-EXTERN")
    T = sl._norm_type(dm.group(1))
    w = sl.scalar_of(T)
    if not w or w[0] == 0:
        return _refuse(why, "R2-NO-SCALAR-EXTERN")
    if (site.get("off") or 0) % w[0] != 0:
        return _refuse(why, "R2-MISALIGNED")
    if site.get("width") != w[0]:
        return _refuse(why, "R2-WIDTH")
    k = (site.get("off") or 0) // w[0]
    out = []
    edits = [(dm.start(), dm.end(), f"extern {T} {base}[];")]
    for mm in re.finditer(r"(&\s*)?(?<![\w.])" + re.escape(base) + r"\b", masked):
        if dm.start() <= mm.start() < dm.end():
            continue
        if site["pos"] <= mm.start() < site["end"]:
            continue
        if mm.group(1):
            edits.append((mm.start(), mm.end(), base))
        else:
            edits.append((mm.start(), mm.end(), f"{base}[0]"))
    edits.append((site["pos"], site["end"], f"{base}[{k}]"))
    try:
        cand = compose_text(text, edits)
    except Refuse:
        return _refuse(why, "R2-NO-EDIT")
    out.append((cand, f"R2 {base} declared extern {T} {base}[] (a18)", False))
    return out


def recipe_walked_pointer(text, tu, fn, site, why=None):
    """R3 (f3): consecutive carved words `D_A, D_(A+w), D_(A+2w)…` of one width mentioned in the body, walked through one pointer:
    `T *p37w = &D_A;` at the body's declarations, every `D_(A+kw)` -> `p37w[k]`. Changes the relocation spelling -> linked mode."""
    base = site.get("base") or ""
    mm = re.fullmatch(r"D_([0-9A-Fa-f]{8})", base)
    if site.get("bclass") not in ("gaddr", "global"):
        return _refuse(why, "R3-NOT-GLOBAL")
    if not mm:
        return _refuse(why, "R3-NOT-CARVED")
    masked = dl.same_len_mask(text)
    decls = {m.group(2): sl._norm_type(m.group(1)) for m in re.finditer(r"\bextern\s+((?:(?:const|volatile|unsigned|signed)\s+)*[A-Za-z_]\w*)\s+(D_[0-9A-Fa-f]{8})\s*;", masked)}
    T = decls.get(base)
    w = sl.scalar_of(T) if T else None
    if not w or w[0] == 0:
        return _refuse(why, "R3-NO-SCALAR-EXTERN")
    A = int(mm.group(1), 16)
    ds_ = [r for r in sc.scan_text(text, tu, shared_defs=None) if r["form"] == "def" and r["name"] == fn]
    if not ds_:
        return _refuse(why, "R3-NO-BODY")
    d = ds_[0]
    ls = dl.line_starts(masked)
    s0, s1 = ls[d["line"] - 1], (ls[d["end"]] if d["end"] < len(ls) else len(masked))
    body = masked[s0:s1]
    # the run: every D_(A+kw) mentioned in the body with the same declared width, k >= 0, contiguous from A
    run = []
    k = 0
    while True:
        name = f"D_{A + k * w[0]:08X}"
        if name not in decls or sl.scalar_of(decls[name]) != w or not re.search(r"(?<![\w.])" + name + r"\b", body):
            break
        run.append(name); k += 1
    if len(run) < 2:
        return _refuse(why, "R3-NOT-CONTIGUOUS")
    edits = []
    for i, name in enumerate(run):
        for m in re.finditer(r"(&\s*)?(?<![\w.])" + name + r"\b", body):
            if m.group(1):
                edits.append((s0 + m.start(), s0 + m.end(), f"(p37w + {i})" if i else "p37w"))
            else:
                edits.append((s0 + m.start(), s0 + m.end(), f"p37w[{i}]"))
    # the declaration: after the body's opening brace, before the first statement — as the last declaration line
    brace = body.find("{")
    decl_end = brace + 1
    for m in re.finditer(r"\n[ \t]*(?:(?:const|volatile|unsigned|signed|struct|union|register)\s+)*[A-Za-z_]\w*\s*\**\s*[A-Za-z_]\w*(?:\s*\[[^\]]*\])*(?:\s*=[^;]*)?;", body):
        if m.start() > decl_end + 400:
            break
        decl_end = m.end()
    indent = re.search(r"\n([ \t]*)\S", body[brace:]) 
    ind = indent.group(1) if indent else "    "
    edits.append((s0 + decl_end, s0 + decl_end, f"\n{ind}{T} *p37w = &{run[0]};"))
    try:
        cand = compose_text(text, edits)
    except Refuse:
        return _refuse(why, "R3-NO-EDIT")
    return [(cand, f"R3 {run[0]}..{run[-1]} ({len(run)} x {T}) walked through one pointer (f3)", True)]


RECIPES = collections.OrderedDict([("R1-ptr-global-member", recipe_ptr_global_member), ("R2-extern-array", recipe_extern_array),
                                   ("R3-walked-pointer", recipe_walked_pointer)])


def run_recipes(tu, fn, text, kept_edits, judge, tag):
    """Every registered recipe on every KEPT site: [(name, note, verdict)]; a recipe that judges IDENTICAL is `adopt`-able (the caller
    takes the first). The kept sites' positions are re-walked on `text` by (line, off, base)."""
    masked, defs, span_of_line, params_of, sites = file_view(tu, text)
    # a kept site is found in the (possibly shifted — a typedef inserted above the body) text by its SHAPE and its rank among the
    # body's same-shaped sites, never by its line (R114: positions are re-derived, not cached)
    def shape(s):
        return (s.get("form"), str(s.get("base")), s.get("off"), s.get("ctype"), s.get("access"))
    ranked = collections.defaultdict(list)
    for s in sites:
        if s.get("fn") == fn and s.get("form") in RAW_FORMS:
            ranked[shape(s)].append(s)
    orig_rank = collections.Counter()
    hits = []
    for e in kept_edits:
        s0 = e[3]
        k = orig_rank[shape(s0)]
        orig_rank[shape(s0)] += 1
        cands_s = ranked.get(shape(s0), [])
        s = cands_s[k] if k < len(cands_s) else None
        if s is None:
            hits.append(dict(name="-", site=s0.get("line"), note="kept site not found in the S2 text", verdict="TOOL-ERROR"))
            continue
        for i, (name, gen) in enumerate(RECIPES.items()):
            try:
                cands = gen(text, tu, fn, s)
            except Exception as ex:     # noqa: BLE001
                hits.append(dict(name=name, site=s.get("line"), note=f"generator error {ex!r}"[:120], verdict="TOOL-ERROR"))
                continue
            for j, (cand, note, reloc) in enumerate(cands):
                r = judge(cand, f"{tag}{i}{j}", reloc)
                hits.append(dict(name=name, site=s.get("line"), note=note, verdict=r["verdict"], linked=bool(r["linked"]), adopt=(r["verdict"] == "IDENTICAL"), text=cand))
                if r["verdict"] == "IDENTICAL":
                    return hits
    return hits


# T5.c2: the R ladder on EVERY raw I/M site whose base is a global (not only S2's kept casts). A site no recipe draws keeps the most
# specific refusal as RESIDUAL(<Rn-CAUSE>) (rank below; a judged verdict — DIFFERS, COMPILE-ERROR … — ranks 4; ties: registry order).
IM_FORMS = ("I", "M")
IM_BCLASS = ("gaddr", "global")
RECIPE_CAUSE_RANK = {"NOT-GLOBAL": 0, "NOT-CARVED": 0, "TOOL-ERROR": 0, "STILL-RAW": 1, "HEADER-EXTERN": 2, "NO-SCALAR-EXTERN": 2,
                     "NO-BODY": 2, "MISALIGNED": 3, "WIDTH": 3, "NOT-CONTIGUOUS": 3, "NO-EDIT": 3, "REKEYS": 3}


def _site_key(s):
    return _residue_key(s.get("form"), f"{s.get('bclass')}:{s.get('base')}", s.get("off"))


def _is_im_global(s, fn):
    return s.get("fn") == fn and s.get("form") in IM_FORMS and s.get("bclass") in IM_BCLASS


def _im_guard(sites0, sites1, fn):
    """None when a recipe candidate (census view sites1) draws one I/M global-base site of `fn` and moves nothing else; else the
    cause: STILL-RAW (the TU's raw + macro site count did not drop: the cast was respelled, not removed) or REKEYS (another raw / macro
    site of the TU — outside fn's I/M global-base set — changed its census key: e.g. R2's `&D_x` -> `D_x` on a covered P site)."""
    allf = RAW_FORMS + ("K",)
    if sum(1 for s in sites1 if s.get("form") in allf) >= sum(1 for s in sites0 if s.get("form") in allf):
        return "STILL-RAW"
    rest = lambda ss: collections.Counter(_site_key(s) + (s.get("fn"),) for s in ss if s.get("form") in allf and not _is_im_global(s, fn))
    if rest(sites1) != rest(sites0):
        return "REKEYS"
    if sum(1 for s in sites1 if _is_im_global(s, fn)) >= sum(1 for s in sites0 if _is_im_global(s, fn)):
        return "STILL-RAW"
    return None


def im_recipe_pass(tu, fn, text, judge, tag):
    """T5.c2: RECIPES (registry order) on every raw I/M site of body `fn` whose bclass is gaddr/global. Per site each recipe's
    candidates pass _im_guard (else `<Rn>-STILL-RAW` / `<Rn>-REKEYS`, never judged), then `judge`; the first IDENTICAL is adopted and the
    file re-walked (positions re-derived, R114). Returns (text, entries, stats): entries = site_row per drawn site (`R:<name>`, its
    pre-draw key) and per site left raw in the FINAL text (RESIDUAL(<cause>), the most specific refusal: RECIPE_CAUSE_RANK, ties
    registry order); stats = dict(drawn{recipe: n}, residual{cause: n}, compiles, seconds)."""
    refused, cause_of = collections.Counter(), {}
    st = dict(drawn=collections.Counter(), residual=collections.Counter(), compiles=0, seconds=0.0)
    ents = []
    sites = file_view(tu, text)[4]
    for it in range(4 * len(sites) + 8):                          # a bound: every pass draws a site or refuses one occurrence
        seen, s = collections.Counter(), None
        for x in sorted((x for x in sites if _is_im_global(x, fn)), key=lambda x: x.get("pos", 0)):
            k = _site_key(x)
            if seen[k] >= refused[k]:
                s = x
                break
            seen[k] += 1
        if s is None:
            break
        best, adopted = None, None
        for i, (name, gen) in enumerate(RECIPES.items()):
            rn = name.split("-", 1)[0]
            why = []
            try:
                cands = gen(text, tu, fn, s, why=why)
            except Exception as ex:     # noqa: BLE001 — a generator crash is a refusal, never a lost site
                cands, why = [], [f"{rn}-TOOL-ERROR"]
            causes = list(why)
            for j, (cand, note, reloc) in enumerate(cands):
                sites1 = file_view(tu, cand)[4]
                g = _im_guard(sites, sites1, fn)
                if g is None:
                    r = judge(cand, f"{tag}{it}{i}{j}", reloc)
                    st["compiles"] += r.get("compiles", 0); st["seconds"] += r.get("seconds", 0.0)
                    if r["verdict"] == "IDENTICAL":
                        adopted = (name, cand, sites1)
                        break
                    g = r["verdict"]
                causes.append(f"{rn}-{g}")
            if adopted:
                break
            for c in causes:
                rk = RECIPE_CAUSE_RANK.get(c.split("-", 1)[1], 4)
                if best is None or rk > best[0]:
                    best = (rk, c)
        if adopted:
            name, text, sites = adopted
            st["drawn"][name] += 1
            ents.append(site_row(s, f"R:{name}", cause=name))
            continue
        k = _site_key(s)
        refused[k] += 1
        cause_of[k] = best[1] if best else "R-NONE"
    for x in sorted((x for x in sites if _is_im_global(x, fn)), key=lambda x: x.get("pos", 0)):
        c = cause_of.get(_site_key(x), "R-UNTRIED")
        st["residual"][c] += 1
        ents.append(site_row(x, f"RESIDUAL({c})", cause=c))
    st["drawn"], st["residual"] = dict(st["drawn"]), dict(st["residual"])
    st["seconds"] = round(st["seconds"], 3)
    return text, ents, st


def im_row_merge(row, ents, st, fresh):
    """T5.c2: the I/M ladder's entries into a rung-S row. Per entry ONE same-key entry (form, normalised base, off) is replaced: any
    non-MEMBER, non-macro entry when the row was walked in this run (`fresh`: s_site_rows' class of that site), else only a RESIDUAL
    one (a prior row's MEMBER / KEPT entries are kept — the T10 binding)."""
    sites = list(row.get("sites") or [])
    for e in ents:
        k = _residue_key(e["form"], e["base"], e["off"])
        for i, x in enumerate(sites):
            v = str(x.get("verdict") or "")
            if _residue_key(x.get("form"), x.get("base"), x.get("off")) == k and (
                    v.startswith("RESIDUAL(") or (fresh and v != "MEMBER" and not v.startswith("R:") and not x.get("macro_of"))):
                del sites[i]
                break
    row["sites"] = sites + ents
    row["im"] = st
    row["compiles"] = row.get("compiles", 0) + st["compiles"]
    row["seconds"] = row.get("seconds", 0.0) + st["seconds"]


# ----------------------------------------------------------------------------------------------------------------------
# rung D: the declaration layer (per TU; a definition-side change as one multi-file unit)
# ----------------------------------------------------------------------------------------------------------------------
_walk = None


def walk():
    global _walk
    if _walk is None:
        _walk = tc.walk_all(16, use_cache=True)
    return _walk


def promoted_params(params):
    """The width-promoted spelling of an ANSI parameter list (what a K&R call passes): narrow integers -> s32, float -> f32? no: double
    is what C89 promotes float to, but the tree spells f32 and PsyQ has no doubles in game code — kept as written."""
    out = []
    for part in sl._split_top(params, ","):
        p = part.strip()
        m = PARAM_DECL.match(p)
        if m and not m.group(2) and sl._norm_type(m.group(1)) in NARROW_TYPES:
            out.append(f"s32 {m.group(3)}")
        elif p in NARROW_TYPES:
            out.append("s32")
        else:
            out.append(p)
    return ", ".join(out)


_kr_cache = {}


def kr_ansi_params(rel, fndef):
    """A K&R definition's DEFAULT-PROMOTED parameter list as ANSI text (argcheck.kr_params on the definition's head). Cached per
    FILE (one mask + one scan per file, never per call — 1,889 K&R definitions re-masked per TU stalled the first batch)."""
    import argcheck
    with _LOCK:
        if rel not in _kr_cache:
            text = (REPO / rel).read_text(errors="surrogateescape")
            masked = sc.mask_text(text)
            found = {}
            for m in argcheck.KR_DEF.finditer(masked):
                names = [n.strip() for n in m.group(2).split(",")]
                types = argcheck.kr_params(names, m.group(3))
                found.setdefault(m.group(1), ", ".join(f"{t} {n}" for t, n in zip(types, names)))
            _kr_cache[rel] = found
    return _kr_cache[rel].get(fndef["fn"])


def defs_visible(tu):
    """{callee: [(def_tu, ret, params_ansi, kr)]} — the definitions a TU's calls can mean: its own file, its binary's source dir(s),
    the shared headers it includes, then main's and resident's (unique names). Distinct signatures -> the caller REFUSES (ambiguous)."""
    if DEFS_OVERRIDE is not None:
        return DEFS_OVERRIDE
    w = walk()
    results, tu_aliases = w["results"], w["tu_aliases"]
    import corpus
    dirs = set()
    for a in tu_aliases.get(tu, ()):
        try:
            dirs.add(corpus.src_dir(a).rstrip("/"))
        except Exception:      # noqa: BLE001
            pass
    files = [tu] + sorted(h for h in headers_of(tu) if h in results)
    for d_ in sorted(dirs):
        for rel in _files_in_dir(d_):
            if rel == tu:
                continue
            # the sibling TU AND the shared headers it includes: since P35 every shared body is a header included by ONE member TU of
            # the binary, so a definition visible to a sibling is a definition this binary links (t4_D21: 10,495 "external" rows were
            # func_80147514-shaped — defined in src/shared/ov/, included by the binary's *_after.c, invisible here)
            files.append(rel)
            files += sorted(h for h in headers_of(rel) if h in results)
    out = collections.defaultdict(list)
    seen = set()
    for rel in files:
        if rel in seen or rel not in results or results[rel] is None:
            continue
        seen.add(rel)
        for f in _defs_of_file(rel):
            out[f[0]].append(f[1:])
    for name, lst in _fallback_defs().items():
        if name not in out:
            out[name] = list(lst)
    for name, lst in _fleet_unique_defs().items():
        # the third level (T4, 2026-09-12): a callee no member TU defines and main/resident do not either — a module calling an
        # overlay-region function — has the fleet's ONE signature when every definition of the name agrees (723 "no visible definition"
        # rows were this; a name with two bodies stays unresolved: the caller's binary decides, R48)
        if name not in out:
            out[name] = list(lst)
    return out


_fleet_unique = None


def _fleet_unique_defs():
    """{name: [(def_tu, ret, params, kr)]} for every name whose definitions across the fleet share ONE (ret, params) — computed once."""
    global _fleet_unique
    if _fleet_unique is None:
        results = walk()["results"]
        by = collections.defaultdict(list)
        for rel in sorted(results):
            if rel.endswith((".c", ".h")) and results[rel]:
                for f in _defs_of_file(rel):
                    by[f[0]].append(f[1:])
        _fleet_unique = {n: [l[0]] for n, l in by.items() if len({(x[1], sl._norm_type(re.sub(r"\s+", " ", x[2]))) for x in l}) == 1}
    return _fleet_unique


_dir_files = {}
_file_defs = {}
_fallback = None


def _files_in_dir(d_):
    with _LOCK:
        if d_ not in _dir_files:
            results = walk()["results"]
            _dir_files[d_] = sorted(rel for rel in results if rel.endswith(".c") and rel.startswith(d_ + "/") and rel.count("/") == d_.count("/") + 1)
    return _dir_files[d_]


def _defs_of_file(rel):
    """[(fn, rel, ret, params_ansi, kr)] for one file's definitions (K&R heads promoted), computed once."""
    with _LOCK:
        cached = _file_defs.get(rel)
    if cached is not None:
        return cached
    r = walk()["results"].get(rel)
    out = []
    for f in (r or {}).get("fndefs", []):
        params = f["params"]
        if f.get("kr"):
            params = kr_ansi_params(rel, f) or params
        out.append((f["fn"], rel, f["ret"], params, bool(f.get("kr"))))
    with _LOCK:
        _file_defs[rel] = out
    return out


def _fallback_defs():
    """main's and resident's definitions (unique names — every overlay calls them), computed once."""
    global _fallback
    if _fallback is None:
        results = walk()["results"]
        fb = collections.defaultdict(list)
        for rel in sorted(results):
            if rel.endswith(".c") and (rel.count("/") == 1 or rel.startswith("src/resident/")):
                for f in _defs_of_file(rel):
                    fb[f[0]].append(f[1:])
        _fallback = fb
    return _fallback


DECL_RX_T = r"(?<![\w.])(extern\s+)?((?:(?:const|volatile|unsigned|signed|struct|union|static)\s+)*[A-Za-z_]\w*[\s*]*)\b{name}\s*\(([^;{{}}]*)\)\s*;"


def decl_sites(masked, callee):
    """[(start, end, line, has_extern, ret, params)] for every declaration of `callee` in a masked TU (file + block scope)."""
    out = []
    rx = re.compile(DECL_RX_T.format(name=re.escape(callee)))
    for m in rx.finditer(masked):
        ret = sl._norm_type(m.group(2))
        if ret in ("return", "goto", "else", "case") or not ret:
            continue
        if "__asm__" in m.group(3):
            continue        # `T f(params) __asm__("sym");` — an asm-label declaration names the symbol; its rewrite would drop the label (P3.39 T6)
        out.append((m.start(), m.end(), masked.count("\n", 0, m.start()) + 1, bool(m.group(1)), ret, re.sub(r"\s+", " ", m.group(3)).strip()))
    return out


def call_arg_counts(masked, callee, decl_spans):
    """The distinct argument counts the TU's CALLS pass to `callee` (declarations and the definition excluded)."""
    counts = set()
    for m in re.finditer(r"(?<![\w.>])" + re.escape(callee) + r"\s*\(", masked):
        if any(a <= m.start() < b for (a, b) in decl_spans):
            continue
        inner, close = tc._paren_body(masked, m.end() - 1)
        if inner is None:
            continue
        # the definition's head: `) {` (whitespace/newlines only) or a K&R head (`) int a; s32 b; {`). The first form of this test
        # skipped any match whose LINE held a later `{` — `if (func_80161B18() != 0) {` read as a definition (t4_D27: `[]`, `? of 1 args`)
        rest = masked[close + 1:close + 400]
        if re.match(r"\s*\{", rest) or re.match(r"(\s*[A-Za-z_][\w\s*,\[\]]*;)+\s*\{", rest):
            continue
        inner = inner.strip()
        counts.add(0 if inner in ("", "void") else len(sl._split_top(inner, ",")))
    return sorted(counts)


def unit_call_counts(tu, masked, unit):
    """(counts, where): the distinct argument counts every call in the TU's COMPILATION passes to the callee — the TU's own text plus
    every shared body it includes — and the headers the counts came from. t4_D23 read `[]` for `func_801483E8` while the 0-argument call
    that made the ANSI form a COMPILE-ERROR sat in shared/ov/func_80161124.h:19: the marker said `? of 1 args` for a known count."""
    counts = set(call_arg_counts(masked, unit["callee"], [(s, e) for (s, e, *_) in unit["decls"]]))
    where = []
    results = walk()["results"]
    for h in sorted(headers_of(tu)):
        if h not in results or not h.endswith(".h") or not (REPO / h).exists():
            continue
        hm = dl.same_len_mask((REPO / h).read_text())
        hc = call_arg_counts(hm, unit["callee"], [(s, e) for (s, e, *_) in decl_sites(hm, unit["callee"])])
        if hc:
            counts.update(hc)
            where.append(h)
    return sorted(counts), where


def d_units(tu, text, callees=None, skipped=None):
    """The TU's declaration units: [dict(callee, decls[(s,e,line,ext,ret,params)], ret, ansi, promoted, defn_tu, kr_def, ambiguous)] —
    every callee with >=1 declaration whose spelling is not the canonical one. `skipped` (a dict) receives {callee: reason} for every
    requested callee that yields NO unit — the planner's rows the engine cannot act on, settled in the ledger with that reason so a
    batch never draws them again (t4_D21 drew 300 TUs for 0 units on exactly these)."""
    masked = dl.same_len_mask(text)
    vis = defs_visible(tu)
    names = set(callees) if callees else set(vis)
    units = []
    for callee in sorted(names):
        cands = vis.get(callee)
        if not cands:
            if skipped is not None:
                al = _alias_of_real().get(callee)
                skipped[callee] = (f"no visible definition — the body is still alias-defined as {al} (an UNALIAS-KEPT class)" if al
                                   else "no visible definition (external to this TU's binary, or argcheck's alias-resolved row)")
            continue
        sigs = {(r, sl._norm_type(re.sub(r"\s+", " ", p))) for (_, r, p, _) in cands}
        decls = decl_sites(masked, callee)
        if not decls:
            if skipped is not None:
                skipped[callee] = "no declaration the engine's regex reads (a typedef'd pointer / a K&R-form the census counts)"
            continue
        if len(sigs) > 1:
            units.append(dict(callee=callee, decls=decls, ambiguous=sorted(sigs)[:4], defn_tu=cands[0][0]))
            continue
        ret, params = next(iter(sigs))
        params_n = params if params not in ("", "void") else "void"
        canon = {sl._norm_type(re.sub(r"\s+", " ", p)) if p.strip() not in ("",) else "void" for (_, _, _, _, r, p) in decls}
        rets = {r for (_, _, _, _, r, _) in decls}
        if canon == {params_n} and rets == {ret}:
            if skipped is not None:
                skipped[callee] = "already canonical"
            continue
        # a byte-proven K&R site already stands: every declaration `()` and marked `// K&R:` on its line — settled, not drawn again
        ls_ = dl.line_starts(masked)
        if all(p.strip() == "" and KR_MARK in text[ls_[ln - 1]:(ls_[ln] - 1 if ln < len(ls_) else len(text))] for (_, _, ln, _, _, p) in decls):
            if skipped is not None:
                skipped[callee] = "a marked K&R site already"
            continue
        units.append(dict(callee=callee, decls=decls, ret=ret, ansi=params_n, promoted=promoted_params(params_n), defn_tu=cands[0][0],
                          kr_def=cands[0][3], ambiguous=None))
    return units


def d_edits(unit, params):
    return [(s, e, f"{'extern ' if ext else ''}{unit['ret']} {unit['callee']}({params});") for (s, e, ln, ext, r, p) in unit["decls"]]


def _kr_marks_on(edits, marks):
    """The K&R markers land on the declaration LINES after the `()` rewrite: the marker edits were computed on the raw text's line
    ends, which the same-line rewrite does not move (a declaration is one line) — both edit sets compose."""
    return edits + marks


def kr_marker_edits(text, unit, counts, label):
    """`// K&R: n of m args (P37 rung D <label>)` appended to each `()` declaration line of the callee (a comment; counted apart)."""
    ls = dl.line_starts(text)
    m_ = 0 if unit["ansi"] == "void" else len(sl._split_top(unit["ansi"], ","))
    n_ = "/".join(str(c) for c in counts) if counts else "?"
    out = []
    seen = set()
    for (s, e, ln, ext, r, p) in unit["decls"]:
        if ln in seen:
            continue
        seen.add(ln)
        end = ls[ln] - 1 if ln < len(ls) else len(text)
        line = text[ls[ln - 1]:end]
        if KR_MARK in line:
            k = line.find(KR_MARK)
            j = k
            while j > 0 and line[j - 1] in " \t":
                j -= 1
            out.append((ls[ln - 1] + j, end, f"  {KR_MARK} {n_} of {m_} args (P37 rung D {label})"))
        else:
            out.append((end, end, f"  {KR_MARK} {n_} of {m_} args (P37 rung D {label})"))
    return out


ALIAS_RX = re.compile(r"(?<![\w.])extern\s+((?:(?:const|volatile|unsigned|signed|struct|union)\s+)*[A-Za-z_]\w*[\s*]*?)\s*\b([A-Za-z_]\w*)\s*((?:\[[^\]]*\])*)\s*__asm__\s*\(\s*\"(\w+)\"\s*\)\s*;")
PLAIN_EXTERN_T = r"(?<![\w.])extern\s+((?:(?:const|volatile|unsigned|signed|struct|union)\s+)*[A-Za-z_]\w*[\s*]*?)\s*\b{name}\s*((?:\[[^\]]*\])*)\s*;"


def e_units(tu, text, masked):
    """Class E: `extern T aD_x __asm__("D_x");` — a second NAME for one symbol. The unit per alias name: the declaration becomes
    `extern T D_x;` (or is deleted when the TU already declares D_x with the same type) and every use is renamed to the real symbol.
    A TU that declares D_x with ANOTHER type keeps the alias: the compile refuses the conflict — the symbol is an aggregate in truth
    (a union / array / struct: a18, f3), T6's."""
    units = {}
    all_decl_spans = []
    for m in ALIAS_RX.finditer(masked):
        T = sl._norm_type(m.group(1)) + (m.group(3) or "")
        aname, real = m.group(2), m.group(4)
        u = units.setdefault(aname, dict(kind="alias", callee=aname, real=real, type=T, decl_spans=[], edits=[], uses=0, conflict=None))
        u["decl_spans"].append((m.start(), m.end(), T))
        all_decl_spans.append((m.start(), m.end()))
    for aname, u in units.items():
        real = u["real"]
        if aname == real:
            # a same-name alias (`extern u8 D_x __asm__("D_x");`): the label says nothing the name does not — the declaration loses its
            # `__asm__`, no use is renamed (src/800.c's `D_80078E7C`; batch t4_D9's overlap with the `_w` alias's declaration)
            for (a, b, T) in u["decl_spans"]:
                u["edits"].append((a, b, f"extern {T.replace('[]', '')} {real}{'[]' if T.endswith('[]') else ''};"))
            u["edits"].sort()
            continue
        plain = [(mm.start(), mm.end(), sl._norm_type(mm.group(1)) + (mm.group(2) or "")) for mm in re.finditer(PLAIN_EXTERN_T.format(name=re.escape(real)), masked)]
        same = {t for (_, _, t) in plain} == {u["type"]} if plain else None
        if plain and not same:
            u["conflict"] = sorted({t for (_, _, t) in plain})
        spans = [(a, b) for (a, b, _) in u["decl_spans"]]
        for (a, b, T) in u["decl_spans"]:
            if plain and same:
                # the real symbol is declared with this very type already: the alias declaration goes (its line when alone)
                le = masked.find("\n", b)
                le = len(masked) if le < 0 else le
                ls_ = masked.rfind("\n", 0, a) + 1
                if masked[ls_:a].strip() == "" and masked[b:le].strip() == "":
                    u["edits"].append((ls_, le + 1 if le < len(masked) else le, ""))
                else:
                    u["edits"].append((a, b, ""))
            else:
                u["edits"].append((a, b, f"extern {T.replace('[]', '')} {real}{'[]' if T.endswith('[]') else ''};"))
        for mm in re.finditer(r"(?<![\w.])" + re.escape(aname) + r"\b", masked):
            if any(a <= mm.start() < b for (a, b) in all_decl_spans):
                continue                     # inside ANY alias declaration (its `__asm__("…")` label names the real symbol)
            u["edits"].append((mm.start(), mm.end(), real))
            u["uses"] += 1
        u["edits"].sort()
    return [u for _, u in sorted(units.items())]


def b_units(tu, text, masked):
    """`__builtin_abs(x)` -> `abs(x)`: gcc 2.7.2 declares `abs` as BUILT_IN_ABS itself when -fno-builtin is absent (c-decl.c
    init_decl_processing), so the spelling is the compiler's own — the oracle decides. One unit per TU."""
    sites = list(re.finditer(r"\b__builtin_abs\s*\(", masked))
    if not sites:
        return []
    return [dict(kind="builtin", callee="abs", n=len(sites), edits=[(m.start(), m.start() + len("__builtin_abs"), "abs") for m in sites])]


def work_file_D(tu, label, calib_id, log, pool=None, callees=None, done=frozenset()):
    path = REPO / tu
    st = path.stat()
    raw = path.read_text(errors="surrogateescape")
    is_hdr = tu.endswith(".h")
    short = hashlib.sha1(tu.encode()).hexdigest()[:6]
    rows, out = [], dict(tu=tu, rows=[], written=False, final="", compiles=0, seconds=0.0, canon=0, promoted=0, kept=0, kr=0, units=0, alias=0, builtin=0)
    out["rows"] = rows
    if not recs_for(tu) and JUDGE_STUB is None:
        out["final"] = "NO-RECIPE"
        return out
    skipped = {}
    units = d_units(tu, raw, callees, skipped=skipped if callees else None)
    masked = dl.same_len_mask(raw)
    for callee, why in sorted(skipped.items()):
        h_ = hashlib.sha1("|".join(f"{ln}:{r}:{p}" for (_, _, ln, _, r, p) in decl_sites(masked, callee)).encode()).hexdigest()[:12]
        if ("D", tu, "decl:" + callee, h_) in done:
            continue
        rows.append(dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=tu, unit="decl:" + callee, callee=callee,
                         header=is_hdr, nhash_before=h_, nhash_after=h_, verdict="DECL-NONE", cause=why, sites=[]))
    extra = e_units(tu, raw, masked) + b_units(tu, raw, masked)

    def unit_hash(u):
        if u.get("kind") in ("alias", "builtin"):
            return hashlib.sha1("|".join(f"{a}:{b}:{r}" for (a, b, r) in u["edits"]).encode()).hexdigest()[:12]
        return hashlib.sha1("|".join(f"{ln}:{r}:{p}" for (_, _, ln, _, r, p) in u["decls"]).encode()).hexdigest()[:12]

    def unit_key(u):
        return {"alias": "alias:", "builtin": "builtin:"}.get(u.get("kind"), "decl:") + u["callee"]
    live = []
    for u in units:
        if ("D", tu, "decl:" + u["callee"], unit_hash(u)) in done:
            continue
        if u.get("ambiguous"):
            rows.append(dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=tu, unit="decl:" + u["callee"], callee=u["callee"],
                             header=is_hdr, nhash_before=unit_hash(u), nhash_after=unit_hash(u), verdict="DECL-KEPT", cause="ambiguous: definitions disagree " + str(u["ambiguous"])[:160],
                             decls=len(u["decls"]), sites=[]))
            out["kept"] += 1
            continue
        live.append(u)
    extra_live = [u for u in extra if ("D", tu, unit_key(u), unit_hash(u)) not in done and u["edits"]]
    out["units"] = len(live) + len(extra_live)
    out["settled"] = len(skipped)
    if not live and not extra_live:
        out["final"] = "UNCHANGED"
        return out

    def compose(acc_units):
        edits = []
        for (u, params, marks) in acc_units:
            if u.get("kind") in ("alias", "builtin"):
                edits += u["edits"]
                continue
            edits += d_edits(u, params) if params is not None else []
            edits += marks
        return {tu: compose_text(raw, edits)}
    # rung A: every unit's ANSI at once (the alias and builtin units ride along as their own edits)
    ansi_units = [(u, u["ansi"], []) for u in live] + [(u, None, []) for u in extra_live]
    accepted, per, compiles, secs, rung = ladder_units(ansi_units, compose, lambda files, tag: judge_files(files, tag, pool=pool), f"{short}D", log=log)
    out["compiles"] += compiles; out["seconds"] += secs
    acc_ids = {id(x[0]) for x in accepted}
    final_units = list(accepted)
    for i, (u, _, _) in enumerate(ansi_units):
        if u.get("kind") in ("alias", "builtin"):
            row = dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=tu, unit=unit_key(u), callee=u["callee"],
                       header=is_hdr, kind=u["kind"], real=u.get("real"), type=u.get("type"), n=(u.get("uses") if u["kind"] == "alias" else u.get("n")),
                       nhash_before=unit_hash(u), nhash_after=None, sites=[])
            if id(u) in acc_ids:
                row["verdict"] = "ALIAS-TYPED" if u["kind"] == "alias" else "BUILTIN-ABS"
                out["alias" if u["kind"] == "alias" else "builtin"] += 1
            else:
                v, err, _ = per[i]
                row["first"] = dict(verdict=v, err=err[:200])
                row["verdict"] = "ALIAS-KEPT" if u["kind"] == "alias" else "BUILTIN-KEPT"
                if u["kind"] == "alias" and (u.get("conflict") or "conflicting types" in err):
                    row["cause"] = f"second typed view of {u['real']}: the TU also declares it as {u.get('conflict') or '?'} vs the alias's {u['type']} — an aggregate in truth (T6)"
                elif u["kind"] == "alias" and v == "DIFFERS":
                    row["cause"] = (f"load-bearing alias of {u['real']}: one symbol under two names is two objects the compiler may not merge "
                                    f"(a18's MEM_IN_STRUCT alias escape) — renaming moves bytes; the shape is an aggregate (T6)")
                else:
                    row["cause"] = f"{v}: {err[:160]}"
                out["kept"] += 1
            rows.append(row)
            continue
        row = dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=tu, unit="decl:" + u["callee"], callee=u["callee"],
                   header=is_hdr, defn_tu=u["defn_tu"], decls=len(u["decls"]), lines=[ln for (_, _, ln, _, _, _) in u["decls"]], ansi=u["ansi"],
                   nhash_before=unit_hash(u), nhash_after=None, sites=[])
        if id(u) in acc_ids:
            row["verdict"] = "DECL-CANON"
            out["canon"] += 1
        else:
            v, err, _ = per[i]
            row["first"] = dict(verdict=v, err=err[:200])
            # the promoted form, on top of what is accepted so far
            if u["promoted"] != u["ansi"] and not v.startswith("COMPILE"):
                r2 = judge_files(compose(final_units + [(u, u["promoted"], [])]), f"{short}Dp{i}", pool=pool)
                out["compiles"] += r2["compiles"]; out["seconds"] += r2["seconds"]
                if r2["verdict"] == "IDENTICAL":
                    final_units.append((u, u["promoted"], []))
                    row["verdict"] = "DECL-PROMOTED"
                    row["cause"] = f"narrow width: the caller does not convert ({u['ansi']} -> {u['promoted']}) — a definition-side question"
                    out["promoted"] += 1
                    rows.append(row)
                    continue
            if "too few arguments" in err or "too many arguments" in err:
                counts, where = unit_call_counts(tu, masked, u)
                marks = kr_marker_edits(raw, u, counts, label)
                infrom = f" (in {', '.join(w.split('src/', 1)[-1] for w in where)})" if where else ""
                empties = [d_ for d_ in u["decls"] if d_[5] == ""]
                if empties and len(empties) == len(u["decls"]):
                    final_units.append((u, None, marks))
                    row["verdict"] = "DECL-KEPT"
                    row["cause"] = f"K&R site: the calls pass {counts} arguments{infrom}, the definition takes {u['ansi']} — kept `()`, marked"
                    row["kr"] = True
                    out["kr"] += 1
                else:
                    # a mix of `()` and truncated ANSI spellings (`(void)` for a one-parameter callee): every declaration becomes `()`
                    # (the K&R form) + the marker — judged; a `(void)` -> `()` is byte-neutral for a 0-argument call, an ANSI -> `()`
                    # may not be (the prototype's conversions vanish), so the oracle decides
                    r3 = judge_files(compose(final_units + [(u, "", marks)]), f"{short}Dk{i}", pool=pool)
                    out["compiles"] += r3["compiles"]; out["seconds"] += r3["seconds"]
                    if r3["verdict"] == "IDENTICAL":
                        final_units.append((u, "", marks))
                        row["verdict"] = "DECL-KEPT"
                        row["cause"] = f"K&R site: the calls pass {counts} arguments{infrom}, the definition takes {u['ansi']} — every declaration `()`, marked"
                        row["kr"] = True
                        out["kr"] += 1
                    else:
                        row["verdict"] = "DECL-KEPT"
                        row["cause"] = f"arity: the calls pass {counts}, the definition takes {u['ansi']}; the all-`()` form {r3['verdict']} — needs a reading"
                out["kept"] += 1
            elif "conflicting types" in err:
                row["verdict"] = "DECL-KEPT"
                row["cause"] = "conflicting types: the TU defines or declares the callee in a form the declaration regex did not reach"
                out["kept"] += 1
            elif "parse error" in err:
                unknown = sorted({sl._norm_type(x.rsplit(" ", 1)[0].replace("*", "").strip()) for x in sl._split_top(u["ansi"], ",") if x.strip() and x.strip() != "void"}
                                 - set(sl.SCALARS) - set(sl.SDK_SIZES) - {"void", "struct", "union"})
                row["verdict"] = "DECL-KEPT"
                row["cause"] = f"type not visible: the prototype names {unknown or ['a type']} the TU cannot see (T5 canonicalises it) — " + err.split("\n")[0][-80:]
                row["needs_types"] = unknown
                out["kept"] += 1
            elif v.startswith("COMPILE"):
                row["verdict"] = "DECL-KEPT"
                row["cause"] = "compile: " + err.split("\n")[0][-100:]
                out["kept"] += 1
            else:
                row["verdict"] = "DECL-KEPT"
                row["cause"] = ("width: " if any(sl._norm_type(x.split()[0]) in NARROW_TYPES for x in sl._split_top(u["ansi"], ",") if x.strip() and x.strip() != "void") else "bytes: ") + (
                    "the canonical prototype moves the caller's bytes" + (f" [{err}]" if err else ""))
                out["kept"] += 1
        rows.append(row)
    files = compose(final_units)
    text = files[tu]
    if text == raw:
        out["final"] = "UNCHANGED"
        for row in rows:
            row["nhash_after"] = row["nhash_before"]
        return out
    fr = judge_files({tu: text}, f"{short}DF", pool=pool)
    out["compiles"] += fr["compiles"]; out["seconds"] += fr["seconds"]
    if fr["verdict"] != "IDENTICAL":
        dl.restore_file(path, raw, st)
        out["final"] = f"COMBINATION-FAILED ({fr['verdict']})"
        log(f"  {tu}: COMBINATION-FAILED ({fr['verdict']} {fr['err'][:120]}) — the TU's declaration units REFUSED, the file restored")
        for row in rows:
            row["verdict"] = "COMBINATION-FAILED"
        out["canon"] = out["promoted"] = out["kr"] = 0
        return out
    out["final"] = "IDENTICAL"
    if JUDGE_STUB is None:
        path.write_text(text, errors="surrogateescape")
    out["written"] = True
    out["final_text"] = text
    masked2 = dl.same_len_mask(text)
    extra2 = {unit_key(u): unit_hash(u) for u in e_units(tu, text, masked2) + b_units(tu, text, masked2)}
    for row in rows:
        if row.get("kind") in ("alias", "builtin"):
            row["nhash_after"] = extra2.get(row["unit"], "gone")
            continue
        decls2 = decl_sites(masked2, row["callee"])
        row["nhash_after"] = hashlib.sha1("|".join(f"{ln}:{r}:{p}" for (_, _, ln, _, r, p) in decls2).encode()).hexdigest()[:12]
    return out


def _ordered_syms(text, rx=re.compile(r"\bD_[0-9A-F]{8}\w*")):
    out = []
    for m in rx.finditer(text):
        if m.group(0) not in out:
            out.append(m.group(0))
    return out


def _sig_key(r_, p_):
    """(ret, parameter TYPES) — names dropped, so a K&R head's promoted list and the ANSI signature compare (P3.39 T6)."""
    ts = [(lambda m_: m_.group(1) + " " + m_.group(2) if m_ else x)(re.search(r"[\s*]", x.strip()) and PARAM_DECL.match(x))
          for x in sl._split_top(p_, ",")]
    return sl._norm_type(r_), tuple(sl._norm_type(t) for t in ts) if p_.strip() not in ("", "void") else ("void",)


def signature_change(callee, signature, label, calib_id, log, pool=None, body_file=None, all_defs=False, only_tu=None, with_files=None,
                     map_data=False):
    """A DEFINITION-side change (`--callee F --signature "ret F(params)"`, or `--callee F --body FILE` — the pack's lever-free function text
    replaces the whole definition and the new signature is read from ITS head): the definition in its TU + every declaration of F in every
    TU of F's scope, ONE judged unit — every recipe IDENTICAL or nothing is written. Returns (rows, verdict, files_written)."""
    body_text = None
    if body_file:
        body_text = pathlib.Path(body_file).read_text(errors="surrogateescape")
        bm = dl.same_len_mask(body_text)
        heads = [m for m in re.finditer(r"(?m)^([A-Za-z_][\w \t*]*?)\b" + re.escape(callee) + r"\s*\(([^{;]*)\)\s*\{", bm)]
        if len(heads) != 1:
            sys.exit(f"restruct: --body {body_file} must define {callee} exactly once (found {len(heads)})")
        signature = f"{heads[0].group(1).strip()} {callee}({heads[0].group(2)})"
    m = re.match(r"^\s*(.+?)\s*\b" + re.escape(callee) + r"\s*\((.*)\)\s*;?\s*$", signature, re.S)
    if not m:
        sys.exit(f"restruct: --signature must read `ret {callee}(params)`")
    ret, params = sl._norm_type(m.group(1)), re.sub(r"\s+", " ", m.group(2)).strip() or "void"
    w = walk()
    results = w["results"]
    def_name = {rel: callee for rel, r in results.items() if r and any(f["fn"] == callee for f in r["fndefs"])}
    if not def_name:
        # an ALIAS-defined callee (`T aF<addr>(…) __asm__("func_<x>")`): the walk names its definition by the asm label (P3.39 T6)
        for rel, r in results.items():
            if not r or not r["fndefs"] or callee not in (txt_ := (REPO / rel).read_text(errors="surrogateescape")):
                continue
            mk_ = dl.same_len_mask(txt_)
            pm = [m_.group(5) for m_ in re.finditer(AF_PROTO_RX_T.format(name=callee), mk_) if m_.group(5)]
            if pm and any(f["fn"] == pm[0] for f in r["fndefs"]) \
                    and re.search(r"(?m)^[A-Za-z_][\w \t*]*?\b" + callee + r"\s*\([^;{]*\)\s*(?:\n[^{;\n]*;)*\s*\{", mk_):
                def_name[rel] = pm[0]
    def_files = list(def_name)
    if only_tu:
        def_files = [d_ for d_ in def_files if d_ == only_tu]
    if body_text is not None and all_defs:
        # a definition carried by a shared HEADER is a variant body (`__<hash>.h`: different bytes for its binaries) or a shared exemplar
        # — not "the same body for every same-address copy": left as is, its includers keep their declarations (t4_sig12b: the pack body
        # written into func_80157D20__99380536.h, its 3 binaries' declarations untouched -> `conflicting types`)
        hdr = [d_ for d_ in def_files if d_.endswith(".h")]
        for h_ in hdr:
            log(f"signature {callee}: {h_} defines {callee} as a shared/variant header — left as is with its includers' declarations")
        def_files = [d_ for d_ in def_files if not d_.endswith(".h")]
    if not def_files or (len(def_files) != 1 and not all_defs):
        sys.exit(f"restruct: {callee} has {len(def_files)} definitions ({def_files[:4]}) — a signature change needs exactly one, or --all-defs "
                 f"(the same body for every same-address copy) or --tu <TU> (R43)")
    def_tu = def_files[0]
    files = {}
    for dtu in def_files:
        if body_text is None and any(f[0] == def_name[dtu] and _sig_key(f[2], (f[4] and kr_ansi_params(dtu, {"fn": callee})) or f[3]) == _sig_key(ret, params) for f in _defs_of_file(dtu)):
            # a CALLER-ONLY declaration unit (P3.39 T6): the definition already reads the signature — not rewritten, not judged; it
            # still scopes the declarations below (its binaries)
            log(f"signature {callee}: {dtu} already defines `{ret} {callee}({params})` — definition left as is")
            continue
        dtext = (REPO / dtu).read_text(errors="surrogateescape")
        dmask = dl.same_len_mask(dtext)
        fd = next(f for f in results[dtu]["fndefs"] if f["fn"] == def_name[dtu])
        ls = dl.line_starts(dmask)
        head_start = ls[fd["line"] - 1]
        if body_text is not None:
            # the WHOLE definition (its head line through its closing brace line) replaced by the pack's text
            span_end = ls[fd["fn_end"]] if fd.get("fn_end") and fd["fn_end"] < len(ls) else len(dtext)
            btext = body_text
            if map_data:
                # `--map-data`: the same code over PER-OVERLAY data — the pack body's `D_` symbols renamed to this copy's own, matched by
                # order of first appearance in the copy's current definition (t4_sig12: `D_80192768` in ov_SC04_011 is `D_801806BC` in
                # ov_MAIN_012, 133 copies); a count mismatch REFUSES the unit (the copy is not the same code over renamed data, R43)
                cur = dl.same_len_mask(dtext)[head_start:span_end]
                ps, cs = _ordered_syms(dl.same_len_mask(body_text)), _ordered_syms(cur)
                if len(ps) != len(cs):
                    log(f"signature {callee}: --map-data REFUSED at {dtu} — the pack body names {len(ps)} D_ symbols {ps[:4]}, this copy's "
                        f"definition {len(cs)} {cs[:4]}")
                    return [], "REFUSED", []
                for a_, b_ in zip(ps, cs):
                    if a_ != b_:
                        btext = re.sub(r"\b" + re.escape(a_) + r"\b", b_, btext)
            edits = [(head_start, span_end, btext if btext.endswith("\n") else btext + "\n")]
        else:
            brace = dmask.find("{", head_start)
            hm = re.search(r"([A-Za-z_][\w \t*]*?)\b" + re.escape(callee) + r"\s*\(([^{;]*)\)\s*(?=\{)", dmask[head_start:brace + 1])
            if not hm:
                sys.exit(f"restruct: cannot read {callee}'s definition head in {dtu}:{fd['line']}")
            edits = [(head_start + hm.start(1), head_start + hm.end(2) + 1, f"{ret} {callee}({params})")]
        files[dtu] = compose_text(dtext, edits)
    # the declarations: every TU/header of the definitions' binaries (a same-address function is one function per binary); for a
    # main/resident definition the whole fleet declares it
    import corpus
    for rel_, path_ in (with_files or {}).items():
        # `--with REL=FILE`: a caller-body edit that is part of the SAME judged unit (the P36 f1 shape: the pin was the missing call
        # ARGUMENT — func_80029D3C's one caller must pass it, the declaration change alone is `too few arguments`); its declarations of
        # the callee are rewritten on top below
        if rel_ in files:
            sys.exit(f"restruct: --with {rel_} is a definition TU of {callee} — give the body with --body instead (R43)")
        files[rel_] = pathlib.Path(path_).read_text(errors="surrogateescape")
        log(f"signature {callee}: {rel_} carries a caller-body edit from {path_} (part of this unit)")
    def_bins = set()
    for dtu in def_files:
        for a_ in w["tu_aliases"].get(dtu, ()):
            def_bins.add(a_)
        if dtu.startswith("src/shared/"):
            # a definition in a shared header: its binaries are its includers' (a header has no tu_aliases; P3.39 T6)
            # (an includer TU built into several binaries — ov_SC01_005 sources build ov_SC01_006 too — gives all its tu_aliases)
            def_bins |= {a_ for t in dl.includers().get(dtu, []) if t.count("/") >= 2
                         for a_ in (w["tu_aliases"].get(t) or (t.split("/")[1],))}
    fleet_wide = any(d_.count("/") == 1 or d_.startswith("src/resident/") or d_.startswith("src/shared/main") for d_ in def_files)
    n_decl = 0
    for rel, r in results.items():
        if not r:
            continue
        if not any(e["name"] == callee for e in r.get("extern_fns", [])) and rel not in files:
            continue
        if not fleet_wide and rel not in files:
            rb = set(w["tu_aliases"].get(rel, ()))
            if rel.startswith("src/shared/"):
                rb = {a_ for t in dl.includers().get(rel, []) if t.count("/") >= 2
                      for a_ in (w["tu_aliases"].get(t) or (t.split("/")[1],))}
            if not rb or not rb <= def_bins:
                if rb & def_bins:
                    log(f"signature {callee}: {rel} reaches binaries outside the definitions' ({sorted(rb - def_bins)[:3]}) — left as is")
                continue
        text = files.get(rel) or (REPO / rel).read_text(errors="surrogateescape")
        ds_ = decl_sites(dl.same_len_mask(text), callee)
        if not ds_:
            continue
        new_ = compose_text(text, [(s, e, f"{'extern ' if ext else ''}{ret} {callee}({params});") for (s, e, ln, ext, r_, p) in ds_])
        if new_ == text and rel not in files:
            continue                    # already spelled so: nothing to judge (P3.39 T6 — a fleet-wide callee's 2,000 canonical TUs)
        files[rel] = new_
        n_decl += len(ds_)
    log(f"signature {callee}: `{ret} {callee}({params})` — {len(def_files)} definition(s) in {def_files[:3]}, {n_decl} declarations in {len(files) - len(def_files)} other files")
    r = judge_files(files, "sig" + hashlib.sha1(callee.encode()).hexdigest()[:6], pool=pool)
    rows = []
    for rel in files:
        rows.append(dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=rel, unit="def:" + callee, callee=callee,
                         signature=f"{ret} {callee}({params})", definition=(rel in def_files), verdict=("DECL-CANON" if r["verdict"] == "IDENTICAL" else "REFUSED"),
                         err=r["err"][:200], nhash_before=None, nhash_after=None, sites=[]))
    if r["verdict"] == "IDENTICAL":
        for rel, text in files.items():
            (REPO / rel).write_text(text, errors="surrogateescape")
        log(f"signature {callee}: IDENTICAL on every recipe ({r['compiles']} objects, {r['seconds']:.1f} s) — {len(files)} files written")
    else:
        log(f"signature {callee}: {r['verdict']} {r['err'][:200]} — nothing written")
    return rows, r["verdict"], (list(files) if r["verdict"] == "IDENTICAL" else [])


# ----------------------------------------------------------------------------------------------------------------------
# rung D — the FUNCTION alias class (`s32 aF8012EFB8(param_1, param_2) __asm__("func_8012EFB8")`): a body defined under an alias C name
# because the fleet's declarations of its real name lied about it. The unit puts the definition back under its real name with its
# byte-true ANSI signature, deletes the alias prototype lines, renames every alias declaration/call, and canonicalises the real
# name's declarations in the TUs that carry the alias — one fleet-wide job, IDENTICAL on every object or nothing written. The real
# name's OTHER callers (declared `extern void func_X(s32)` in TUs that never used the alias) are then ordinary rung-D units: once
# the definition is visible under its real name, argcheck sees them and the cycle draws them.
# ----------------------------------------------------------------------------------------------------------------------
AF_DEF_RX = re.compile(r"(?m)^([A-Za-z_][\w \t*]*?)\b(aF[0-9A-F]{8})\s*\(([^;{)]*)\)\s*((?:\n[^{;\n]*;)*)\s*\{")
AF_PROTO_RX_T = r"(?m)^[ \t]*(extern\s+)?([A-Za-z_][\w \t*]*?)\b{name}\s*\(([^;{{)]*)\)\s*(__asm__\s*\(\s*\"(\w+)\"\s*\))?\s*;[ \t]*\n?"


_alias_real_cache = None


def _alias_of_real():
    global _alias_real_cache
    if _alias_real_cache is None:
        _alias_real_cache = {v["real"]: k for k, v in fn_alias_index().items()}
    return _alias_real_cache


def fn_alias_index():
    """{aF name: dict(file, real, ret, params_ansi, head_start, head_end)} over every .c and shared .h — the alias DEFINITIONS."""
    import argcheck
    out = {}
    for f in sorted(list((REPO / "src").glob("**/*.c")) + list((REPO / "src" / "shared").glob("**/*.h"))):
        rel = f.relative_to(REPO).as_posix()
        text = f.read_text(errors="surrogateescape")
        if "aF" not in text:
            continue
        masked = dl.same_len_mask(text)
        for m in AF_DEF_RX.finditer(masked):
            aname = m.group(2)
            real = None
            pm = re.search(AF_PROTO_RX_T.format(name=aname), masked)
            for pm2 in re.finditer(AF_PROTO_RX_T.format(name=aname), masked):
                if pm2.group(5):
                    real = pm2.group(5)
                    break
            if real is None:
                continue
            ret = sl._norm_type(m.group(1)) or "int"
            inner = m.group(3).strip()
            kr_block = m.group(4) or ""
            if inner and re.fullmatch(r"[A-Za-z_]\w*(\s*,\s*[A-Za-z_]\w*)*", inner) and inner != "void":
                # a K&R head: the names in the parens, the types in the block before `{` (argcheck.kr_params: default-promoted)
                names = [n.strip() for n in inner.split(",")]
                types = argcheck.kr_params(names, kr_block)
                params = ", ".join((f"{t}{n}" if t.endswith("*") else f"{t} {n}") for t, n in zip(types, names))
            else:
                params = re.sub(r"\s+", " ", inner) or "void"
            out.setdefault(aname, dict(file=rel, real=real, ret=ret, params=params, head_start=m.start(), head_end=m.end() - 1, aname=aname))
    return out


def unalias_function(aname, label, calib_id, log, pool=None):
    """The unit for one alias-defined function. Returns (rows, verdict, files_written)."""
    idx = fn_alias_index()
    if aname not in idx:
        # accept the real name too
        cands = [k for k, v in idx.items() if v["real"] == aname]
        if len(cands) != 1:
            sys.exit(f"restruct --unalias: {aname} is not an alias-defined function ({len(cands)} candidates) (R43)")
        aname = cands[0]
    d = idx[aname]
    real, ret, params, def_file = d["real"], d["ret"], d["params"], d["file"]
    canon = f"extern {ret} {real}({params});"
    _, _, inc = recipes()
    scope = set()
    if def_file.endswith(".h"):
        scope.update(inc.get(def_file, []))
    scope.add(def_file)
    def bins(tus):
        return {t.split("/")[1] for t in tus if t.count("/") >= 2}
    members = bins(inc.get(def_file, [])) if def_file.endswith(".h") else bins([def_file])
    real_decl_rx = re.compile(DECL_RX_T.format(name=re.escape(real)))
    hoist, non_member_files = {}, set()
    for f in list((REPO / "src").glob("**/*.c")) + list((REPO / "src" / "shared").glob("**/*.h")):
        rel = f.relative_to(REPO).as_posix()
        if rel in scope:
            continue
        t = f.read_text(errors="surrogateescape")
        if re.search(r"(?<![\w.])" + re.escape(aname) + r"\b", t):
            scope.add(rel)
            continue
        # a SHARED HEADER that declares the real name reaches every one of its includers: it joins the unit only if all of them are
        # members of this body (the same function at that address) — otherwise the canonical prototype would lie to a non-member
        # binary in a way no byte can show, and the unit REFUSES (R43)
        if rel.startswith("src/shared/") and rel.endswith(".h") and real_decl_rx.search(dl.same_len_mask(t)):
            others = bins(inc.get(rel, [])) - members
            if others:
                # the header declares the real name for binaries where that address is ANOTHER function: the declaration is HOISTED out of the
                # header into every includer (the same text, before the #include — byte-neutral by construction); the members' copies then
                # go canonical with the unit, the non-members keep the hoisted text (their own function's prototype is theirs to settle)
                hoist[rel] = sorted(inc.get(rel, []))
                non_member_files.update(t_ for t_ in inc.get(rel, []) if t_.split("/")[1] not in members)
                log(f"unalias {aname}: {rel} declares {real} for non-member binaries {sorted(others)[:4]} — its declaration is hoisted into {len(hoist[rel])} includers")
            scope.add(rel)
            scope.update(inc.get(rel, []))          # its includers: their own declarations of the real name must agree with the header's
    proto_rx_a = re.compile(AF_PROTO_RX_T.format(name=aname))
    proto_rx_r = re.compile(DECL_RX_T.format(name=re.escape(real)))
    data_decl_rx = re.compile(r"(?<![\w.])extern\s+((?:(?:const|volatile|unsigned|signed|struct|union)\s+)*[A-Za-z_]\w*[\s*]*)\b" + re.escape(real) + r"\s*(?:\[\s*\])?\s*;")
    m_ = 0 if params == "void" else len(sl._split_top(params, ","))
    kr_files = set()          # files whose calls pass another count: their declarations stay `()` (K&R) with the marker

    def kr_head():
        """`RET real(a, b, c)\n    u16 a;\n    s32 b; …` — the definition spelled K&R-style with its narrow parameter types in the block."""
        parts = [x.strip() for x in sl._split_top(params, ",")] if params != "void" else []
        names, decls = [], []
        for x in parts:
            mm = PARAM_DECL.match(x)
            if not mm:
                return None
            names.append(mm.group(3))
            decls.append(f"    {sl._norm_type(mm.group(1))} {mm.group(2)}{mm.group(3)};")
        return f"{ret} {real}({', '.join(names)})\n" + "\n".join(decls) + ("\n" if decls else "")
    promoted = promoted_params(params)
    canon_promoted = f"extern {ret} {real}({promoted});"

    promoted_files = set()    # pure callers whose bytes carry NO narrowing: the default-promoted prototype (a K&R-era call against a narrow definition)
    untouched_files = set()   # pure callers that differ under every prototype form: left as they are (their lie is load-bearing — a rung-D KEPT row later)

    def build(kr_files, mode="ansi"):
        """mode 'ansi': the definition's exact head; 'krdef': the definition spelled K&R-style (its own types in the block — the last resort
        when callers pass another argument count and the definition is visible to them)."""
        files, per_file = {}, {}
        # the hoisted declaration text per header (its first declaration line of the real name, verbatim)
        hoisted_text = {}
        for h in hoist:
            ht = (REPO / h).read_text(errors="surrogateescape")
            hm = real_decl_rx.search(dl.same_len_mask(ht))
            hoisted_text[h] = ht[hm.start():hm.end()] if hm else None
        for rel in sorted(scope):
            if rel in untouched_files:
                continue
            text = (REPO / rel).read_text(errors="surrogateescape")
            masked = dl.same_len_mask(text)
            edits, n_decl_a, n_decl_r, n_calls = [], 0, 0, 0
            spans = []
            kr = rel in kr_files
            if kr:
                counts = call_arg_counts(masked, real, []) + call_arg_counts(masked, aname, [])
                decl_text = f"extern {ret} {real}();  {KR_MARK} {'/'.join(str(c) for c in sorted(set(counts))) or '?'} of {m_} args (P37 unalias {label})"
            elif rel in promoted_files:
                decl_text = canon_promoted
            else:
                decl_text = canon
            if rel in hoist:
                # the header loses its declaration line(s) of the real name (hoisted into the includers below)
                for m in real_decl_rx.finditer(masked):
                    le = masked.find("\n", m.end())
                    edits.append((m.start(), (le + 1) if le >= 0 and masked[m.end():le].strip() == "" else m.end(), ""))
                    spans.append((m.start(), m.end()))
            for h, incs in hoist.items():
                if rel in incs and hoisted_text.get(h) and not real_decl_rx.search(masked):
                    im = re.search(r"(?m)^[ \t]*#include\s*\"[^\"]*" + re.escape(pathlib.Path(h).name) + r"\"", masked)
                    if im:
                        edits.append((im.start(), im.start(), hoisted_text[h] + "\n"))
            if rel in non_member_files:
                # a non-member includer: the hoisted text only — its own declarations of the real name are not this unit's to change
                if edits:
                    files[rel] = compose_text(text, sorted(edits))
                    per_file[rel] = dict(alias_decls=0, real_decls=0, renames=0, kr=False, hoisted=True)
                continue
            if rel == def_file:
                # the definition head: `RET aF(params) [K&R block] {` -> `RET real(params) {` (or the K&R-style head under 'krdef')
                m = None
                for mm in AF_DEF_RX.finditer(masked):
                    if mm.group(2) == aname:
                        m = mm
                        break
                head_text = f"{ret} {real}({params})\n" if mode == "ansi" else (kr_head() or f"{ret} {real}({params})\n")
                edits.append((m.start(), m.end() - 1, head_text))
                spans.append((m.start(), m.end()))
            for m in proto_rx_a.finditer(masked):
                if any(a <= m.start() < b for (a, b) in spans):
                    continue
                edits.append((m.start(), m.end(), ""))          # the alias prototype (with or without its __asm__ label) goes
                spans.append((m.start(), m.end()))
                n_decl_a += 1
            for m in proto_rx_r.finditer(masked):
                if any(a <= m.start() < b for (a, b) in spans):
                    continue
                edits.append((m.start(), m.end(), decl_text))
                spans.append((m.start(), m.end()))
                n_decl_r += 1
            # a DATA declaration of the real name — `extern s32 func_X;` written by a drafter whose caller takes the function's address as
            # a plain pointer (`f(&func_X)`) — becomes the prototype too: under the real name it is "redeclared as different kind of
            # symbol" (t4_ua10: 11 of the 19 compile refusals; the `&func_X` use is a function designator's address, the same relocation)
            for m in data_decl_rx.finditer(masked):
                if any(a <= m.start() < b for (a, b) in spans):
                    continue
                edits.append((m.start(), m.end(), decl_text))
                spans.append((m.start(), m.end()))
                n_decl_r += 1
            if n_decl_a and not n_decl_r and rel != def_file:
                # a TU that only knew the alias: one declaration under the real name where the first alias prototype stood
                first = min(e for e in edits if e[2] == "")
                edits.remove(first)
                edits.append((first[0], first[1], decl_text + "\n"))
            for m in re.finditer(r"(?<![\w.])" + re.escape(aname) + r"\b", masked):
                if any(a <= m.start() < b for (a, b) in spans):
                    continue
                edits.append((m.start(), m.end(), real))
                n_calls += 1
            if not edits:
                continue
            files[rel] = compose_text(text, sorted(edits))
            per_file[rel] = dict(alias_decls=n_decl_a, real_decls=n_decl_r, renames=n_calls, kr=kr, promoted=(rel in promoted_files))
        return files, per_file
    mode = "ansi"
    try:
        files, per_file = build(kr_files, mode)
    except Refuse as ex:
        return [dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=def_file, unit="unalias:" + real, callee=real,
                     verdict="UNALIAS-REFUSED", err=f"overlapping edits: {ex}", sites=[])], "REFUSED", []
    log(f"unalias {aname} -> {real}: `{ret} {real}({params})` defined in {def_file}; {len(files)} files ({sum(v['alias_decls'] for v in per_file.values())} alias "
        f"prototypes, {sum(v['real_decls'] for v in per_file.values())} real-name declarations, {sum(v['renames'] for v in per_file.values())} renames)")
    r = judge_files(files, "ua" + hashlib.sha1(aname.encode()).hexdigest()[:6], pool=pool)
    # THE FALLBACKS (per file, bounded; the definition keeps its exact ANSI head unless the last resort):
    #   DIFFERS at a PURE caller F (no definition in its includes): F's callers carry no narrowing -> the promoted prototype; still DIFFERS -> `()`.
    #   DIFFERS at a MEMBER TU (the definition visible): its callers' bytes disagree with the definition's head in one TU — the original was
    #     separate translation units (a jr merge): KEPT, cause named.
    #   `too few/many arguments` at F: F (and the in-scope headers it includes) go `()` + the marker; a second such file -> every declaration
    #     of the unit goes `()`; still an arity error (the definition's head is what the TU sees) -> the definition spelled K&R-style (krdef).
    #   `conflicting types` / `previous declaration` at F outside the unit: F joins the unit (canonical).
    _, by_src_all, _ = recipes()
    obj_to_src = {r_["obj"]: r_["src"] for rs_ in by_src_all.values() for r_ in rs_}
    tried = collections.Counter()
    cause = None
    for _ in range(20):
        v, err = r["verdict"], r["err"]
        bad, kind = None, None
        if v == "COMPILE-ERROR":
            fm = (re.search(r"(src/[^\s:]+):\d+: too (?:few|many) arguments to function `" + re.escape(real) + "'", err)
                  or re.search(r"(src/[^\s:]+):\d+: conflicting types for `" + re.escape(real) + "'", err)
                  or re.search(r"(src/[^\s:]+):\d+: previous declaration of `" + re.escape(real) + "'", err))
            if fm:
                bad = os.path.normpath(fm.group(1))
                kind = "arity" if "arguments" in fm.group(0) else "conflict"
        elif v == "DIFFERS":
            om = re.search(r"\[(build/\S+\.o)\]", err)
            if om and om.group(1) in obj_to_src:
                bad, kind = obj_to_src[om.group(1)], "differs"
        if bad is None:
            break
        tried[(bad, kind)] += 1
        if tried[(bad, kind)] > 3:
            break
        if bad not in scope:
            scope.add(bad)
        members_of_bad = def_file == bad or def_file in headers_of(bad)
        if kind == "differs":
            if members_of_bad:
                cause = f"the callers in {bad} disagree with the definition's head inside one TU (a jr merge of separate original units) — KEPT"
                log(f"unalias {aname}: {cause}")
                break
            if bad not in promoted_files and bad not in kr_files:
                promoted_files.add(bad)
                log(f"unalias {aname}: {bad} differs under the exact prototype (no narrowing in its bytes) — the promoted prototype for this file; re-judging")
            elif bad not in kr_files:
                kr_files.add(bad)
                log(f"unalias {aname}: {bad} still differs — `()` (K&R, marked) for this file; re-judging")
            elif bad not in untouched_files:
                # a pure caller whose bytes need a prototype none of the three forms spells: its text is left exactly as it is — its own
                # `aF… __asm__("func_X")` prototype (if any) still binds to the same symbol, so the unit lands without it; rung D records
                # the load-bearing lie as DECL-KEPT on its own pass
                untouched_files.add(bad)
                log(f"unalias {aname}: {bad} differs under every prototype form — left untouched (its declaration is load-bearing); re-judging without it")
            else:
                cause = f"{bad} differs under every prototype form — KEPT"
                log(f"unalias {aname}: {cause}")
                break
        elif kind == "arity":
            all_kr = all(f_ in kr_files for f_ in scope if f_ not in hoist and f_ not in non_member_files)
            if all_kr:
                if mode == "ansi" and kr_head():
                    mode = "krdef"
                    log(f"unalias {aname}: {bad} still passes another count with every declaration `()` — the definition itself goes K&R-style (last resort); re-judging")
                else:
                    cause = f"{bad} passes another argument count even against a K&R-style definition — KEPT"
                    log(f"unalias {aname}: {cause}")
                    break
            elif sum(n_ for (f_, k_), n_ in tried.items() if k_ == "arity") >= 2:
                # a second arity ERROR (the same file again counts: t4_ua10/12 — one shared body raised the same error three times and the
                # ladder never escalated, because this test counted distinct files)
                kr_files.update(f_ for f_ in scope if f_ not in hoist and f_ not in non_member_files)
                log(f"unalias {aname}: a second arity caller ({bad}) — every declaration of the unit goes `()` (K&R, marked); re-judging")
            else:
                kr_files.add(bad)                    # the definition TU's own DECLARATIONS may go `()` too (its head is governed by `mode`)
                for h in headers_of(bad):
                    if h in scope and h not in hoist:
                        kr_files.add(h)
                if bad.endswith(".h"):
                    # the short call is in a shared BODY: the declaration it sees is the INCLUDING TU's — those TUs (in the unit) go `()`
                    # (t4_ua10: func_80162CCC/func_8016BF50/func_8016F0E4 — `too few arguments` at shared/ov/*.h, the header holds no
                    # declaration to respell, three tries, KEPT)
                    _, _, inc_ = recipes()
                    for t_ in inc_.get(bad, ()):
                        if t_ in scope and t_ not in non_member_files:
                            kr_files.add(t_)
                log(f"unalias {aname}: {bad} passes another argument count — its declaration (and the in-scope headers it includes) stays `()`, a K&R site, marked; re-judging")
        else:
            log(f"unalias {aname}: {bad} declares {real} another way — joining the unit (canonical); re-judging")
        try:
            files, per_file = build(kr_files, mode)
        except Refuse as ex:
            r = dict(verdict="REFUSED", err=f"overlapping edits: {ex}", compiles=0, seconds=0.0, linked=[])
            break
        r = judge_files(files, "ua" + hashlib.sha1((aname + str(sum(tried.values()))).encode()).hexdigest()[:6], pool=pool)
    rows = [dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="D", calib=calib_id, tu=rel, unit="unalias:" + real, callee=real, alias=aname,
                 signature=f"{ret} {real}({params})", mode=mode, definition=(rel == def_file), **per_file[rel],
                 verdict=("UNALIAS-DONE" if r["verdict"] == "IDENTICAL" else "UNALIAS-KEPT"), cause=cause, err=r["err"][:300], nhash_before=None, nhash_after=None, sites=[])
            for rel in files]
    if r["verdict"] == "IDENTICAL":
        for rel, text in files.items():
            (REPO / rel).write_text(text, errors="surrogateescape")
        log(f"unalias {aname}: IDENTICAL on every recipe ({r['compiles']} objects, {r['seconds']:.1f} s) — {len(files)} files written")
        return rows, "IDENTICAL", list(files)
    log(f"unalias {aname}: {r['verdict']} {r['err'][:300]} — nothing written")
    return rows, r["verdict"], []


# ----------------------------------------------------------------------------------------------------------------------
# rung L: definition folds with member renames
# ----------------------------------------------------------------------------------------------------------------------
def _canon_by_layout():
    """{layout hash: [canonical definition]} + the canonical field-name set per definition."""
    can = canon_types()
    by = collections.defaultdict(list)
    seen = set()
    for name, (d, res, fm) in can.items():
        if id(d) in seen:
            continue
        seen.add(id(d))
        lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in d["attrs"]))
        if lay:
            by[sl.layout_hash(lay)].append(d)
    return by


def l_units(tu, text):
    """The TU's fold units: [dict(defn, kind, canon_name, edits, renames, refused)] for every file-scope definition with a canonical layout twin."""
    can = canon_types()
    if not can:
        return []
    by_l = _canon_by_layout()
    anyres = next(iter(can.values()))[1]
    w = tc.walk_file(text, tu)
    masked = dl.same_len_mask(text)
    ls = dl.line_starts(masked)
    # the TU's scope: canonical names + its own
    scope = dict(anyres.defs)
    for d in w["definitions"]:
        for n in d["names"] + ([d["tag"]] if d["tag"] else []):
            scope.setdefault(n, d)
    res = sl.Resolver(scope)
    # field names of every OTHER definition visible in the TU (the ambiguity check for renames)
    all_field_names = collections.Counter()
    for d in w["definitions"]:
        for f in d["fields"]:
            if f["name"]:
                all_field_names[f["name"]] += 1
    for name, (d, _, _) in can.items():
        pass
    canon_field_names = collections.Counter(f["name"] for (d, _, _) in {id(v[0]): v for v in can.values()}.values() for f in d["fields"] if f["name"])
    units = []
    for d in w["definitions"]:
        if d["kind"] == "enum" or d["scope"] != "file" or not d["fields"] or d["is_canon"]:
            continue
        lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in d["attrs"]))
        if not lay:
            continue
        cs = by_l.get(sl.layout_hash(lay), [])
        if not cs:
            continue
        names = d["names"] + ([d["tag"]] if d["tag"] else [])
        same_name = [c for c in cs if set(c["names"] + ([c["tag"]] if c["tag"] else [])) & set(names)]
        span = (ls[d["line"] - 1], ls[d["end"]] if d["end"] < len(ls) else len(masked))
        unit = dict(defn=names[0] if names else "?", line=d["line"], kind=None, canon=None, edits=[], renames=0, refused=None)
        if same_name:
            if any(c["text_hash"] == d["text_hash"] for c in same_name):
                unit.update(kind="delete-same", canon=same_name[0]["names"][0] if same_name[0]["names"] else same_name[0]["tag"], edits=[(span[0], span[1], "")])
            else:
                unit.update(kind="same-name-different-text", refused="the canonical definition under this name has another text (a VARIANT camp? §64a)")
            units.append(unit)
            continue
        if not d["typedef"] or not d["names"]:
            unit.update(kind="tag-only", refused="a tag-only local definition (struct tag {...}) — the alias form needs a typedef name")
            units.append(unit)
            continue
        c = cs[0]
        cname = c["names"][0] if c["names"] else f"struct {c['tag']}"
        # the offset map local -> canonical (top-level named scalar fields)
        lf = dict(sl.field_offsets(res, d))
        cf = {off: nm for (nm, off) in sl.field_offsets(next(iter(can.values()))[1], c)}
        renames = {}
        for nm, off in lf.items():
            tgt = cf.get(off)
            if tgt is None:
                unit.update(kind="alias+rename", refused=f"no canonical field at {off:#x} for local `{nm}`")
                break
            if tgt != nm:
                renames[nm] = tgt
        if unit["refused"]:
            units.append(unit)
            continue
        edits = [(span[0], span[1], "".join(f"typedef {cname} {n};\n" for n in d["names"]))]
        amb = [nm for nm in renames if all_field_names[nm] > 1 or canon_field_names.get(nm, 0) > 0]
        if amb:
            unit.update(kind="alias+rename", refused=f"ambiguous member name(s) {amb[:4]}: also a field of another type visible in the TU (a textual rename could hit it)")
            units.append(unit)
            continue
        for nm, tgt in renames.items():
            for m in re.finditer(r"(->|\.)\s*" + re.escape(nm) + r"\b", masked):
                if span[0] <= m.start() < span[1]:
                    continue
                edits.append((m.start(), m.end(), m.group(1) + tgt))
        unit.update(kind=("alias+rename" if renames else "alias"), canon=cname, edits=sorted(edits), renames=len(edits) - 1)
        units.append(unit)
    return units


def work_file_L(tu, label, calib_id, log, pool=None, done=frozenset()):
    path = REPO / tu
    st = path.stat()
    raw = path.read_text(errors="surrogateescape")
    short = hashlib.sha1(tu.encode()).hexdigest()[:6]
    rows, out = [], dict(tu=tu, rows=[], written=False, final="", compiles=0, seconds=0.0, folded=0, refused=0, renames=0, units=0)
    out["rows"] = rows
    if not recs_for(tu) and JUDGE_STUB is None:
        out["final"] = "NO-RECIPE"
        return out
    units = l_units(tu, raw)
    out["units"] = len(units)
    live = []
    for u in units:
        key = ("L", tu, "fold:" + u["defn"] + f"@{u['line']}")
        if u["refused"]:
            rows.append(dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="L", calib=calib_id, tu=tu, unit=key[2], defn=u["defn"], kind=u["kind"],
                             verdict="FOLD-REFUSED", cause=u["refused"], nhash_before="-", nhash_after="-", sites=[]))
            out["refused"] += 1
            continue
        live.append(u)
    if not live:
        out["final"] = "UNCHANGED"
        return out

    def compose(acc):
        edits = [e for u in acc for e in u["edits"]]
        return {tu: compose_text(raw, edits)}
    accepted, per, compiles, secs, rung = ladder_units(live, compose, lambda files, tag: judge_files(files, tag, pool=pool), f"{short}L", log=log)
    out["compiles"] += compiles; out["seconds"] += secs
    acc_ids = {id(u) for u in accepted}
    for i, u in enumerate(live):
        row = dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="L", calib=calib_id, tu=tu, unit="fold:" + u["defn"] + f"@{u['line']}", defn=u["defn"],
                   kind=u["kind"], canon=u["canon"], renames=u["renames"], nhash_before="-", nhash_after="-", sites=[])
        if id(u) in acc_ids:
            row["verdict"] = "FOLDED"
            out["folded"] += 1; out["renames"] += u["renames"]
        else:
            v, err, _ = per[i]
            row["verdict"] = "FOLD-REFUSED"
            row["cause"] = f"{v}: {err[:160]}"
            out["refused"] += 1
        rows.append(row)
    if not accepted:
        out["final"] = "UNCHANGED"
        return out
    text = compose(accepted)[tu]
    if rung == "A":
        fr = dict(verdict="IDENTICAL", compiles=0, seconds=0.0, err="", linked=[])
    else:
        fr = judge_files({tu: text}, f"{short}LF", pool=pool)
        out["compiles"] += fr["compiles"]; out["seconds"] += fr["seconds"]
    if fr["verdict"] != "IDENTICAL":
        dl.restore_file(path, raw, st)
        out["final"] = f"COMBINATION-FAILED ({fr['verdict']})"
        for row in rows:
            row["verdict"] = "COMBINATION-FAILED"
        out["folded"] = 0
        return out
    out["final"] = "IDENTICAL"
    if JUDGE_STUB is None:
        path.write_text(text, errors="surrogateescape")
    out["written"] = True
    out["final_text"] = text
    return out

# ----------------------------------------------------------------------------------------------------------------------
# rung L HEAD-FOLD mode (P38 T4): `--only <canonical type> …` folds every SAME-SIZE, OTHER-LAYOUT struct definition (file or block
# scope, .c and — with --headers — src/**/*.h) onto the named canonical type: the definition becomes `typedef <Canon> <Local>;`, `struct
# <Tag>` uses become the typedef name, and member accesses on bases OF THE LOCAL TYPE (typed vars/params/arrays, `((Local *)e)->f`,
# `v[i].f`, chains through self-typed fields) are renamed by offset. A header unit's renames reach its includer TUs (one judged unit).
# Width/sign/pointer mismatches are not refused up front: the judge decides.
# ----------------------------------------------------------------------------------------------------------------------
HEAD_FOLD_EXCLUDE = {"Blk152*": "struct-copy blob, 800_b.c:311", "Fr_*": "stack frame"}    # name glob -> cause (never a candidate)
HF_INCLUDERS_OVERRIDE = None     # the selftest sets {header: [tu]}; None = delever.includers() through recipes()
_HF_STATS = {}                   # plan_L's head-fold counts for describe_plan
HF_DECLARATOR = re.compile(r"^\s*(\**)\s*(?:const\s+|volatile\s+)*([A-Za-z_]\w*)\s*((?:\[[^\]]*\]\s*)*)$")
HF_ACCESS = re.compile(r"(->|\.)\s*([A-Za-z_]\w*)")
HF_DEFINE = re.compile(r"^[ \t]*#[ \t]*define[ \t]+(\w+)(\([^)\n]*\))?((?:[^\n]*\\\n)*[^\n]*)", re.M)


def head_split(only):
    """(heads, rest): the --only items naming a canonical type (head-fold mode) and the others (file/alias filters as today)."""
    if not only:
        return [], []
    can = canon_types()
    return [o for o in only if o in can], [o for o in only if o not in can]


def head_info(heads):
    """{head: dict(size, lhash, file, cf{off: (name, size)})} — the canonical side of a head fold."""
    can = canon_types()
    out = {}
    for h in heads:
        d, res, fm = can[h]
        lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in (d.get("attrs") or "")))
        if not lay:
            continue
        cf = {}
        for nm, off in sl.field_offsets(res, d):
            cf.setdefault(off, (nm, ((fm or {}).get(off) or {}).get("width")))
        out[h] = dict(size=lay[0], lhash=sl.layout_hash(lay), file=d["file"], cf=cf)
    return out


def hf_names(d):
    return d["names"] + ([d["tag"]] if d["tag"] else [])


def hf_cands(rel, defs, hinfo):
    """[(d, head, resolver, excluded_cause | None)] — the definitions of one file sized like a head with another layout."""
    if rel.startswith("include/") or not hinfo or rel in {hi["file"] for hi in hinfo.values()}:      # plan_HF draws src/ only
        return []
    can = canon_types()
    scope = dict(next(iter(can.values()))[1].defs)
    for d in defs:
        for n in hf_names(d):
            scope.setdefault(n, d)
    res = sl.Resolver(scope)
    out = []
    for d in defs:
        if d["kind"] == "enum" or not d["fields"]:
            continue
        lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in (d.get("attrs") or "")))
        if not lay:
            continue
        for h, hi in hinfo.items():
            if lay[0] == hi["size"] and sl.layout_hash(lay) != hi["lhash"]:
                ex = next((c for g, c in HEAD_FOLD_EXCLUDE.items() if any(fnmatch.fnmatchcase(n, g) for n in hf_names(d))), None)
                out.append((d, h, res, ex))
                break
    return out


def hf_keys(cands):
    """The ledger unit key per candidate: `fold:<name>@<function|file>` (#k on a repeat) — stable across line shifts."""
    seen, keys = collections.Counter(), []
    for d, *_ in cands:
        k = "fold:" + (hf_names(d) or ["?"])[0] + "@" + (d["fn"] or "file")
        seen[k] += 1
        keys.append(k if seen[k] == 1 else f"{k}#{seen[k]}")
    return keys


def hf_settled(rows, redraw=()):
    """{(tu, unit)} whose LATEST head-fold row is FOLDED / FOLD-REFUSED, minus the --redraw keys (VERDICT[:cause-substring] or a
    definition name). A unit is NOT settled when its label also holds a file-level row (<file>) for its TU that is TOOL-ERROR /
    COMBINATION-FAILED, before OR after it (T4.c2: t38_4L1 ran twice concurrently, so row order within a label is not causal —
    ov_SC06_029_jr_801898CC's FOLDED row lands after its <file> TOOL-ERROR row, and the file was restored by hand)."""
    keys = [(k.split(":", 1)[0], k.split(":", 1)[1] if ":" in k else None) for k in redraw]
    bad = {(r.get("label"), r["tu"]) for r in rows
           if r.get("rung") == "L" and r.get("unit") == "<file>" and r.get("verdict") in ("TOOL-ERROR", "COMBINATION-FAILED")}
    out = set()
    for (rung, tu, unit), r in ledger_latest(rows).items():
        if rung != "L" or not r.get("head") or r.get("verdict") not in ("FOLDED", "FOLD-REFUSED"):
            continue
        if (r.get("label"), tu) in bad:
            continue
        v, c = r.get("verdict"), r.get("cause") or ""
        if any((v == kv and (ks is None or ks in c)) or r.get("defn") == kv for kv, ks in keys):
            continue
        out.add((tu, unit))
    return out


def _fn_spans(text, rel, masked):
    ls = dl.line_starts(masked)
    out = []
    for r in sc.scan_text(text, rel, shared_defs=None):
        if r["form"] == "def":
            out.append((r["name"], ls[r["line"] - 1], ls[r["end"]] if r["end"] < len(ls) else len(masked)))
    return out


def _match_close(s, i):
    """s[i] in '([' -> the index of its closer (depth over both kinds), -1 if none."""
    depth = 0
    for k in range(i, len(s)):
        if s[k] in "([":
            depth += 1
        elif s[k] in ")]":
            depth -= 1
            if depth == 0:
                return k
    return -1


def _match_open(s, j):
    """s[j] in ')]' -> the index of its opener, -1 if none."""
    depth = 0
    for k in range(j, -1, -1):
        if s[k] in ")]":
            depth += 1
        elif s[k] in "([":
            depth -= 1
            if depth == 0:
                return k
    return -1


def _typed_vars(masked, spans, trx, params):
    """{name: level} of the declarators spelled with the local type in the spans (level = pointer stars + array dims; 0 = a value).
    `params`: also a type right after `(`/`,` (a parameter; its first declarator only) — never at file level (prototypes)."""
    V = {}
    for lo, hi in spans:
        for m in trx.finditer(masked, lo, hi):
            prev = masked[lo:m.start()].rstrip()[-1:]
            as_param = prev in ("(", ",")
            if as_param and not params:
                continue
            depth, k, cur, parts = 0, m.end(), m.end(), []
            while k < hi:
                c = masked[k]
                if c in "([":
                    depth += 1
                elif c in ")]":
                    if depth == 0:
                        break
                    depth -= 1
                elif c in ";{" and depth == 0:
                    break
                elif c == "," and depth == 0:
                    parts.append(masked[cur:k]); cur = k + 1
                    if as_param:
                        break
                k += 1
            parts.append(masked[cur:k])
            for p in (parts[:1] if as_param else parts):
                dm = HF_DECLARATOR.match(p.split("=", 1)[0])
                if dm:
                    V[dm.group(2)] = len(dm.group(1)) + dm.group(3).count("[")
    return V


def _postfix_start(s, i):
    """The start of the postfix expression that ends right before s[i] (the base of a `->`/`.` at i)."""
    k = i
    while True:
        j = k - 1
        while j >= 0 and s[j] in " \t\r\n":
            j -= 1
        if j < 0:
            return k
        c = s[j]
        if c.isalnum() or c == "_":
            st = j
            while st > 0 and (s[st - 1].isalnum() or s[st - 1] == "_"):
                st -= 1
            p = st - 1
            while p >= 0 and s[p] in " \t\r\n":
                p -= 1
            if p >= 0 and s[p] == ".":
                k = p; continue
            if p >= 1 and s[p - 1:p + 1] == "->":
                k = p - 1; continue
            return st
        if c in ")]":
            o = _match_open(s, j)
            if o < 0:
                return k
            if c == "]":
                k = o; continue
            p = o - 1
            while p >= 0 and s[p] in " \t\r\n":
                p -= 1
            if p >= 0 and (s[p].isalnum() or s[p] == "_"):
                k = o; continue                  # a call: its callee continues the expression (judged None below)
            return o
        return k


def _split_binary(t):
    """The operands of t's top-level binary + / - (None when another top-level binary operator is present)."""
    depth, parts, cur, prevc = 0, [], 0, ""
    k = 0
    while k < len(t):
        c = t[k]
        if c in "([":
            depth += 1
        elif c in ")]":
            depth -= 1
        elif depth == 0 and not c.isspace():
            nxt = t[k + 1:k + 2]
            binary = bool(prevc) and (prevc.isalnum() or prevc in "_)]")
            if c == "-" and nxt == ">":
                prevc = ">"; k += 2; continue
            if c in "+-" and nxt == c:
                prevc = ")"; k += 2; continue            # ++ / -- (postfix keeps the operand's level)
            if c in "+-" and binary:
                parts.append(t[cur:k]); cur = k + 1
            elif c in "*/%&|^<>=!?:" and binary:
                return None
        if not c.isspace():
            prevc = c if depth == 0 or c in ")]" else prevc
        k += 1
    parts.append(t[cur:])
    return parts


def _lvl(t, V, crx, lself):
    """The local-type level of expression text t (1 = a pointer to the local type, 0 = a value), None when not the local type."""
    t = t.strip()
    if not t:
        return None
    parts = _split_binary(t)
    if parts is None:
        return None
    if len(parts) > 1:
        ls_ = [_lvl(p, V, crx, lself) for p in parts]
        ptr = [x for x in ls_ if x]
        return ptr[0] if len(ptr) == 1 and ls_[0] else None
    t = re.sub(r"(\+\+|--)\s*$", "", t).strip()
    if t.startswith(("++", "--")):
        return _lvl(t[2:], V, crx, lself)
    if t[0] == "*":
        x = _lvl(t[1:], V, crx, lself)
        return x - 1 if x else None
    if t[0] == "&":
        x = _lvl(t[1:], V, crx, lself)
        return x + 1 if x is not None else None
    cm = crx.match(t)
    if cm and t[cm.end():].strip():
        return len(cm.group(1))
    if t[0] == "(":
        c = _match_close(t, 0)
        if c < 0:
            return None
        rest = t[c + 1:].lstrip()
        if rest and not rest.startswith(("[", ".", "->", "(")):
            return None                                   # a cast to another type
        lvl, rest = _lvl(t[1:c], V, crx, lself), t[c + 1:]
    else:
        m = re.match(r"[A-Za-z_]\w*", t)
        if not m:
            return None
        lvl, rest = V.get(m.group(0)), t[m.end():]
    while True:
        rest = rest.lstrip()
        if not rest or lvl is None:
            return lvl
        if rest[0] == "[":
            c = _match_close(rest, 0)
            if c < 0:
                return None
            lvl, rest = (lvl - 1 if lvl else None), rest[c + 1:]
        elif rest.startswith("->") or rest[0] == ".":
            need = 1 if rest.startswith("->") else 0
            m = re.match(r"(?:->|\.)\s*([A-Za-z_]\w*)", rest)
            if not m:
                return None
            lvl, rest = (lself.get(m.group(1)) if lvl == need else None), rest[m.end():]
        else:
            return None


def _hf_file_edits(masked, lo_hi_fns, glob_spans, lnames, tag, lfields, lself, block):
    """(accesses[(start, end, local field)], tag_edits[(start, end, repl)], refusals[cause]) over one file's view of the local type.
    lo_hi_fns: the function spans judged (a block unit: the one span after its definition); glob_spans: file-level text (the
    globals of the type; empty for a block unit)."""
    alts = [re.escape(n) for n in lnames] + ([r"struct\s+" + re.escape(tag)] if tag else [])
    trx = re.compile(r"(?<![\w])(?:" + "|".join(alts) + r")(?![\w])")
    crx = re.compile(r"^\(\s*(?:(?:const|volatile)\s+)*(?:" + "|".join(alts) + r")\s*(\**)\s*\)")
    G = {} if block else _typed_vars(masked, glob_spans, trx, params=False)
    acc = []
    for lo, hi in lo_hi_fns:
        V = dict(G)
        V.update(_typed_vars(masked, [(lo, hi)], trx, params=not block))
        for m in HF_ACCESS.finditer(masked, lo, hi):
            if m.group(2) not in lfields:
                continue
            base = masked[_postfix_start(masked, m.start()):m.start()]
            if _lvl(base, V, crx, lself) == (1 if m.group(1) == "->" else 0):
                acc.append((m.start(2), m.end(2), m.group(2)))
    # file-scope #define bodies (T4.c3: ov_SC05_010_jr_80181CDC.c's AIM macro reads `obj->x`, `obj` a parameter of the functions that
    # expand it): the base is typed by the file's globals, else by every expanding function's locals — all agree or the unit is refused.
    refusals = []
    for lo, hi in ([] if block else glob_spans):
        for mm in HF_DEFINE.finditer(masked, lo, hi):
            mname, mparams = mm.group(1), set(re.findall(r"\w+", mm.group(2) or ""))
            urx = re.compile(r"(?<![\w])" + re.escape(mname) + r"(?![\w])")
            users = [(a, b) for a, b in lo_hi_fns if urx.search(masked, a, b)]
            for m in HF_ACCESS.finditer(masked, mm.start(3), mm.end(3)):
                if m.group(2) not in lfields:
                    continue
                base = masked[_postfix_start(masked, m.start()):m.start()]
                if set(re.findall(r"[A-Za-z_]\w*", base)) & mparams:
                    continue                                  # a macro parameter's base: typed at each expansion (left to the judge)
                need = 1 if m.group(1) == "->" else 0
                if _lvl(base, G, crx, lself) == need:
                    acc.append((m.start(2), m.end(2), m.group(2))); continue
                got = set()
                for a, b in users:
                    V = dict(G)
                    V.update(_typed_vars(masked, [(a, b)], trx, params=True))
                    got.add(_lvl(base, V, crx, lself))
                if got == {need}:
                    acc.append((m.start(2), m.end(2), m.group(2)))
                elif need in got:
                    refusals.append(f"macro `{mname}` access `{base.strip()}{m.group(1)}{m.group(2)}` is the local type in only some of its expansions")
    tag_edits = []
    if tag:
        for lo, hi in list(lo_hi_fns) + list(glob_spans):
            for m in re.compile(r"\bstruct\s+" + re.escape(tag) + r"\b(\s*;)?").finditer(masked, lo, hi):
                tag_edits.append((m.start(), m.end(), "" if m.group(1) else lnames[0]))
    return acc, tag_edits, refusals


def _complement(spans, n):
    out, last = [], 0
    for a, b in sorted(spans):
        if a > last:
            out.append((last, a))
        last = max(last, b)
    if last < n:
        out.append((last, n))
    return out


def hf_unit(rel, text, masked, d, head, hi, res, fns, defs):
    """One head-fold unit: dict(defn, line, fn, kind, canon, edits{rel: [(s, e, repl)]}, renames, refused)."""
    defn = (hf_names(d) or ["?"])[0]
    u = dict(defn=defn, line=d["line"], fn=d["fn"], kind="head-fold", canon=head, edits={}, renames=0, refused=None)

    def refuse(cause):
        u["refused"] = cause
        return u
    ls = dl.line_starts(masked)
    lim = ls[d["line"]] if d["line"] < len(ls) else len(masked)
    m = sl.DEF_START.search(masked, ls[d["line"] - 1])
    if not m or m.start() >= lim:
        return refuse("the definition was not found at its line")
    close = sl._match_brace(masked, m.end() - 1)
    semi = masked.find(";", close) if close != -1 else -1
    if semi == -1:
        return refuse("the definition's end was not found")
    tag = d["tag"]
    if d["typedef"]:
        if d["ptr_names"]:
            return refuse(f"the typedef also declares pointer/array names {d['ptr_names'][:3]}")
        if not d["names"]:
            return refuse("a typedef without a plain name")
        lnames = d["names"]
    else:
        if ATTR_STRIP.sub("", masked[close + 1:semi]).strip():
            return refuse("the definition declares variables (struct T {…} v;)")
        if not tag:
            return refuse("an anonymous definition without a name")
        lnames = [tag]
    lf = dict(sl.field_offsets(res, d))
    lsize, lself = {}, {}
    self_types = {re.sub(r"\s+", " ", n) for n in lnames} | ({f"struct {tag}"} if tag else set())
    for f in d["fields"]:
        if not f["name"] or f["name"] not in lf:
            continue
        if f.get("nested"):
            nd = f["nested"]
            r = res.layout_of_fields(nd["fields"], nd["kind"], packed=("packed" in (nd.get("attrs") or ""))) if nd["kind"] != "enum" else (4, 4, [])
        else:
            r = res.layout(f["type"], f["stars"], f["dims"])
            if re.sub(r"\s+", " ", f["type"] or "").strip() in self_types:
                lself[f["name"]] = f["stars"] + len(f["dims"] or [])
        lsize[f["name"]] = (r[0] if r else None, bool(f.get("dims")))
    span = (m.start(), semi + 1)
    edits = collections.defaultdict(list)
    edits[rel].append((span[0], span[1], " ".join(f"typedef {head} {n};" for n in lnames)))
    views = []                      # (rel, masked, fn spans, global spans, block?)
    if d["scope"] == "block":
        fs = next(((lo, hi_) for (nm, lo, hi_) in fns if nm == d["fn"] and lo <= span[0] < hi_), None)
        if fs is None:
            return refuse(f"the enclosing function {d['fn']} was not found")
        views.append((rel, masked, [(span[1], fs[1])], [], True))
    else:
        def file_view_hf(r_, msk, fns_, defs_, skip):
            shadow = {x["fn"] for x in defs_ if x["scope"] == "block" and set(hf_names(x)) & set(lnames)}
            fsp = [(lo, hi_) for (nm, lo, hi_) in fns_ if nm not in shadow]
            glob = _complement([(lo, hi_) for (_, lo, hi_) in fns_] + ([skip] if skip else []), len(msk))
            return (r_, msk, fsp, glob, False)
        views.append(file_view_hf(rel, masked, fns, defs, span))
        if rel.endswith(".h"):
            imap = HF_INCLUDERS_OVERRIDE if HF_INCLUDERS_OVERRIDE is not None else recipes()[2]
            incs = sorted(i for i in set(imap.get(rel) or ()) if i != rel and i.endswith(".c") and (REPO / i).exists())
            incset = set(incs)
            # T4.c3: the OTHER src/ headers those includers see (the per-function headers of engine_types.h's types) spell the
            # local type's members too — every one in the includers' include closure (delever.includers' -I order) joins the unit.
            sibs = {h for h, tus in imap.items() if h != rel and not h.startswith("include/") and h.endswith(".h") and not incset.isdisjoint(tus)}
            pat = re.compile(r"\b(?:" + "|".join(re.escape(n) for n in lnames + ([tag] if tag else [])) + r")\b")
            for inc in incs + sorted(h for h in sibs if (REPO / h).exists()):
                itext = (REPO / inc).read_text(errors="surrogateescape")
                if not pat.search(itext):
                    continue
                imask = dl.same_len_mask(itext)
                views.append(file_view_hf(inc, imask, _fn_spans(itext, inc, imask), tc.walk_file(itext, inc)["definitions"], None))
    renames = {}
    for r_, msk, fsp, glob, block in views:
        acc, tag_edits, why = _hf_file_edits(msk, fsp, glob, lnames, tag, set(lf), lself, block)
        if why:
            return refuse(f"{r_}: {why[0]}")
        for (s, e, nm) in acc:
            if nm not in renames:
                off = lf[nm]
                c = hi["cf"].get(off)
                if c is None or re.match(r"^pad[0-9A-F]+$", c[0]):
                    return refuse(f"no canonical field at {off:#x} for local `{nm}`" + (f" (only {c[0]})" if c else ""))
                sz, is_arr = lsize.get(nm, (None, False))
                if is_arr and sz and c[1] and sz > c[1]:
                    return refuse(f"indexed local array field `{nm}` [{off:#x}+{sz:#x}] spans several canonical fields (`{c[0]}` is {c[1]:#x})")
                renames[nm] = c[0]
            if renames[nm] != nm:
                edits[r_].append((s, e, renames[nm]))
                u["renames"] += 1
        edits[r_].extend(tag_edits)
    u["edits"] = {k: sorted(v) for k, v in edits.items() if v}
    u["fields"] = {k: v for k, v in renames.items() if k != v}
    return u


ATTR_STRIP = re.compile(r"__attribute__\s*\(\((?:[^()]|\([^()]*\))*\)\)")


def hf_units(tu, text, heads, settled=frozenset()):
    """The TU's head-fold units (the excluded and the settled left out), in source order."""
    hinfo = head_info(heads)
    w = tc.walk_file(text, tu)
    cands = hf_cands(tu, w["definitions"], hinfo)
    if not cands:
        return []
    masked = dl.same_len_mask(text)
    fns = _fn_spans(text, tu, masked)
    units = []
    for (d, h, res, ex), key in zip(cands, hf_keys(cands)):
        if ex or (tu, key) in settled:
            continue
        u = hf_unit(tu, text, masked, d, h, hinfo[h], res, fns, w["definitions"])
        u["key"] = key
        units.append(u)
    return units


def _inflight_add(files):
    """Extra files a header unit writes (its includers) join inflight.json BEFORE the write, so --restore reaches them (R102)."""
    if JUDGE_STUB is not None or not INFLIGHT.exists():
        return

    def add(d):
        for rel, raw in files.items():
            d["files"].setdefault(rel, raw)
    inflight_update(add)


def _selftest_inflight_worker(path, wid, n=25):
    """Selftest: n read-modify-writes + n reads of a scratch inflight.json; returns the number of failed reads (0 = serialised)."""
    path, bad = pathlib.Path(path), 0
    for i in range(n):
        inflight_update(lambda d: d["files"].setdefault(f"w{wid}_{i}", "x" * 256), path)
        d, _why = load_inflight(path)
        bad += d is None
    return bad


def _run_threads(path, p, k=4):
    """Selftest: k threads of _selftest_inflight_worker in one process (ids p*k..p*k+k-1); returns the failed reads."""
    with ThreadPoolExecutor(k) as ex:
        return sum(ex.map(lambda t: _selftest_inflight_worker(path, p * k + t), range(k)))


def tool_error_restore(tu, text, log=None):
    """A worker that crashed (TOOL-ERROR) puts its file back to the batch's original text: its edit, if any, was never judged."""
    p = REPO / tu
    if p.exists() and p.read_text(errors="surrogateescape") != text:
        p.write_text(text, errors="surrogateescape")
        if log:
            log(f"  {tu}: TOOL-ERROR — restored to its original text")
        return True
    return False


def work_file_HF(tu, label, calib_id, log, pool=None, heads=(), settled=frozenset()):
    """Rung L head-fold on one file (a .c or a header whose units reach its includers): the ladder over its units, the winners written."""
    path = REPO / tu
    raw = path.read_text(errors="surrogateescape")
    short = hashlib.sha1(tu.encode()).hexdigest()[:6]
    rows, out = [], dict(tu=tu, rows=[], written=False, final="", compiles=0, seconds=0.0, folded=0, refused=0, renames=0, units=0)
    out["rows"] = rows
    if not recs_for(tu) and JUDGE_STUB is None:
        out["final"] = "NO-RECIPE"
        return out
    units = hf_units(tu, raw, heads, settled)
    out["units"] = len(units)

    def row(u, verdict, **kw):
        return dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="L", calib=calib_id, tu=tu, unit=u["key"], defn=u["defn"], kind=u["kind"],
                    head=u["canon"], canon=u["canon"], fn=u["fn"], renames=u["renames"], fields=u.get("fields", {}), files=sorted(u["edits"]),
                    verdict=verdict, nhash_before="-", nhash_after="-", sites=[], **kw)
    live = []
    for u in units:
        if u["refused"]:
            rows.append(row(u, "FOLD-REFUSED", cause=u["refused"]))
            out["refused"] += 1
        else:
            live.append(u)
    if not live:
        out["final"] = "UNCHANGED"
        return out
    raws = {tu: (raw, path.stat())}
    for u in live:
        for rel in u["edits"]:
            if rel not in raws:
                p = REPO / rel
                raws[rel] = (p.read_text(errors="surrogateescape"), p.stat())

    def compose(acc):
        per = collections.defaultdict(list)
        for u in acc:
            for rel, es in u["edits"].items():
                per[rel].extend(es)
        return {rel: compose_text(raws[rel][0], es) for rel, es in per.items()}
    accepted, per, compiles, secs, rung = ladder_units(live, compose, lambda files, tag: judge_files(files, tag, pool=pool), f"{short}H", log=log)
    out["compiles"] += compiles; out["seconds"] += secs
    acc_ids = {id(u) for u in accepted}
    for i, u in enumerate(live):
        if id(u) in acc_ids:
            rows.append(row(u, "FOLDED"))
            out["folded"] += 1; out["renames"] += u["renames"]
        else:
            v, err, _ = per[i]
            rows.append(row(u, "FOLD-REFUSED", cause=f"{v}: {err[:160]}"))
            out["refused"] += 1
    if not accepted:
        out["final"] = "UNCHANGED"
        return out
    files = compose(accepted)
    if rung == "A":
        fr = dict(verdict="IDENTICAL", compiles=0, seconds=0.0, err="", linked=[])
    else:
        fr = judge_files(files, f"{short}HF", pool=pool)
        out["compiles"] += fr["compiles"]; out["seconds"] += fr["seconds"]
    if fr["verdict"] != "IDENTICAL":
        for rel, (r0, st) in raws.items():
            dl.restore_file(REPO / rel, r0, st)
        out["final"] = f"COMBINATION-FAILED ({fr['verdict']})"
        for r_ in rows:
            r_["verdict"] = "COMBINATION-FAILED"
        out["folded"] = 0
        return out
    out["final"] = "IDENTICAL"
    if JUDGE_STUB is None:
        _inflight_add({rel: raws[rel][0] for rel in files if rel != tu})
        for rel, t in files.items():
            (REPO / rel).write_text(t, errors="surrogateescape")
    out["written"] = True
    out["final_text"] = files.get(tu, raw)
    out["final_texts"] = files
    return out


def _norm_cause(c):
    c = re.sub(r"`[^`]*`", "`…`", c)
    c = re.sub(r"\[[^\]]*\]", "[…]", c)
    c = re.sub(r"0x[0-9a-fA-F]+", "0x…", c)
    return re.sub(r"\b(src/\S+?):\d+", r"\1:…", c)[:120]


def fold_report(heads):
    """--status --rung L --only <heads>: the head-fold rows (latest per unit) bucketed verdict -> cause -> units."""
    lat = [r for (rung, _, _), r in ledger_latest(load_ledger()).items() if rung == "L" and r.get("head") in heads]
    by = collections.defaultdict(lambda: collections.defaultdict(list))
    for r in lat:
        cause = r.get("cause") or (f"onto {r.get('canon')}" if r.get("verdict") == "FOLDED" else "-")
        by[r.get("verdict")][_norm_cause(cause)].append(f"{r['tu']}:{r['unit']}")
    print(f"restruct --status L head-fold {' '.join(heads)}: {len(lat)} units (latest row each)")
    for v, causes in sorted(by.items(), key=lambda x: -sum(len(u) for u in x[1].values())):
        print(f"   {v:20s} {sum(len(u) for u in causes.values())}")
        for c, us in sorted(causes.items(), key=lambda x: -len(x[1])):
            print(f"      {len(us):5d}  {c}  e.g. {', '.join(us[:2])}")
    return 0

# ----------------------------------------------------------------------------------------------------------------------
# planning and --apply (the batch: files in leverage order, workers own whole TUs, headers serial and last)
# ----------------------------------------------------------------------------------------------------------------------
BBT_PIN = os.environ.get("RESTRUCT_BBT") or None      # P3.39 T3.c2: a pinned body_base_type.json (--bbt / RESTRUCT_BBT)


def merge_bbt(cur, pin, can):
    """cur with each base whose type is NOT canonical replaced by the pinned entry for the same (body, base) when that one is canonical.
    T3.c2: the cycle's per-batch census rewrites body_base_type.json and the map's names drift as sites become members (after t3_S5 the
    ov bases' top type was Unkstruct_800D3888, not in a canonical header: 0 of 103469 ov bases canonical, plan_S drew 0 files)."""
    out, n = {}, 0
    for key, bases in cur.items():
        pb = pin.get(key, {})
        nb = {}
        for bk, ent in bases.items():
            pe = pb.get(bk)
            if ent["type"] not in can and pe and pe["type"] in can:
                nb[bk], n = pe, n + 1
            else:
                nb[bk] = ent
        out[key] = nb
    return out, n


def bbt():
    p = CENSUS / "body_base_type.json"
    if not p.exists():
        sys.exit("restruct: no body_base_type.json — run `tools/type_census.py -j 16 --sites` first (R43)")
    cur = json.loads(p.read_text())
    if BBT_PIN:
        pp = pathlib.Path(BBT_PIN)
        pp = pp if pp.is_absolute() else REPO / pp
        if not pp.exists():
            sys.exit(f"restruct: the pinned body_base_type ({BBT_PIN}) does not exist")
        cur, _ = merge_bbt(cur, json.loads(pp.read_text()), canon_types())
    return cur


def matches_only(only, tu, unit, extra=()):
    if not only:
        return True
    hay = [tu, unit] + list(extra)
    if tu and unit and f"{tu}:{unit}" in only:                     # T3.c4: `TU:FN` names one body (overlay fn names repeat)
        return True
    if "main" in only and tu and (tu.count("/") == 1 or tu.startswith("src/resident/")):   # P39 T4: main-executable TUs (as :1718/:4137)
        return True
    globs =[o for o in only if any(c in o for c in "*?[")]       # P39 T3: `ov_*` against the alias / src dir (and the path)
    if globs and tu and any(fnmatch.fnmatchcase(tu, o) or (tu.startswith("src/") and fnmatch.fnmatchcase(tu.split("/")[1], o)) for o in globs):
        return True
    return any(o == h or h.endswith("/" + o) or h.startswith("src/" + o + "/") or ("/" + o + "/") in h
               or (o in h and o.startswith(("Unkstruct_", "func_", "D_"))) for o in only if o != "main" for h in hay if h)   # exact: not src/shared/main/


def s_finished(tu, fns, latest, done=frozenset()):
    """True when every body in fns has a latest ("S", tu, fn) ledger row whose nhash_after is the body's CURRENT nhash (T3.c2: t3_S1–S5
    re-drew finished files — drawable stayed ~2088 after 250 files done).
    T3.c3: a latest row none of whose bases was judged (no CANONICAL/LOCAL status: every base NO-TYPE-IN-MAP in t3_S6..S14, S16..S18)
    is not a judgement — the body stays drawable.
    T3.c5: a body apply skips as done (("S", tu, fn, current nhash) in `done`, ledger_index) is finished too — t3_S55..S61 drew 6 files
    whose only unfinished bodies had an unjudged latest KEPT row (t3c4_rejudge) over an earlier judged row at the same hash: rows 0."""
    path = REPO / tu
    if not path.exists():
        return False
    masked, defs, _, _, _ = file_view(tu, path.read_text(errors="surrogateescape"))
    cur = {d["name"]: body_nhash(masked, d) for d in defs if d["name"] in fns}

    def fin(fn):
        r = latest.get(("S", tu, fn)) or {}
        return ("S", tu, fn, cur.get(fn)) in done or (r.get("nhash_after") and s_judged(r) and cur.get(fn) == r["nhash_after"])
    return all(fin(fn) for fn in fns)


def plan_S(headers, batch, only, done, latest=None, data=None):
    """[(tu, {fn: bases})] — files with typed bases whose type is a CANONICAL definition (visible), ordered by the map's leverage.
    latest = ledger_latest(rows): files whose every body is finished at its current text (s_finished) are not drawn; data: a bbt() dict (selftest)."""
    smap = struct_map()
    can = canon_types()
    files = collections.defaultdict(dict)
    weight = collections.Counter()
    skipped = collections.Counter()
    for key, bases in (bbt() if data is None else data).items():
        tu, fn = key.split("|", 1)
        if tu.endswith(".h") != headers:
            continue
        if only and not matches_only(only, tu, fn, [b["type"] for b in bases.values()]):
            continue
        usable = {}
        for bk, ent in bases.items():
            if ent["type"] not in can:
                skipped["type-not-canonical"] += 1
                continue
            if not type_visible(tu, ent["type"]):
                skipped["type-not-visible"] += 1
                continue
            usable[bk] = ent
            weight[tu] += smap.get(ent["type"], {}).get("sites", 0)
        if usable:
            files[tu][fn] = usable
    if latest:
        for tu in [t for t in files if s_finished(t, set(files[t]), latest, done)]:
            del files[tu]
            skipped["file-finished"] += 1
    ordered = sorted(files, key=lambda t: (-weight[t], t))
    return [(tu, files[tu]) for tu in ordered[:batch]], len(ordered), skipped


# T3.c7: the residue — plan_S skips every body none of whose bases is a visible canonical type (34131 ov bodies had no rung-S row).
# `--rung S --residue` ledgers one no-edit row per such body (no source touched, no compile); `--check-residue` counts what is left.
RESIDUE_FILE_UNIT = "<file-scope>"       # the unit of census sites outside any function (site fn null)
RESIDUE_DEFAULT_ONLY = ["ov_*"]


def residue_cause(s, can=None):
    """Why an undrawn P/X census site stays raw: FILE-SCOPE (fn null), NO-TYPE-IN-MAP (untyped), TYPE-NOT-CANONICAL, TYPE-NOT-VISIBLE,
    else site_class's cause for a typed base (MISALIGNED / NO-EDIT: a visible canonical type plan_S's bbt did not pair with the base)."""
    can = canon_types() if can is None else can
    t = s.get("type")
    if not s.get("fn"):
        return "FILE-SCOPE"
    if not t:
        return "NO-TYPE-IN-MAP"
    if t not in can:
        return "TYPE-NOT-CANONICAL"
    if not type_visible(s["tu"], t):
        return "TYPE-NOT-VISIBLE"
    return site_class(s, None, typed=True)


RESIDUE_FORMS = ("P", "X")               # T10.c1: --forms default; I and M accepted (ledger-only rows, same entry shape)


def residue_cause_im(s, can=None):
    """T10.c1: why a raw I/M census site stays raw: ABS-ADDR (base bclass abs: a fixed address literal), GADDR (bclass gaddr: `&D_x`,
    a symbol's address reinterpreted — T5.c2: not an absolute address), GLOBAL (bclass global: a global's own storage reinterpreted),
    else residue_cause (FILE-SCOPE / NO-TYPE-IN-MAP / TYPE-NOT-* / site_class)."""
    if s.get("bclass") == "abs":
        return "ABS-ADDR"
    if s.get("bclass") == "gaddr":
        return "GADDR"
    if s.get("bclass") == "global":
        return "GLOBAL"
    return residue_cause(s, can)


def _residue_key(form, base, off):
    return (form, s_base_norm(base or ""), off)


def residue_match(latest, sites, forms=RESIDUE_FORMS):
    """T10.c1 (pure): (covered, uncovered) census sites of `forms`. A site is covered only when latest[("S", tu, unit)] (ledger_latest,
    R100; unit = fn or RESIDUE_FILE_UNIT) has a sites[] entry with the same form, s_base_norm'd base `<bclass>:<base>`, off, verdict
    RESIDUAL(<cause>) and a non-empty cause — a multiset: one entry covers one site. Never by line (lines drift); MEMBER / KEPT / REFUSED
    entries cover nothing (a raw site under them is still raw)."""
    pool = {}
    covered, uncovered = [], []
    for s in sites:
        if s.get("form") not in forms:
            continue
        unit = s.get("fn") or RESIDUE_FILE_UNIT
        bk = (s["tu"], unit)
        if bk not in pool:
            pool[bk] = collections.Counter(
                _residue_key(e.get("form"), e.get("base"), e.get("off"))
                for e in (latest.get(("S", s["tu"], unit)) or {}).get("sites") or []
                if str(e.get("verdict") or "").startswith("RESIDUAL(") and e.get("cause"))
        k = _residue_key(s.get("form"), f"{s.get('bclass')}:{s.get('base')}", s.get("off"))
        if pool[bk][k] > 0:
            pool[bk][k] -= 1
            covered.append(s)
        else:
            uncovered.append(s)
    return covered, uncovered


def residue_sites(only, latest, path=None, forms=RESIDUE_FORMS):
    """{(tu, unit): [uncovered census site of `forms`]} over the TUs matching `only` (default ov_*) — per site (residue_match), not per
    body: a body with a latest rung-S row still lists every raw site no RESIDUAL entry of that row covers."""
    only = only or RESIDUE_DEFAULT_ONLY
    pre = tuple(f'{{"form": "{f}"' for f in forms)
    cand = []
    with open(path or CENSUS / "sites.jsonl") as f:
        for l in f:
            if not l.startswith(pre):
                continue
            s = json.loads(l)
            if matches_only(only, s["tu"], s.get("fn") or RESIDUE_FILE_UNIT):
                cand.append(s)
    out = collections.defaultdict(list)
    for s in residue_match(latest, cand, forms)[1]:
        out[(s["tu"], s.get("fn") or RESIDUE_FILE_UNIT)].append(s)
    return out


def residue_rows(groups, label, calib_id, latest=None):
    """One rung-S no-edit row per (tu, unit) of residue_sites, sorted (tu, unit): nhash_before == nhash_after == the body's current nhash
    (the masked file's for RESIDUE_FILE_UNIT; None when the body is gone); every site RESIDUAL(<cause>); verdict the shared cause when it
    is TYPE-NOT-CANONICAL / TYPE-NOT-VISIBLE (S_NO_EDIT_VERDICTS), else RESIDUAL. Bases carry the cause as status: never s_judged.
    I/M sites take residue_cause_im. T10.c1: a body with a latest rung-S row (`latest`) gets a MERGED row instead — a copy of that row
    (verdict, hashes, bases, every MEMBER/KEPT/RESIDUAL entry: macro backing kept) with ts/label/calib renewed, `residue_of` = its label,
    and one RESIDUAL entry appended per uncovered site."""
    can = canon_types()
    by_tu = collections.defaultdict(list)
    for tu, unit in groups:
        by_tu[tu].append(unit)
    rows = []
    for tu in sorted(by_tu):
        path = REPO / tu
        nh, file_nh = {}, None
        if path.exists():
            text = path.read_text(errors="surrogateescape")
            masked = dl.same_len_mask(text)
            for d in sc.scan_text(text, tu, shared_defs=None):
                if d["form"] == "def":
                    nh.setdefault(d["name"], body_nhash(masked, d))
            file_nh = lc.norm_hash(masked)
        for unit in sorted(by_tu[tu]):
            sites = []
            for s in sorted(groups[(tu, unit)], key=lambda x: (x.get("line") or 0, x.get("pos") or 0)):
                c = residue_cause_im(s, can) if s.get("form") in ("I", "M") else residue_cause(s, can)
                sites.append(dict(form=s.get("form"), line=s.get("line"), base=f"{s.get('bclass')}:{s.get('base')}", off=s.get("off"),
                                  type=s.get("type"), verdict=f"RESIDUAL({c})", cause=c))
            prior = (latest or {}).get(("S", tu, unit))
            if prior is not None:
                m_ = json.loads(json.dumps(prior))
                m_.update(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, calib=calib_id, residue_of=prior.get("label"),
                          sites=(m_.get("sites") or []) + sites)
                rows.append(m_)
                continue
            causes = {x["cause"] for x in sites}
            verdict = next(iter(causes)) if len(causes) == 1 and causes <= set(S_NO_EDIT_VERDICTS) else "RESIDUAL"
            bases = {}
            for x in sites:
                bases.setdefault(x["base"], dict(base=x["base"], type=x["type"], status=x["cause"]))
            fs = unit == RESIDUE_FILE_UNIT
            h = file_nh if fs else nh.get(unit)
            rows.append(dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, rung="S", calib=calib_id, tu=tu, unit=unit,
                             fn=None if fs else unit, addr=None if fs else dl.fn_addr(unit, tu), header=tu.endswith(".h"),
                             nhash_before=h, nhash_after=h, bases=list(bases.values()), skips={}, sites=sites, verdict=verdict))
    return rows


def residue_forms(a):
    fs = tuple(x.strip().upper() for x in (getattr(a, "forms", None) or ",".join(RESIDUE_FORMS)).split(",") if x.strip())
    bad = [x for x in fs if x not in ("P", "I", "X", "M")]
    if bad or not fs:
        sys.exit(f"restruct: --forms takes P,I,X,M (got {bad or fs})")
    return fs


def im_mode(a):
    """T5.c2: True when --plan/--apply --rung S carries `--forms I,M` (the I/M recipe-ladder sweep; it implies --recipes)."""
    if getattr(a, "forms", None) is None or a.rung != "S":
        return False
    if set(residue_forms(a)) != set(IM_FORMS):
        sys.exit("restruct --plan/--apply --rung S --forms takes I,M (the recipe ladder on I/M global-base sites)")
    return True


def plan_S_im(headers, batch, only, latest, path=None):
    """T5.c2 `--plan/--apply --rung S --forms I,M`: ([(tu, {fn: {}})], drawable files, skipped, {(tu, fn): n}) — ONLY the bodies with an
    uncovered (residue_match) census I/M site on a global base (bclass gaddr/global; never file scope), files with the most such sites
    first (ties by path); a body whose latest S row carries `im` (an I/M ladder ran) at its current nhash is finished (a stale census)."""
    pre = tuple(f'{{"form": "{f}"' for f in IM_FORMS)
    cand = []
    with open(path or CENSUS / "sites.jsonl") as f:
        for l in f:
            if not l.startswith(pre):
                continue
            s = json.loads(l)
            if (s.get("bclass") in IM_BCLASS and s.get("fn") and s["tu"].endswith(".h") == headers
                    and matches_only(only, s["tu"], s["fn"])):
                cand.append(s)
    per = collections.defaultdict(collections.Counter)
    for s in residue_match(latest, cand, IM_FORMS)[1]:
        per[s["tu"]][s["fn"]] += 1
    plan, skipped, nsites = [], collections.Counter(), {}
    for tu in sorted(per, key=lambda t: (-sum(per[t].values()), t)):
        if len(plan) >= batch:
            break
        if not (REPO / tu).exists():
            skipped["file-gone"] += 1
            continue
        masked, defs, _, _, _ = file_view(tu, (REPO / tu).read_text(errors="surrogateescape"))
        cur = {d["name"]: body_nhash(masked, d) for d in defs}
        fns = [fn for fn in sorted(per[tu]) if fn in cur and not ((latest.get(("S", tu, fn)) or {}).get("im") is not None
                                                                     and latest[("S", tu, fn)].get("nhash_after") == cur[fn])]
        skipped["body-finished"] += len(per[tu]) - len(fns)
        if fns:
            plan.append((tu, {fn: {} for fn in fns}))
            nsites.update({(tu, fn): per[tu][fn] for fn in fns})
    return plan, len(per), skipped, nsites


def residue(a):
    """--rung S --residue [--forms P,X]: append the residue rows (ledger only; merged rows for bodies with a latest rung-S row) and print
    the per-cause counts of the appended sites. Held under the apply lock (no --apply may append between the read and the write)."""
    lk = _apply_exclusive()
    if lk is None:
        sys.exit("restruct --residue: another --apply/--residue holds the apply lock")
    forms = residue_forms(a)
    calib = json.loads(oracle.CALIB.read_text()) if oracle.CALIB.exists() else {}
    latest = ledger_latest(load_ledger())
    g = residue_sites(a.only, latest, forms=forms)
    rows = residue_rows(g, a.label, dict(head=calib.get("head"), stamp=calib.get("stamp")), latest)
    ledger_append(rows)
    new = [x for r in rows for x in r["sites"][-len(g[(r["tu"], r["unit"])]):]]
    cause = collections.Counter(x["cause"] for x in new)
    verd = collections.Counter(r["verdict"] for r in rows)
    print(f"restruct --residue {a.label} forms {','.join(forms)}: {len(rows)} rows ({sum(1 for r in rows if 'residue_of' in r)} merged) · "
          f"{len(new)} sites · causes {dict(sorted(cause.items()))} · verdicts {dict(sorted(verd.items()))}")
    lk.close()
    return 0


def check_residue(a):
    """--check-residue [--forms P,X]: the census sites of the forms (TUs matching --only, default ov_*) that no RESIDUAL entry of their
    body's latest rung-S row covers (residue_match, per site); exit 1 if any."""
    g = residue_sites(a.only, ledger_latest(load_ledger()), forms=residue_forms(a))
    n = sum(len(v) for v in g.values())
    print(f"uncovered {n} sites / {len(g)} bodies")
    return 1 if n else 0


def argcheck_rows():
    """argcheck's lying-declaration rows [{tu, callee, …}] (every callee spelled other than its definition), cached on the src stamp."""
    import argcheck
    cache_p = RUN / "argcheck_cache.json"
    stamp = lc.src_stamp()
    rows = None
    if cache_p.exists():
        try:
            c = json.loads(cache_p.read_text())
            if c.get("stamp") == stamp:
                rows = c["rows"]
        except Exception:      # noqa: BLE001 — a torn cache is rebuilt
            rows = None
    if rows is None:
        defs = argcheck.definitions()
        rows = argcheck.scan(defs, only_needed_argpins=False)              # ~2.4 min over the fleet: cached on the src stamp
        RUN.mkdir(parents=True, exist_ok=True)
        cache_p.write_text(json.dumps(dict(stamp=stamp, rows=rows)))
    return rows


def plan_D(headers, batch, only, settled=frozenset()):
    """[(tu, callees)] — TUs with lying declarations (argcheck's set widened to every callee spelled other than its definition), most first.
    `settled` = {(tu, callee)} the ledger has judged (any DONE verdict, latest row): a TU whose every lying callee is settled is not drawn
    again (batches t4_D2–D9 re-drew done TUs whose KEPT rows kept them ranked high — 300 files for 6 written at D9); `--redraw` lifts it."""
    rows = argcheck_rows()
    by_tu = collections.defaultdict(set)
    for r in rows:
        if r["tu"].endswith(".h") != headers:
            continue
        if only and not matches_only(only, r["tu"], r["callee"]):
            continue
        if (r["tu"], r["callee"]) in settled:
            continue
        by_tu[r["tu"]].add(r["callee"])
    ordered = sorted(by_tu, key=lambda t: (-len(by_tu[t]), t))
    return [(tu, sorted(by_tu[tu])) for tu in ordered[:batch]], len(ordered)


def settled_units(rows, redraw=()):
    """{(tu, callee)} whose LATEST rung-D row is a DONE verdict not lifted by `redraw` (R70: the last row is the verdict). A redraw key is a
    verdict (`DECL-KEPT`) or `VERDICT:cause-substring` (`DECL-NONE:no visible definition` — the 667 rows settled before defs_visible's
    fleet-unique level; the plain `DECL-NONE` key redraws every "already canonical"/external pair too, the t4_D21–D36 REDRAW's cost)."""
    latest = {(r["tu"], r["callee"]): (r.get("verdict"), r.get("cause") or "")
              for (rung, _tu, unit), r in ledger_latest(rows).items() if rung == "D" and unit.startswith("decl:")}
    keys = [(k.split(":", 1)[0], k.split(":", 1)[1] if ":" in k else None) for k in redraw]
    def lifted(v, c):
        return any(v == kv and (ks is None or ks in c) for kv, ks in keys)
    return {k for k, (v, c) in latest.items() if v in DONE_VERDICTS and not lifted(v, c)}


def stale_lifted(rows, lying, redraw, headers, only):
    """[latest rung-D `decl:` row] lifted by `redraw` (settled_units' keys) whose (tu, callee) has NO lying declaration left in `lying`
    (argcheck_rows; hand-fixed TUs): never drawn again, so the stale row would stay latest forever (P3.39 T1) — superseded instead."""
    keys = [(k.split(":", 1)[0], k.split(":", 1)[1] if ":" in k else None) for k in redraw]
    have = {(r["tu"], r["callee"]) for r in lying}
    out = []
    for (rung, tu, unit), r in ledger_latest(rows).items():
        if rung != "D" or not unit.startswith("decl:") or tu.endswith(".h") != headers:
            continue
        v, c = r.get("verdict"), r.get("cause") or ""
        if v not in DONE_VERDICTS or not any(v == kv and (ks is None or ks in c) for kv, ks in keys):
            continue
        if only and not matches_only(only, tu, r["callee"]):
            continue
        if (tu, r["callee"]) not in have:
            out.append(r)
    return out


def supersede_rows(stale, label):
    """One DECL-NONE row per stale_lifted row (no source touched, no compile)."""
    keep = ("rung", "tu", "unit", "callee", "header", "defn_tu", "nhash_before", "nhash_after")
    return [dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=label, **{k: r.get(k) for k in keep}, verdict="DECL-NONE",
                 cause=f"already canonical: no lying declaration left (stale {r.get('verdict')} row superseded)") for r in stale]


def plan_HF(headers, batch, heads, rest, settled=frozenset()):
    """Head-fold mode: [(rel, [unit keys])] — the files holding same-size, other-layout definitions of the heads, most first."""
    global _HF_STATS
    hinfo = head_info(heads)
    w = walk()
    cands, excl, kinds, n_settled = [], collections.Counter(), collections.Counter(), 0
    for rel, r in sorted(w["results"].items()):
        if not r or rel.endswith(".h") != headers or not rel.startswith("src/"):
            continue
        if rest and not matches_only(rest, rel, ""):
            continue
        cs = hf_cands(rel, r["definitions"], hinfo)
        keys = []
        for (d, h, _, ex), key in zip(cs, hf_keys(cs)):
            if ex:
                excl[ex] += 1
                continue
            if (rel, key) in settled:
                n_settled += 1
                continue
            keys.append(key)
            kinds[f"{h}/{d['scope']}"] += 1
        if keys:
            cands.append((len(keys), rel, keys))
    cands.sort(key=lambda x: (-x[0], x[1]))
    plan = [(rel, keys) for _, rel, keys in cands[:batch]]
    _HF_STATS = dict(heads=heads, defs=sum(n for n, _, _ in cands), excluded=dict(excl), kinds=dict(kinds), settled=n_settled)
    return plan, len(cands)


def plan_L(headers, batch, only, rows=None, redraw=()):
    heads, rest = head_split(only)
    if heads:
        return plan_HF(headers, batch, heads, rest, hf_settled(rows if rows is not None else load_ledger(), redraw))
    w = walk()
    by_l = _canon_by_layout()
    cands = []
    for rel, r in w["results"].items():
        if not r or rel.endswith(".h") != headers or not rel.startswith("src/") or rel in CANON_HEADERS:
            continue
        if only and not matches_only(only, rel, ""):
            continue
        n = sum(1 for d in r["definitions"] if d["scope"] == "file" and d["kind"] != "enum" and d["fields"] and d.get("lhash") in by_l) if by_l else 0
        if n == 0:
            # lhash is only present in census output; fall back to counting file-scope definitions
            n = sum(1 for d in r["definitions"] if d["scope"] == "file" and d["kind"] != "enum" and d["fields"])
        if n:
            cands.append((n, rel))
    cands.sort(reverse=True)
    return [(rel, None) for _, rel in cands[:batch]], len(cands)


def describe_plan(rung, plan, total, skipped=None):
    if rung == "S":
        n_b = sum(len(bs) for _, bs in plan)
        n_bases = sum(len(b) for _, bs in plan for b in bs.values())
        n_sites = sum(e["sites"] for _, bs in plan for b in bs.values() for e in b.values())
        return (f"restruct --plan S: {len(plan)} of {total} drawable files · {n_b} bodies · {n_bases} typed bases · {n_sites} deref sites"
                + (f" · skipped bases {dict(skipped)}" if skipped else ""))
    if rung == "D":
        return f"restruct --plan D: {len(plan)} of {total} TUs with lying declarations · {sum(len(c) for _, c in plan)} callees"
    if plan and plan[0][1] is not None:
        s = _HF_STATS
        return (f"restruct --plan L head-fold {' '.join(s['heads'])}: {len(plan)} of {total} files · {sum(len(k) for _, k in plan)} of {s['defs']} "
                f"definitions · by head/scope {s['kinds']} · excluded {s['excluded']} · settled {s['settled']}")
    return f"restruct --plan L: {len(plan)} of {total} files with file-scope definitions"


def describe_plan_im(plan, total, skipped, nsites):
    return (f"restruct --plan S --forms I,M: {len(plan)} of {total} drawable files · {sum(len(bs) for _, bs in plan)} bodies · "
            f"{sum(nsites.values())} uncovered I/M global-base sites" + (f" · skipped {dict(skipped)}" if skipped else ""))


def _apply_exclusive(path=None):
    """One --apply per RUN dir at a time: a non-blocking fcntl lock held for the process's life (T4.c2 — t38_4L1 was started twice
    11 s apart; the second unlinked and rewrote the first's inflight.json and both edited the same 150 files). Returns the open
    lock file (keep it referenced), or None when another process holds it."""
    path = path or RUN / "apply.lock"
    path.parent.mkdir(parents=True, exist_ok=True)
    f = open(path, "a")
    try:
        fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB)
    except BlockingIOError:
        f.close()
        return None
    return f


def apply_batch(a):
    RUN.mkdir(parents=True, exist_ok=True)
    global _APPLY_LOCK_F
    _APPLY_LOCK_F = _apply_exclusive()
    if _APPLY_LOCK_F is None:
        sys.exit(f"restruct --apply: another restruct --apply holds {RUN / 'apply.lock'} — one batch at a time (T4.c2)")
    clean, dirty = dl.src_clean()
    if not clean:
        sys.exit(f"restruct --apply: src/ is dirty — commit, or `tools/restruct.py --restore` if a batch is in flight (R42/R102):\n{dirty[:600]}")
    if INFLIGHT.exists():
        INFLIGHT.unlink()
    ok, why = oracle.calibration_current()
    if not ok:
        sys.exit(f"restruct --apply: the oracle's calibration is not current ({why}) — tools/delever_oracle.py --calibrate … first (R56)")
    calib = json.loads(oracle.CALIB.read_text())
    calib_id = dict(head=calib.get("head"), stamp=calib.get("stamp"))
    if not oracle.LINKS.exists():
        sys.exit("restruct --apply: the baseline snapshot carries no link inputs — tools/delever_oracle.py --snapshot-baseline after a GREEN check-all (R112)")
    rows = load_ledger()
    done, latest = ledger_index(rows)
    if a.redraw:
        # the same VERDICT[:cause-substring] keys as settled_units (the planner's side): the engine's `done` filter must lift the same
        # rows, or a redrawn TU is drawn and then skipped as done — "rows 0" (t4_D49/D56 on the `DECL-NONE:visible` key)
        # T3.c4: rung S too (was: D only) — `--rung S --only <fns> --redraw KEPT MEMBERS …` re-judges finished bodies
        vc = {(rung, tu, unit): (r.get("verdict"), r.get("cause") or "") for (rung, tu, unit), r in ledger_latest(rows).items()
              if rung == a.rung and rung in ("D", "S") and unit}
        keys = [(k.split(":", 1)[0], k.split(":", 1)[1] if ":" in k else None) for k in a.redraw]
        def lifted(k):
            v, c = vc.get((k[0], k[1], k[2]), (None, ""))
            return any(v == kv and (ks is None or ks in c) for kv, ks in keys)
        done = {k for k in done if not lifted(k)}
    log_p = RUN / f"apply_{a.label}.log"
    log_f = open(log_p, "a")

    def log(msg):
        line = f"{time.strftime('%H:%M:%S')} {msg}"
        with _LOCK:
            print(line, flush=True)
            log_f.write(line + "\n"); log_f.flush()
    recipes()
    if a.unalias is not None:
        pool = ThreadPoolExecutor(max_workers=a.jobs)
        names = a.unalias if a.unalias and a.unalias != ["ALL"] else sorted(fn_alias_index())
        done_n, kept_n, all_written = 0, 0, []
        for nm in names:
            if not dl.src_clean()[0] and not all_written:
                sys.exit("restruct --unalias: src/ is dirty (R42)")
            rows_, v, written = unalias_function(nm, a.label, calib_id, log, pool=pool)
            ledger_append(rows_)
            if v == "IDENTICAL":
                done_n += 1; all_written += written
            else:
                kept_n += 1
        pool.shutdown(wait=True)
        line = f"restruct: unalias {a.label} — {len(names)} alias-defined functions: {done_n} back under their real name / {kept_n} kept · {len(all_written)} files written"
        log(line)
        log_f.close()
        return 0
    if a.callee:
        pool = ThreadPoolExecutor(max_workers=a.jobs)
        with_files = dict(w_.split("=", 1) for w_ in (a.with_files or []))
        rows_, v, written = signature_change(a.callee, a.signature, a.label, calib_id, log, pool=pool, body_file=a.body, all_defs=a.all_defs, only_tu=a.tu,
                                             with_files=with_files, map_data=a.map_data)
        pool.shutdown(wait=True)
        ledger_append(rows_)
        line = f"restruct: signature {a.callee} — {v} · {len(written)} files written"
        log(line)
        log_f.close()
        return 0 if v == "IDENTICAL" else 1
    im = im_mode(a)
    lat_ = None
    if a.rung == "S" and im:                                       # T5.c2: only bodies with uncovered I/M global-base sites
        lat_ = ledger_latest(rows)
        plan, total, skipped, n_im = plan_S_im(a.headers, a.batch, a.only, lat_)
        print(describe_plan_im(plan, total, skipped, n_im), flush=True)
    elif a.rung == "S":
        lat_ = ledger_latest(rows)
        if a.redraw:                                               # a lifted body is not finished (s_finished) either (T3.c4)
            lat_ = {k: r for k, r in lat_.items() if not lifted(k)}
        plan, total, skipped = plan_S(a.headers, a.batch, a.only, done, lat_)
        if a.redraw:
            # T3.c4: a lifted `TU:FN` body with no drawable base left (only macro / residual sites) is re-walked with no bases: its rows
            # re-classify the raw sites and carry the macro sites' KEPT rows (s_macro_rows); plan_S never draws it (no usable base)
            have = {(tu, fn) for tu, bs in plan for fn in bs}
            for o in a.only or []:
                tu, _, fn = o.rpartition(":")
                if (tu.startswith("src/") and fn and (tu, fn) not in have and (REPO / tu).exists() and tu.endswith(".h") == a.headers
                        and lifted(("S", tu, fn))):
                    ent = next((bs for t_, bs in plan if t_ == tu), None)
                    if ent is None:
                        plan.append((tu, ent := {}))
                    ent[fn] = {}
        print(describe_plan("S", plan, total, skipped), flush=True)
    elif a.rung == "D":
        if a.redraw:
            sup = supersede_rows(stale_lifted(rows, argcheck_rows(), a.redraw, a.headers, a.only), a.label)
            ledger_append(sup)
            print(f"restruct --apply D: superseded {len(sup)} stale lifted rows (no lying declaration left)", flush=True)
        plan, total = plan_D(a.headers, a.batch, a.only, settled_units(rows, a.redraw))
        print(describe_plan("D", plan, total), flush=True)
    else:
        plan, total = plan_L(a.headers, a.batch, a.only, rows, a.redraw)
        print(describe_plan("L", plan, total), flush=True)
    hf_heads = head_split(a.only)[0] if a.rung == "L" else []
    hf_set = hf_settled(rows, a.redraw) if hf_heads else frozenset()
    if not plan:
        print(f"restruct --apply {a.rung}: nothing to do (no drawable file)")
        return 0
    # negative control (R39/R56): the first file of the batch compiled untouched must equal the snapshot
    ctl = next((tu for tu, _ in plan if recs_for(tu)), None)
    if ctl is None:
        sys.exit("restruct --apply: no file of the batch has a recipe (R43)")
    r0 = recs_for(ctl)[0]
    v, dt, err = oracle.judge(r0, None, tag="ctl")
    if v != "IDENTICAL":
        sys.exit(f"restruct --apply: the negative control FAILED — {ctl} untouched compiles {v} vs the snapshot ({err[:200]}); the baseline is stale (R56)")
    orig = {tu: (REPO / tu).read_text(errors="surrogateescape") for tu, _ in plan}
    with _inflight_lock():
        _inflight_write(dict(label=a.label, rung=a.rung, files=dict(orig)))
    if a.rung in ("D", "L"):
        walk()                      # the fleet walk forks a process pool: it must run BEFORE any worker thread exists (a fork from a
        _fallback_defs()            # threaded process deadlocked batch t3d1 at 0 % CPU); the shared definition tables likewise
    log(f"apply {a.label} rung {a.rung}: {len(plan)} files, control {ctl} IDENTICAL ({dt:.2f} s), calibration {calib_id['head']}")
    t0 = time.time()
    pool = ThreadPoolExecutor(max_workers=a.jobs)

    def one(item, hdr_pool=None):
        tu, payload = item
        try:
            if a.rung == "S":
                r = work_file_S(tu, payload, a.label, calib_id, log, pool=hdr_pool, allow_local=False, want_sa=not a.no_sa, want_recipes=a.recipes or im,
                                done=done, im_only=im, latest=lat_)
            elif a.rung == "D":
                r = work_file_D(tu, a.label, calib_id, log, pool=hdr_pool, callees=payload, done=done)
            elif hf_heads:
                r = work_file_HF(tu, a.label, calib_id, log, pool=hdr_pool, heads=hf_heads, settled=hf_set)
            else:
                r = work_file_L(tu, a.label, calib_id, log, pool=hdr_pool, done=done)
        except Exception as ex:      # noqa: BLE001 — a worker's crash is a row, never a silent gap (R55)
            import traceback
            log(f"  {tu}: TOOL-ERROR {ex!r}\n{traceback.format_exc()[-600:]}")
            tool_error_restore(tu, orig[tu], log)      # never an unjudged edit left behind (T4.c2)
            r = dict(tu=tu, rows=[dict(ts=time.strftime("%Y-%m-%d %H:%M:%S"), label=a.label, rung=a.rung, calib=calib_id, tu=tu, unit="<file>", verdict="TOOL-ERROR",
                                       err=repr(ex)[:300], sites=[])], written=False, final="TOOL-ERROR", compiles=0, seconds=0.0)
        ledger_append(r["rows"])
        log(f"  {tu}: {r['final']} · rows {len(r['rows'])} · compiles {r['compiles']} · {r['seconds']:.1f} s" +
            (f" · members {r.get('members', 0)} kept {r.get('kept', 0)} skipped {r.get('skipped', 0)} levers off {r.get('levers_off', 0)}" if a.rung == "S" else "") +
            (f" · I/M drawn {r.get('im_drawn', 0)} residual {r.get('im_residual', 0)}" if a.rung == "S" and (im or a.recipes) else "") +
            (f" · canon {r.get('canon', 0)} promoted {r.get('promoted', 0)} K&R {r.get('kr', 0)} aliases {r.get('alias', 0)} abs {r.get('builtin', 0)} kept {r.get('kept', 0)}" if a.rung == "D" else "") +
            (f" · folded {r.get('folded', 0)} refused {r.get('refused', 0)} renames {r.get('renames', 0)}" if a.rung == "L" else ""))
        return r
    if a.headers:
        results = [one(item, hdr_pool=pool) for item in plan]      # a header's includers compile in parallel; headers themselves serial
    else:
        with ThreadPoolExecutor(max_workers=a.jobs) as ex:
            results = list(ex.map(one, plan))
    pool.shutdown(wait=True)
    wall = time.time() - t0
    agg = collections.Counter()
    im_by = dict(drawn=collections.Counter(), residual=collections.Counter())
    for r in results:
        for k in ("compiles", "members", "kept", "skipped", "levers_off", "canon", "promoted", "kr", "alias", "builtin", "folded", "refused", "renames", "units", "bodies",
                  "im_drawn", "im_residual"):
            agg[k] += r.get(k, 0)
        for row in r["rows"]:                                      # T5.c2: the I/M ladder per recipe / per cause
            for nm, n in ((row.get("im") or {}).get("drawn") or {}).items():
                im_by["drawn"][nm] += n if r["final"].startswith(("IDENTICAL", "UNCHANGED")) else 0
            for c, n in ((row.get("im") or {}).get("residual") or {}).items():
                im_by["residual"][c] += n
        agg["seconds"] += r["seconds"]
        agg["rows"] += len(r["rows"])
        agg["written"] += bool(r.get("written"))
        agg["final_ok"] += r["final"].startswith(("IDENTICAL", "UNCHANGED"))
        agg["final_bad"] += r["final"].startswith(("COMBINATION-FAILED", "TOOL-ERROR")) or r["final"] == ""
        agg["no_recipe"] += r["final"] == "NO-RECIPE"
    summary = dict(label=a.label, rung=a.rung, generated=time.strftime("%Y-%m-%d %H:%M"), headers=a.headers, batch=a.batch, only=a.only, files=len(plan),
                   drawable_files=total, wall_s=round(wall, 1), calib=calib_id, **{k: agg[k] for k in agg},
                   per_file=[dict(tu=r["tu"], final=r["final"], written=bool(r.get("written")), rows=len(r["rows"]), compiles=r["compiles"]) for r in results],
                   im_by_recipe=dict(sorted(im_by["drawn"].items())), im_by_cause=dict(sorted(im_by["residual"].items())))
    (RUN / f"batch_{a.label}.json").write_text(json.dumps(summary, indent=1) + "\n")
    if a.rung == "S":
        detail = (f"{agg['bodies']} bodies: {agg['members']} sites → members / {agg['kept']} kept / {agg['skipped']} skipped · levers off {agg['levers_off']}")
        if im or a.recipes:
            detail += (f" · I/M recipes drawn {agg['im_drawn']} {dict(sorted(im_by['drawn'].items()))} / residual {agg['im_residual']} "
                       f"{dict(sorted(im_by['residual'].items()))}")
    elif a.rung == "D":
        detail = (f"{agg['units']} declaration units: {agg['canon']} canonical / {agg['promoted']} promoted / {agg['kr']} K&R marked / "
                  f"{agg['alias']} aliases typed / {agg['builtin']} __builtin_abs → abs / {agg['kept']} kept")
    else:
        detail = f"{agg['units']} definitions: {agg['folded']} folded ({agg['renames']} member renames) / {agg['refused']} refused"
    line = (f"restruct: batch {a.label} rung {a.rung} — {len(plan)} files ({'headers' if a.headers else 'TUs'}; {total} drawable) · {detail} · "
            f"compiles {agg['compiles']} in {wall:.0f} s wall · final {agg['final_ok']}/{len(plan)} identical · written {agg['written']} files")
    log(line)
    log_f.close()
    return 0 if agg["final_bad"] == 0 else 1


# ----------------------------------------------------------------------------------------------------------------------
# the WRITER (--write-types), the naming invariant (--audit-types), the ledger's field assertion (--check-ledger)
# ----------------------------------------------------------------------------------------------------------------------
def write_types(a):
    smap = struct_map()
    names = list(a.type or [])
    if a.top:
        names += [t["name"] for t in sorted(smap.values(), key=lambda t: -t["sites"])[:a.top] if t["name"] not in names]
    if not names:
        sys.exit("restruct --write-types: name the types (--type NAME … or --top N)")
    out_dir = RUN / "types_preview"
    out_dir.mkdir(parents=True, exist_ok=True)
    chunks, report = [], []
    sites_all = [json.loads(l) for l in (CENSUS / "sites.jsonl").read_text().splitlines() if l.strip()] if a.pointees and (CENSUS / "sites.jsonl").exists() else []
    for n in names:
        t = smap.get(n)
        if not t:
            report.append(f"{n}: not in the struct map"); continue
        ctypes = collections.defaultdict(list)
        for s in sites_all:
            if s.get("type") == n and s.get("ctype"):
                ctypes[s.get("off") or 0].append(s["ctype"])
        entries, skipped = sl.entries_from_layout(t["layout"], ctypes)
        if not entries:
            report.append(f"{n}: no entry survives the layout rules ({len(skipped)} skipped)"); continue
        size = None
        if t.get("size_hint"):
            end = max(e[0] + (sl.scalar_of(e[1]) or (4,))[0] for e in entries)
            size = max(t["size_hint"], end)
            size = (size + 3) // 4 * 4
        try:
            txt = sl.render_struct(n, entries, size=size, comment=f"P37 struct map: {t['sites']} sites in {t['bodies']} bodies; evidence {t.get('evidence')}" +
                                   (f"; at {','.join(t.get('globals_at', [])[:3])}" if t.get("globals_at") else ""))
        except ValueError as ex:
            report.append(f"{n}: writer refused — {ex}"); continue
        chunks.append(txt)
        by = collections.Counter(s[3] for s in skipped)
        report.append(f"{n}: {len(entries)} fields, size {size:#x} · skipped {dict(by)}" if size else f"{n}: {len(entries)} fields · skipped {dict(by)}")
    space = a.space or "ov"
    p = out_dir / f"{space}.h"
    p.write_text("/* restruct --write-types PREVIEW — not a build input; T5 authors the canonical files from this */\n\n" + "\n".join(chunks))
    print(f"restruct --write-types: {len(chunks)} definitions -> {p.relative_to(REPO)}")
    for r in report:
        print("  ", r)
    return 0


def audit_type_violations():
    """struct_layout.audit_definition over every canonical type file's definitions (with their raw text for the comment/trailer checks):
    (n definitions audited, [violation strings]). Shared by --audit-types and type_census --check-structs."""
    viol, n = [], 0
    for h in CANON_HEADERS:
        if not (REPO / h).exists():
            continue
        raw = (REPO / h).read_text(errors="surrogateescape")
        ls = dl.line_starts(raw)
        w = tc._walk_worker(h)
        defs = {}
        for d in w["definitions"]:
            for nm in d["names"] + ([d["tag"]] if d["tag"] else []):
                defs.setdefault(nm, d)
        for al in w["typedef_aliases"]:
            defs.setdefault(al["name"], dict(kind="alias", alias_of=al["alias_of"], alias_stars=al["alias_stars"], alias_dims=al["alias_dims"]))
        res = sl.Resolver(defs)
        for d in w["definitions"]:
            if d["kind"] == "enum" or not d["fields"]:
                continue
            n += 1
            text = raw[ls[d["line"] - 1]:ls[d["end"]] if d["end"] < len(ls) else len(raw)]
            for v in sl.audit_definition(d, res, text):
                viol.append(f"{h}:{d['line']} {v}")
    return n, viol


def audit_types(a=None, quiet=False):
    """--audit-types: print audit_type_violations(); exit 1 on any."""
    n, viol = audit_type_violations()
    if not quiet:
        print(f"restruct --audit-types: {n} canonical definitions audited; {len(viol)} naming/offset violation(s)")
        for v in viol[:40]:
            print("  ", v)
    return 0 if not viol else 1


def check_ledger(a=None):
    """Every MEMBER site the ledger recorded is still a leaf (off, width, sign) of its CURRENT canonical type."""
    can = canon_types()
    rows = load_ledger()
    bad, n = [], 0
    for r in rows:
        if r.get("rung") not in ("S",):
            continue
        for s in r.get("sites", []):
            if s.get("verdict") != "MEMBER" or not s.get("type") or s["type"].startswith("P37S_"):
                continue
            n += 1
            c = can.get(s["type"])
            if not c:
                bad.append(f"{r['tu']}:{s['line']} {s['type']} no longer a canonical type"); continue
            d, res, fm = c
            lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in d["attrs"]))
            sign = s.get("sign") if s.get("access") != "store" else None
            if not sl.leaf_at(lay, s["off"], s["width"], sign):
                bad.append(f"{r['tu']}:{s['line']} {s['type']}+{s['off']:#x} ({s['width']}{s.get('sign')}) is not a field of the current definition")
    print(f"restruct --check-ledger: {n} MEMBER sites checked against the canonical types; {len(bad)} violation(s)")
    for b in bad[:30]:
        print("  ", b)
    return 0 if not bad else 1
# ----------------------------------------------------------------------------------------------------------------------
# the probe (T2)
# ----------------------------------------------------------------------------------------------------------------------
def draw_sample(n, seed, strata):
    """Bodies stratified by the base's kind, from body_base_type.json: returns [(tu, fn, base_key, type, stratum)]."""
    bbt = json.loads((CENSUS / "body_base_type.json").read_text())
    smap = struct_map()
    rng = random.Random(seed)
    # every (body, base) with a type; classify the stratum
    cands = collections.defaultdict(list)
    lever_bodies = {(k[0], k[1]) for k in ds.sites_by_body()}
    for key, bases in bbt.items():
        tu, fn = key.split("|", 1)
        for bk, ent in bases.items():
            t = smap.get(ent["type"])
            if not t or ent["sites"] < 2:
                continue
            bcls = bk.split(":", 1)[0]
            if t["sites"] >= 50000:
                stratum = "A-entity(0x24C)" if t["size_hint"] >= 0x200 else "B-large-ptr-globals"
            elif bcls in ("gaddr", "global") and t["bodies"] >= 5:
                stratum = "D-record-tables"
            elif t["size_hint"] in (8, 32, 48, 16) and t["bodies"] >= 20:
                stratum = "C-matrix/vector-shaped"
            elif tu.startswith("src/shared/"):
                stratum = "E-shared-header-bodies"
            elif t["bodies"] >= 2:
                stratum = "F-other-multi-body-types"
            else:
                stratum = "G-single-body-types"
            lev = (tu, fn) in lever_bodies
            cands[stratum].append((tu, fn, bk, ent["type"], stratum, ent["sites"], lev))
    out = []
    for stratum, want in strata.items():
        pool = cands.get(stratum, [])
        rng.shuffle(pool)
        # half of each stratum from lever-bearing bodies where available (the struct hypothesis needs them)
        lev = [c for c in pool if c[6]]
        non = [c for c in pool if not c[6]]
        take = lev[: want // 2] + non[: want - min(len(lev), want // 2)]
        if len(take) < want:
            take = (lev + non)[:want]
        out.extend(take)
    return out, {k: len(v) for k, v in cands.items()}

def _probe_worker(args):
    tu, fn, bk, tname, stratum, nsites, lev = args
    try:
        row = try_body(tu, fn, base_key=bk, tname_hint=tname, tag="pr" + hashlib.sha1(tu.encode()).hexdigest()[:6])
    except Exception as e:      # noqa: BLE001
        row = dict(tu=tu, fn=fn, base=bk, type=tname, verdict="TOOL-ERROR", err=repr(e)[:200])
    row.update(stratum=stratum, base_sites=nsites, lever_body=lev)
    return row

def run_probe(a):
    PROBE.mkdir(parents=True, exist_ok=True)
    strata = {"A-entity(0x24C)": 40, "B-large-ptr-globals": 25, "C-matrix/vector-shaped": 25, "D-record-tables": 25,
              "E-shared-header-bodies": 20, "F-other-multi-body-types": 20, "G-single-body-types": 10}
    if a.sample:
        scale = a.sample / sum(strata.values())
        strata = {k: max(1, int(round(v * scale))) for k, v in strata.items()}
    sample, pool_sizes = draw_sample(a.sample or sum(strata.values()), a.seed, strata)
    # workers own whole FILES: group by tu; headers run serially at the end (their includers are other workers' files)
    by_tu = collections.defaultdict(list)
    for c in sample:
        by_tu[c[0]].append(c)
    c_files = [v for k, v in by_tu.items() if not k.endswith(".h")]
    h_files = [v for k, v in by_tu.items() if k.endswith(".h")]
    t0 = time.time()
    rows = []
    recipes()          # warm the caches in the parent before forking
    with ProcessPoolExecutor(max_workers=a.jobs) as ex:
        for res in ex.map(_probe_file, c_files):
            rows.extend(res)
    for group in h_files:
        rows.extend(_probe_file(group))
    dt = time.time() - t0
    with (PROBE / "probe_rows.jsonl").open("w") as fh:
        for r in rows:
            fh.write(json.dumps(r) + "\n")
    table = render_probe(rows, pool_sizes, dt, a.seed)
    (PROBE / "probe_table.md").write_text(table)
    print(table)

def _probe_file(group):
    return [_probe_worker(c) for c in group]

def render_probe(rows, pool_sizes, dt, seed):
    L = [f"# T2 probe (i) — rung 1 (struct spelling) on a stratified sample; seed {seed}; {len(rows)} bodies; {dt:.0f} s wall", ""]
    L.append(f"Pool sizes (bodies × typed bases in the census): {pool_sizes}")
    L.append("")
    L.append("| stratum | bodies | IDENTICAL | DIFFERS | COMPILE-ERROR/CRASH | no site / other | sites rewritten | DIFFERS closed by S2 (casts kept) | of DIFFERS with levers: S+A IDENTICAL | levers-off alone IDENTICAL | residual kinds (DIFFERS) |")
    L.append("|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---|")
    tot = collections.Counter()
    for stratum in sorted({r["stratum"] for r in rows}):
        rs = [r for r in rows if r["stratum"] == stratum]
        v = collections.Counter(r["verdict"] for r in rs)
        rew = sum(r.get("rewritten", 0) or 0 for r in rs)
        diff_lev = [r for r in rs if r["verdict"] == "DIFFERS" and r.get("levers")]
        sa_ok = sum(1 for r in diff_lev if (r.get("sa") or {}).get("verdict") == "IDENTICAL")
        alone_ok = sum(1 for r in diff_lev if (r.get("sa") or {}).get("levers_off_alone") == "IDENTICAL")
        kinds = collections.Counter((r.get("residual") or {}).get("kind", "?") for r in rs if r["verdict"] == "DIFFERS")
        ce = v["COMPILE-ERROR"] + v["COMPILE-CRASH"]
        other = len(rs) - v["IDENTICAL"] - v["DIFFERS"] - ce
        s2 = [r for r in rs if r["verdict"] == "DIFFERS" and (r.get("s2") or {}).get("verdict") == "IDENTICAL"]
        s2k = sum(r["s2"]["kept"] for r in s2)
        L.append(f"| {stratum} | {len(rs)} | {v['IDENTICAL']} | {v['DIFFERS']} | {ce} | {other} | {rew} | {len(s2)}/{v['DIFFERS']} ({s2k} casts kept) | {sa_ok}/{len(diff_lev)} | {alone_ok}/{len(diff_lev)} | {dict(kinds)} |")
        tot.update(dict(n=len(rs), ident=v["IDENTICAL"], diff=v["DIFFERS"], ce=ce, rew=rew, dl=len(diff_lev), sa=sa_ok, alone=alone_ok, s2=len(s2), s2k=s2k))
    L.append(f"| **all** | {tot['n']} | {tot['ident']} | {tot['diff']} | {tot['ce']} | {tot['n'] - tot['ident'] - tot['diff'] - tot['ce']} | {tot['rew']} | {tot['s2']}/{tot['diff']} ({tot['s2k']} casts kept) | {tot['sa']}/{tot['dl']} | {tot['alone']}/{tot['dl']} | |")
    L.append("")
    judged = tot["ident"] + tot["diff"]
    if judged:
        L.append(f"**Rung 1 is byte-neutral on {tot['ident']}/{judged} judged bodies ({100.0 * tot['ident'] / judged:.1f} %), moving {tot['rew']} sites; "
                 f"rung S2 (a minimal set of sites kept as casts, delever's rung-B shape) closes {tot['s2']} of the {tot['diff']} DIFFERS bodies keeping {tot['s2k']} casts "
                 f"({tot['ident'] + tot['s2']}/{judged} = {100.0 * (tot['ident'] + tot['s2']) / max(1, judged):.1f} % of judged bodies byte-identical with members everywhere but {tot['s2k']} sites); "
                 f"of the {tot['dl']} DIFFERS bodies that carry marked levers, {tot['sa']} become IDENTICAL with the struct AND the levers off "
                 f"(the struct hypothesis), of which {tot['alone']} were already identical with the levers off alone (the struct did not decide those).**")
    errs = collections.Counter(r.get("err", "")[:70] for r in rows if r["verdict"] in ("COMPILE-ERROR", "COMPILE-CRASH", "TOOL-ERROR"))
    if errs:
        L.append("")
        L.append("Compile errors / tool errors (top): " + " · ".join(f"{k!r} ×{n}" for k, n in errs.most_common(8)))
    skips = collections.Counter()
    for r in rows:
        for k, n in (r.get("skips") or {}).items():
            skips[k] += n
    L.append(f"\nSites skipped by the rewrite (not converted; counted): {dict(skips)}")
    secs = [r.get("seconds", 0) for r in rows if r.get("seconds")]
    if secs:
        L.append(f"Seconds per body judgement: mean {sum(secs) / len(secs):.2f}, max {max(secs):.2f} (headers judge every includer).")
    L.append("")
    L.append("Rows: `.run/P37/probe/probe_rows.jsonl` (per body: tu, fn, base, type, rewritten, skips, verdict, residual, sa).")
    return "\n".join(L) + "\n"

# ----------------------------------------------------------------------------------------------------------------------
# (ii) the declaration probe: the in-scope declaration replaced by the definition's ANSI signature, per TU and per callee
# ----------------------------------------------------------------------------------------------------------------------
NARROW = re.compile(r"\b(s16|u16|s8|u8|short|char)\b")

def _decl_repair_text(raw, rows, real_ret=None):
    """Rewrite every lying extern of the given rows (same TU, same callee) to the definition's parameter list."""
    lines = raw.split("\n")
    changed = 0
    for r in rows:
        i = r["line"] - 1
        if i >= len(lines):
            continue
        pat = re.compile(r"\b" + re.escape(r["callee"]) + r"\s*\(([^;)]*)\)")
        new, n = pat.subn(lambda m: f"{r['callee']}({r['real_params']})", lines[i], count=1)
        if n:
            lines[i] = new
            changed += 1
    return "\n".join(lines), changed

def probe_decls(a):
    import argcheck
    defs = argcheck.definitions()
    rows = argcheck.scan(defs, only_needed_argpins=False)
    by_tu = collections.defaultdict(lambda: collections.defaultdict(list))
    for r in rows:
        by_tu[r["tu"]][r["callee"]].append(r)
    rng = random.Random(a.seed)
    # stratify TUs by kind
    kinds = collections.defaultdict(list)
    for tu in by_tu:
        k = "shared-header" if tu.startswith("src/shared/") else "main" if tu.count("/") == 1 else "md" if tu.startswith("src/md_") else "ov"
        kinds[k].append(tu)
    want = {"ov": 200, "main": 40, "md": 30, "shared-header": 30}
    if a.sample:
        scale = a.sample / sum(want.values())
        want = {k: max(1, int(round(v * scale))) for k, v in want.items()}
    sample = []
    for k, n in want.items():
        pool = kinds.get(k, [])
        rng.shuffle(pool)
        sample.extend((tu, k) for tu in pool[:n])
    recipes()
    work = [(tu, k, dict(by_tu[tu]), defs) for tu, k in sample]
    out = []
    t0 = time.time()
    with ProcessPoolExecutor(max_workers=a.jobs) as ex:
        for res in ex.map(_decl_worker, [w for w in work if not w[0].endswith(".h")]):
            out.extend(res)
    for w in work:
        if w[0].endswith(".h"):
            out.extend(_decl_worker(w))
    dt = time.time() - t0
    PROBE.mkdir(parents=True, exist_ok=True)
    with (PROBE / "decl_rows.jsonl").open("w") as fh:
        for r in out:
            fh.write(json.dumps(r) + "\n")
    print(render_decls(out, dt, a.seed, sum(len(v) for v in by_tu.values()), len(by_tu)))
    (PROBE / "decl_table.md").write_text(render_decls(out, dt, a.seed, sum(len(v) for v in by_tu.values()), len(by_tu)))

def _decl_worker(args):
    tu, kind, by_callee, defs = args
    out = []
    try:
        raw = (REPO / tu).read_text(errors="surrogateescape")
    except OSError:
        return out
    for callee, rows in by_callee.items():
        text, changed = _decl_repair_text(raw, rows)
        if not changed:
            out.append(dict(tu=tu, kind=kind, callee=callee, rows=len(rows), verdict="NO-EDIT"))
            continue
        real = defs.get(callee)
        v, dt, err, _ = judge_text(tu, text, "dc" + hashlib.sha1((tu + callee).encode()).hexdigest()[:6])
        cause = None
        if v != "IDENTICAL":
            if "too few arguments" in err or "too many arguments" in err:
                cause = "arity (the call passes a different count)"
            elif "conflicting types" in err:
                cause = "conflicting declaration elsewhere in the TU"
            elif v.startswith("COMPILE"):
                cause = "compile: " + err.split("\n")[0][-70:]
            elif NARROW.search(real[1] or ""):
                cause = "narrow parameter width (caller-side conversion)"
            else:
                cause = "other (bytes moved with no narrow width)"
        out.append(dict(tu=tu, kind=kind, callee=callee, rows=len(rows), declared_kinds=sorted({r["kind"] for r in rows}),
                        real_params=real[1] if real else None, verdict=v, cause=cause, err=err[:120], seconds=round(dt, 2)))
    return out

def render_decls(rows, dt, seed, n_rows_all, n_tus_all):
    L = [f"# T2 probe (ii) — the canonical prototype (the definition's ANSI signature) per TU × callee; seed {seed}; {len(rows)} judgements; {dt:.0f} s wall", "",
         f"Population: {n_rows_all} lying declarations in {n_tus_all} TUs (argcheck). Sample: per TU, every lying callee repaired ALONE (its declarations in that TU), judged on the object.", "",
         "| TU kind | judgements | IDENTICAL | DIFFERS | COMPILE-ERROR | no edit | causes (non-identical) |", "|---|---:|---:|---:|---:|---:|---|"]
    tot = collections.Counter()
    for kind in sorted({r["kind"] for r in rows}):
        rs_ = [r for r in rows if r["kind"] == kind]
        v = collections.Counter(r["verdict"] for r in rs_)
        causes = collections.Counter((r.get("cause") or "")[:45] for r in rs_ if r["verdict"] not in ("IDENTICAL", "NO-EDIT"))
        ce = sum(n for k, n in v.items() if k.startswith("COMPILE"))
        L.append(f"| {kind} | {len(rs_)} | {v['IDENTICAL']} | {v['DIFFERS']} | {ce} | {v['NO-EDIT']} | {dict(causes.most_common(4))} |")
        tot.update(dict(n=len(rs_), ident=v["IDENTICAL"], diff=v["DIFFERS"], ce=ce, noedit=v["NO-EDIT"]))
    L.append(f"| **all** | {tot['n']} | {tot['ident']} | {tot['diff']} | {tot['ce']} | {tot['noedit']} | |")
    judged = tot["ident"] + tot["diff"] + tot["ce"]
    if judged:
        L.append("")
        L.append(f"**The definition's signature is a free replacement for {tot['ident']}/{judged} judged (TU, callee) pairs ({100.0 * tot['ident'] / judged:.1f} %); "
                 f"{tot['diff']} move bytes, {tot['ce']} refuse to compile (arity contradictions and conflicting declarations).** Per callee, the non-free "
                 f"cases are the declaration solver's input (T3): the definition's width or return axis, or a byte-proven K&R call.")
    kr = [r for r in rows if r["verdict"] in ("DIFFERS",) and "K&R-empty" in (r.get("declared_kinds") or [])]
    narrow = [r for r in rows if r["verdict"] == "DIFFERS" and "narrow parameter" in (r.get("cause") or "")]
    L.append(f"\nOf the DIFFERS: {len(narrow)} have a narrow parameter in the definition (`s16/u16/s8/u8`: the caller now converts — the width rule); "
             f"{len(kr)} were `()` declarations.")
    L.append("\nRows: `.run/P37/probe/decl_rows.jsonl`.")
    return "\n".join(L) + "\n"

# ----------------------------------------------------------------------------------------------------------------------
# (iii) the definition fold: a TU's file-scope definition that duplicates a canonical type (same layout, tier 1/2) becomes a
#       typedef alias of the canonical name (or is deleted when it IS the canonical name) — judged on the object
# ----------------------------------------------------------------------------------------------------------------------
def probe_defs(a):
    import lever_census as lc
    aliases, dirs = sc.fleet_and_dirs()
    tu_aliases, headers, _ = lc.enumerate_files(aliases, dirs)
    canon = tc._walk_worker("src/shared/engine_types.h")
    cdefs = {}
    for d in canon["definitions"]:
        for n in d["names"] + ([d["tag"]] if d["tag"] else []):
            cdefs.setdefault(n, d)
    for al in canon["typedef_aliases"]:
        cdefs.setdefault(al["name"], dict(kind="alias", alias_of=al["alias_of"], alias_stars=al["alias_stars"], alias_dims=al["alias_dims"]))
    cres = tc.Resolver(dict(cdefs))
    canon_by_lhash = collections.defaultdict(list)
    for d in canon["definitions"]:
        if d["kind"] == "enum" or not d["fields"]:
            continue
        lay = cres.layout_of_fields(d["fields"], d["kind"], packed=("packed" in d["attrs"]))
        if lay:
            d["lhash"] = tc.layout_hash(lay)
            canon_by_lhash[d["lhash"]].append(d)
    def sig(d):
        return tuple(("*" if re.match(r"^(?:unk|f|field_?|pad|p|a|b|c|d|w|v|m|t|x|s|u|_|arr|buf|data|val|word|byte|half|tmp|r|q|n)?[0-9A-Fa-fx_]*$", f.get("name") or "") else f["name"]) for f in d["fields"])
    # candidate TUs: overlay TUs including the prelude with the most file-scope definitions
    cands = []
    for tu in sorted(tu_aliases):
        if not tu.startswith("src/ov_"):
            continue
        raw = (REPO / tu).read_text(errors="surrogateescape")
        if "engine_prelude.h" not in raw:
            continue
        n = len(re.findall(r"^(?:typedef\s+)?(?:struct|union)\b[^;]*\{", raw, re.M))
        if n:
            cands.append((n, tu))
    cands.sort(reverse=True)
    rng = random.Random(a.seed)
    top = [tu for _, tu in cands[:60]]
    rng.shuffle(top)
    sample = top[:20]
    rows = []
    for tu in sample:
        r = tc._walk_worker(tu)
        raw = (REPO / tu).read_text(errors="surrogateescape")
        scope = dict(cdefs)
        for d in r["definitions"]:
            for n in d["names"] + ([d["tag"]] if d["tag"] else []):
                scope.setdefault(n, d)
        res = tc.Resolver(scope)
        ls = dl.line_starts(raw)
        edits, kinds = [], collections.Counter()
        for d in r["definitions"]:
            if d["kind"] == "enum" or d["scope"] != "file" or not d["fields"]:
                continue
            lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in d["attrs"]))
            if not lay:
                kinds["unresolved"] += 1
                continue
            lh = tc.layout_hash(lay)
            cs = canon_by_lhash.get(lh, [])
            names = d["names"] + ([d["tag"]] if d["tag"] else [])
            same_name = [c for c in cs if set(c["names"] + ([c["tag"]] if c["tag"] else [])) & set(names)]
            if same_name:
                # the canonical definition IS visible under this name: the local copy is a redefinition the TU tolerates only because
                # cdecl/strip left it — delete it (R43: identical text or refuse)
                if any(c["text_hash"] == d["text_hash"] for c in same_name):
                    edits.append((ls[d["line"] - 1], ls[d["end"]], "")); kinds["deleted-same"] += 1
                else:
                    kinds["same-name-different-text"] += 1
                continue
            tier = [c for c in cs if sig(c) == sig(d) or all(x == "*" for x in sig(d) + sig(c))]
            if not tier:
                kinds["no-canonical-twin"] += 1 if not cs else 0
                kinds["layout-twin-kept-apart"] += 1 if cs else 0
                continue
            c = tier[0]
            cname = c["names"][0] if c["names"] else f"struct {c['tag']}"
            if not d["typedef"] and d["tag"] and not d["names"]:
                kinds["tag-only-local"] += 1
                continue
            alias_lines = "".join(f"typedef {cname} {n};\n" for n in d["names"])
            edits.append((ls[d["line"] - 1], ls[d["end"]], alias_lines)); kinds["aliased"] += 1
        if not edits:
            rows.append(dict(tu=tu, folds=0, kinds=dict(kinds), verdict="NO-EDIT"))
            continue
        out, last = [], 0
        for (a0, b0, rep) in sorted(edits):
            out.append(raw[last:a0]); out.append(rep); last = b0
        out.append(raw[last:])
        text = "".join(out)
        v, dt, err, _ = judge_text(tu, text, "df" + hashlib.sha1(tu.encode()).hexdigest()[:6])
        rows.append(dict(tu=tu, folds=len(edits), kinds=dict(kinds), verdict=v, err=err[:160]))
        print(f"{v:14s} {len(edits):3d} folds {dict(kinds)} {tu} {err[:80]}")
    PROBE.mkdir(parents=True, exist_ok=True)
    (PROBE / "defs_rows.jsonl").write_text("".join(json.dumps(r) + "\n" for r in rows))
    v = collections.Counter(r["verdict"] for r in rows)
    folds = sum(r["folds"] for r in rows)
    print(f"restruct --probe-defs: {len(rows)} TUs, {folds} definitions folded onto the canonical header: {dict(v)}")
# ----------------------------------------------------------------------------------------------------------------------
# (iv) the layout engine audited against cc1
# ----------------------------------------------------------------------------------------------------------------------
def audit_layouts(a):
    """For every definition the census parsed: a probe TU asserting sizeof and every top-level named field's offset with the
    negative-array-size idiom, compiled through the pinned cc1 (cdecl's oracle). 0 rejections = the engine agrees with the compiler."""
    import cdecl
    files = {}
    defs_all = []
    aliases, dirs = sc.fleet_and_dirs()
    import lever_census as lc
    tu_aliases, headers, _ = lc.enumerate_files(aliases, dirs)
    todo = sorted(tu_aliases) + list(headers) + sorted(p.relative_to(REPO).as_posix() for p in (REPO / "include").glob("*.h"))
    with ProcessPoolExecutor(max_workers=a.jobs) as ex:
        for r in ex.map(tc._walk_worker, todo, chunksize=8):
            files[r["rel"]] = r
    # the census's resolvers, per file (its own definitions first, then the canonical header)
    global_defs = {}
    for r in files.values():
        for d in r["definitions"]:
            if d["file"].startswith("include/") or d["is_canon"]:
                for n in d["names"] + ([d["tag"]] if d["tag"] else []):
                    global_defs.setdefault(n, d)
        for al in r["typedef_aliases"]:
            if al["file"].startswith("include/") or al["file"] in tc.CANON_HEADERS:
                global_defs.setdefault(al["name"], dict(kind="alias", alias_of=al["alias_of"], alias_stars=al["alias_stars"], alias_dims=al["alias_dims"]))
    probes, n_defs, n_fields, unresolved = [], 0, 0, 0
    for rel, r in files.items():
        scope = dict(global_defs)
        for d in r["definitions"]:
            for n in d["names"] + ([d["tag"]] if d["tag"] else []):
                scope.setdefault(n, d)
        for al in r["typedef_aliases"]:
            scope.setdefault(al["name"], dict(kind="alias", alias_of=al["alias_of"], alias_stars=al["alias_stars"], alias_dims=al["alias_dims"]))
        res = tc.Resolver(scope)
        for d in r["definitions"]:
            if d["kind"] == "enum" or not d["fields"] or d["scope"] != "file":
                continue
            lay = res.layout_of_fields(d["fields"], d["kind"], packed=("packed" in d["attrs"]))
            if lay is None:
                unresolved += 1
                continue
            n_defs += 1
            offs = field_offsets(res, d)
            if not d["names"] and not d["tag"]:
                continue            # an anonymous, tagless definition (a member's inline type) cannot be named by a probe
            spans = [(x["line"], x["end"]) for x in r["definitions"] if x["scope"] == "file" and x["line"] <= d["line"]]
            tname = d["names"][0] if d["names"] else (f"struct {d['tag']}" if d["kind"] == "struct" else f"union {d['tag']}")
            fnspans = [(f["line"], f["fn_end"]) for f in r["fndefs"] if f.get("fn_end")]
            probes.append((rel, d["line"], tname, lay[0], offs, spans, fnspans))
            n_fields += len(offs)
    # compile in batches: each probe is its own tiny TU (a definition may depend on its file's other types: include the file's
    # own file-scope definitions verbatim before it — the masked text, in order — plus its scalar typedefs and common.h)
    rej, checked = [], 0
    with ProcessPoolExecutor(max_workers=a.jobs) as ex:
        for res_ in ex.map(_audit_one, probes, chunksize=16):
            checked += 1
            if not res_[4]:
                rej.append(res_)
    PROBE.mkdir(parents=True, exist_ok=True)
    (PROBE / "layout_audit.json").write_text(json.dumps(dict(checked=checked, definitions=n_defs, fields=n_fields, unresolved=unresolved, rejected=rej[:200]), indent=1))
    print(f"restruct --audit-layouts: {checked} file-scope definitions ({n_fields} named fields) asserted against cc1; rejected {len(rej)}; "
          f"unresolved layouts {unresolved}")
    for r in rej[:12]:
        print("  REJECT", r[0], r[1], r[2], r[3])
    return 0 if not rej else 1

def cc1_accepts(body):
    """cdecl._cc1_accepts with a scratch path keyed by the body (R111: cdecl's fixed `cc1probe.c` would collide across workers)."""
    import cdecl
    import tempfile
    d = PROBE / "cc1"
    d.mkdir(parents=True, exist_ok=True)
    fd, cpath = tempfile.mkstemp(dir=str(d), prefix="p", suffix=".c")      # unique per call (R111): identical bodies from the
    os.close(fd)                                                           # cross-address copies raced on a shared hash name
    c = pathlib.Path(cpath); i = pathlib.Path(cpath[:-2] + ".i")
    c.write_text(body, errors="surrogateescape")
    p = subprocess.run(cdecl.CPP + ["-Isrc", str(c)], capture_output=True, text=True, cwd=REPO)
    if p.returncode:
        c.unlink(missing_ok=True)
        return None
    i.write_text(p.stdout)
    r = subprocess.run([cdecl.CC1] + cdecl.CC1FLAGS + [str(i), "-o", "/dev/null"], capture_output=True, text=True, cwd=REPO)
    ok = not (r.returncode or cdecl._ERR.search(r.stderr or ""))
    if ok:
        c.unlink(missing_ok=True); i.unlink(missing_ok=True)
    else:
        c.with_suffix(".err").write_text(r.stderr[-2000:])
    return ok

def _audit_one(args):
    rel, dline, tname, size, offs, spans, fnspans = args
    raw = (REPO / rel).read_text(errors="surrogateescape")
    masked = tc._blank_dead_guards(sc.mask_text(raw), raw, rel)
    ls = dl.line_starts(masked)
    upto = ls[spans[-1][1]] if spans else len(masked)          # the target definition's end (the last span is the target)
    # the TU's real environment IN ORDER: #include lines (shared BODY headers dropped — code, not types), file-scope typedef statements
    # and struct/union definitions, each at its own position, up to the target; function bodies and externs left out
    items = []
    for m in sc.INCLUDE_LINE.finditer(masked):
        if m.start() >= upto:
            break
        target = os.path.normpath(os.path.join(os.path.dirname(rel), m.group(1)))
        if re.search(r"/func_[0-9A-Fa-f]{8}", target):
            continue
        inc = os.path.relpath(REPO / target, REPO / "include") if (REPO / target).exists() else m.group(1)
        items.append((m.start(), f'#include "{inc}"'))
    def_spans = [(ls[a0 - 1], ls[b0]) for (a0, b0) in spans]
    for (a0, b0) in def_spans:
        txt = masked[a0:b0].rstrip()
        items.append((a0, txt if txt.endswith(";") else txt + ";"))
    fn_pos = [(ls[a0 - 1], ls[b0]) for (a0, b0) in fnspans if a0 - 1 < len(ls) and b0 < len(ls)]
    for m in re.finditer(r"(?<![\w.])typedef\s+[^;{}]+?;", masked):
        if m.start() >= upto:
            break
        if any(a0 <= m.start() < b0 for (a0, b0) in def_spans):
            continue                    # inside a definition's span already emitted
        if any(a0 <= m.start() < b0 for (a0, b0) in fn_pos):
            continue                    # a block-scope typedef inside a function body: not the file scope's
        items.append((m.start(), masked[m.start():m.end()]))
    items.sort()
    body = "\n".join(t for _, t in items) + "\n"
    if '#include "common.h"' not in body:
        body = '#include "common.h"\n' + body
    body += f"char p37_size[(sizeof({tname}) == {size}) ? 1 : -1];\n"
    for (fname, off) in offs:
        body += f"char p37_{fname}[((int)&((({tname} *)0)->{fname}) == {off}) ? 1 : -1];\n"
    ok = cc1_accepts(body)
    return (rel, dline, tname, size, ok)

# ----------------------------------------------------------------------------------------------------------------------
# (vi) the fan-out cost of one canonical-header edit
# ----------------------------------------------------------------------------------------------------------------------
def fanout_cost(a):
    hdr = "src/shared/engine_types.h"
    _, by_src, inc = recipes()
    tus = inc.get(hdr, [])
    recs = [r for t in tus for r in by_src.get(t, [])]
    path = REPO / hdr
    raw = path.read_text(errors="surrogateescape")
    st = path.stat()
    text = raw.replace("#endif", "typedef struct { s32 p37_probe_unused; } P37_FANOUT_PROBE;\n#endif", 1) if raw.rstrip().endswith("#endif") else raw + "\ntypedef struct { s32 p37_probe_unused; } P37_FANOUT_PROBE;\n"
    t0 = time.time()
    verdicts = collections.Counter()
    try:
        path.write_text(text, errors="surrogateescape")
        def one(r):
            base = oracle.baseline_bytes(r["obj"])
            data, dt, err = oracle.compile_obj(r, None, tag="fo" + hashlib.sha1(r["obj"].encode()).hexdigest()[:6])
            if data is None:
                return "COMPILE-ERROR", dt
            return ("IDENTICAL" if data == base else "DIFFERS"), dt
        from concurrent.futures import ThreadPoolExecutor
        cpu = 0.0
        with ThreadPoolExecutor(max_workers=a.jobs) as ex:
            for v, dt in ex.map(one, recs):
                verdicts[v] += 1
                cpu += dt
    finally:
        dl.restore_file(path, raw, st)
    wall = time.time() - t0
    print(f"restruct --fanout-cost: {hdr} reaches {len(tus)} TUs / {len(recs)} objects; one harmless typedef added: {dict(verdicts)}; "
          f"wall {wall:.0f} s at -j{a.jobs} (cpu {cpu:.0f} s, {cpu / max(1, len(recs)):.3f} s/object)")

# ----------------------------------------------------------------------------------------------------------------------
# --selftest: the fixture (a stub oracle) + negative controls; --real adds the calibration and the known-true controls
# ----------------------------------------------------------------------------------------------------------------------
VISIBLE_OVERRIDE = None       # the selftest sets True: every canonical type is visible (no recipes/includers are consulted)
DEFS_OVERRIDE = None          # the selftest sets {callee: [(def_tu, ret, params, kr)]} for defs_visible()

FIXTURE_TYPES = '''#ifndef BFM_ENGINE_TYPES_H
#define BFM_ENGINE_TYPES_H
typedef struct {
    /* 0x0000 */ s16 unk0;
    /* 0x0002 */ u8 pad2[0x2];
    /* 0x0004 */ s32 unk4;
    /* 0x0008 */ u16 unk8;
    /* 0x000a */ u8 padA[0x2];
    /* 0x000c */ s16 *unkC;
} Unkstruct_TEST; /* size = 0x10 */
typedef struct { s16 a; s16 b; s32 c; } Blk8_TEST;
typedef struct { s16 x; s16 y; s32 z; } Twin_TEST;
#endif
'''

FIXTURE_TU = '''#include "common.h"
#include "../shared/engine_types.h"
extern s32 D_80078E00;
extern Unkstruct_TEST D_80078E20;
extern s32 D_80078E40;
extern s16 D_801F8870;
extern s16 D_801F8872;
extern s16 D_801F8874;
extern void fx_callee(s16 a0, s32 a1);
extern s32 fx_kr();
extern u16 aD_80078E10 __asm__("D_80078E10");
extern s32 D_80078E30;
extern u16 aD_80078E30 __asm__("D_80078E30");
typedef struct { s16 a; s16 b; s32 c; } Loc8;
typedef struct { s16 q; s16 r; s32 s; } Loc8b;

void fx_a(s32 a0, Unkstruct_TEST *a1) {
    s32 p;
    Loc8 lb;
    Loc8b lc;
    p = a0 + 4;
    *(s16 *)(a0 + 0x0) = 1;
    *(u16 *)(a0 + 0x0) = 2;
    if (*(u16 *)(a0 + 0x0)) {
        p = 0;
    }
    *(s32 *)(a0 + 0x4) = *(s32 *)(a1 + 0x4);
    *(u8 *)(a0 + 0x4) = 3;
    *(s16 *)(a0 + 0x6) = 4;
    ((s16 *)a0)[p] = 5;
    *(s16 *)(a0 - 2) = 6;
    *(s32 *)(&D_80078E20 + 4) = 7;
    *(s16 *)(D_80078E40 + 0) = 8;
    M2C_FIELD(a0, u16 *, 8) = 9;
    *(s16 **)(a0 + 0xC) = 0;
    *(u8 **)(a0 + 0xC) = 0;
    lb.a = 1; lc.q = lb.b;
    fx_callee(1, 2);
    fx_kr(3, 4);
    D_801F8872 = D_801F8870 + D_801F8874;
    aD_80078E10 = aD_80078E10 + 1;
    p = __builtin_abs(p) + aD_80078E30;
}

void fx_b(s32 a0) {
    ((Unkstruct_TEST *)a0)->unk4 = 1;
}
'''

HF_FIX_H = '''typedef struct { s32 h0; s32 h4; u32 h8; s32 hC; } HdrT;
'''

HF_FIX_SIB = '''#define HS(v) { hp->hC = (v); }
void hf_s(HdrT *hp) {
    hp->h8 = 5;
    HS(6);
}
'''

HF_FIX_TU = '''#include "common.h"
#include "hf.h"
typedef struct { s32 f4; } Oth;
typedef struct { s32 w0; s32 w4; s32 w8; s32 wC; } Fr_TEST;
extern HdrT D_80078E50;
extern Oth D_80078E60;

void hf_a(s32 a0) {
    typedef struct EntT { s16 f0; s16 f2; s32 f4; u16 f8; u16 fA; struct EntT *fC; } Ent;
    Ent *e;
    Ent v, arr[2];
    struct EntT *q;
    Oth o;
    e = (Ent *)a0;
    e->f0 = 1;
    v.f4 = e->f8;
    arr[1].f8 = ((Ent *)a0)->f4;
    q = e->fC->fC;
    q->f4 = 0;
    o.f4 = 2;
    D_80078E60.f4 = 3;
    D_80078E50.h4 = 4;
}

void hf_b(s32 a0) {
    typedef struct { s16 g0; s16 g2; s32 g4; s32 g8; s32 gC; } Bad;
    Bad *b = (Bad *)a0;
    b->g2 = 1;
}
'''

FIXTURE_TU_S2 = '''#include "common.h"
#include "../shared/engine_types.h"
extern s32 D_80078E00;

void fx_c(s32 a0) {
    *(s16 *)(a0 + 0x0) = 1;
    if (*(u16 *)(a0 + 0x0)) {
        a0 = 0;
    }
    *(s32 *)(a0 + 0x4) = 7;
    *(s16 *)(a0 + 0x5) = 2;
    *(s16 *)(a0 + 0x6) = 5;
    *(s16 *)((u8 *)&D_80078E00 + 0x2) = 4;
    *(u8 *)(a0 + 0x8) = 3;
    *(s16 *)(a0 - 2) = 6;
}
'''

FIXTURE_BASES = {"param:a0":dict(type="Unkstruct_TEST", sites=12), "param:a1": dict(type="Unkstruct_TEST", sites=1),
                 "gaddr:D_80078E20": dict(type="Unkstruct_TEST", sites=1), "global:D_80078E40": dict(type="Unkstruct_TEST", sites=1)}

# T3.c4: the real cases — func_8017DD0C (ov_SC02_026) re-judged after its respell: the outer macro's base is the inner macro (census
# `other:None`), its t3_S1 row keyed `nested:*(s32 **)(a0 + 0x20)`, the latest row NO-SITE; func_8017F714 (ov_SC01_077) an alias-named def
FIXTURE_TU_S3 = '''#include "common.h"
#include "../shared/engine_types.h"

void fx_e(s32 a0) {
    s32 saved;
    saved = CAST_WIDTH(s32, CAST_SIGN(s32 *, a0, 0x20), 8);
}

void func_8FF00000_impl(s32 param_1) __asm__("func_8FF00000");

void func_8FF00000_impl(s32 param_1) {
    *(s32 *)(param_1 + 0x10) = 1;
}
'''

# T5.c2: the I/M ladder — `&D_x` scalar sites (one R2 can draw, one of another width) and a param I site the sweep never touches
FIXTURE_TU_IM = '''#include "common.h"

extern s32 D_80078F00;
extern s16 D_80078F10;

void fx_im(s32 a0) {
    *(s32 *)&D_80078F00 = 1;
    *(s32 *)&D_80078F10 = 2;
    *(u16 *)a0 = 3;
}

void fx_par(s32 a0) {
    *(u16 *)a0 = 5;
}
'''


def _install_fixture(dirp):
    """The fixture tree under .run/P37/restruct/selftest/ (R12) with the canonical header and the TU; the module's caches pointed at it."""
    global _canon, _map_cache, VISIBLE_OVERRIDE
    dirp.mkdir(parents=True, exist_ok=True)
    (dirp / "shared").mkdir(exist_ok=True)
    (dirp / "ov").mkdir(exist_ok=True)
    hdr = dirp / "shared" / "engine_types.h"
    hdr.write_text(FIXTURE_TYPES)
    tu = dirp / "ov" / "fx.c"
    tu.write_text(FIXTURE_TU)
    hrel = hdr.relative_to(REPO).as_posix()
    w = tc.walk_file(FIXTURE_TYPES, hrel)
    defs = {}
    for d in w["definitions"]:
        d["file"] = hrel
        for n in d["names"] + ([d["tag"]] if d["tag"] else []):
            defs.setdefault(n, d)
    res = sl.Resolver(dict(defs))
    _canon = {}
    for d in w["definitions"]:
        fm = sl.field_map(res, d)
        for n in d["names"]:
            _canon[n] = (d, res, fm)
    _map_cache = {"Unkstruct_TEST": dict(name="Unkstruct_TEST", sites=100, bodies=3, size_hint=0x10, layout=[[0, 2, "s", 5], [4, 4, "s", 3], [8, 2, "u", 1], [12, 4, "p", 1]])}
    VISIBLE_OVERRIDE = True
    return tu.relative_to(REPO).as_posix(), hrel


MACRO_PROBE_A = '''#include "common.h"
extern s32 D_80078E00; extern u32 D_80078E04; extern s32 D_80078E08;
s32 probe_a(void) { s16 a = LOH(D_80078E00); u16 b = LOHU(D_80078E04); s16 c = HIH(D_80078E08); u8 d = LOBU(D_80078E00); u16 e = HIHU(D_80078E04);
  s32 f = LOW(D_80078E04); u32 g = LOWU(D_80078E00); return a + b + c + d + e + f + g; }
'''
MACRO_PROBE_B = '''#include "common.h"
extern s32 D_80078E00; extern u32 D_80078E04; extern s32 D_80078E08;
s32 probe_a(void) { s16 a = (*(s16 *)&(D_80078E00)); u16 b = (*(u16 *)&(D_80078E04)); s16 c = (((s16 *)&(D_80078E08))[1]); u8 d = (*(u8 *)&(D_80078E00)); u16 e = (((u16 *)&(D_80078E04))[1]);
  s32 f = (*(s32 *)&(D_80078E04)); u32 g = (*(u32 *)&(D_80078E00)); return a + b + c + d + e + f + g; }
'''


def macro_probe():
    """The reinterpret macros of include/common.h (LOBU/LOH/HIH/LOHU/HIHU/LOW/LOWU) produce cc1 assembly IDENTICAL to the bare casts they
    spell — the proof the campaign rests on when it writes one (R110: the compiler's own output, not a belief). Returns True/False."""
    import cdecl
    d = RUN / "macro_probe"
    d.mkdir(parents=True, exist_ok=True)
    outs = []
    for name, text in (("a", MACRO_PROBE_A), ("b", MACRO_PROBE_B)):
        c = d / f"{name}.c"
        c.write_text(text)
        cpp = subprocess.run(cdecl.CPP + ["-Iinclude", str(c)], capture_output=True, text=True, cwd=REPO)
        if cpp.returncode:
            return False
        r = subprocess.run([cdecl.CC1] + cdecl.CC1FLAGS + ["-o", "-"], input=cpp.stdout, capture_output=True, text=True, cwd=REPO)
        if r.returncode:
            return False
        outs.append("\n".join(ln for ln in r.stdout.splitlines() if not ln.strip().startswith((".file", "#"))))
    return bool(outs[0]) and outs[0] == outs[1] and outs[0].count("lh") >= 2


def selftest(real=False):
    global JUDGE_STUB, DEFS_OVERRIDE, _canon, _map_cache, VISIBLE_OVERRIDE, HF_INCLUDERS_OVERRIDE, S_PRIOR
    checks = []
    S_PRIOR = {}                                                   # T3.c4: no live ledger in the fixture runs

    def ok(name, cond, note=""):
        checks.append((name, bool(cond), note))
    dirp = RUN / "selftest"
    tu, hrel = _install_fixture(dirp)
    text = (REPO / tu).read_text()
    masked, defs, span_of_line, params_of, sites = file_view(tu, text)
    d = next(x for x in defs if x["name"] == "fx_a")
    bsites = [s for s in sites if s.get("fn") == "fx_a"]
    ok("fixture parsed: 14 raw sites on fx_a", sum(1 for s in bsites if s["form"] in RAW_FORMS) == 14, str(collections.Counter(s["form"] for s in bsites)))
    # ---- rung S edits per base
    per = s_body_edits(tu, "fx_a", text, masked, d, bsites, FIXTURE_BASES, False, {})
    by = {bk: (stt, es, sk) for (bk, tn, stt, es, sk) in per}
    stt, es, sk = by["param:a0"]
    reps = [e[2] for e in es]
    ok("a0: 5 members", len(es) == 5, str(reps))
    ok("a0 store sign u->s allowed", "((Unkstruct_TEST *)a0)->unk0" in reps and reps.count("((Unkstruct_TEST *)a0)->unk0") == 2)
    ok("a0 M2C_FIELD -> unk8", "((Unkstruct_TEST *)a0)->unk8" in reps)
    ok("a0 pointer field pointee s16* -> unkC", "((Unkstruct_TEST *)a0)->unkC" in reps)
    ok("a0 skips: sign/width/no-field/index/negative/pointee each once", dict(sk) == {"sign": 1, "width": 1, "no-field": 1, "index": 1, "negative-offset": 1, "pointee": 1}, str(dict(sk)))
    stt1, es1, _ = by["param:a1"]
    ok("a1 typed parameter -> a1->unk4", [e[2] for e in es1] == ["a1->unk4"], str([e[2] for e in es1]))
    stt2, es2, _ = by["gaddr:D_80078E20"]
    ok("typed global address -> D_80078E20.unk4", [e[2] for e in es2] == ["D_80078E20.unk4"], str([e[2] for e in es2]))
    stt3, es3, _ = by["global:D_80078E40"]
    ok("pointer global (s32) -> cast form", [e[2] for e in es3] == ["((Unkstruct_TEST *)D_80078E40)->unk0"], str([e[2] for e in es3]))
    all_edits = [e for (_, _, _, es_, _) in per for e in es_]
    cand = compose_text(text, all_edits)
    ok("compose keeps the untouched sites", "*(u8 *)(a0 + 0x4) = 3;" in cand and "((s16 *)a0)[p] = 5;" in cand and "a1->unk4" in cand)
    # the no-op: fx_b already spelled with a member -> 0 edits
    db = next(x for x in defs if x["name"] == "fx_b")
    perb = s_body_edits(tu, "fx_b", text, masked, db, [s for s in sites if s.get("fn") == "fx_b"], {"param:a0": dict(type="Unkstruct_TEST", sites=1)}, False, {})
    ok("known-true no-op: a member-spelled body yields 0 edits", sum(len(es_) for (_, _, _, es_, _) in perb) == 0)
    # negative controls on the type builder
    ents, skipped = sl.entries_from_layout([(0, 4, "s", 5), (2, 2, "u", 1), (5, 2, "u", 3), (12, None, None, 1)])
    ok("layout: overlap/misaligned/width skipped", sorted(s_[3] for s_ in skipped) == ["misaligned", "overlap", "width"])
    # a wrong-offset field map must not convert the +0x4 site (the site says width 4 at +4; a map with s16 at +4 -> width skip)
    wrong = {4: dict(name="unk4", width=2, sign="s", type="s16", stars=0, dims=[])}
    e_w, sk_w = s_edits(text, masked, d, bsites, "Unkstruct_TEST", wrong, "param:a0", "s32 a0, Unkstruct_TEST *a1")
    ok("negative: a field of the wrong width converts nothing at that offset", not any(e[3].get("off") == 4 for e in e_w) and sk_w["width"] >= 1)
    # ---- S2 greedy with a stub: DIFFERS iff the +0x8 (M form) edit is in the candidate
    target = next(e for e in es if e[3]["form"] == "M")
    def stub_s2(files, tag):
        t = files[tu]
        return ("DIFFERS", "") if "((Unkstruct_TEST *)a0)->unk8" in t else ("IDENTICAL", "")
    JUDGE_STUB = stub_s2
    kept, n_c, gv = greedy_kept(lambda sub, tag: judge_files({tu: compose_text(text, sub)}, tag)["verdict"], es, "t")
    ok("S2 leave-one-out finds the one kept cast", gv == "IDENTICAL" and len(kept) == 1 and kept[0] is target and n_c <= len(es), f"{gv} kept={len(kept)} compiles={n_c}")
    # cumulative path: DIFFERS iff BOTH unk0 stores are members
    def stub_s2b(files, tag):
        return ("DIFFERS", "") if files[tu].count("((Unkstruct_TEST *)a0)->unk0") == 2 else ("IDENTICAL", "")
    JUDGE_STUB = stub_s2b
    kept2, n_c2, gv2 = greedy_kept(lambda sub, tag: judge_files({tu: compose_text(text, sub)}, tag)["verdict"], es, "t")
    ok("S2 keeps exactly one of two conflicting sites", gv2 == "IDENTICAL" and len(kept2) == 1 and kept2[0][3]["off"] == 0, f"kept={[k[3]['off'] for k in kept2]}")
    # ---- work_file_S with the stub: MEMBERS on fx_a (stub IDENTICAL), the ledger row shape, no write under the stub
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "")
    logs = []
    r = work_file_S(tu, {"fx_a": FIXTURE_BASES}, "st", dict(head="x"), logs.append, allow_local=False, want_sa=False)
    ok("work_file_S: MEMBERS, 8 members, final IDENTICAL", r["final"] == "IDENTICAL" and r["members"] == 8 and r["rows"][0]["verdict"] == "MEMBERS", f"{r['final']} {r['members']} {r['rows'][0]['verdict']}")
    ok("work_file_S: every site row has a verdict and the skips are counted", all(s_["verdict"] for s_ in r["rows"][0]["sites"]) and r["rows"][0]["skips"]["no-field"] == 1)
    ok("work_file_S: the stub never writes the tree", (REPO / tu).read_text() == text)
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "") if tag.endswith("F") else ("DIFFERS", "")   # was: always DIFFERS (P39 T3: the respelled-only final text is judged)
    r2 = work_file_S(tu, {"fx_a": FIXTURE_BASES}, "st", dict(head="x"), logs.append, allow_local=False, want_sa=False)
    ok("work_file_S: an all-DIFFERS body is KEPT-ALL with S2 NO-SET named", r2["rows"][0]["verdict"] == "KEPT-ALL" and "NO-SET" in r2["rows"][0].get("err", ""), r2["rows"][0].get("err", "")[:60])
    # ---- pass hints
    ok("hint SCHED-ALIAS", pass_hint(dict(kind="ORDER", pairs=[(3, "8c620000 lw", "a4620034 sh"), (4, "a4620034 sh", "8c620000 lw")])) == "SCHED-ALIAS")
    ok("hint CSE-KILL", pass_hint(dict(kind="COUNT", pairs=[(3, "3c020000 lui", "--")])) == "CSE-KILL")
    ok("hint WIDTH", pass_hint(dict(kind="MIXED", pairs=[(3, "3042ffff andi", "00021400 sll")])) == "WIDTH")
    ok("hint REGALLOC", pass_hint(dict(kind="REG", pairs=[(3, "00431021 addu", "00431821 addu")])) == "REGALLOC")
    ok("hint: a register-pair row (int count) is skipped, not split (T3.c3)", pass_hint(dict(kind="REG", pairs=[("v0", "v1", 2)])) == "REGALLOC")
    ov_k, ov_d = drop_overlaps([(20, 30, "b", {}), (10, 40, "a", {}), (10, 15, "c", {}), (40, 45, "d", {})])
    ok("drop_overlaps: the earlier/longer edit stays, the nested ones drop (T3.c3)", [e[2] for e in ov_k] == ["a", "d"] and sorted(e[2] for e in ov_d) == ["b", "c"],
       f"{[e[2] for e in ov_k]} {[e[2] for e in ov_d]}")
    # ---- P39 T3: the per-site class order, the macro respell, the census backing, the --only glob
    ok("class order: misaligned beats sign / width / kept / untyped", site_class(dict(width=2, off=5), "sign", True, False) == "MISALIGNED"
       and site_class(dict(width=2, off=4), "sign", True) == "SIGN" and site_class(dict(width=4, off=4), "width", True) == "WIDTH"
       and site_class(dict(width=4, off=4), "overlap-edit", True) == "WIDTH" and site_class(dict(width=4, off=4), None, True, False) == "SCHED-ALIAS"
       and site_class(dict(width=4, off=4), None, False, False) == "NON-STRUCT" and site_class(dict(width=4, off=4, index="i"), None, False, False) == "INDEX"
       and site_class(dict(width=4, off=4), "no-field") == "NO-FIELD" and site_class(dict(width=4, off=4), "pointee") == "POINTEE")
    fx2 = dirp / "ov" / "fx2.c"
    fx2.write_text(FIXTURE_TU_S2)
    tu2 = fx2.relative_to(REPO).as_posix()
    JUDGE_STUB = lambda files, tag: ("DIFFERS", "") if "->unk4" in files[tu2] else ("IDENTICAL", "")
    r3 = work_file_S(tu2, {"fx_c": {"param:a0": dict(type="Unkstruct_TEST", sites=7)}}, "st", dict(head="x"), logs.append, allow_local=False, want_sa=False)
    row3 = r3["rows"][0] if r3["rows"] else {}
    cls3 = {(s_["off"], s_["access"], s_["base"]): s_["verdict"] for s_ in row3.get("sites", [])}
    ok("site classes: S2 body, one class per raw site", row3.get("verdict") == "S2" and cls3 == {
        (0, "store", "param:a0"): "MEMBER", (0, "load", "param:a0"): "KEPT(SIGN)", (4, "store", "param:a0"): "KEPT(SCHED-ALIAS)",
        (5, "store", "param:a0"): "KEPT(MISALIGNED)", (6, "store", "param:a0"): "RESIDUAL(NO-FIELD)", (2, "store", "gaddr:D_80078E00"): "KEPT(NON-STRUCT)",
        (8, "store", "param:a0"): "KEPT(WIDTH)", (-2, "store", "param:a0"): "RESIDUAL(NEGATIVE-OFFSET)"}, f"{row3.get('verdict')} {sorted(cls3.items())}")
    ok("site cause on every site", all(s_.get("cause") for s_ in row3.get("sites", [])))
    ft3 = r3.get("final_text", "")
    want3 = ["((Unkstruct_TEST *)a0)->unk0 = 1;", "if (CAST_SIGN(u16, a0, 0x0))", "CAST_ALIAS(s32, a0, 0x4) = 7;", "CAST_MISALIGNED(s16, a0, 0x5) = 2;",
             "*(s16 *)(a0 + 0x6) = 5;", "CAST_NONSTRUCT(s16, (u8 *)&D_80078E00, 0x2) = 4;", "CAST_WIDTH(u8, a0, 0x8) = 3;", "*(s16 *)(a0 - 2) = 6;"]
    ok("respell: KEPT P-forms become their macros, residuals stay raw, final IDENTICAL", r3["final"] == "IDENTICAL" and all(w_ in ft3 for w_ in want3)
       and r3["respelled"] == 5, f"{r3['final']} {r3['respelled']} missing={[w_ for w_ in want3 if w_ not in ft3]}")
    mk3 = [s_ for s_ in file_view(tu2, ft3)[4] if s_["form"] == "K"] if ft3 else []
    rc3, line3 = tc.check_casts_verdict({}, mk3, {("S", tu2, "fx_c"): row3}, [], set())
    ok("respell: type_census backs every respelled macro (unbacked 0)", len(mk3) == 5 and "(unbacked 0)" in line3, line3)
    rc4, line4 = tc.check_casts_verdict({}, mk3, {("S", tu2, "fx_c"): dict(row3, verdict="NO-SITE")}, [], set())
    ok("negative: a row verdict outside the backed set backs nothing", "(unbacked 5)" in line4, line4)
    # ---- T3.c4: macro sites in the census's key; a re-judged body carries its earlier KEPT rows; alias-named defs see their params
    fx3 = dirp / "ov" / "fx3.c"
    fx3.write_text(FIXTURE_TU_S3)
    tu3 = fx3.relative_to(REPO).as_posix()
    v3 = file_view(tu3, FIXTURE_TU_S3)[4]
    ok("alias-named def: param_1 is a param base (census rule; was local:param_1)", [s_["bclass"] for s_ in v3 if s_.get("fn") == "func_8FF00000" and s_["form"] == "P"] == ["param"],
       str([(s_.get("fn"), s_["form"], s_["bclass"]) for s_ in v3]))
    mk5 = [s_ for s_ in v3 if s_["form"] == "K"]
    prior5 = dict(rung="S", tu=tu3, unit="fx_e", label="t3_S1", verdict="KEPT", sites=[
        dict(base="nested:*(s32 **)(a0 + 0x20)", off=8, line=mk5[0]["line"], verdict="KEPT(WIDTH)"),
        dict(base="param:a0", off=0x20, line=mk5[0]["line"], verdict="KEPT(SIGN)")])
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "")
    S_PRIOR = {}
    r5n = work_file_S(tu3, {"fx_e": {"param:a0": dict(type="Unkstruct_TEST", sites=1)}}, "st", dict(head="x"), logs.append, want_sa=False)
    line5n = tc.check_casts_verdict({}, mk5, {("S", tu3, "fx_e"): r5n["rows"][0]}, [], set())[1]
    ok("negative: a re-judged macro body with no earlier KEPT row stays unbacked", len(mk5) == 2 and "(unbacked 2)" in line5n, line5n)
    S_PRIOR = {(tu3, "fx_e"): [prior5]}
    r5 = work_file_S(tu3, {"fx_e": {"param:a0": dict(type="Unkstruct_TEST", sites=1)}}, "st", dict(head="x"), logs.append, want_sa=False)
    row5 = r5["rows"][0]
    line5 = tc.check_casts_verdict({}, mk5, {("S", tu3, "fx_e"): row5}, [], set())[1]
    ok("re-judge carries the earlier KEPT rows in the census key: KEPT, unbacked 0", row5["verdict"] == "KEPT" and "(unbacked 0)" in line5
       and {e["macro_of"] for e in row5["sites"] if e.get("macro_of")} == {"t3_S1"}, f"{row5['verdict']} {line5}")
    # T3.c8: func_8017EA20 shape — the earlier KEPT(NON-STRUCT) row keyed the pre-respell nested base on another line
    txt6 = FIXTURE_TU_S3.replace("void func_8FF00000_impl(s32 param_1) __asm__", "void fx_f(s32 a0) {\n    s32 v;\n"
                                 "    v = CAST_NONSTRUCT(u16, *(s32 *)(((Unkstruct_TEST *)a0)->unk4 + 0x20), 0x12);\n}\n\n"
                                 "void func_8FF00000_impl(s32 param_1) __asm__", 1)
    mk6 = [s_ for s_ in file_view(tu3, txt6)[4] if s_["form"] == "K" and s_.get("fn") == "fx_f"]
    S_PRIOR = {(tu3, "fx_f"): [dict(rung="S", tu=tu3, unit="fx_f", label="t3_S13", verdict="KEPT", sites=[
        dict(base="nested:*(s32 *)(*(s32 *)(a0 + 0x4) + 0x20)", off=0x12, line=999, verdict="KEPT(NON-STRUCT)")])]}
    row6 = dict(fn="fx_f", verdict="MEMBERS", sites=[], bases=[])
    s_macro_rows(tu3, txt6, [row6])
    line6 = tc.check_casts_verdict({}, mk6, {("S", tu3, "fx_f"): row6}, [], set())[1]
    ok("carry: a nested base respelled under a kept macro still matches its earlier KEPT row (unbacked 0)", len(mk6) == 1
       and "(unbacked 0)" in line6 and [e.get("macro_of") for e in row6["sites"]] == ["t3_S13"], f"{[(s_['bclass'], s_['base']) for s_ in mk6]} {line6}")
    S_PRIOR = {}
    ok("respell_edit: a lower-precedence p or a non-literal k stays raw", respell_edit("*(s32 *)(a << 2 + 4)", "*(s32 *)(a << 2 + 4)",
       dict(form="P", pos=0, end=20, base=None, off=4), "SIGN") is None and respell_edit("*(s32 *)(a + i)", "*(s32 *)(a + i)", dict(form="P", pos=0, end=15, base="a", off=0), "SIGN") is None)
    ok("--only glob: ov_* matches the src dir, not main", matches_only(["ov_*"], "src/ov_SC05_010/x.c", "f") and not matches_only(["ov_*"], "src/main/x.c", "f")
       and matches_only(["src/ov_SC05_010/x.c"], "src/ov_SC05_010/x.c", "f")
       and matches_only(["src/a/x.c:func_1"], "src/a/x.c", "func_1") and not matches_only(["src/a/x.c:func_1"], "src/b/y.c", "func_1"))
    ok("--only main: top-level src/*.c and src/resident/, not md_/ov_", matches_only(["main"], "src/800.c", "f") and matches_only(["main"], "src/resident/x.c", "f")
       and not matches_only(["main"], "src/md_A/x.c", "f") and not matches_only(["main"], "src/ov_A/x.c", "f")
       and not matches_only(["main"], "src/shared/main/x.h", "f"))
    # ---- rung D on the fixture
    DEFS_OVERRIDE = {"fx_callee": [("src/ov/fx_defs.c", "void", "s32 a0, s32 a1", False)], "fx_kr": [("src/ov/fx_defs.c", "s32", "s32 a, s32 b", True)]}
    units = d_units(tu, text)
    byc = {u["callee"]: u for u in units}
    ok("D units: the two lying callees found", set(byc) == {"fx_callee", "fx_kr"}, str(sorted(byc)))
    ok("D: fx_callee's narrow decl vs the definition's s32", byc["fx_callee"]["ansi"] == "s32 a0, s32 a1" and byc["fx_callee"]["promoted"] == "s32 a0, s32 a1")
    ok("promoted_params widens narrow ints", promoted_params("s16 a0, u8 b, void *c, s32 d") == "s32 a0, s32 b, void *c, s32 d")
    ok("--callee caller-only unit: _sig_key drops parameter names (a definition already spelled so is left as is)",
       _sig_key("s32", "s32, s32, s32, s16 *, int") == _sig_key("s32", "s32 a0, s32 a1, s32 a2, s16 *a3, int a4")
       and _sig_key("void", "") == _sig_key("void", "void") and _sig_key("void", "s32 a0") != _sig_key("s32", "s32 a0")
       and _sig_key("void", "s32 *a0") != _sig_key("void", "s32 a0"))
    ed = d_edits(byc["fx_kr"], byc["fx_kr"]["ansi"])
    ok("d_edits rewrites the `()` declaration", ed[0][2] == "extern s32 fx_kr(s32 a, s32 b);", ed[0][2])
    counts = call_arg_counts(masked, "fx_kr", [(s_, e_) for (s_, e_, *_) in byc["fx_kr"]["decls"]])
    ok("call_arg_counts reads the call's arity", counts == [2], str(counts))
    marks = kr_marker_edits(text, byc["fx_kr"], counts, "st")
    ok("K&R marker text", marks and "// K&R: 2 of 2 args (P37 rung D st)" in marks[0][2], marks[0][2] if marks else "")
    _asm_t = 'extern s32 aF1(void *) __asm__("func_1");\nextern s32 aF1();\n'
    ok("decl_sites skips an asm-label declaration (its rewrite would drop the label)",
       [d_[2] for d_ in decl_sites(dl.same_len_mask(_asm_t), "aF1")] == [2])
    # the alias and builtin units
    eu = e_units(tu, text, masked)
    bye = {u["callee"]: u for u in eu}
    ok("E units: two aliases found", set(bye) == {"aD_80078E10", "aD_80078E30"}, str(sorted(bye)))
    ok("E: an alias with no plain declaration becomes `extern u16 D_80078E10;` + 2 renamed uses",
       any(e[2] == "extern u16 D_80078E10;" for e in bye["aD_80078E10"]["edits"]) and bye["aD_80078E10"]["uses"] == 2, str(bye["aD_80078E10"]["edits"][:3]))
    ok("E: an alias whose symbol the TU declares with ANOTHER type carries the conflict", bye["aD_80078E30"]["conflict"] == ["s32"], str(bye["aD_80078E30"]["conflict"]))
    bu = b_units(tu, text, masked)
    ok("B unit: one __builtin_abs -> abs", len(bu) == 1 and bu[0]["n"] == 1 and bu[0]["edits"][0][2] == "abs")
    # the D ladder under stubs: all-at-once IDENTICAL -> both DECL-CANON (+ the alias and builtin units)
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "")
    rD = work_file_D(tu, "st", dict(head="x"), logs.append)
    ok("work_file_D: both units DECL-CANON on an IDENTICAL stub", rD["canon"] == 2 and rD["final"] == "IDENTICAL", f"{rD['canon']} {rD['final']}")
    ok("work_file_D: the aliases typed and the builtin respelled ride along", rD["alias"] == 2 and rD["builtin"] == 1 and "abs(p)" in rD["final_text"] and "D_80078E10 = D_80078E10 + 1;" in rD["final_text"], f"{rD['alias']} {rD['builtin']}")
    def stub_e(files, tag):
        return ("COMPILE-ERROR", "fx.c:9: conflicting types for `D_80078E30'") if "extern u16 D_80078E30;" in files[tu] else ("IDENTICAL", "")
    JUDGE_STUB = stub_e
    rE = work_file_D(tu, "st", dict(head="x"), logs.append)
    ve = {row["callee"]: (row["verdict"], row.get("cause", "")) for row in rE["rows"] if row.get("kind") == "alias"}
    ok("work_file_D: the conflicting alias is ALIAS-KEPT with the second-typed-view cause, the other typed", ve["aD_80078E30"][0] == "ALIAS-KEPT" and "second typed view" in ve["aD_80078E30"][1] and ve["aD_80078E10"][0] == "ALIAS-TYPED", str(ve))
    # ANSI DIFFERS for fx_callee only -> promoted (equal here) is skipped -> DECL-KEPT(width); fx_kr's ANSI arity error -> K&R marked
    def stub_d(files, tag):
        t = files[tu]
        if "extern void fx_callee(s32 a0, s32 a1);" in t:
            return ("DIFFERS", "")
        if "extern s32 fx_kr(s32 a, s32 b);" in t:
            return ("COMPILE-ERROR", "fx.c:35: too few arguments to function `fx_kr'")
        return ("IDENTICAL", "")
    JUDGE_STUB = stub_d
    rD2 = work_file_D(tu, "st", dict(head="x"), logs.append)
    vs = {row["callee"]: (row["verdict"], row.get("cause", "")) for row in rD2["rows"]}
    ok("work_file_D: DIFFERS -> DECL-KEPT(width/bytes)", vs["fx_callee"][0] == "DECL-KEPT" and vs["fx_callee"][1].startswith(("width", "bytes")), str(vs["fx_callee"]))
    ok("work_file_D: arity error on `()` -> K&R site marked", vs["fx_kr"][0] == "DECL-KEPT" and vs["fx_kr"][1].startswith("K&R site") and rD2["kr"] == 1, str(vs["fx_kr"]))
    ok("work_file_D: the K&R marker lands in the final text", rD2.get("final_text", "") .count("// K&R: 2 of 2 args") == 1)
    # ---- rung L on the fixture: Loc8 folds onto Blk8_TEST with renames a->a? (same names: alias only); Loc8b (q/r/s) -> renames; ambiguity
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "")
    lu = l_units(tu, text)
    byd = {u["defn"]: u for u in lu}
    ok("L units: both local definitions have a canonical layout twin", set(byd) >= {"Loc8", "Loc8b"}, str(sorted(byd)))
    ok("L: Loc8 (same member names) is a plain alias", byd["Loc8"]["kind"] == "alias" and byd["Loc8"]["canon"] in ("Blk8_TEST", "Twin_TEST"), str(byd["Loc8"]))
    ok("L: Loc8b needs renames and is REFUSED as ambiguous or renamed", byd["Loc8b"]["kind"] == "alias+rename", str(byd["Loc8b"])[:120])
    rL = work_file_L(tu, "st", dict(head="x"), logs.append)
    ok("work_file_L: folds land under an IDENTICAL stub", rL["folded"] >= 1 and rL["final"] == "IDENTICAL", f"{rL['folded']} {rL['refused']} {rL['final']}")
    if rL.get("final_text"):
        ok("work_file_L: the alias replaces the definition", "typedef Blk8_TEST Loc8;" in rL["final_text"] or "typedef Twin_TEST Loc8;" in rL["final_text"])
    # ---- rung L HEAD-FOLD (P38 T4): block-scope fold with type-aware renames, a header unit reaching its includer, a refusal, an exclusion
    (dirp / "ov" / "hf.h").write_text(HF_FIX_H)
    (dirp / "ov" / "hf.c").write_text(HF_FIX_TU)
    (dirp / "ov" / "hf_sib.h").write_text(HF_FIX_SIB)
    hf_h, hf_c = (dirp / "ov" / "hf.h").relative_to(REPO).as_posix(), (dirp / "ov" / "hf.c").relative_to(REPO).as_posix()
    hf_s = (dirp / "ov" / "hf_sib.h").relative_to(REPO).as_posix()
    HF_INCLUDERS_OVERRIDE = {hf_h: [hf_c], hf_s: [hf_c]}
    ok("head_split: a canonical name is a head, an alias filters", head_split(["Unkstruct_TEST", "ov_SC01_000"]) == (["Unkstruct_TEST"], ["ov_SC01_000"]))
    hf_text = HF_FIX_TU
    cands = hf_cands(hf_c, tc.walk_file(hf_text, hf_c)["definitions"], head_info(["Unkstruct_TEST"]))
    cby = {(hf_names(d_) or ["?"])[0]: ex for (d_, _, _, ex) in cands}
    ok("HF candidates: same size other layout (Ent, Bad, Fr_TEST); Oth (0x4) not", set(cby) == {"Ent", "Bad", "Fr_TEST"}, str(cby))
    ok("HF exclusion: Fr_* carries its cause and makes no unit", cby.get("Fr_TEST") == "stack frame" and all(u_["defn"] != "Fr_TEST" for u_ in hf_units(hf_c, hf_text, ["Unkstruct_TEST"])))
    hu = {u_["defn"]: u_ for u_ in hf_units(hf_c, hf_text, ["Unkstruct_TEST"])}
    ok("HF refusal: a referenced field with no canonical field at its offset", (hu["Bad"]["refused"] or "").startswith("no canonical field at 0x2 for local `g2`"), str(hu["Bad"]["refused"]))
    ok("HF block unit: 8 member renames, key by function", hu["Ent"]["refused"] is None and hu["Ent"]["renames"] == 8 and hu["Ent"]["key"] == "fold:Ent@hf_a", f"{hu['Ent']['renames']} {hu['Ent'].get('key')}")
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "")
    rH = work_file_HF(hf_c, "st", dict(head="x"), logs.append, heads=["Unkstruct_TEST"])
    ft = rH.get("final_text", "")
    ok("work_file_HF: Ent FOLDED, Bad FOLD-REFUSED", rH["folded"] == 1 and rH["refused"] == 1 and rH["final"] == "IDENTICAL", f"{rH['folded']} {rH['refused']} {rH['final']}")
    ok("HF text: the definition becomes the typedef, struct Tag uses the name",
       "typedef Unkstruct_TEST Ent;" in ft and "Ent *q;" in ft and "struct EntT" not in ft)
    ok("HF text: renames on every typed base form (ptr var, value, array index, cast, self-typed chain)",
       all(s_ in ft for s_ in ("e->unk0 = 1;", "v.unk4 = e->unk8;", "arr[1].unk8 = ((Ent *)a0)->unk4;", "q = e->unkC->unkC;", "q->unk4 = 0;")),
       ft[ft.find("e->"):][:200])
    ok("HF text: same-named fields of OTHER types untouched (type-aware, not textual)", "o.f4 = 2;" in ft and "D_80078E60.f4 = 3;" in ft and "b->g2 = 1;" in ft)
    ok("HF: the stub never writes the tree", (REPO / hf_c).read_text() == hf_text)
    rHh = work_file_HF(hf_h, "st", dict(head="x"), logs.append, heads=["Unkstruct_TEST"])
    fts = rHh.get("final_texts", {})
    ok("HF header unit: the header folds and its includer's access is renamed in the same unit",
       rHh["folded"] == 1 and "typedef Unkstruct_TEST HdrT;" in fts.get(hf_h, "") and "D_80078E50.unk4 = 4;" in fts.get(hf_c, ""), f"{rHh['folded']} {sorted(fts)}")
    ok("HF header unit: a sibling header in the includers' closure is renamed too (its #define body by the expanding function's type)",
       "hp->unk8 = 5;" in fts.get(hf_s, "") and "hp->unkC = (v);" in fts.get(hf_s, ""), fts.get(hf_s, "")[:120])
    JUDGE_STUB = lambda files, tag: ("DIFFERS", "") if "typedef Unkstruct_TEST Ent;" in files.get(hf_c, "") else ("IDENTICAL", "")
    rHd = work_file_HF(hf_c, "st", dict(head="x"), logs.append, heads=["Unkstruct_TEST"])
    ok("HF: a DIFFERS judgement is FOLD-REFUSED with the verdict as cause", any(r_["verdict"] == "FOLD-REFUSED" and r_["cause"].startswith("DIFFERS") and r_["defn"] == "Ent" for r_ in rHd["rows"]))
    st_rows = [dict(rung="L", tu=hf_c, unit="fold:Ent@hf_a", verdict="FOLDED", head="Unkstruct_TEST", defn="Ent"),
               dict(rung="L", tu=hf_c, unit="fold:Bad@hf_b", verdict="FOLD-REFUSED", cause="no canonical field at 0x2", head="Unkstruct_TEST", defn="Bad")]
    ok("HF settled: FOLDED/FOLD-REFUSED settle; --redraw FOLD-REFUSED lifts", hf_settled(st_rows) == {(hf_c, "fold:Ent@hf_a"), (hf_c, "fold:Bad@hf_b")}
       and hf_settled(st_rows, ["FOLD-REFUSED"]) == {(hf_c, "fold:Ent@hf_a")})
    ok("HF settled units make no unit", [u_["defn"] for u_ in hf_units(hf_c, hf_text, ["Unkstruct_TEST"], hf_settled(st_rows))] == [])
    HF_INCLUDERS_OVERRIDE = None
    # ---- recipes (text transforms)
    site_glob = next(s for s in bsites if s.get("bclass") == "global")
    r1 = recipe_ptr_global_member(text, tu, "fx_a", site_glob)
    ok("R1 respells the pointer global as a struct member", r1 and "(((struct { s32 p; } *)&D_80078E40)->p)" in r1[0][0], (r1[0][0][:0] if r1 else "none"))
    site_g = next(s for s in bsites if s.get("bclass") == "gaddr")
    r2_ = recipe_extern_array(text, tu, "fx_a", site_g)
    ok("R2 refuses a non-scalar extern (D_80078E20 is a struct)", r2_ == [])
    fake = dict(site_g, base="D_80078E00", bclass="gaddr", off=0, width=4, pos=text.index("*(s32 *)(&D_80078E20 + 4)"), end=text.index("*(s32 *)(&D_80078E20 + 4)") + len("*(s32 *)(&D_80078E20 + 4)"))
    r2b = recipe_extern_array(text, tu, "fx_a", fake)
    ok("R2 rewrites the extern to an array and the site to an index", r2b and "extern s32 D_80078E00[];" in r2b[0][0] and "D_80078E00[0]" in r2b[0][0])
    fake3 = dict(site_g, base="D_801F8870", bclass="global", off=0, width=2)
    r3 = recipe_walked_pointer(text, tu, "fx_a", fake3)
    ok("R3 walks the three carved halves through one pointer (reloc flagged)", r3 and "s16 *p37w = &D_801F8870;" in r3[0][0] and "p37w[1] = p37w[0] + p37w[2];" in r3[0][0] and r3[0][2] is True, (r3[0][0][r3[0][0].find("p37w"):][:80] if r3 else "none"))
    # ---- ledger + inflight
    rows = [dict(rung="S", tu=tu, unit="fx_a", verdict="MEMBERS", nhash_after="h1", label="st", bases=[dict(status="CANONICAL")]), dict(rung="S", tu=tu, unit="fx_a", verdict="COMBINATION-FAILED", nhash_after=None, label="st2")]
    done, latest = ledger_index(rows)
    ok("ledger: done keyed per unit+hash, latest verdict wins", ("S", tu, "fx_a", "h1") in done and latest[("S", tu, "fx_a")] == "COMBINATION-FAILED")
    # the in-flight snapshot's parser and restore core, on a SCRATCH path — never the real inflight.json (the first selftest run
    # deleted batch t3d1's live snapshot: an instrument's write path is part of the instrument, R57)
    scratch = dirp / "ov" / "inflight_probe.c"
    scratch.write_text("original\n")
    rel_s = scratch.relative_to(REPO).as_posix()
    probe_inflight = dirp / "inflight.json"
    probe_inflight.write_text(json.dumps(dict(label="selftest-x", files={rel_s: "original\n"})))
    scratch.write_text("candidate\n")
    d_, why = load_inflight(probe_inflight)
    ok("inflight parses", d_ is not None and rel_s in d_["files"], why)
    for f_, t_ in d_["files"].items():
        if (REPO / f_).read_text() != t_:
            (REPO / f_).write_text(t_)
    ok("inflight restore returns the original text", scratch.read_text() == "original\n")
    probe_inflight.write_text("")
    d_, why = load_inflight(probe_inflight)
    ok("an EMPTY inflight is refused loudly", d_ is None and "EMPTY" in why)
    probe_inflight.unlink()
    # T4.c2: parallel writers/readers (4 processes x 4 threads) on a scratch inflight under .run/P38/ — every read parses, no write lost
    import multiprocessing
    par = REPO / ".run/P38/restruct_selftest"
    par.mkdir(parents=True, exist_ok=True)
    par_inf = par / "inflight.json"
    with _inflight_lock(par_inf):
        _inflight_write(dict(label="selftest-par", files={}), par_inf)
    with ProcessPoolExecutor(4, mp_context=multiprocessing.get_context("fork")) as pp:
        futs = [pp.submit(_run_threads, str(par_inf), p) for p in range(4)]
        torn = sum(f_.result() for f_ in futs)
    d_, why = load_inflight(par_inf)
    ok("inflight: 16 parallel writers/readers — no torn read, no lost write", torn == 0 and d_ is not None and len(d_["files"]) == 16 * 25,
       f"torn {torn} files {len(d_['files']) if d_ else why}")
    ok("inflight: no tmp file left behind", not list(par.glob("inflight.json.tmp*")))
    lk1 = _apply_exclusive(par / "apply.lock")
    lk2 = _apply_exclusive(par / "apply.lock")
    ok("apply lock: a second --apply is refused while the first holds it", lk1 is not None and lk2 is None)
    lk1.close()
    # a TOOL-ERROR worker restores its file; its label's unit rows stop counting as settled
    scratch.write_text("unjudged edit\n")
    ok("TOOL-ERROR restores the file's original text", tool_error_restore(rel_s, "original\n") and scratch.read_text() == "original\n")
    te_rows = st_rows[:1] + [dict(rung="L", tu=hf_c, unit="<file>", verdict="TOOL-ERROR", label=None),
                             dict(st_rows[1], label="other")]
    ok("HF settled: a TOOL-ERROR <file> row in the unit's label unsettles it (either order); other labels unaffected",
       hf_settled(te_rows) == {(hf_c, "fold:Bad@hf_b")} and hf_settled([te_rows[1], te_rows[0]]) == set(), f"{hf_settled(te_rows)}")
    sl_led = [dict(rung="D", tu="src/a.c", unit="decl:f1", callee="f1", verdict="DECL-KEPT", cause="conflicting x"),
              dict(rung="D", tu="src/a.c", unit="decl:f2", callee="f2", verdict="DECL-KEPT", cause="conflicting y"),
              dict(rung="D", tu="src/b.c", unit="decl:f1", callee="f1", verdict="DECL-KEPT", cause="other"),
              dict(rung="D", tu="src/c.h", unit="decl:f1", callee="f1", verdict="DECL-KEPT", cause="conflicting z"),
              dict(rung="D", tu="src/d.c", unit="decl:f3", callee="f3", verdict="DECL-KEPT", cause="conflicting w"),
              dict(rung="D", tu="src/d.c", unit="decl:f3", callee="f3", verdict="DECL-CANON")]
    st_ = stale_lifted(sl_led, [dict(tu="src/a.c", callee="f2")], ["DECL-KEPT:conflicting"], False, None)
    sup_ = supersede_rows(st_, "st")
    ok("rung D supersede: only lifted latest rows with no lying declaration left (.c only; cause key; latest row)",
       [(r["tu"], r["unit"]) for r in st_] == [("src/a.c", "decl:f1")] and sup_[0]["verdict"] == "DECL-NONE" and "stale DECL-KEPT" in sup_[0]["cause"]
       and stale_lifted(sl_led, [], ["DECL-KEPT:conflicting"], True, None)[0]["tu"] == "src/c.h", f"{st_}")
    # T3.c2: the pinned base→type fallback, and finished files left out of the plan
    key_ = f"{tu}|fx_a"
    cur_ = {key_: {"param:a0": dict(type="Unkstruct_DRIFT", sites=12), "param:a1": dict(type="Unkstruct_DRIFT2", sites=1)}}
    pin_ = {key_: {"param:a0": dict(type="Unkstruct_TEST", sites=12), "param:a1": dict(type="Unkstruct_GONE", sites=1)}}
    mg_, nfb_ = merge_bbt(cur_, pin_, _canon)
    ok("bbt pin: a drifted non-canonical type falls back to the pinned canonical one; a non-canonical pin is not taken",
       nfb_ == 1 and mg_[key_]["param:a0"]["type"] == "Unkstruct_TEST" and mg_[key_]["param:a1"]["type"] == "Unkstruct_DRIFT2", f"{mg_}")
    ok("plan_S: drifted bbt draws nothing; the pinned merge draws the file",
       plan_S(False, 50, None, set(), {}, cur_)[1] == 0 and plan_S(False, 50, None, set(), {}, mg_)[1] == 1)
    m_, defs_, _, _, _ = file_view(tu, text)
    nh_ = body_nhash(m_, next(x for x in defs_ if x["name"] == "fx_a"))
    b_can_ = [dict(base="param:a0", type="Unkstruct_TEST", status="CANONICAL")]
    fin_ = ledger_latest([dict(rung="S", tu=tu, unit="fx_a", verdict="MEMBERS", nhash_after=nh_, bases=b_can_)])
    old_ = ledger_latest([dict(rung="S", tu=tu, unit="fx_a", verdict="MEMBERS", nhash_after=nh_, bases=b_can_),
                          dict(rung="S", tu=tu, unit="fx_a", verdict="MEMBERS", nhash_after="stale", bases=b_can_)])
    p_fin, p_old = plan_S(False, 50, None, set(), fin_, mg_), plan_S(False, 50, None, set(), old_, mg_)
    ok("plan_S: a file whose bodies' latest S rows are at the current nhash is not drawn; a stale latest hash draws it",
       p_fin[1] == 0 and p_fin[2]["file-finished"] == 1 and p_old[1] == 1, f"{p_fin[1:]} {p_old[1:]}")
    unj_ = ledger_latest([dict(rung="S", tu=tu, unit="fx_a", verdict="NO-SITE", nhash_after=nh_,
                               bases=[dict(base="param:a0", type="Unkstruct_TEST", status="NO-TYPE-IN-MAP")])])
    ok("plan_S (T3.c3): a current-hash row with no judged base (every base NO-TYPE-IN-MAP) leaves the file drawable",
       plan_S(False, 50, None, set(), unj_, mg_)[1] == 1 and ledger_index(list(unj_.values()))[0] == set()
       and ledger_index(list(fin_.values()))[0] == {("S", tu, "fx_a", nh_)})
    # T3.c3: plan and apply agree on a pinned base even when the (drifted) struct map lacks its name
    map_keep_, _map_cache = _map_cache, {}
    d_a_ = next(x for x in defs_ if x["name"] == "fx_a")
    pb_ = s_body_edits(tu, "fx_a", text, m_, d_a_, [s_ for s_ in file_view(tu, text)[4] if s_.get("fn") == "fx_a"],
                       plan_S(False, 50, None, set(), {}, mg_)[0][0][1]["fx_a"], False, {})
    _map_cache = map_keep_
    ok("apply: the planned pinned base is CANONICAL with edits though the struct map lacks the name",
       [(b_[0], b_[1], b_[2]) for b_ in pb_] == [("param:a0", "Unkstruct_TEST", "CANONICAL")] and len(pb_[0][3]) > 0, f"{[b_[:3] for b_ in pb_]}")
    # T3.c7: --residue rows (ledger only) and --check-residue over a fixture sites.jsonl; T10.c1: per-site match, merged rows, I/M forms
    rs_p = dirp / "residue_sites.jsonl"
    rs_p.write_text("".join(json.dumps(x) + "\n" for x in [
        dict(form="P", tu=tu, fn="fx_a", line=9, base="a0", bclass="param", off=0, type="Unkstruct_TEST"),
        dict(form="X", tu=tu, fn="fx_b", line=20, base="a0", bclass="param", off=4, type=None),
        dict(form="P", tu=tu, fn="fx_z", line=30, base="D_1", bclass="global", off=0, type="Unkstruct_GONE"),
        dict(form="P", tu=tu, fn=None, line=2, base="D_2", bclass="gaddr", off=0, type=None),
        dict(form="I", tu=tu, fn="fx_b", line=21, base="D_3", bclass="gaddr", off=0, type="Unkstruct_TEST"),
        dict(form="M", tu=tu, fn="fx_d", line=50, base="a1", bclass="param", off=16, type=None),
        dict(form="K", tu=tu, fn="fx_c", line=40, base="a0", bclass="param", off=0, type=None)]))
    kept_e_ = dict(form="P", line=7, base="param:a0", off=8, type="Unkstruct_TEST", verdict="KEPT(SIGN)", cause="SIGN")
    lat_ = ledger_latest([dict(rung="S", tu=tu, unit="fx_a", label="sprior", verdict="MEMBERS", nhash_after=nh_, bases=b_can_,
                               sites=[kept_e_])])
    rg_ = residue_sites([tu], lat_, rs_p)
    rr_ = residue_rows(rg_, "rtest", {}, lat_)
    new_ = [r for r in rr_ if "residue_of" not in r]
    db_ = next(x for x in defs_ if x["name"] == "fx_b")
    ok("--residue: one no-edit row per undrawn body (sorted), causes FILE-SCOPE/NO-TYPE-IN-MAP/TYPE-NOT-CANONICAL, never judged",
       [(r["unit"], r["verdict"], r["sites"][0]["verdict"]) for r in new_] == [("<file-scope>", "RESIDUAL", "RESIDUAL(FILE-SCOPE)"),
           ("fx_b", "RESIDUAL", "RESIDUAL(NO-TYPE-IN-MAP)"), ("fx_z", "TYPE-NOT-CANONICAL", "RESIDUAL(TYPE-NOT-CANONICAL)")]
       and new_[1]["nhash_before"] == new_[1]["nhash_after"] == body_nhash(m_, db_) and not any(s_judged(r) for r in new_)
       and ledger_index(new_)[0] == set(), f"{[(r['unit'], r['verdict'], r['nhash_after']) for r in new_]}")
    ok("--check-residue (T10.c1): a MEMBERS body's raw site no RESIDUAL entry lists is uncovered (per site, not per body)",
       [s_["line"] for s_ in rg_.get((tu, "fx_a"), [])] == [9] and sum(len(v) for v in rg_.values()) == 4, f"{dict(rg_)}")
    mg_r = next((r for r in rr_ if r["unit"] == "fx_a"), {})
    ok("--residue (T10.c1): the merged row keeps the prior verdict, bases and KEPT entries and appends one RESIDUAL entry",
       mg_r.get("verdict") == "MEMBERS" and mg_r.get("bases") == b_can_ and mg_r.get("residue_of") == "sprior"
       and mg_r.get("sites", [None])[0] == kept_e_ and len(mg_r["sites"]) == 2
       and mg_r["sites"][1]["verdict"].startswith("RESIDUAL(") and mg_r["sites"][1]["cause"]
       and lat_[("S", tu, "fx_a")]["sites"] == [kept_e_], f"{mg_r}")
    lat2_ = ledger_latest(list(lat_.values()) + rr_)
    ok("--check-residue: the residue rows cover every P/X site; without them 4 bodies / 4 sites stay uncovered",
       residue_sites([tu], lat2_, rs_p) == {} and sum(len(v) for v in rg_.values()) == 4 and len(rg_) == 4)
    e_ = dict(form="P", base="param:a0", off=0, verdict="RESIDUAL(X)", cause="X")
    s1_ = dict(form="P", tu=tu, fn="fx_q", bclass="param", base="a0", off=0, line=1)
    mq_ = lambda ents, n: residue_match({("S", tu, "fx_q"): dict(sites=ents)}, [dict(s1_, line=i + 1) for i in range(n)])
    ok("residue_match: a multiset (one entry covers one site); an empty cause or a KEPT entry covers nothing; line never matters",
       [len(x) for x in mq_([e_], 2)] == [1, 1] and [len(x) for x in mq_([e_, e_], 2)] == [2, 0]
       and [len(x) for x in mq_([dict(e_, cause="")], 1)] == [0, 1]
       and [len(x) for x in mq_([dict(e_, verdict="KEPT(SIGN)", cause="SIGN")], 1)] == [0, 1])
    rim_ = residue_rows(residue_sites([tu], lat2_, rs_p, ("I", "M")), "rtest_im", {}, lat2_)
    im_e = {(r["unit"], x["form"], x["cause"]) for r in rim_ for x in r["sites"] if x["form"] in ("I", "M")}
    ok("--residue --forms I,M (T10.c1): I and M entries written with non-empty causes (GADDR — T5.c2, was ABS-ADDR — NO-TYPE-IN-MAP); then covered",
       im_e == {("fx_b", "I", "GADDR"), ("fx_d", "M", "NO-TYPE-IN-MAP")}
       and residue_sites([tu], ledger_latest(list(lat2_.values()) + rim_), rs_p, ("I", "M")) == {}
       and residue_sites([tu], ledger_latest(list(lat2_.values()) + rim_), rs_p) == {}, f"{im_e}")
    # T5.c2: the I/M recipe ladder (`--forms I,M`): a drawn &D_x site (R2), a refused one (RESIDUAL(R2-…), covered), the param site untouched
    fxi = dirp / "ov" / "fx_im.c"
    fxi.write_text(FIXTURE_TU_IM)
    tui = fxi.relative_to(REPO).as_posix()
    vi_ = [dict(form=s_["form"], **{k: v for k, v in s_.items() if k not in ("form", "tu")}, tu=tui) for s_ in file_view(tui, FIXTURE_TU_IM)[4]]
    ip_ = dirp / "im_sites.jsonl"
    ip_.write_text("".join(json.dumps(x) + "\n" for x in vi_))
    pim_, tot_, _, nim_ = plan_S_im(False, 10, None, {}, ip_)
    ok("--forms I,M plan: only the body with I/M global-base sites (fx_im, 2 sites); fx_par's param I site draws nothing",
       pim_ == [(tui, {"fx_im": {}})] and nim_ == {(tui, "fx_im"): 2} and tot_ == 1, f"{pim_} {nim_}")
    w_ent = dict(form="I", line=8, base="gaddr:D_80078F10", off=0, verdict="RESIDUAL(GADDR)", cause="GADDR")
    lat_i = {("S", tui, "fx_im"): dict(rung="S", tu=tui, unit="fx_im", fn="fx_im", label="sprior", verdict="MEMBERS", bases=b_can_,
                                      nhash_after="h0", sites=[kept_e_, w_ent])}
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "")
    ri_ = work_file_S(tui, {"fx_im": {}}, "st_im", dict(head="x"), logs.append, want_sa=False, want_recipes=True, im_only=True, latest=lat_i)
    rwi = ri_["rows"][0] if ri_["rows"] else {}
    fti = ri_.get("final_text") or ""
    vfi = {(e["base"], e["verdict"]) for e in rwi.get("sites", [])[1:]}
    ok("--forms I,M: the s32 &D_x site drawn by R2 (extern array), the s16 one RESIDUAL(R2-WIDTH), the param site untouched",
       ri_["final"] == "IDENTICAL" and "extern s32 D_80078F00[];" in fti and "D_80078F00[0] = 1;" in fti and "*(s32 *)&D_80078F10 = 2;" in fti
       and "*(u16 *)a0 = 3;" in fti and vfi == {("gaddr:D_80078F00", "R:R2-extern-array"), ("gaddr:D_80078F10", "RESIDUAL(R2-WIDTH)")}
       and rwi.get("im", {}).get("drawn") == {"R2-extern-array": 1} and ri_["im_drawn"] == 1 and ri_["im_residual"] == 1, f"{ri_['final']} {vfi}")
    ok("--forms I,M: the prior row merged (verdict, bases, KEPT entry kept; its RESIDUAL entry for the site replaced; im_of)",
       rwi.get("verdict") == "MEMBERS" and rwi.get("bases") == b_can_ and rwi.get("im_of") == "sprior" and rwi["sites"][0] == kept_e_
       and len(rwi["sites"]) == 3 and lat_i[("S", tui, "fx_im")]["sites"] == [kept_e_, w_ent], f"{rwi.get('sites')}")
    vf2 = [dict(s_, tu=tui) for s_ in file_view(tui, fti)[4]]
    cov_i, unc_i = residue_match(ledger_latest([rwi]), vf2, IM_FORMS)
    ok("--forms I,M: the refused site is covered by its RESIDUAL(R2-WIDTH) entry; only the param sites stay uncovered",
       [s_["base"] for s_ in cov_i] == ["D_80078F10"] and [(s_["fn"], s_["bclass"]) for s_ in unc_i] == [("fx_im", "param"), ("fx_par", "param")],
       f"{cov_i} {unc_i}")
    JUDGE_STUB = lambda files, tag: ("IDENTICAL", "") if tag.endswith("F") else ("DIFFERS", "")
    rd_ = work_file_S(tui, {"fx_im": {}}, "st_im", dict(head="x"), logs.append, want_sa=False, want_recipes=True, im_only=True, latest={})
    rdw = rd_["rows"][0] if rd_["rows"] else {}
    ok("--forms I,M: a DIFFERS judgement is RESIDUAL(R2-DIFFERS); nothing written (UNCHANGED); a new no-base row RESIDUAL",
       rd_["final"] == "UNCHANGED" and rdw.get("verdict") == "RESIDUAL" and rdw.get("bases") == []
       and [e["verdict"] for e in rdw.get("sites", [])] == ["RESIDUAL(R2-DIFFERS)", "RESIDUAL(R2-WIDTH)"], f"{rd_['final']} {rdw.get('sites')}")
    ok("--forms I,M: the stub never writes the tree", fxi.read_text() == FIXTURE_TU_IM)
    ok("the selftest never touches the live inflight.json", True)
    ok("struct_layout selftest", sl.selftest() == 0)
    JUDGE_STUB = None
    DEFS_OVERRIDE = None
    VISIBLE_OVERRIDE = None
    _canon = None
    _map_cache = None
    if real:
        okc, whyc = oracle.calibration_current()
        ok("[real] the oracle's calibration is current", okc, whyc)
        tu_r = "src/ov_SC05_010/ov_SC05_010_jr_80180F84.c"
        if (REPO / tu_r).exists() and okc:
            raw_r = (REPO / tu_r).read_text(errors="surrogateescape")
            rr = judge_files({tu_r: raw_r}, "stkt")
            ok("[real] known-true: the tree's own text judges IDENTICAL", rr["verdict"] == "IDENTICAL", f"{rr['verdict']} {rr['err'][:80]}")
            rn = judge_files({tu_r: raw_r.replace("\n}\n", "\n    __asm__(\"nop\");\n}\n", 1)}, "stneg")
            ok("[real] negative: a nop injected judges DIFFERS", rn["verdict"] == "DIFFERS", rn["verdict"])
        ok("[real] the linked-mode control (oracle --linked-control)", oracle.linked_control() == 0)
        ok("[real] common.h's reinterpret macros == the bare casts on cc1's assembly", macro_probe())
    bad = [(n, note) for n, c, note in checks if not c]
    print(f"restruct --selftest{' --real' if real else ''}: {len(checks) - len(bad)}/{len(checks)} OK")
    for n, note in bad:
        print(f"   FAIL {n}: {note}")
    return 0 if not bad else 1

# ----------------------------------------------------------------------------------------------------------------------
def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    ap.add_argument("--try", dest="try_", nargs=2, metavar=("TU", "FN"))
    ap.add_argument("--base", help="bclass:name (default: the body's largest typed base)")
    ap.add_argument("--recipes", action="store_true", help="also run the R recipes on the kept casts and (T5.c2, rung S) on every I/M site with a global base (gaddr/global)")
    ap.add_argument("--plan", action="store_true")
    ap.add_argument("--apply", action="store_true")
    ap.add_argument("--rung", choices=("S", "D", "L"), default="S")
    ap.add_argument("--batch", type=int, default=50)
    ap.add_argument("--label", default=time.strftime("r%m%d%H%M"))
    ap.add_argument("--headers", action="store_true", help="the batch draws shared headers (serial; judged on every includer)")
    ap.add_argument("--only", nargs="*", help="aliases / TUs / functions / type names to restrict the batch to")
    ap.add_argument("--no-sa", action="store_true", help="rung S without the struct-hypothesis lever pass")
    ap.add_argument("--redraw", nargs="*", default=[], help="draw again the units whose latest ledger verdict is one of these (e.g. DECL-KEPT after T5); rung D: lifted units with no lying declaration left are superseded (DECL-NONE; --plan reports)")
    ap.add_argument("--try-file", nargs="+", metavar="TU_OR_FN", help="rung S on one TU's named bodies with the REAL oracle, local types allowed, NOTHING written")
    ap.add_argument("--callee", help="rung D: a DEFINITION-side signature change for this function (with --signature)")
    ap.add_argument("--signature", help='rung D: the new signature, e.g. "void func_800385C0(s32 a0)"')
    ap.add_argument("--body", help="rung D with --callee: a file whose function text REPLACES the definition (the signature is read from its head)")
    ap.add_argument("--all-defs", action="store_true", help="rung D with --callee: apply the body/signature to EVERY same-address definition (copies of one function)")
    ap.add_argument("--map-data", action="store_true", help="rung D --callee --body --all-defs: rename the body's D_ symbols to each copy's own (by order of first appearance); a count mismatch refuses")
    ap.add_argument("--with", dest="with_files", action="append", metavar="REL=FILE", help="rung D --callee: a caller TU's edited text that is part of the same judged unit (repeatable)")
    ap.add_argument("--tu", help="rung D with --callee: restrict to the definition in this TU")
    ap.add_argument("--unalias", nargs="*", help="rung D: put alias-defined functions (aF<addr> __asm__(\"func_<addr>\")) back under their real names; names or ALL")
    ap.add_argument("--restore", action="store_true")
    ap.add_argument("--status", action="store_true")
    ap.add_argument("--check-ledger", action="store_true")
    ap.add_argument("--residue", action="store_true", help="rung S: a no-edit row per body with uncovered census sites of --forms (ledger only; --only, default ov_*); "
                    "a body with a latest rung-S row gets a merged copy of it plus one RESIDUAL(<cause>) entry per uncovered site")
    ap.add_argument("--check-residue", action="store_true", help="census sites of --forms (--only, default ov_*) not covered PER SITE by a RESIDUAL(<cause>) entry "
                    "(same form, normalised base, off; one entry per site) of their body's latest rung-S row; exit 1 if any")
    ap.add_argument("--forms", default=None, help="--residue/--check-residue: raw census forms, comma list of P,I,X,M (default P,X); "
                    "--plan/--apply --rung S --forms I,M (T5.c2): only bodies with uncovered I/M global-base sites, the R ladder only (implies --recipes)")
    ap.add_argument("--audit-types", action="store_true")
    ap.add_argument("--write-types", action="store_true")
    ap.add_argument("--type", nargs="*")
    ap.add_argument("--top", type=int, default=0)
    ap.add_argument("--space", default="ov")
    ap.add_argument("--pointees", action="store_true", help="--write-types: read sites.jsonl for pointer fields' pointees (slow)")
    ap.add_argument("--selftest", action="store_true")
    ap.add_argument("--real", action="store_true", help="--selftest: add the calibration + known-true + linked controls (the real oracle)")
    ap.add_argument("--probe", action="store_true")
    ap.add_argument("--sample", type=int, default=0)
    ap.add_argument("--seed", type=int, default=37)
    ap.add_argument("--audit-layouts", action="store_true")
    ap.add_argument("--fanout-cost", action="store_true")
    ap.add_argument("--rerun-differs", action="store_true", help="re-run only the DIFFERS rows of the last probe (with S2) and re-render")
    ap.add_argument("--probe-decls", action="store_true", help="probe (ii): the definition's signature as the in-scope declaration, per TU x callee")
    ap.add_argument("--probe-defs", action="store_true", help="probe (iii): fold a TU's duplicate file-scope definitions onto the canonical header")
    ap.add_argument("--bbt", help="a pinned body_base_type.json: a base whose current type is not canonical falls back to its pinned entry (env RESTRUCT_BBT)")
    ap.add_argument("-j", "--jobs", type=int, default=16)
    a = ap.parse_args()
    global BBT_PIN
    BBT_PIN = a.bbt or BBT_PIN
    if a.selftest:
        sys.exit(selftest(real=a.real))
    if a.restore:
        sys.exit(restore())
    if a.status:
        if a.rung == "L" and head_split(a.only)[0]:
            sys.exit(fold_report(head_split(a.only)[0]))
        sys.exit(status())
    if a.check_ledger:
        sys.exit(check_ledger(a))
    if a.residue:
        if a.rung != "S":
            sys.exit("restruct --residue is rung S only")
        sys.exit(residue(a))
    if a.check_residue:
        sys.exit(check_residue(a))
    if a.audit_types:
        sys.exit(audit_types(a))
    if a.write_types:
        sys.exit(write_types(a))
    if a.try_:
        row = try_body(a.try_[0], a.try_[1], base_key=a.base, want_recipes=a.recipes)
        print(json.dumps(row, indent=1))
        return
    if a.try_file:
        tu, fns = a.try_file[0], a.try_file[1:]
        recipes()
        all_b = {k.split("|", 1)[1]: v for k, v in bbt().items() if k.split("|", 1)[0] == tu}
        bodies = {fn: all_b[fn] for fn in (fns or all_b) if fn in all_b}
        if not bodies:
            sys.exit(f"restruct --try-file: no typed body of {tu} named {fns or '(any)'} in body_base_type.json (R43)")
        pool = ThreadPoolExecutor(max_workers=a.jobs)
        r = work_file_S(tu, bodies, "try", dict(head=oracle.head()), lambda m: print(m, flush=True), pool=pool, allow_local=True, want_sa=not a.no_sa,
                        want_recipes=a.recipes, write=False)
        pool.shutdown(wait=True)
        for row in r["rows"]:
            print(json.dumps({k: v for k, v in row.items() if k not in ("sites",)}, indent=1))
            print("   sites:", dict(collections.Counter(s_["verdict"] for s_ in row["sites"])))     # was: verdict.split("(")[0] (P39 T3: the class shows)
            for s_ in row["sites"]:
                if s_["verdict"] != "MEMBER":
                    print(f"     line {s_['line']} {s_['base']}+{s_['off']:#x} {s_['access']} {s_['verdict']}")
        for ln in (r.get("final_text") or "").splitlines():
            if re.search(r"\bCAST_[A-Z]+\s*\(", ln):
                print("   respelled:", ln.strip()[:140])
        print(f"restruct --try-file: final {r['final']} · members {r['members']} kept {r['kept']} skipped {r['skipped']} levers off {r['levers_off']} · "
              f"compiles {r['compiles']} in {r['seconds']:.1f} s · NOTHING written")
        return
    if a.plan:
        recipes()
        led = load_ledger()
        done, _ = ledger_index(led)
        if im_mode(a):
            plan, total, skipped, n_im = plan_S_im(a.headers, a.batch, a.only, ledger_latest(led))
            print(describe_plan_im(plan, total, skipped, n_im))
        elif a.rung == "S":
            plan, total, skipped = plan_S(a.headers, a.batch, a.only, done, ledger_latest(led))
            print(describe_plan("S", plan, total, skipped))
        elif a.rung == "D":
            if a.redraw:
                st = stale_lifted(load_ledger(), argcheck_rows(), a.redraw, a.headers, a.only)
                print(f"restruct --plan D: {len(st)} stale lifted rows (no lying declaration left; --apply supersedes them)")
                for r in st:
                    print(f"   stale {r['tu']}  {r['unit']}  {r.get('verdict')}")
            plan, total = plan_D(a.headers, a.batch, a.only, settled_units(load_ledger(), a.redraw))
            print(describe_plan("D", plan, total))
        else:
            plan, total = plan_L(a.headers, a.batch, a.only, None, a.redraw)
            print(describe_plan("L", plan, total))
        for tu, payload in plan[:40]:
            print(f"   {tu}  " + (f"{len(payload)} bodies" if a.rung == "S" else f"{len(payload)} callees" if a.rung == "D" else
                                  f"{len(payload)} definitions {payload[:3]}" if payload is not None else ""))
        return
    if a.apply:
        if a.callee and not (a.signature or a.body):
            sys.exit("restruct --apply --callee needs --signature or --body")
        if a.unalias is not None and a.unalias == []:
            sys.exit("restruct --apply --unalias needs names or ALL")
        sys.exit(apply_batch(a))
    if a.probe:
        run_probe(a)
        return
    if a.rerun_differs:
        rows = [json.loads(l) for l in (PROBE / "probe_rows.jsonl").read_text().splitlines() if l.strip()]
        out = []
        for r in rows:
            if r["verdict"] == "DIFFERS":
                r2 = _probe_worker((r["tu"], r["fn"], r["base"], r["type"], r["stratum"], r.get("base_sites", 0), r.get("lever_body", False)))
                out.append(r2)
            else:
                out.append(r)
        with (PROBE / "probe_rows.jsonl").open("w") as fh:
            for r in out:
                fh.write(json.dumps(r) + "\n")
        table = render_probe(out, {}, 0, a.seed)
        (PROBE / "probe_table.md").write_text(table)
        print(table)
        return
    if a.probe_decls:
        probe_decls(a)
        return
    if a.probe_defs:
        probe_defs(a)
        return
    if a.audit_layouts:
        sys.exit(audit_layouts(a))
    if a.fanout_cost:
        fanout_cost(a)
        return
    ap.print_help()


if __name__ == "__main__":
    main()