@asmlift/core 0.9.0 → 0.11.0

package/README.md

@@ -94,25 +94,25 @@ 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` 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 a read of a map-declared volatile object), `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| 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` (toolchain compiles → `@match-kit/scoring`, the in-process pinned objdiff engine, fail-closed)
@@ -125,14 +125,15 @@ 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),
+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 lifts an
+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 declines the rest; 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),
+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 —

package/package.json

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

package/src/aggregate.ts

@@ -9,9 +9,14 @@ import {
   type FnProto,
   type Prototypes,
   STANDARD_SIGNATURES,
+  declaredCallArgs,
   declaredWidth,
   declaresAggregateReturn,
   declaresVoidReturn,
+  ownArgumentWords,
+  ownLeadingWordParams,
+  paramClassOf,
+  wordsOf,
 } from './proto';
 import type { TargetDescription } from './target';
 
@@ -151,6 +156,28 @@ 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. */
@@ -159,6 +186,9 @@ export function returnsInMemory(layout: AggregateLayout, target: TargetDescripti
   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;
@@ -246,3 +276,122 @@ export function returnsWithoutHiddenPointer(
   }
   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

@@ -13,6 +13,8 @@ export { cComment }; // re-export: the shared spelling lives in cfamily.ts
 export const cBackend: LanguageBackend = {
   id: 'c',
   spellsSwitchFallthrough: true,
+  spellsSwitchBreak: true,
+  spellsEarlyReturn: true,
   emit(fn: SFn): string {
     // 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