@asmlift/core 0.8.1 → 0.10.0

package/README.md

@@ -75,8 +75,8 @@ Everything under `src/` is importable as `@asmlift/core/<path>` (e.g.
 
 Three ISA frontends (ARMv4T/Thumb, MIPS, PowerPC), four compiler families (`agbcc`, `ido`, `gcc`,
 `mwcc` — `codegen-flags.ts`'s `FlagFamily`) over seven target keys, three language backends over one neutral AST — all scored across the package seam
-by [`@asmlift/cli`](../cli/README.md) with the community `objdiff` engine (in-process, pinned
-`objdiff-wasm`; asmlift never hand-rolls a diff).
+by [`@asmlift/cli`](../cli/README.md) with the community `objdiff` engine (in-process through
+`@match-kit/scoring`, pinned `objdiff-wasm`; asmlift never hand-rolls a diff).
 
 ### The pipeline (`decompile()` in `pipeline.ts`)
 
@@ -94,27 +94,28 @@ injected via hooks, never copied. `verify()` runs after every IR-mutating pass;
 
 ### Modules
 
-| Module                                    | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ir/*.ts`                                 | MLIR-lite substrate (`types`, `core`, `opcodes`, `print`, `parse`, `verify`, plus `alias.ts`'s alias predicate, `simplify.ts`, `bits.ts` and `struct-names.ts`): CFG of blocks + typed **block-arguments**, the typed opcode registry (`Opcode`, the one `effects` table DCE and hoist guards derive from), printer + parser (round-trip for L1/scalar types — see the domain note in parse.ts), verifier (arity/attrs/terminators/SSA dominance, located errors); `core.ts` also owns the CFG facts every level reads — `successorsOf`, `predecessors`, `dominators`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `frontend/{thumb,mips,ppc}.ts`            | ISA frontends: decode → CFG → L1 with **Braun-2013 block-arg SSA** (`ssa.ts`), incl. loops, calls (signature-driven arity), memory, jump tables. Shared scaffolding: `disasm.ts` (objdump parsing), `splat.ts` (Splat-dialect MIPS → objdump-shaped instrs), `format.ts` (input-format classification), `emit.ts` (per-block emitter kit + `switch_br`), `opaque.ts` (the unmodelled-op → loud-`opaque` contract), `errors.ts` (`FrontendUnsupportedError`; PPC's subclass), `registry.ts`, `asmdata.ts` (Regime-B jump-table side-table), `high-half.ts` (a relocated address's high half is a link-time placeholder, never a value), `reloc-symbol.ts` (the per-KIND policy deciding which linker names C can spell), `stackargs.ts` (the outgoing stack-argument fixpoint, over digested slot events rather than instructions)                                                                                                                                                                                                                                     |
-| `pattern/engine.ts`                       | Idiom layer: **rewrite patterns as data** + greedy driver + DCE; `patternApplies` gates on Target capabilities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `raise/*.ts`                              | The pre-recovery recognizers, in ONE ordered list — `PRE_RECOVERY_PASSES` in `pre-recovery.ts` is the source of truth for the order, and reads: address-numbering (`gvn.ts`) → const-materialize → magic-division (`magicdiv.ts`, Hacker's Delight inverse) → pow2-division (`divpow2.ts`) → soft-division → scaled-extension (`extscale.ts`) → array-legalize → struct-array → member-array (`memberarrays.ts`, a constant offset feeding a variable-index walk is a struct's ARRAY member) → struct-pointer → short-circuit → branch-short-circuit → narrow-reads (`narrow.ts`) → narrow-local (`narrowlocal.ts`, a carrier read only through its own extension IS that width) → parameter-width (`paramwidth.ts`, a parameter extended in the prologue is DECLARED at that width) → scaled-extension-restore; plus `recover.ts` (L1→L2 type recovery), `retsink.ts` + `tailsink.ts` (return- and tail-sinking), `latch.ts` (empty-latch folding), `globalshape.ts` (which derived shapes the source is only correct beside), `errors.ts` (`RaiseUnsupportedError`) |
-| `structure/*.ts`                          | L2→L3: `loops.ts` (natural-loop discovery, over `ir/core.ts`'s dominators), `analysis.ts` (use registry, liveness, C4 materialization), `switch-recover.ts` (Regime-A comparison-tree recovery), `hazards.ts` (the checks a loop emitter runs before committing to a loop form), `namecoalesce.ts` (copy coalescing over the interference graph — the `/merge-names` variation), `structure.ts` (SSA-destruction coalescing with interference checks + emission: if/while/do-while/for/switch, break/early-return), `retspell.ts` (which `return;` the source wrote, read off the epilogue's in-edges), `bitfields.ts` + `globalaccess.ts` (the map-driven bitfield and global-access spellings, both refusal machines)                                                                                                                                                                                                                                                                                                                                               |
-| `l3/*.ts`                                 | `ast.ts`: language-**neutral** structured AST, the one traversal vocabulary (`exprChildren` etc.), and the `LanguageBackend` seam. Post-structure passes `dce.ts` + `basecse.ts`, the shared hoist mechanism `hoist.ts`, the differ-ranked respell variations (`regspell.ts`, `reindex.ts`, `argbase.ts`, `scopebase.ts`, `argcopy.ts` — five of the 31 the registry holds; a module may mint more than one, as `scopebase.ts` does with `/scopebase` and `/regionbase`), the spelling pass `tailret.ts` (drop a void `return;` `structure/retspell.ts` marked unspelled), and `typing.ts` (the rendered-expression C type the backends and contracts share)                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `backend/{c,cpp,cfamily,pascal}.ts`       | Three backends: C and C++ (CodeWarrior mangling via `mangle.ts`) over the shared `cfamily.ts` substrate, and Pascal (`:=`, `div`, tail-position returns; unspellable constructs throw)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `pipeline.ts`                             | `decompile()` + the shared tower spine + annotate-mode stubs/diagnostics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `trace.ts`                                | `decompileTraced` — the traced tower (per-stage IR dumps + pattern before/after events), browser-pure; @asmlift/cli's `report.ts` enriches it with objdiff scores/candidates, the playground's Pipeline tab renders it directly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `rank.ts`                                 | Pure candidate enumeration + `rankBy` (an injected score function ranks). @asmlift/cli's differ ranks through `rankBy`; the playground's wasm scorer consumes the same enumeration with its own async loop                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `rank-variations.ts`, `rank-declare.ts`   | The two halves `rank.ts` walks rather than hand-codes: the enumeration TABLES (declaration order is published behaviour — it breaks a score tie), and the declarations a candidate needs to compile outside the project's headers, including which names one must REFUSE to claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `variation-{tokens,definitions,gates}.ts` | The variation REGISTRY as data: every variation a candidate's name can carry, what each one MEANS for a reader, and the admission tables a definition names. Keyed by the registry in both directions, so a variation with no definition and a definition naming no variation are each a type error                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `codegen-flags.ts`                        | Compiler flags parsed into the codegen profile a function was compiled at — each option that can change what the compiler emits, as a named slot. One flag set reaches both the compile and the decompile                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `symbols.ts`, `declare.ts`, `macros.ts`   | The address→symbol map seam (core consumes the VALUE; the providers that read files live in `@asmlift/cli`), the declaration block a self-declaring candidate carries, and the address-cast macro spelling — a `#define` emits a NUMERIC pool word where an `extern` emits a relocated one, so the two are not interchangeable in the bytes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `target.ts`                               | `TargetDescription` (ABI + capabilities + compilerBehaviors as data — no `arch ==` in shared code); toolchain paths live in `@asmlift/toolchains`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `contracts.ts`, `proto.ts`, `mangle.ts`   | Boundary contracts; prototype tables; the CodeWarrior mangler                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Module                                    | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ir/*.ts`                                 | MLIR-lite substrate (`types`, `core`, `opcodes`, `print`, `parse`, `verify`, plus `alias.ts`'s alias predicate, `simplify.ts`, `bits.ts` and `struct-names.ts`): CFG of blocks + typed **block-arguments**, the typed opcode registry (`Opcode` and its `effects`/`reads`/`traps` flags), `discipline.ts` (the access discipline: an op's placement — `call`, `helper`, `device`, `declared` — and the questions DCE, hoist and placement guards ask of an op instead of an opcode set), printer + parser (round-trip for L1/scalar types — see the domain note in parse.ts), verifier (arity/attrs/terminators/SSA dominance, located errors); `core.ts` also owns the CFG facts every level reads — `successorsOf`, `predecessors`, `dominators`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `frontend/{thumb,mips,ppc}.ts`            | ISA frontends: decode → CFG → L1 with **Braun-2013 block-arg SSA** (`ssa.ts`), incl. loops, calls (signature-driven arity), memory, jump tables. Shared scaffolding: `disasm.ts` (objdump parsing), `splat.ts` (Splat-dialect MIPS → objdump-shaped instrs), `format.ts` (input-format classification), `emit.ts` (per-block emitter kit + `switch_br`), `opaque.ts` (the unmodelled-op → loud-`opaque` contract), `errors.ts` (`FrontendUnsupportedError`; PPC's subclass), `registry.ts`, `asmdata.ts` (Regime-B jump-table side-table), `high-half.ts` (a relocated address's high half is a link-time placeholder, never a value), `reloc-symbol.ts` (the per-KIND policy deciding which linker names C can spell), `stackargs.ts` (the outgoing stack-argument fixpoint, over digested slot events rather than instructions), `frame-objects.ts` (the ISA-neutral audit of every address-taken frame object, over the frame partition a frontend measured), `device-pins.ts` (the device pin that audit answers: which device-register accesses must run where the machine ran them, per `DEVICE_PIN_POLICIES` row)                                                                                                                                                     |
+| `pattern/engine.ts`                       | Idiom layer: **rewrite patterns as data** + greedy driver + DCE; `patternApplies` gates on Target capabilities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `raise/*.ts`                              | The pre-recovery recognizers, in ONE ordered list — `PRE_RECOVERY_PASSES` in `pre-recovery.ts` is the source of truth for the order, and reads: address-numbering (`gvn.ts`) → const-materialize → magic-division (`magicdiv.ts`, Hacker's Delight inverse) → pow2-division (`divpow2.ts`) → soft-division → scaled-extension (`extscale.ts`) → array-legalize → struct-array → member-array (`memberarrays.ts`, a constant offset feeding a variable-index walk is a struct's ARRAY member) → struct-pointer → short-circuit → branch-short-circuit → narrow-reads (`narrow.ts`) → narrow-local (`narrowlocal.ts`, a carrier read only through its own extension IS that width) → parameter-width (`paramwidth.ts`, a parameter extended in the prologue is DECLARED at that width) → scaled-extension-restore; plus `recover.ts` (L1→L2 type recovery), `retsink.ts` + `tailsink.ts` (return- and tail-sinking), `latch.ts` (empty-latch folding), `globalshape.ts` (which derived shapes the source is only correct beside), `declared-volatile.ts` (the `declared` stamp on an access of an object the symbol map or the declaration context declares volatile, or through a pointer the context declares to point at a volatile), `errors.ts` (`RaiseUnsupportedError`) |
+| `structure/*.ts`                          | L2→L3: `loops.ts` (natural-loop discovery, over `ir/core.ts`'s dominators), `analysis.ts` (use registry, liveness, C4 materialization), `switch-recover.ts` (Regime-A comparison-tree recovery), `hazards.ts` (the checks a loop emitter runs before committing to a loop form), `namecoalesce.ts` (copy coalescing over the interference graph — the `/merge-names` variation), `structure.ts` (SSA-destruction coalescing with interference checks + emission: if/while/do-while/for/switch, break/early-return), `retspell.ts` (which `return;` the source wrote, read off the epilogue's in-edges), `bitfields.ts` + `globalaccess.ts` (the map-driven bitfield and global-access spellings, both refusal machines)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `l3/*.ts`                                 | `ast.ts`: language-**neutral** structured AST, the one traversal vocabulary (`exprChildren` etc.), and the `LanguageBackend` seam. Post-structure passes `dce.ts` + `basecse.ts`, the shared hoist mechanism `hoist.ts`, the differ-ranked respell variations (`regspell.ts`, `reindex.ts`, `argbase.ts`, `scopebase.ts`, `argcopy.ts`, `narrowdecl.ts`, six of the modules behind the registry in `variation-tokens.ts`; a module may mint more than one, as `scopebase.ts` does with `/scopebase` and `/regionbase` and `narrowdecl.ts` with `/narrow-decl` and `/narrow-read`), the spelling pass `tailret.ts` (drop a void `return;` `structure/retspell.ts` marked unspelled), and `typing.ts` (the rendered-expression C type the backends and contracts share)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `backend/{c,cpp,cfamily,pascal}.ts`       | Three backends: C and C++ (CodeWarrior mangling via `mangle.ts`) over the shared `cfamily.ts` substrate, and Pascal (`:=`, `div`, tail-position returns; unspellable constructs throw)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `pipeline.ts`                             | `decompile()` + the shared tower spine + annotate-mode stubs/diagnostics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `trace.ts`                                | `decompileTraced` — the traced tower (per-stage IR dumps + pattern before/after events), browser-pure; @asmlift/cli's `report.ts` enriches it with objdiff scores/candidates, the playground's Pipeline tab renders it directly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `rank.ts`                                 | Pure candidate enumeration + `rankBy` (an injected score function ranks). Every driver ranks through `rankBy`: the sync driver (@asmlift/cli's `decompileRanked`, which the benchmark and `bench fan` run) scores inside it, and the two async drivers (the CLI's pooled ranker, the playground's wasm scorer) compile on their own schedule, memoize the outcomes and hand `rankBy` the memo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `stillborn.ts`, `compiler-diagnostics.ts` | The stillborn-fan rule, one copy for every driver: when the default candidate is rejected, each signedness half's default and one probe per variation name in that half are compiled, and only a fan whose every half's default keeps an error through every probe of its half, in every attempt, is left uncompiled — the rest reported as NOT COMPILED, never as dropped. `compiler-diagnostics.ts` is how a rejection is read: `CompilerRejection` (a compile that ran to completion and said no, as distinct from a transient), the error lines of each compiler's output with positions normalised away, the attempts of a rejection that holds several compiles (`joinAttempts`/`attemptsOf`), and `errorsFirst` for whatever bounds a diagnostic downstream                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `rank-variations.ts`, `rank-declare.ts`   | The two halves `rank.ts` walks rather than hand-codes: the enumeration TABLES (declaration order is published behaviour — it breaks a score tie), and the declarations a candidate needs to compile outside the project's headers, including which names one must REFUSE to claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `variation-{tokens,definitions,gates}.ts` | The variation REGISTRY as data: every variation a candidate's name can carry, what each one MEANS for a reader, and the admission tables a definition names. Keyed by the registry in both directions, so a variation with no definition and a definition naming no variation are each a type error                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `codegen-flags.ts`                        | Compiler flags parsed into the codegen profile a function was compiled at — each option that can change what the compiler emits, as a named slot. One flag set reaches both the compile and the decompile                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `symbols.ts`, `declare.ts`, `macros.ts`   | The address→symbol map seam (core consumes the VALUE; the providers that read files live in `@asmlift/cli`), the declaration block a self-declaring candidate carries, and the address-cast macro spelling — a `#define` emits a NUMERIC pool word where an `extern` emits a relocated one, so the two are not interchangeable in the bytes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `target.ts`                               | `TargetDescription` (ABI + capabilities + compilerBehaviors as data — no `arch ==` in shared code); toolchain paths live in `@asmlift/toolchains`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `contracts.ts`, `proto.ts`, `mangle.ts`   | Boundary contracts; prototype tables; the CodeWarrior mangler                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 Scoring and ranking live across the package seam in [`@asmlift/cli`](../cli/README.md):
-`score.ts` + `objdiff.ts` (toolchain compiles → in-process pinned `objdiff-wasm`, fail-closed)
+`score.ts` (toolchain compiles → `@match-kit/scoring`, the in-process pinned objdiff engine, fail-closed)
 and `rank.ts` (ranked type candidates re-ranked by the differ).
 
 ### Honest coverage gaps
@@ -124,17 +125,21 @@ properly nested, in-body `break`/early-`return`), comparison-tree and jump-table
 direct calls, constant-offset and variable-index memory (`*p`, `p[n]`, `a[i]`, struct fields),
 magic-number and soft division, short-circuit booleans, width casts, PowerPC small-data access
 through its `R_PPC_EMB_SDA21` relocation, a call's outgoing stack arguments on agbcc, where the
-declaration and the code agree (`stagesOutgoingArgsInFrame`; MIPS still declines the same shape),
-and a MIPS likely branch's nullified delay slot. Still DECLINED (loud, never
-wrong code): **local stack frames** (address-taken locals / sp-as-data; MIPS models word `sp`
-slots and PPC elides callee-saved save slots, so a spill/reload pair is modelled on those two —
-anything the narrow models cannot honour declines),
-**cross-block condition flags** on PPC (a `cmpw` whose branch lands in another block — the
-capability gap behind the mwcc switch stubs), computed tail calls, PIC and `gp`-relative access outside PowerPC's
+declaration and the code agree (`stagesOutgoingArgsInFrame`; MIPS lifts a declared callee's too),
+a compare read by a branch in a later block that only its own block enters (Thumb and
+PowerPC, `frontend/flags-edge.ts`), and a MIPS likely branch's nullified delay slot. Still DECLINED (loud,
+never wrong code): **local stack frames** beyond what the models prove (Thumb, MIPS and PPC lift an
+address-taken local the frame-object audit can bound — a scalar, or an untyped buffer that fills
+the frame — and decline the rest, MIPS inside the O32 local area and PPC inside mwcc's local area
+that its compiler's measured layout draws; MIPS and PPC also read an incoming stack word as a
+parameter, MIPS models word `sp` slots and PPC elides callee-saved save slots, so a spill/reload
+pair is modelled on those two — anything the narrow models cannot honour declines),
+**condition flags at a join** (a compare two or more edges bring to one branch, or one the caller
+set), computed tail calls, PIC and `gp`-relative access outside PowerPC's
 small-data relocation — MIPS refuses `R_MIPS_GOT16`/`R_MIPS_CALL16`/`R_MIPS_GPREL16` alike —
-switch fall-through, multi-latch/irreducible loops, floats, and 64-bit memory ops. Prototypes
-(callee arities, void-ness) come from a caller-supplied map, as a real project takes them from
-headers.
+switch fall-through, irreducible loops and loops that exit to more than one live merge, floats,
+and 64-bit memory ops. Prototypes (callee arities, void-ness) come from a caller-supplied map, as a
+real project takes them from headers.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asmlift/core",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "description": "Match decompile an assembly function to C or Pascal",

package/src/aggregate.ts

@@ -0,0 +1,397 @@
+// asmlift — a declared struct or union on a target: its size, and whether a function returning it
+// by value hands it back through a hidden pointer. The members come from a declaration
+// (`proto.ts` AggregateLayout); the layout rules and the return rule are the target's
+// (`compilerBehaviors.aggregateBoundary`, `largestAlignment`, `aggregateReturn`).
+import { type IrType, type StructField, T } from './ir/types';
+import {
+  type AggregateLayout,
+  type AggregateMember,
+  type FnProto,
+  type Prototypes,
+  STANDARD_SIGNATURES,
+  declaredCallArgs,
+  declaredWidth,
+  declaresAggregateReturn,
+  declaresVoidReturn,
+  ownArgumentWords,
+  ownLeadingWordParams,
+  paramClassOf,
+  wordsOf,
+} from './proto';
+import type { TargetDescription } from './target';
+
+/** The size and alignment of a laid-out aggregate in bytes, or undefined where the declaration or
+ *  the target leaves either open: a member not laid out, a member whose size or placement the
+ *  target does not state (an enum, a bitfield), or a target that states no largest alignment. */
+export function aggregateSize(
+  layout: AggregateLayout,
+  target: TargetDescription,
+): { size: number; align: number } | undefined {
+  const placed = place(layout, target);
+  return placed && { size: placed.size, align: placed.align };
+}
+
+/** Each member's offset — a bitfield's is the byte its first bit is in — with the aggregate's size
+ *  and alignment: `aggregateSize`'s walk. The cursor is in bits, since a bitfield can end
+ *  mid-byte. */
+function place(
+  layout: AggregateLayout,
+  target: TargetDescription,
+): { size: number; align: number; offsets: number[] } | undefined {
+  const { aggregateBoundary, largestAlignment, bitfieldPacking } = target.compilerBehaviors;
+  if (layout.members === undefined || aggregateBoundary === undefined || largestAlignment === undefined) {
+    return undefined;
+  }
+  let bits = 0;
+  let align = aggregateBoundary;
+  const offsets: number[] = [];
+  for (const m of layout.members) {
+    if (m.bits !== undefined) {
+      if (bitfieldPacking !== 'contiguous' || m.bits === 0 || typeof m.type !== 'string') {
+        return undefined;
+      }
+      if (scalarBytes(m.type, target) === undefined) {
+        return undefined;
+      }
+      offsets.push(layout.kind === 'struct' ? Math.floor(bits / 8) : 0);
+      bits = layout.kind === 'struct' ? bits + m.bits : Math.max(bits, m.bits);
+      continue;
+    }
+    const one = memberSize(m, target);
+    if (one === undefined) {
+      return undefined;
+    }
+    align = Math.max(align, one.align);
+    if (layout.kind === 'struct') {
+      offsets.push(roundUp(Math.ceil(bits / 8), one.align));
+      bits = (offsets[offsets.length - 1] + one.size) * 8;
+    } else {
+      offsets.push(0);
+      bits = Math.max(bits, one.size * 8);
+    }
+  }
+  return { size: roundUp(Math.ceil(bits / 8), align), align, offsets };
+}
+
+/** A declared struct as the IR types it: `name` at the size this target lays it out at, spelled as
+ *  the headers spell it (`spelling`, which is what marks it theirs — ir/types.ts), with a field at
+ *  its offset for each member the IR can type: a scalar, a pointer, or an array of either. A member
+ *  it cannot — a nested struct or union, a bitfield, an enum, a plain `char`, whose signedness is
+ *  the compiler's and stated nowhere — has no field, and so no read of it is typed. The struct is
+ *  DEFINED from the declaration (declare.ts), not from these fields. Undefined for a union, whose IR
+ *  type carries no name to declare it by, and where this target does not size it. */
+export function aggregateType(
+  name: string,
+  spelling: string,
+  layout: AggregateLayout,
+  target: TargetDescription,
+): IrType | undefined {
+  const placed = layout.kind === 'struct' ? place(layout, target) : undefined;
+  if (placed === undefined) {
+    return undefined;
+  }
+  const fields: StructField[] = [];
+  for (const [i, m] of layout.members!.entries()) {
+    const scalar = m.bits === undefined && typeof m.type === 'string' ? scalarType(m.type) : undefined;
+    if (scalar !== undefined) {
+      const type = (m.dims ?? []).reduceRight<IrType>((elem, n) => T.array(elem, n), scalar);
+      fields.push({ off: placed.offsets[i], type, name: m.name });
+    }
+  }
+  return { kind: 'struct', name, fields, size: placed.size, declared: spelling };
+}
+
+/** The IR type of a scalar or pointer member spelling: a pointer to a scalar keeps its pointee, any
+ *  other pointer is `void *`, which lays out the same. */
+function scalarType(spelling: string): IrType | undefined {
+  const s = spelling
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (s.endsWith('*')) {
+    return T.ptr(scalarType(s.slice(0, -1)) ?? T.void());
+  }
+  if (s === 'float' || s === 'double') {
+    return s === 'float' ? T.f32() : T.f64();
+  }
+  const bits = declaredWidth(s);
+  return bits === undefined || s === 'char' ? undefined : T.int(bits, !/^u\d|\bunsigned\b/.test(s));
+}
+
+function memberSize(m: AggregateMember, target: TargetDescription): { size: number; align: number } | undefined {
+  const count = (m.dims ?? []).reduce((n, d) => n * d, 1);
+  if (typeof m.type !== 'string') {
+    const inner = aggregateSize(m.type, target);
+    return inner === undefined ? undefined : { size: inner.size * count, align: inner.align };
+  }
+  const bytes = scalarBytes(m.type, target);
+  if (bytes === undefined) {
+    return undefined;
+  }
+  return { size: bytes * count, align: Math.min(bytes, target.compilerBehaviors.largestAlignment!) };
+}
+
+/** The bytes a scalar or pointer member spelled `spelling` takes in storage. Not `declaredWidth`'s
+ *  question, which is how many argument registers a parameter takes, and which leaves the floating
+ *  types out because on an FPU target they take none: in memory a `float` is 4 bytes and a `double`
+ *  8 on every target here (IEEE single and double). An enum (`enum E`) is the target's `enumBytes`,
+ *  and unsized where it states none. */
+function scalarBytes(spelling: string, target: TargetDescription): number | undefined {
+  const s = spelling
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (/^enum [A-Za-z_]\w*$/.test(s)) {
+    return target.compilerBehaviors.enumBytes;
+  }
+  const bits = s === 'float' ? 32 : s === 'double' ? 64 : declaredWidth(s);
+  return bits === undefined ? undefined : bits / 8;
+}
+
+const roundUp = (n: number, to: number): number => Math.ceil(n / to) * to;
+
+/** The aggregate a declaration says `p` returns by value (`declaresAggregateReturn`): its stated
+ *  layout, or the bare kind its `returns` spells. */
+export function returnedAggregate(p: FnProto): AggregateLayout {
+  return p.returnLayout ?? { kind: /\bunion\b/.test(p.returns ?? '') ? 'union' : 'struct' };
+}
+
+/** THE ARGUMENT WORDS A FUNCTION'S OWN DECLARATION FILLS (`proto.ts` `ownArgumentWords`), with the
+ *  hidden pointer a struct return may put ahead of them decided by this target's rule: a struct
+ *  `returnsInMemory` answers `false` for comes back in registers and takes no argument word, as a
+ *  call to it does (frontend/call-plan.ts `returnedStruct`). One the rule cannot place still counts
+ *  the word, since the bound must not fall short. */
+export function ownArgumentWordsOn(
+  name: string,
+  p: FnProto | undefined,
+  target: TargetDescription,
+): number | undefined {
+  const registerReturn = declaresAggregateReturn(p) && returnsInMemory(returnedAggregate(p!), target) === false;
+  return ownArgumentWords(name, p, target, registerReturn);
+}
+
+/** The first argument registers that surely hold one of the function's own word parameters
+ *  (`proto.ts` `ownLeadingWordParams`), with the hidden pointer decided by this target's rule as
+ *  {@link ownArgumentWordsOn} decides it. */
+export function ownLeadingWordParamsOn(name: string, p: FnProto | undefined, target: TargetDescription): number {
+  const registerReturn = declaresAggregateReturn(p) && returnsInMemory(returnedAggregate(p!), target) === false;
+  return ownLeadingWordParams(name, p, target, registerReturn);
+}
+
+/** Whether a function declared to return `layout` by value hands it back through memory — so its
+ *  caller passes the address as argument 0 — or `undefined` where the target states no rule or the
+ *  rule needs a size the layout does not give. */
+export function returnsInMemory(layout: AggregateLayout, target: TargetDescription): boolean | undefined {
+  const rule = target.compilerBehaviors.aggregateReturn;
+  if (rule === undefined) {
+    return undefined;
+  }
+  if (rule === 'memory') {
+    return true;
+  }
+  if (rule === 'svr4') {
+    const size = aggregateSize(layout, target)?.size;
+    return size === undefined ? undefined : size > 8;
+  }
+  // agbcc thumb.c:1423-1493: a struct's second member that is not a bitfield puts it in memory
+  // whatever its size; otherwise anything over a word does
+  const members = layout.members;
+  if (layout.kind === 'struct' && members?.slice(1).some((m) => m.bits === undefined)) {
+    return true;
+  }
+  const size = aggregateSize(layout, target)?.size;
+  if (size === undefined) {
+    return undefined;
+  }
+  if (size > 4 || layout.kind === 'struct') {
+    return size > 4;
+  }
+  // a union: in memory as soon as one member would be on its own — an array member is an aggregate
+  // that is neither a struct nor a union, which thumb.c puts in memory (line 1491)
+  let answer: boolean | undefined = false;
+  for (const m of members!) {
+    const own = m.dims !== undefined ? true : typeof m.type === 'string' ? false : returnsInMemory(m.type, target);
+    if (own === true) {
+      return true;
+    }
+    if (own === undefined) {
+      answer = undefined;
+    }
+  }
+  return answer;
+}
+
+/** Whether a call to `callee` is KNOWN not to be handed a hidden struct-return pointer in
+ *  argument 0. A callee that returns nothing has no such pointer to be given; neither has one
+ *  whose return travels in a register. Every other answer — including silence — is `false`,
+ *  because this is a fact a caller must be TOLD: the two frames are the same instructions in the
+ *  same order, so there is nothing in the assembly to read it off.
+ *
+ *  A RETURN WIDER THAN A REGISTER STILL TRAVELS IN REGISTERS — it travels in a PAIR, which is
+ *  still not a hidden pointer the caller supplied — so `declaredWidth` answering 64 is the right
+ *  answer here rather than a width that slipped through a test meant for words. Nothing reaches
+ *  it: `STANDARD_SIGNATURES` has one entry and it returns `void *`.
+ *
+ *  TWO SOURCES AND NEITHER RANKS ABOVE THE OTHER, because on this one question they cannot
+ *  disagree: the project's own headers — `returnsVoid`, or a struct or union `target` hands back
+ *  in a register — and the `returns` of a signature the C standard fixes, which is as known as its
+ *  parameters. That a project may re-declare a standard function differently is real and is why
+ *  `declaredCall` ranks the two for ARITY — but a re-declaration that changed `memcpy` into a
+ *  struct-returning function would not be `memcpy`.
+ *
+ *  `Object.hasOwn`, not `in`: `prototypes` is caller-supplied JSON and the table is an object
+ *  literal, so `in` would answer for `toString` and every other name on `Object.prototype`. The
+ *  ENTRY is read through `?.` for the other half of the same fact: `decompile` is a published
+ *  entry point that runs no `validatePrototypes`, so a `null` entry out of parsed JSON reaches
+ *  here, and a raw TypeError would leave through neither the decline channel nor anything a
+ *  caller can act on. Every other reader of this table — `declaredCallArgs`, and `declaredCall`
+ *  through it — answers "nothing is declared" for such an entry, and so does this. */
+export function returnsWithoutHiddenPointer(
+  callee: string,
+  prototypes: Prototypes,
+  target: TargetDescription,
+): boolean {
+  // Nothing at all, a value in registers, or a spelling nobody here can size — the last of which is
+  // the only one that leaves the hidden pointer open. A pair is `declaredWidth` 64 and still
+  // travels in registers, so a width wider than a word is an answer here and not an overflow.
+  const travelsInRegisters = (spelling: string): boolean => {
+    const t = spelling.trim();
+    return t === 'void' || declaredWidth(t) !== undefined;
+  };
+  const own = Object.hasOwn(prototypes, callee) ? prototypes[callee] : undefined;
+  if (declaresVoidReturn(own)) {
+    return true;
+  }
+  // A STRUCT OR UNION IS THE TARGET'S TO PLACE — agbcc hands a one-word struct back in r0, mwcc up
+  // to eight bytes in r3/r3:r4 — so this asks the rule the call lowering reads, and the two cannot
+  // disagree. A rule or a size nothing states leaves the pointer open.
+  if (own && declaresAggregateReturn(own)) {
+    return returnsInMemory(returnedAggregate(own), target) === false;
+  }
+  // A PROJECT'S OWN `returns` ANSWERS THIS THROUGH THE SAME READING A STANDARD SIGNATURE'S DOES,
+  // and it ranks above the table for the same reason `declaredCall` ranks a re-declaration above
+  // one: a project that spells the return has told you about the function it is building.
+  if (own?.returns !== undefined) {
+    return travelsInRegisters(own.returns);
+  }
+  return Object.hasOwn(STANDARD_SIGNATURES, callee) && travelsInRegisters(STANDARD_SIGNATURES[callee].returns);
+}
+
+/** One struct a call passes by value in argument words (`byValueCallArgs`). */
+export interface ByValueArg {
+  /** the parameter's index in the declared list */
+  readonly param: number;
+  /** its first argument word, among the call's widths */
+  readonly word: number;
+  /** how many argument words it fills */
+  readonly words: number;
+  /** the struct as the IR types it (`aggregateType`) */
+  readonly type: IrType;
+}
+
+/** Where a declaration's by-value structs travel (`byValueCallArgs`), or why that is not known. */
+type ByValueLayout =
+  | { widths: readonly number[]; doubles: ReadonlySet<number>; byValue: readonly ByValueArg[] }
+  | { refused: string; param: number };
+
+/** THE ARGUMENT WORDS OF A DECLARATION WITH A STRUCT PASSED BY VALUE, where the target passes one
+ *  in consecutive argument words (`compilerBehaviors.byValueAggregateArgWords`) and the declaration
+ *  lays it out (`FnProto.byValueLayouts`): each such parameter is its size in words, rounded up, of
+ *  32 bits each, and every other parameter is what `declaredCallArgs` makes of it. Undefined where
+ *  any parameter is unsized that way — a union, a layout this target does not size, a spelling that
+ *  names no tag — or placed where no rule here follows it (`byValueRefusal` names which), and where
+ *  the declaration passes no struct by value at all, which `declaredCallArgs` answers alone. */
+export function byValueCallArgs(
+  p: FnProto | undefined,
+  target: TargetDescription,
+  hidden = 0,
+): { widths: readonly number[]; doubles: ReadonlySet<number>; byValue: readonly ByValueArg[] } | undefined {
+  const laid = layOutByValue(p, target, hidden);
+  return laid === undefined || 'refused' in laid ? undefined : laid;
+}
+
+/** Why `byValueCallArgs` places none of a declaration that does pass a struct or union by value:
+ *  the parameter it stops at (an index into `params`) and the reason. Undefined where it places
+ *  them, or where the declaration passes none. */
+export function byValueRefusal(
+  p: FnProto | undefined,
+  target: TargetDescription,
+  hidden = 0,
+): { refused: string; param: number } | undefined {
+  const laid = layOutByValue(p, target, hidden);
+  return laid !== undefined && 'refused' in laid ? laid : undefined;
+}
+
+/** `hidden` is the argument words ahead of the declared list — 1 for a call handed a hidden
+ *  struct-return pointer in argument 0 — which the even-word rule counts and `widths` leaves out. */
+function layOutByValue(p: FnProto | undefined, target: TargetDescription, hidden: number): ByValueLayout | undefined {
+  if (!Array.isArray(p?.params)) {
+    return undefined;
+  }
+  const params = p.params;
+  const first = params.findIndex((_, i) => paramClassOf(p, params, i) === 'by-value');
+  if (first < 0) {
+    return undefined;
+  }
+  if (!target.compilerBehaviors.byValueAggregateArgWords) {
+    return { refused: 'this target states no rule for which argument words carry one', param: first };
+  }
+  const widths: number[] = [];
+  const doubles = new Set<number>();
+  const byValue: ByValueArg[] = [];
+  for (const [i, t] of params.entries()) {
+    if (paramClassOf(p, params, i) === 'by-value') {
+      const layout =
+        p.byValueLayouts !== undefined && Object.hasOwn(p.byValueLayouts, i) ? p.byValueLayouts[i] : undefined;
+      if (layout === undefined) {
+        return { refused: 'the declaration does not lay it out (a context does, by defining the struct)', param: i };
+      }
+      const spelling = t
+        .replace(/\b(?:const|volatile)\b/g, ' ')
+        .trim()
+        .replace(/\s+/g, ' ');
+      const tag = /^(?:struct\s+)?([A-Za-z_]\w*)$/.exec(spelling)?.[1];
+      const type = tag === undefined ? undefined : aggregateType(tag, spelling, layout, target);
+      if (type?.kind !== 'struct' || type.size === undefined) {
+        return { refused: 'it is a union, or has a member this target does not size', param: i };
+      }
+      // A STRUCT OF NO BYTES (GNU C's `struct E { };`) occupies no argument word, so it would be an
+      // argument with no operand to name it, and the fold that names the struct has none to read.
+      if (type.size === 0) {
+        return { refused: 'it has no members, so no argument word carries it', param: i };
+      }
+      // An 8-aligned struct starts at an even argument word where the target aligns one
+      // (`evenWordAlignedArgs`). Placed at an even word that changes nothing; placed at an odd
+      // one, the skipped word would be an argument operand nothing passes, so that one refuses.
+      // The word is counted from argument 0, a hidden struct-return pointer included: O32's
+      // `struct S8 f(s32 k, struct L l)` passes `l` in a2:a3, and `struct S8 f(struct L l)` skips a1.
+      if (
+        target.evenWordAlignedArgs === true &&
+        (aggregateSize(layout, target)?.align ?? 0) >= 8 &&
+        (hidden + wordsOf(widths, target)) % 2 === 1
+      ) {
+        return {
+          refused:
+            'it is aligned to 8 and would start at an odd argument word, which this target skips — an argument word left empty is not modelled',
+          param: i,
+        };
+      }
+      const words = Math.ceil(type.size / 4);
+      byValue.push({ param: i, word: widths.length, words, type });
+      widths.push(...Array.from({ length: words }, () => 32));
+      continue;
+    }
+    const one = declaredCallArgs({ params: [t], wordParams: p.wordParams?.includes(i) ? [0] : [] }, target);
+    if (one === undefined) {
+      return {
+        refused: `its parameter ${i + 1} '${t}' is not sized, so where the struct starts is not known`,
+        param: first,
+      };
+    }
+    if (one.doubles.size > 0) {
+      doubles.add(widths.length);
+    }
+    widths.push(...one.widths);
+  }
+  return { widths, doubles, byValue };
+}

package/src/backend/c.ts

@@ -6,15 +6,19 @@
 // this backend owns only the C SIGNATURE line. The Pascal backend implements the same
 // LanguageBackend interface over the same L3 with its OWN spelling.
 import { LanguageBackend, SFn } from '../l3/ast';
-import { cComment, cType, emitCFamily } from './cfamily';
+import { cComment, cDeclare, cType, emitCFamily } from './cfamily';
 
 export { cComment }; // re-export: the shared spelling lives in cfamily.ts
 
 export const cBackend: LanguageBackend = {
   id: 'c',
   spellsSwitchFallthrough: true,
+  spellsSwitchBreak: true,
   emit(fn: SFn): string {
-    const params = fn.params.map((p) => `${cType(p.type)} ${p.name}`).join(', ') || 'void';
+    // The SAME declarator placement the local list and the struct-field printer use, so one
+    // function cannot spell the `*` on the type in its signature and on the declarator in its
+    // body.
+    const params = fn.params.map((p) => cDeclare(p.type, p.name)).join(', ') || 'void';
     return emitCFamily(`${cType(fn.retType)} ${fn.name}(${params})`, fn);
   },
   comment: cComment,