@asmlift/core 0.8.1 → 0.10.0

package/src/ir/core.ts

@@ -56,8 +56,101 @@ export interface Fn {
   /** L1 SIDE DATA (see {@link ParamEvidence}); set by the SSA builder, `undefined` on parsed IR.
    *  REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` and `slotHomes` are. */
   paramEvidence: ParamEvidence | undefined;
+  /** L1 SIDE DATA (see {@link LocalObjects}); set by a frontend that recovered one, `undefined` on
+   *  every other `Fn`. REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` is. */
+  localObjects: LocalObjects | undefined;
 }
 
+/** Where a function-scope static lives, which decides how its definition is spelled: `rodata` is
+ *  `const` with an initializer, `data` has an initializer, `bss` has none. */
+export type LocalObjectSection = 'rodata' | 'data' | 'bss';
+
+/** One function-scope static, as the target defines it (frontend/local-object.ts). */
+export interface LocalObject {
+  /** the name the source wrote — the linker name without the compiler's counter */
+  name: string;
+  /** the linker name the target carries (`tide.3`, `sprHideTbl$797`) */
+  symbol: string;
+  /** the counter in that name, which is the order the source declared the function's statics in
+   *  (frontend/reloc-symbol.ts `localStaticName`) */
+  order: number;
+  section: LocalObjectSection;
+  /** bytes */
+  size: number;
+  /** the initial contents in target byte order; absent exactly for a `bss` object */
+  bytes?: Uint8Array;
+  bigEndian: boolean;
+  /** What an assembler LISTING shows of an initialized definition beyond its bytes, absent where
+   *  the target is an object file, which keeps no directives. */
+  directives?: LocalObjectDirectives;
+  /** What an object FILE records of where the object sits, absent for an assembler listing, whose
+   *  `.align` is among its directives. */
+  placement?: LocalObjectPlacement;
+  /** Every address the initializer holds, in offset order — the words a relocation fills in at
+   *  link time, which the bytes alone do not carry. Absent for an object holding none. The bytes
+   *  under one say nothing: the relocation's `addend` is the whole of it. */
+  relocs?: readonly LocalObjectReloc[];
+  /** The object is the compiler's own, under a label the source never wrote (agbcc's `.LC0`): the
+   *  constant image a local aggregate's initializer is copied from. `name` is then the label, no
+   *  declaration spells it, and it reaches the C only as that local's initializer
+   *  (l3/constinit.ts). */
+  anonymous?: true;
+}
+
+/** The bytes of every address an initializer holds ({@link LocalObjectReloc}): a pointer's, on every
+ *  target whose initializers the frontends relocate (agbcc's `.word sym`, mwcc's `R_PPC_ADDR32`). */
+export const LOCAL_OBJECT_ADDRESS_BYTES = 4;
+
+/** One address an initializer holds: the pointer-width word at byte `offset` of the object is
+ *  `symbol`'s address plus `addend` — an ordinary global's, the only kind a declaration outside the
+ *  function can name (frontend/reloc-symbol.ts). */
+export interface LocalObjectReloc {
+  offset: number;
+  symbol: string;
+  addend: number;
+}
+
+/** What an object file records of where a static sits. */
+export interface LocalObjectPlacement {
+  /** the alignment the compiler gave the object (mwcc's `.comment` record for its symbol) */
+  align: number;
+  /** the object file's own section (`.sbss`, where {@link LocalObject.section} says `bss`) */
+  section: string;
+  /** its offset in that section */
+  offset: number;
+}
+
+/** An initialized static's data directives, as the compiler wrote them. The compiler writes each
+ *  scalar of the initializer with the directive of its width, and aligns the object to its type's
+ *  alignment; both are facts about the source's TYPE that the bytes alone have lost. */
+export interface LocalObjectDirectives {
+  /** the alignment the object was placed at, in bytes (`.align N` ahead of the label: 2^N; none: 1) */
+  align: number;
+  /** the width every value directive writes, when they all agree (`.word` → 4); padding does not count */
+  unit?: number;
+  /** the directives share a `unit` narrower than a word and one wrote a negative value, which the
+   *  compiler only does for a signed element type */
+  negative: boolean;
+  /** every value directive writes a string (`.ascii`), as the compiler writes a string literal —
+   *  whole, or as the elements of an array or struct of strings */
+  string: boolean;
+  /** every run of padding among the value directives, as [byte offset, byte length], when there
+   *  is one: in an array, the elements its brace initializer left out — the compiler writes every
+   *  element the source spelled, zero or not, as a value, and each run it left out as a `.space`
+   *  (varasm.c `output_constructor`), wherever the run falls: after the last value, ahead of the
+   *  first, or between two (a designator, a nested brace's short row). In a struct, alignment too. */
+  gaps?: [number, number][];
+}
+
+/** The function-scope statics a function DEFINES, keyed by {@link LocalObject.symbol} — the object a
+ *  `gaddr` of that name denotes. The IR keeps the linker name because it carries a `.` or `$` that
+ *  no C identifier and no declared symbol has, so a static can never be one name with a global of
+ *  its source name (a symbol map's `tide` beside `tide.3`); structure spells it by its source name.
+ *  A `gaddr` names a symbol some declaration elsewhere describes; these have none, because the
+ *  source defined them inside the function, so the definition travels with the function to the
+ *  emitter, which writes it in the body (structure/local-statics.ts). */
+export type LocalObjects = ReadonlyMap<string, LocalObject>;
+
 /** What the machine's own object shows about each ENTRY PARAMETER, beyond the value graph — two
  *  observations the lift destroys, recorded so raise/paramwidth.ts can read them. Every entry
  *  parameter of a lifted function has an entry; a `Fn` with no map is one nobody measured.
@@ -67,15 +160,19 @@ export interface Fn {
  *  `compilerBehaviors.narrowParamWitness` decides what the pair means, and the disassemblies for
  *  each value live there.
  *
- *  `deadHome` — THE STORE DOES NOT REACH THE IR. Both slot-modelling frontends spell a word
+ *  `deadHome` — THE STORE DOES NOT REACH THE IR. Every slot-modelling frontend spells a word
  *  sp-relative store as a write to the SSA key `sp@k` instead of a `store` op (`stackSlotKey`), so
- *  a slot nothing reloads has no reader, no op and no value: it simply is not there by L1. A
+ *  a slot nothing reloads has no reader, no op and no value: it simply is not there by L1. MIPS and
+ *  Thumb lift such a store. PowerPC refuses it, because an unread slot store may be a call's
+ *  outgoing stack argument; in a function that makes no call, mwcc's local area takes such a store
+ *  as a store to a frame object instead of a slot (frontend/ppc.ts `measurePpcFrame`). Either way a
+ *  PowerPC lift never reports a dead home. A
  *  parameter stored to two slots, one of them reloaded, still counts — the dead store happened —
  *  and the reader's own gates decide what a parameter with that much traffic may become.
  *
  *  It asks NO FRAME PARTITION, and that is the difference from {@link SlotHomes}. A slot home is a
  *  DECLARATION RANK, so `sp@40` had to be classified as this function's local before it could be
- *  stamped, and MIPS declares no partition and so stamps none. "Stored here and never read back"
+ *  stamped, and MIPS declares no `declaredLocals` and so stamps none. "Stored here and never read back"
  *  needs no such classification: it is a statement about the store, true at any offset.
  *
  *  `selfRedefined` — THE REGISTER IDENTITY DOES NOT REACH THE IR EITHER. SSA renames, so nothing
@@ -111,7 +208,7 @@ export type ParamEvidence = ReadonlyMap<Value, ParamObservation>;
  *  A KEY IS NOT A FRAME COORDINATE, and the frontends differ on exactly that. `sp@40` is a local
  *  on one ABI and the caller's fifth argument on another, so the shared stamp asks the frontend's
  *  own `LiveInModel.declaredLocals` and refuses an offset outside it — Thumb declares a range,
- *  MIPS and PPC declare no partition and so stamp nothing. An entry here therefore means "storage
+ *  MIPS and PPC declare none and so stamp nothing. An entry here therefore means "storage
  *  this function DECLARES, homed at k", not "some sp-relative key".
  *
  *  DECLARES, NOT OWNS, AND THE DIFFERENCE IS AN AGBCC FACT WITH A LIVE DEPENDENCY: `ownedLocals`,
@@ -216,6 +313,35 @@ export function foldWriteOrder(order: WriteOrder | undefined, from: Block, into:
   order.writes.set(into, base + (order.writes.get(from) ?? 0));
 }
 
+/** The `laddr` attribute that marks a function's OWN struct return object: the local its hidden
+ *  struct-return pointer became, or the one its struct returned in a register is built in
+ *  (frontend/own-struct-return.ts). Neither lives in this frame, so no frame offset names it and
+ *  its `off` means nothing. */
+export const OWN_RETURN_OBJECT = 'returned';
+
+/** The `call` attribute of L1 that says its result is the IMAGE of a struct its callee is declared
+ *  to return in the return register (frontend/call-plan.ts `registerStructLocal`): a word the
+ *  frontend reads as any call's, which `liftRegisterStructCalls` (frontend/register-struct-call.ts)
+ *  turns into the struct assigned to a local and re-read off it. No call carries it past that.
+ *  `true`, or {@link STRUCT_HOMED} where the frontend saw the image stored to a frame home. */
+export const REGISTER_STRUCT = 'registerStruct';
+
+/** The value of {@link REGISTER_STRUCT} on a call whose image the function stores to a frame word
+ *  (frontend/ppc.ts): mwcc gives a struct the source names a home, read or not, and one the source
+ *  only returns none — `struct T s = mk(1); return s;` is `bl mk; stw r3,8(r1)`, `return mk(1);` is
+ *  `bl mk` alone. */
+export const STRUCT_HOMED = 'homed';
+
+/** The `laddr` attribute that marks the local a struct returned in a register is assigned to
+ *  (frontend/register-struct-call.ts), holding the callee's name, which names the local. The
+ *  struct lives in the return register, not in this frame, so no frame offset names it and its
+ *  `off` means nothing, as for {@link OWN_RETURN_OBJECT}. */
+export const CALL_RETURN_OBJECT = 'callReturned';
+
+/** The `ret` attribute that says it hands back the {@link OWN_RETURN_OBJECT} whole, by value: its
+ *  operand is that object's address, and the C returns the object. */
+export const RETURNS_OBJECT = 'returnsObject';
+
 export function mkValue(type: IrType): Value {
   return { type };
 }
