#!/usr/bin/env python3 """conform_decls.py — conform every fleet DECLARATION of a function to its byte-true DEFINITION. WHY (§58b): when a draft reaches `match_one` MATCH, **the draft's signature is byte-TRUTH** — it is the shape that produced the target's instructions. The `extern` in `engine_core.h` and in each overlay TU is a stub-era GUESS, written before anyone knew. So the fix for `conflicting types for func_X` is to move the DECLS, never the draft. WHY A TOOL (Phase 29 SESSION-21): this was applied by hand three times in one session (func_8014D2A0, func_8014D820, func_8012AAAC) and it is the single dominant gate-failure class — 7 of 7 plain drafts and 3 of the first 4 jtbl drafts. Doing it by hand is how a half-axis happens. THE TWO LAWS THIS ENCODES ========================= 1. **ALL-OR-NOTHING (§85).** A declaration axis rewritten at only some sites is a GUARANTEED break, not a smaller win: the source overlay carries its own local `extern`s, so widening the shared header alone conflicts with them by construction. Every site is rewritten, and a completion assertion (R32) proves none survived — a count, not a hope. 2. **THE RETURN AXIS HAS A PRECONDITION (§85).** Widening `void` -> `s32` is byte-neutral only if NO caller consumes the return value. That is checked and the run REFUSES if any does, because a consumed return changes the caller's codegen. The whole-binary byte-gate remains the sole arbiter (G3/P9): this only removes a declaration conflict so the gate can judge the BODY. A wrong signature still fails to bank. Usage: tools/conform_decls.py --fn func_XXXX --draft [--check] [--apply] """ import argparse, glob, os, re, sys import importlib.util as _ilu def _load(mod, rel): _spec = _ilu.spec_from_file_location(mod, os.path.join( os.path.dirname(os.path.dirname(os.path.abspath(__file__))), rel)) _m = _ilu.module_from_spec(_spec) _spec.loader.exec_module(_m) return _m cdecl = _load('cdecl', 'tools/cdecl.py') # for _mask: comments/strings are never rewritten (H5) REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) SRC = [os.path.join(REPO, p) for p in ("src",)] def sources(): out = [] for root in SRC: out += glob.glob(os.path.join(root, "**", "*.c"), recursive=True) out += glob.glob(os.path.join(root, "**", "*.h"), recursive=True) return out def def_signature(draft_path, fn): """(return_type, params_text) of the draft's DEFINITION — the byte-true shape.""" txt = open(draft_path, errors="replace").read() m = re.search(rf"^([A-Za-z_][\w \t\*]*?)\b{fn}\s*\(([^;{{]*)\)\s*\{{", txt, re.M) if not m: sys.exit(f"conform_decls: no DEFINITION of {fn} in {draft_path} " f"(a declaration alone is not byte-truth — refusing to guess)") return m.group(1).strip(), m.group(2).strip() def strip_names(params): """`s32 a0, void *a1` -> `s32, void *` — compare shapes, not parameter spellings.""" if params.strip() in ("", "void"): return params.strip() out = [] for p in params.split(","): p = p.strip() p = re.sub(r"\b[A-Za-z_]\w*\s*$", "", p).strip() # drop a trailing identifier out.append(re.sub(r"\s+", " ", p)) return ", ".join(out) def consumers(fn): """Call sites whose VALUE is used — the §85 return-axis precondition.""" pats = [re.compile(rf"=\s*{fn}\s*\("), re.compile(rf"return\s+{fn}\s*\("), re.compile(rf"(?:if|while|switch)\s*\(\s*{fn}\s*\(")] hits = [] for p in sources(): try: txt = open(p, errors="replace").read() except OSError: continue for pat in pats: for m in pat.finditer(txt): ls = txt.rfind("\n", 0, m.start()) + 1 le = txt.find("\n", m.start()) hits.append((os.path.relpath(p, REPO), txt[ls: le if le != -1 else len(txt)].strip()[:100])) return hits def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("--fn", required=True) ap.add_argument("--draft", required=True) ap.add_argument("--check", action="store_true", help="dry run (default)") ap.add_argument("--apply", action="store_true") a = ap.parse_args() ret, params = def_signature(a.draft, a.fn) canon_plain = f"{ret} {a.fn}({params});" canon = "extern " + canon_plain print(f"byte-true definition: {ret} {a.fn}({params})") # `extern` is OPTIONAL: a file-scope prototype without it is equally a declaration, and the # `;` terminator is what separates a declaration from a definition (which ends in `{`). # Requiring `extern` made this tool report "no declaration of func_8013BD74 found" for a TU that # declares it on line 23 as `void func_8013BD74(void *a0, s32 a1);` — a silent miss that reads # exactly like "nothing to do" (R32). The leading `extern` is PRESERVED where present, so the # rewrite never changes a declaration's linkage. # `[^;{\n]*` — NOT `[^;]*` (Phase 29 SESSION-22, byte-witnessed on ov_SC07_006). # `[^;]*` matches NEWLINES, so a match starting at a DEFINITION line # s32 func_8014CF04(s32 param_1, void *param_2, void *param_3) { # ran straight past the brace and through the body to the first `;` it found — the register-pin # declaration on the next line — and replaced BOTH with a prototype. The definition was deleted, # the binary failed to link (`undefined reference to func_8014CF04`), and R22 caught it at # 139/140 while the per-binary gate on ov_SC01_077 had said BYTE-IDENTICAL. Excluding `\n` and # `{` makes a definition unmatchable by construction; a multi-line prototype simply is not # matched, and the R32 completion assertion below then reports it rather than mangling it. decl_re = re.compile(rf"(extern\s+)?[A-Za-z_][\w \t\*]*?\b{a.fn}\s*\([^;{{\n]*\);") # A DEFINITION of the target, for the guard below: the same head, followed by `{` not `;`. def_re = re.compile(rf"(?:[A-Za-z_][\w \t\*]*?)\b{a.fn}\s*\([^;{{\n]*\)\s*\{{") def _canon_for(m): return (m.group(1) or "") + f"{ret} {a.fn}({params});" def _decl_spans(txt): """Declaration matches, found on MASKED text so a comment or string literal can never be rewritten (H5 — this tool mangled three comment lines before the mask went in), with the spans applied to the ORIGINAL. `cdecl._mask` is length-preserving precisely so that offsets into the mask are valid offsets into the source (R33: reuse it, do not write a third one).""" return [(m.start(), m.end(), _canon_for(m)) for m in decl_re.finditer(cdecl._mask(txt))] forms, total = {}, 0 for p in sources(): try: txt = open(p, errors="replace").read() except OSError: continue for m in decl_re.finditer(txt): forms[m.group(0)] = forms.get(m.group(0), 0) + 1 total += 1 if not total: sys.exit(f"conform_decls: no `extern` declaration of {a.fn} found — nothing to conform") print(f"declaration sites: {total}") for f, n in sorted(forms.items(), key=lambda kv: -kv[1]): mark = " (already canonical)" if f in (canon, canon_plain) else "" print(f" {n:>5} {f}{mark}") # ---- THE ARITY PRECONDITION (Phase 29 SESSION-21, learned by breaking 138 binaries) ---- # Conforming a decl from `(void)` to a signature that TAKES parameters is not a decl-only # change: it makes every existing 0-ARG CALL SITE a hard `too few arguments` error the moment a # prototype is in scope. That is fleet-wide, and the per-binary gate CANNOT see it — ov_SC01_077 # gated BYTE-IDENTICAL while 138 other binaries failed to compile, exactly the §63/§85 shape. # # func_8012AAAC needed 137 call-site casts to absorb this; func_8015B950 would need ~926. So the # tool REFUSES and names the cost, rather than leaving a half-axis that only R22 can discover. if strip_names(params) not in ("", "void"): zero_arg = re.compile(rf"(?.]){a.fn}\(\)\s*;") callers = [] for p in sources(): try: txt = open(p, errors="replace").read() except OSError: continue for m in zero_arg.finditer(txt): ls = txt.rfind("\n", 0, m.start()) + 1 le = txt.find("\n", m.start()) line = txt[ls: le if le != -1 else len(txt)] if "extern" in line: continue # a declaration, not a call callers.append(os.path.relpath(p, REPO)) if callers: print(f"\n*** REFUSED: the byte-true signature takes parameters, but {len(callers)} " f"0-ARG CALL SITE(s) exist across {len(set(callers))} file(s). Conforming the " f"decl alone turns every one into `too few arguments` — a fleet-wide COMPILE " f"break the per-binary gate cannot see (measured: 138/140 binaries).", file=sys.stderr) print(f" Fix the call sites FIRST — cast each to the 0-arg shape " f"(((void (*)(void)){a.fn})(), §17a-1; gcc folds the cast of a known symbol to a " f"direct jal) — then re-run. Files: {', '.join(sorted(set(callers))[:3])}" + (" …" if len(set(callers)) > 3 else ""), file=sys.stderr) return 2 # ---- THE SCALAR-NARROWING WARNING (Phase 29 SESSION-21, byte-proven) ---- # A POINTER type change in a decl is caller-neutral (passing a pointer is passing a pointer — # func_80179B74 conformed 1,600 sites s16*/short* -> u16* and stayed byte-identical fleet-wide). # A SCALAR WIDTH change is NOT: narrowing `s32 a0` -> `u16 param_1` changes argument promotion, # so callers emit different code. Measured on func_80175DA8 — with the decls reverted the gate # says PLUMBING (`conflicting types`), with the conform applied it says **DIFF**. The conform # did not fix the draft; it changed the callers. # # This is NOT a refusal: the draft's signature is still byte-truth for the CALLEE, and the # whole-binary gate is the arbiter. It is a warning that the usual "decls are free" intuition # does not hold here, so a DIFF after this conform means re-examine the CALLERS (the §17a-1 # pair — keep the caller decl compatible and cast at the call site) rather than the body. NARROW = {"u8": 1, "s8": 1, "char": 1, "u16": 2, "s16": 2, "short": 2} old_shapes = {strip_names(re.search(rf"\(([^;]*)\)\s*;", f).group(1)) for f in forms if re.search(rf"\(([^;]*)\)\s*;", f)} new_shape = strip_names(params) narrowing = [] for old in old_shapes: for o, n in zip([x.strip() for x in old.split(",")], [x.strip() for x in new_shape.split(",")]): if "*" in o or "*" in n: continue # pointer change: caller-neutral nb = NARROW.get(n.replace("unsigned ", "u").replace("signed ", "s")) if nb and o not in ("", "void") and o != n: narrowing.append(f"{o} -> {n}") if narrowing: print(f"\n⚠ SCALAR-NARROWING in the parameter list ({', '.join(sorted(set(narrowing)))}). " f"Unlike a pointer-type change this is NOT caller-neutral — argument promotion at " f"every call site changes, so callers emit different code (byte-proven on " f"func_80175DA8: PLUMBING before the conform, DIFF after). Applying is still valid — " f"the draft's signature is byte-truth for the CALLEE and the whole-binary gate " f"arbitrates — but if the gate then reports DIFF, examine the CALLERS (§17a-1: keep " f"their decl compatible and cast at the call site), not the body.") # §85 precondition — only matters when the RETURN type changes. ret_changes = any(not re.match(rf"extern\s+{re.escape(ret)}\s", f) for f in forms) if ret_changes: cs = consumers(a.fn) if cs: print(f"\n*** REFUSED: {len(cs)} caller(s) CONSUME the return value, so widening the " f"return type is NOT byte-neutral (§85 precondition):", file=sys.stderr) for p, l in cs[:5]: print(f" {p}: {l}", file=sys.stderr) return 2 print("§85 precondition: 0 callers consume the return => widening is byte-neutral") if not a.apply: print("\n(dry run — pass --apply to rewrite)") return 0 # PLAN -> VALIDATE -> WRITE. Never write as you go: this axis spans ~1,748 files, and aborting # halfway through leaves a HALF-AXIS, which §85 says is a guaranteed break rather than a smaller # win. Planning first means a refusal costs nothing and leaves the tree untouched. plan, changed, defining = [], 0, [] for p in sources(): try: txt = open(p, errors="replace").read() except OSError: continue # A TU THAT DEFINES THE FUNCTION OWNS ITS OWN DECLARATIONS — SKIP THE WHOLE FILE. # (Phase 29 SESSION-22, byte-witnessed on ov_SC07_006; the Phase-16 loose-typing wall.) # This engine gives ONE address DIFFERENT byte-true signatures in different overlays: # ov_SC01_077 needs `(s32, void*, void*)` while ov_SC07_006's own banked definition needs # `(s32, s32, void*)`, and that file carries a local decl explicitly marked # /* de-macroized: per-overlay-local decl (byte-true sig); do NOT re-macroize */ # Conforming it to the fleet-wide canonical produced `conflicting types` against the very # definition below it — the tool overwrote a deliberate, byte-true, per-overlay exception. # A fleet-wide axis is only meaningful for TUs that CONSUME the symbol; a TU that DEFINES it # is byte-truth for itself and must be left entirely alone. if def_re.search(cdecl._mask(txt)): defining.append(os.path.relpath(p, REPO)) continue spans = _decl_spans(txt) if not spans: continue new = txt for s, e, rep in reversed(spans): # right-to-left keeps earlier offsets valid new = new[:s] + rep + new[e:] if new == txt: continue # THE GUARD (R32, and the reason this run exists): a DEFINITION must never be rewritten. # A binary that has already BANKED this function carries its definition, and that definition # is byte-truth there — conforming it away silently turns a matched function back into an # unresolved symbol (`undefined reference`), which only R22 can see. if len(def_re.findall(cdecl._mask(new))) != len(def_re.findall(cdecl._mask(txt))): print(f"\n*** REFUSED: the rewrite would DESTROY a definition of {a.fn} in " f"{os.path.relpath(p, REPO)}. Nothing has been written — the plan is discarded " f"whole. This is the ov_SC07_006 class: that binary has already BANKED the " f"function, so its definition is byte-truth there and must be left alone.", file=sys.stderr) return 2 plan.append((p, new)) changed += len(spans) for p, new in plan: # validated -> commit the whole axis at once open(p, "w").write(new) touched = len(plan) if defining: print(f"skipped {len(defining)} file(s) that DEFINE {a.fn} — a defining TU owns its own " f"declarations (per-overlay byte-true signatures differ; §16 loose typing): " f"{', '.join(defining[:4])}{' …' if len(defining) > 4 else ''}") # R32: the axis is complete or it is a guaranteed break — assert, never assume. left = 0 for p in sources(): try: txt = open(p, errors="replace").read() except OSError: continue if def_re.search(cdecl._mask(txt)): continue # a DEFINING TU is a deliberate exception, not a missed site — the # all-or-nothing invariant (§85) is over the CONSUMING TUs. Counting # the exception here made the tool report a false HALF-AXIS and refuse # a complete, correct rewrite. An assertion must be exact about its # DOMAIN, or it cries wolf on its own by-design behaviour (R32). left += sum(1 for m in decl_re.finditer(cdecl._mask(txt)) if m.group(0) != _canon_for(m)) print(f"rewrote {changed} declaration sites across {touched} files") print(f"non-canonical declarations remaining: {left} " f"{'OK (axis complete)' if left == 0 else '*** HALF-AXIS — DO NOT BUILD ***'}") return 0 if left == 0 else 1 if __name__ == "__main__": sys.exit(main())