@@ -230,6 +356,46 @@ export function mkOp(opcode: Opcode, o: Partial<Op> = {}): Op {
   };
 }
 
+// ── a call's callee: a NAME (`attrs.target`) or, for a call through a register, a VALUE ─────────
+//
+// An INDIRECT call carries `indirect: true` and no `target`, and calls the function whose address
+// is its LAST operand. The arguments come first on both forms, so `operands[k]` is argument k on
+// either and a reader that indexes an argument needs no case; a reader that takes the WHOLE operand
+// list as the arguments must go through `callArgs`.
+
+/** The function an indirect call calls, or undefined for a call that names its callee. */
+export function calleeValue(op: Op): Value | undefined {
+  return op.opcode === 'call' && op.attrs.indirect === true ? op.operands[op.operands.length - 1] : undefined;
+}
+
+/** The callee a call names, or undefined for an indirect one. */
+export function calleeName(op: Op): string | undefined {
+  return op.opcode === 'call' && typeof op.attrs.target === 'string' ? op.attrs.target : undefined;
+}
+
+/** The operands a call passes a struct BY VALUE (frontend/call-plan.ts `foldByValueArgs`): each
+ *  one's place in the operands and the declared parameter it is. The two differ by more than a
+ *  hidden return pointer wherever a parameter before it takes two operands, so the parameter is
+ *  carried rather than re-derived. */
+export function byValueOperands(op: Op): { at: number; param: number }[] {
+  const pairs = op.opcode === 'call' ? ((op.attrs.byValue as number[] | undefined) ?? []) : [];
+  return Array.from({ length: pairs.length / 2 }, (_, i) => ({ at: pairs[2 * i], param: pairs[2 * i + 1] }));
+}
+
+/** A call's arguments, the callee value of an indirect call aside. */
+export function callArgs(op: Op): Value[] {
+  return calleeValue(op) === undefined ? op.operands : op.operands.slice(0, -1);
+}
+
+/** Cut a call down to its first `n` arguments, keeping an indirect call's callee. */
+export function truncateCallArgs(op: Op, n: number): void {
+  const callee = calleeValue(op);
+  op.operands.length = n;
+  if (callee !== undefined) {
+    op.operands.push(callee);
+  }
+}
+
 /** A block's last op — its terminator on well-formed IR, `undefined` on a block with no ops.
  *
  *  `ir/verify.ts` rejects an empty block and every entry path verifies before raising, so the
@@ -290,6 +456,33 @@ export function reachableBlocks(fn: Fn): Set<Block> {
   return seen;
 }
 
+/** The blocks `from` reaches along FORWARD edges — never a back-edge, whose target dominates its
+ *  source — `from` itself included. A block of `stop` is reached but not walked past.
+ *
+ *  Forward only, so an enclosing loop's next iteration does not count: the exit of a loop nested in
+ *  another reaches every block of the inner body round the outer back-edge, and a full walk would
+ *  say it runs the inner loop's own arms. Two passes ask "does a loop's exit run this block":
+ *  `raise/latch.ts`'s exit-trampoline scope gate and `structure.ts`'s `offExitPathOf` (the
+ *  duplication policy `codeBreakArm` and `earlyReturnArm` share). */
+export function reachForward(
+  from: Block,
+  dom: ReadonlyMap<Block, ReadonlySet<Block>>,
+  stop: ReadonlySet<Block> = new Set(),
+): Set<Block> {
+  const seen = new Set<Block>();
+  for (const stack = [from]; stack.length > 0;) {
+    const x = stack.pop()!;
+    if (seen.has(x)) {
+      continue;
+    }
+    seen.add(x);
+    if (!stop.has(x)) {
+      stack.push(...successorsOf(x).filter((s) => !dom.get(x)!.has(s)));
+    }
+  }
+  return seen;
+}
+
 /** Predecessor map for the whole function's CFG. */
 export function predecessors(fn: Fn): Map<Block, Block[]> {
   const preds = new Map<Block, Block[]>();
@@ -307,7 +500,7 @@ export function predecessors(fn: Fn): Map<Block, Block[]> {
 /** Forward dominators (iterative data-flow). dom(b) = {b} ∪ ⋂ dom(preds).
  *
  *  A CFG fact, so it lives beside `predecessors` it is built on rather than with either consumer:
- *  `verify` needs it to check def-dominates-use, `structure/loops.ts` to tell a back-edge from a
+ *  `verify` needs it to check def-dominates-use, `ir/loops.ts` to tell a back-edge from a
  *  forward one, and `raise/latch.ts` to tell a latch from a preheader. */
 
 export function dominators(fn: Fn): Map<Block, Set<Block>> {
@@ -412,7 +605,7 @@ export function forwardingTarget(b: Block): Block {
  *  a CFG fact a parameter for one caller's extra edges — so it stays where it is, and what this
  *  paragraph buys is that the next reader looking for a fourth copy knows which of the two the
  *  third one is. */
-export function mergeClasses(fn: Fn): Map<Value, readonly Value[]> {
+export function mergeClasses(fn: Pick<Fn, 'blocks'>): Map<Value, readonly Value[]> {
   const parent = new Map<Value, Value>();
   const find = (v: Value): Value => {
     let r = v;

package/src/ir/discipline.ts

@@ -0,0 +1,313 @@
+// asmlift IR — the access discipline: which ops the recompile must run where, and as often as, the
+// asm ran them, and the questions every pass asks about that.
+//
+// Two kinds of fact meet here. The registry's flags (ir/opcodes.ts `OpSig`: `effects`, `reads`,
+// `traps`) are facts about an OPCODE. A PLACEMENT is a fact about one OP, decided once by the pass
+// that knew it: `call` is its own opcode; `helper` is the stamp `runtime-helpers.ts` `helperOp` puts
+// on a value op the asm computed by calling a runtime routine; `device` is the `volatile` a frontend
+// puts on a memory access, decided by two pins — the device pin (frontend/device-pins.ts), for an
+// access of a device register, and the dead-read pin (frontend/dead-reads.ts), for a read at ANY
+// address whose value the lifted function never uses; `declared` is the
+// stamp raise/declared-volatile.ts puts on an access of an object the symbol map declares volatile —
+// a read only where the compiler could have made it of a `volatile` — as the lift is made and again
+// when structuring starts. Every question below takes the op, so a pass
+// asks one question instead of re-deriving the combination, and `PLACEMENT_ANSWERS` is the one
+// place a placement's answers are written, the attrs a rebuilt op carries it by among them.
+//
+// A new placement is three edits: its `Placement` member with a `PLACEMENT_ANSWERS` row, the
+// `placedAt` clause that reads its stamp, and its key in contracts.ts `assertEffectsPreserved`,
+// whose switch over `placedAt` does not compile until the member is keyed or answered as uncounted.
+//
+// NAMED RESIDUE. The sites below ask a registry question where a placement could change the answer,
+// and keep the registry's answer. DELIBERATE: the placement does not bear on what the site asks.
+// GAP: it does, and some input gets a wrong answer.
+//
+//   `speculationUnsafe` answers no for a plain read — DELIBERATE, argued at the function — and for
+//   a trapping divide — GAP: raise/shortcircuit.ts hoists one the structurer may name above its guard.
+//   A QUALIFIED read is one `qualified` answers yes for.
+//   Two qualified reads commuting (`orderSensitive` without `effectful` on either side):
+//     pattern/engine.ts `reordersUnsequenced` — DELIBERATE: the structurer's barrier scan names the
+//       first of two qualified reads the fold would join in one expression.
+//     structure/hazards.ts `movesPast` — DELIBERATE: the analysis names a qualified read another
+//       qualified read stands between it and its render, so the scan never weighs two.
+//   `effectful` as the barrier a read may not cross, without `isBarrier`'s helper and qualified-read
+//   clauses (structure/analysis.ts):
+//     structure/analysis.ts `writeBetween`, `standsOnMovableRead`, the multi-render rule — DELIBERATE:
+//       each asks about a memory write, and a qualified read writes nothing.
+//   The `call` placement alone, in structure/analysis.ts:
+//     `callPos` — DELIBERATE: it asks which values live across the registers a call clobbers.
+//     `readCone`, `isHomeableDef`, `copyInterdependentValues` — DELIBERATE: a qualified read is a
+//       `load` there, which each already stops at.
+//   `effectful` as block purity — structure.ts's exit ownership, preheader claim, header purity,
+//   copied `ret` target, `ends` and latch effect roots; structure/hazards.ts `testSkipsAnEffect`;
+//   structure/redundant-test.ts `testRereadsOnly` — DELIBERATE: a qualified read renders with its
+//   block, once on each path that runs the block, or declines upstream.
+//     raise/divpow2.ts's bias arm — GAP: the arm is deleted, and a dead qualified read in it with it.
+//   And three accesses the deciders leave unplaced, where a placement would change an answer — GAP:
+//     a device store a pinned read of the same cell re-reads in a loop, under the per-object policy
+//       (frontend/device-pins.ts's header argues it);
+//     a read of a map-declared volatile object through a base that reaches no name — a pointer
+//       walked along the object in a loop, a join of two different addresses in it
+//       (raise/declared-volatile.ts);
+//     a read the stamp cannot place by byte — a runtime index, an `aload` — of an object the map
+//       qualifies only some members of, which may reach a plain member (symbols.ts
+//       `declaresVolatile`).
+import type { Block, Op, Value } from './core';
+import { MEM_BASE_OPS, type OpSig, opSig } from './opcodes';
+
+/** Why an op must run where the asm ran it. */
+export type Placement = 'call' | 'helper' | 'device' | 'declared';
+
+/** Where a qualified access's spelling carries its `volatile`: on a cast of its own address, or
+ *  through the declaration of the object it names. */
+export type Qualifier = 'cast' | 'declaration';
+
+/** The attr raise/declared-volatile.ts stamps a `declared` access with. */
+export const DECLARED_VOLATILE = 'declaredVolatile';
+
+interface PlacementAnswers {
+  /** spelled even when nothing reads the result */
+  keptWhenDead: boolean;
+  /** never run on a path that did not run it */
+  speculationUnsafe: boolean;
+  /** each render is one more execution, so it renders once on every path the asm ran it on */
+  counted: boolean;
+  /** an access whose spelling must carry `volatile`, and where it carries it */
+  qualifiedBy: Qualifier | null;
+  /** the attrs that put this placement on an op a pass builds to stand for `from` */
+  carried: (from: Op) => Op['attrs'];
+}
+
+const PLACEMENT_ANSWERS: Readonly<Record<Placement, PlacementAnswers>> = {
+  // The registry's `effects` flag gives a call the first two answers on its own, and its opcode is
+  // its placement, which an op built to stand for it does not inherit.
+  call: { keptWhenDead: true, speculationUnsafe: true, counted: true, qualifiedBy: null, carried: () => ({}) },
+  // The value the helper computes is pure: nothing observes a divide nobody reads, a fold that
+  // moves one under a guard drops the stamp (`forgetHelperPlacement`), and agbcc computes one
+  // spelled twice once (`a / n + a / n` is one `bl __divsi3`).
+  helper: {
+    keptWhenDead: false,
+    speculationUnsafe: false,
+    counted: false,
+    qualifiedBy: null,
+    carried: (from) => ({ helper: from.attrs.helper }),
+  },
+  // The access is what is observable, not the value it yields, so its spelling is qualified.
+  device: {
+    keptWhenDead: true,
+    speculationUnsafe: true,
+    counted: true,
+    qualifiedBy: 'cast',
+    carried: () => ({ volatile: true }),
+  },
+  declared: {
+    keptWhenDead: true,
+    speculationUnsafe: true,
+    counted: true,
+    qualifiedBy: 'declaration',
+    carried: () => ({ [DECLARED_VOLATILE]: true }),
+  },
+};
+
+/** Every placement stamp an op carries, the one that places it first. An op can carry two: a read
+ *  of an object the map declares volatile is `declared` and, kept by the lift's own pin (frontend/
+ *  dead-reads.ts, frontend/device-pins.ts), `device` too.
+ *
+ *  A declaration that qualifies the object places the access before a lift's own stamp does: both
+ *  say the access is `volatile`, and the declaration is the spelling the source used, so the
+ *  access counts and spells as the object's (raise/declared-volatile.ts re-derives it per map, and
+ *  under a map that declares nothing the lift's stamp places it again — which is why a rebuild
+ *  carries both, `carryDiscipline`). */
+function stampsOf(op: Op): Placement[] {
+  if (op.opcode === 'call') {
+    return ['call'];
+  }
+  const stamps: Placement[] = [];
+  if (MEM_BASE_OPS.has(op.opcode) && op.attrs[DECLARED_VOLATILE] === true) {
+    stamps.push('declared');
+  }
+  if (MEM_BASE_OPS.has(op.opcode) && op.attrs.volatile === true) {
+    stamps.push('device');
+  }
+  // An `opaque` carries `helper` too, naming the call nothing could fold (`refuseUnmodelledHelpers`);
+  // it is no value op, and its `effects` flag already places it.
+  if (op.opcode !== 'opaque' && typeof op.attrs.helper === 'string') {
+    stamps.push('helper');
+  }
+  return stamps;
+}
+
+/** The placement an op carries, or null for an op that may render wherever its value is used. */
+export function placedAt(op: Op): Placement | null {
+  return stampsOf(op)[0] ?? null;
+}
+
+const answered = (op: Op, q: 'keptWhenDead' | 'speculationUnsafe' | 'counted'): boolean => {
+  const p = placedAt(op);
+  return p !== null && PLACEMENT_ANSWERS[p][q];
+};
+
+/** Where this access's spelling carries the `volatile` the recompile needs to make it where, and as
+ *  often as, the asm did — or null for an op whose spelling needs none. A spelling through the
+ *  declaration needs a cast's qualifier too wherever it reaches the object through a cast, since a
+ *  cast's pointee drops the declaration's qualifiers (l3/volstore.ts `castOffDeclaration`). */
+export function qualifiedBy(op: Op): Qualifier | null {
+  const p = placedAt(op);
+  return p === null ? null : PLACEMENT_ANSWERS[p].qualifiedBy;
+}
+
+/** Must this access's spelling carry `volatile`? */
+export function qualified(op: Op): boolean {
+  return qualifiedBy(op) !== null;
+}
+
+const sigOf = (op: Op): OpSig | undefined => opSig(op.opcode);
+
+/** Does each render of this op execute it — a call, or a qualified access? Such an op is spelled
+ *  once on every path the asm ran it on, at the position it ran: named where a second use, an edge
+ *  or another block would render it again or elsewhere. */
+export function counted(op: Op): boolean {
+  return answered(op, 'counted');
+}
+
+/** Has an observable side effect: a memory write, a call, an unmodelled instruction. The question a
+ *  block-purity test asks, and the write a memory read may not cross. */
+export function effectful(op: Op): boolean {
+  return sigOf(op)?.effects === true;
+}
+
+/** May a dead result be deleted? Registered, no effect, not control flow, and not an op whose
+ *  placement keeps it. A memory read whose value the RAW lift never uses is never asked: the
+ *  frontend stamps it `volatile` first (frontend/dead-reads.ts), because a compiler deletes every
+ *  plain read nobody uses, so one still in the target was qualified. What reaches this question
+ *  plain is a read only asmlift's own rewrites orphaned, or one that pass's gates refused. */
+export function deletableWhenDead(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && !sig.effects && !sig.terminator && !answered(op, 'keptWhenDead');
+}
+
+/** THE DEAD OPS of these blocks: each op `deletableWhenDead` answers yes for whose single result no
+ *  op outside the set reads, as an operand or as a successor's argument, to a fixed point. The ONE
+ *  definition of dead: pattern/engine.ts `dce` deletes exactly this set, and the dead-read pin
+ *  (frontend/dead-reads.ts) asks it of the raw lift before anything is deleted, so the pin's "dead"
+ *  cannot drift from what the pass would delete.
+ *
+ *  `usesOperands` says whether an op's operands are uses at all. Every op's are, for `dce`; the pin
+ *  passes the one exception a declaration makes: the `ret` of a function its own prototype declares
+ *  void, whose operand the structurer suppresses (structure/analysis.ts `indexUses`). */
+export function deadOps(blocks: readonly Block[], usesOperands: (op: Op) => boolean = () => true): Set<Op> {
+  const dead = new Set<Op>();
+  let changed = true;
+  while (changed) {
+    changed = false;
+    const used = new Set<Value>();
+    for (const b of blocks) {
+      for (const op of b.ops) {
+        if (dead.has(op)) {
+          continue;
+        }
+        if (usesOperands(op)) {
+          for (const o of op.operands) {
+            used.add(o);
+          }
+        }
+        for (const s of op.successors) {
+          for (const a of s.args) {
+            used.add(a);
+          }
+        }
+      }
+    }
+    for (const b of blocks) {
+      for (const op of b.ops) {
+        if (!dead.has(op) && deletableWhenDead(op) && op.results.length === 1 && !used.has(op.results[0])) {
+          dead.add(op);
+          changed = true;
+        }
+      }
+    }
+  }
+  return dead;
+}
+
+/** Must the structurer still SPELL this op when nothing consumes its result — an effect, or a
+ *  memory read?
+ *
+ *  The read half points the opposite way from `deletableWhenDead`, and both are right. That one is
+ *  the C claim: nothing observes a load nobody reads. This one is the COMPILER claim: an optimizing
+ *  compiler deletes every dead read it is allowed to delete, so one still in the target is evidence
+ *  the source's access was `volatile`. A yes here only says the op may not be dropped silently;
+ *  whether the read was `volatile` is decided once, by the dead-read pin (frontend/dead-reads.ts),
+ *  and the caller spells a read only where it is `qualified` (structure.ts `volatileQualifiable`),
+ *  dropping one the pin left plain.
+ *
+ *  Its own function and not `orderSensitive`, though the two agree on every registered opcode: they
+ *  ask different questions, and a registry change that splits them is a decision to make at each. */
+export function spelledWhenDead(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && (!!sig.effects || !!sig.reads);
+}
+
+/** May this op NOT be speculated — run on a path that did not run it? An effect, or an op whose
+ *  placement forbids it.
+ *
+ *  A plain memory read answers no, and that is the answer worth arguing. The consumer is
+ *  raise/shortcircuit.ts, which hoists an arm's body into the block above, and the structurer
+ *  inlines an unnamed value back into the `&&`/`||` right-hand side, where C's own short circuit
+ *  re-guards it. Answering yes for plain reads refuses every connective whose arm reads memory,
+ *  which branch-shortcircuit.test.ts's `refusals` pin. A qualified read is the read the re-guard
+ *  argument does not cover — it moves an access, not a value — so its placement answers yes.
+ *
+ *  The trapping divides answer no as well, and there the re-guard argument does NOT carry: a hoisted
+ *  `sdiv` the structurer NAMES becomes an unconditional statement. `reevalUnsafe` answers yes for
+ *  them, so the pre-update sink is not exposed to it.
+ *
+ *  THE EXEMPTION IS NOT TRANSFERABLE. A consumer asking "would gcc have speculated this arm above a
+ *  compare", where nothing re-guards anything, must refuse single-load arms (`gcc/jump.c:483`'s
+ *  `! may_trap_p`); `raise/narrowlocal.ts` asks `reevalUnsafe`, and asking this instead loses
+ *  `synthetic:mergeldcast:agbcc` its byte match. Ask this only where a C-level re-guard at the new
+ *  point actually holds. */
+export function speculationUnsafe(op: Op): boolean {
+  return effectful(op) || answered(op, 'speculationUnsafe');
+}
+
+/** Does this op's answer depend on WHERE it runs on one path? An effect (its order against other
+ *  effects is observable) or a memory read (it answers whichever stores ran before it). */
+export function orderSensitive(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && (!!sig.effects || !!sig.reads);
+}
+
+/** May this op NOT be re-evaluated at another program point — order-sensitive, or trapping? The trap
+ *  half separates it from `orderSensitive`: it matters only when the new point can be reached on a
+ *  path the old one was not. A collapsed switch re-renders a test block's ops at their uses, each
+ *  dominated by the def, so on a subset of the original paths — a narrowing, never a speculation —
+ *  and asks `orderSensitive` instead. */
+export function reevalUnsafe(op: Op): boolean {
+  const sig = sigOf(op);
+  return !!sig && (!!sig.effects || !!sig.reads || !!sig.traps);
+}
+
+/** Drop the `helper` placement from an op a pass moves out of the block the asm called it in, and
+ *  return the op. The stamp is read as WHERE the call ran, so an op moved elsewhere must stop
+ *  claiming it and renders as the pure value it computes. raise/shortcircuit.ts hoists a `&&`/`||`
+ *  guarded arm's body above the branch, and there C's short circuit re-guards the op at its use:
+ *  agbcc's `if (a > 0 && k / n != 0)` runs the `bl __divsi3` under the first compare, and named at
+ *  its hoisted def it would divide on the path the `&&` skips. */
+export function forgetHelperPlacement(op: Op): Op {
+  if (placedAt(op) === 'helper') {
+    const { helper: _, ...rest } = op.attrs;
+    op.attrs = rest;
+  }
+  return op;
+}
+
+/** `attrs`, plus every placement stamp of `from`, for an op a pass builds to stand for `from`: a
+ *  memory access keeps its `volatile` and its `declared` stamp, a value op its `helper`. Every op
+ *  rebuilder carries the stamps through here, so a placement decided once is not lost to a rebuild
+ *  that forgot to copy it. EVERY stamp, not only the one that places the op: a read carrying both
+ *  `declared` and `device` that kept only `declared` would be left plain — and deleted as dead — by
+ *  a later stamp that no longer finds the declaration. */
+export function carryDiscipline(from: Op, attrs: Op['attrs']): Op['attrs'] {
+  return stampsOf(from).reduce((acc, p) => ({ ...acc, ...PLACEMENT_ANSWERS[p].carried(from) }), attrs);
+}