@asmlift/core 0.8.1 → 0.10.0

package/src/structure/local-statics.ts

@@ -0,0 +1,517 @@
+// asmlift — the C DEFINITION of each function-scope static a function names (ir/core.ts
+// `LocalObjects`), typed from the target's own definition and the accesses the function makes.
+//
+// The frontend hands over what the target shows: section, size and bytes, and where the target is
+// an assembler listing (agbcc's `.s`) the definition's directives too. Those say the element: the
+// compiler writes each scalar of the initializer with the directive of its width, so a table of
+// `.short`s is one of 16-bit elements whatever the function reads out of it, and a narrow negative
+// value is only ever written for a signed type. An object file (mwcc) shows no directives, and
+// there the element is the one width every access agrees on. The loads of the element's width then
+// settle its signedness — they are what the function computes, and a byte holds the same bits
+// declared either way, so they outrank a negative the source wrote through another type (a struct's
+// signed field, a cast) — and the definition settles it where no load does. An object nothing says
+// anything about is bytes.
+//
+// The target also shows the ALIGNMENT — the listing's `.align`, mwcc's `.comment` record — which
+// decides where the object lands after the statics declared before it, and whether a DMA or GX
+// buffer is where the hardware needs it. The definition this pass picks gets its compiler's own
+// alignment, which the target declares ({@link StaticLayout}): a scalar to its width, an array to
+// its element or the compiler's aggregate floor, a string literal to the compiler's string
+// alignment. A target aligned wider — a struct, an `s64`, an `ALIGNED(32)` — keeps that alignment
+// in an attribute, because a table one element off is misread by the machine and scored as a
+// MATCH. A byte array the listing wrote as strings and placed at the string alignment is spelled
+// with a string literal, which is what gives it that alignment.
+//
+// The definition is a SymbolInfo as well as a declaration, because the structurer spells an access
+// through a symbol's declared shape (`tide[i]` for an array, the bare `q` for a scalar): the shape
+// it spells against and the object the backend defines are one reading of the same facts. Both are
+// keyed by the LINKER name the IR carries (`tide.3`), and the finished tree is renamed to the
+// source's (`tide`) in one step, `nameLocalStatics`, which is where a clash between that name and
+// anything else the function names can first be seen whole.
+//
+// An element the target RELOCATES holds an address — a table of function pointers, of data
+// pointers, of `&arr[k]` — and is spelled as the address constant it is, `(u32)&sym` or
+// `(u32)((u8 *)&sym + k)`, in the integer element the rest of this typing picks: such an element
+// compiles to the same word and the same relocation as the pointer-typed source (agbcc and mwcc,
+// compiled), so the definition needs no pointer type to put the bytes where the target has them.
+//
+// REFUSES, naming the static, when the target's compiler declares no layout rules, when nothing
+// in the definition settles the width and the accesses disagree on it, when the width is no
+// integer type's or does not divide the size, when the loads disagree on the signedness, when the
+// definition is aligned narrower than its declaration here would be, when a bss static sits where
+// only a scalar initialized to zero is sure to land and it is no scalar (or the input does not
+// show where it sits), when an element holding an address — a static's or the compiler's
+// anonymous image's — is no pointer's width;
+// and, at the rename, when two statics share a source name (one block cannot declare both) or
+// when the function names anything else by it — a global, a callee, a parameter, a local, itself —
+// which the block-scope static would hide — and when a global an initializer holds the address of
+// is hidden there by a static, parameter or local of its name.
+import {
+  type Fn,
+  LOCAL_OBJECT_ADDRESS_BYTES,
+  type LocalObject,
+  type LocalObjects,
+  type Op,
+  type Value,
+  defOpMap,
+} from '../ir/core';
+import { type IrType, T } from '../ir/types';
+import {
+  type Expr,
+  type InitAddress,
+  type SFn,
+  type SImage,
+  type SStatic,
+  type Stmt,
+  mapExprChildren,
+  mapStmtExprs,
+  mapStmtLists,
+  walkExprs,
+} from '../l3/ast';
+import { takenNames } from '../l3/hoist';
+import { type SymbolInfo, accessSignedness } from '../symbols';
+
+/** How a compiler lays out a function-scope static — facts about the COMPILER, declared per target
+ *  (target.ts `compilerBehaviors.staticLayout`), from which the definition that puts a static where
+ *  the target has it follows. */
+export interface StaticLayout {
+  /** the least alignment it gives an array or a struct, whatever the element */
+  aggregateAlign: number;
+  /** the alignment it gives a declaration initialized by a string literal */
+  stringAlign: number;
+  /** where a scalar initialized to zero goes: kept in `.data`, or moved to bss — where its
+   *  initializer is gone, and one element of zero in `.data` must then have been an aggregate */
+  zeroScalar: 'data' | 'bss';
+  /** The bss sections of such a compiler, each laying out the scalars it moved there first, in
+   *  declaration order, and then the statics with no initializer: in reverse declaration order
+   *  (mwcc's `.sbss`: `a = 0; b; c = 0;` at +0, +8, +4), or in the order its code first uses them
+   *  (mwcc's `.bss`: `a; b = 0;` used a first at +4, +0). Either way the offsets say which statics
+   *  sit where only one with the `= 0` is sure to land. */
+  uninitOrder?: Readonly<Record<string, 'reversed' | 'first-use'>>;
+}
+
+/** The bss statics of `objs` to write `= 0` ({@link StaticLayout.uninitOrder}), or
+ *  the symbol of one whose placement the input does not show. In a section of either order a
+ *  function's zero-initialized statics come first, scalars with their counters rising.
+ *
+ *  Where the others follow reversed, a static with a later-declared one at a higher offset had the
+ *  initializer. The last of the rising run cannot be told from the first of the falling one, and
+ *  both declarations put it in the same place: it is left without.
+ *
+ *  Where the others follow by first use, the leading run of `scalarShaped` statics with rising
+ *  counters had it, save that a run that is the whole section leaves its last without, which lands
+ *  after the rest either way. Any of that run may have had none and been used first, and the `= 0`
+ *  puts it where it was, which the candidate's code would decide otherwise. */
+function zeroInitialized(
+  objs: readonly LocalObject[],
+  uninitOrder: NonNullable<StaticLayout['uninitOrder']>,
+  scalarShaped: (o: LocalObject) => boolean,
+): Set<string> | { symbol: string } {
+  const out = new Set<string>();
+  const bss = objs.filter((o) => o.section === 'bss');
+  for (const o of bss) {
+    if (o.placement === undefined) {
+      return { symbol: o.symbol };
+    }
+  }
+  for (const [section, order] of Object.entries(uninitOrder)) {
+    const run = bss
+      .filter((o) => o.placement!.section === section)
+      .sort((a, b) => a.placement!.offset - b.placement!.offset);
+    if (order === 'reversed') {
+      for (const o of run) {
+        if (run.some((p) => p.placement!.offset > o.placement!.offset && p.order > o.order)) {
+          out.add(o.symbol);
+        }
+      }
+      continue;
+    }
+    let lead = 0;
+    while (lead < run.length && scalarShaped(run[lead]) && (lead === 0 || run[lead].order > run[lead - 1].order)) {
+      lead++;
+    }
+    for (const o of run.slice(0, lead === run.length ? lead - 1 : lead)) {
+      out.add(o.symbol);
+    }
+  }
+  return out;
+}
+
+/** Each static's shape for the structurer, and its definition for the backend. */
+export interface LocalStaticShapes {
+  infos: Map<string, SymbolInfo>;
+  statics: SStatic[];
+  /** the compiler's anonymous constant images, which no declaration spells (l3/constinit.ts) */
+  images: SImage[];
+}
+
+/** One access through a static's address: the width it reads or writes, and a load's extension. */
+interface Access {
+  width: number;
+  signed?: boolean;
+}
+
+/** The width an `aload`/`astore` reads or writes. Its `elemSize` is the element's, which for an
+ *  element of a struct array (raise/struct-arrays.ts, `fieldOff`) is the STRIDE: the access itself
+ *  is the field's, whose type the base's struct carries. Null for a field that type does not hold. */
+function indexedWidth(op: Op): number | null {
+  const fieldOff = op.attrs.fieldOff as number | undefined;
+  if (fieldOff === undefined) {
+    return op.attrs.elemSize as number;
+  }
+  const bt = op.operands[0].type;
+  const field = bt.kind === 'ptr' && bt.to.kind === 'struct' ? bt.to.fields.find((f) => f.off === fieldOff) : undefined;
+  return field !== undefined && field.type.kind === 'int' ? field.type.width / 8 : null;
+}
+
+/** Every access through each static's address. */
+function accessesOf(fn: Fn, names: ReadonlySet<string>): Map<string, Access[]> {
+  const defs = defOpMap(fn);
+  /** the static an address is computed from — its `gaddr`, through adds of anything else */
+  const baseOf = (v: Value, seen = new Set<Value>()): string | null => {
+    const d = defs.get(v);
+    if (d === undefined || seen.has(v)) {
+      return null;
+    }
+    seen.add(v);
+    if (d.opcode === 'gaddr') {
+      return names.has(d.attrs.sym as string) ? (d.attrs.sym as string) : null;
+    }
+    if (d.opcode === 'add' || d.opcode === 'sub') {
+      const found = d.operands.slice(0, d.opcode === 'sub' ? 1 : undefined).map((o) => baseOf(o, seen));
+      const hits = found.filter((f): f is string => f !== null);
+      return hits.length === 1 ? hits[0] : null;
+    }
+    return null;
+  };
+  const out = new Map<string, Access[]>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      const plain = op.opcode === 'load' || op.opcode === 'store';
+      const indexed = op.opcode === 'aload' || op.opcode === 'astore';
+      if (!plain && !indexed) {
+        continue;
+      }
+      const sym = baseOf(op.operands[0]);
+      if (sym === null) {
+        continue;
+      }
+      const width = plain ? (op.attrs.width as number) : indexedWidth(op);
+      if (width === null) {
+        continue;
+      }
+      const isLoad = op.opcode === 'load' || op.opcode === 'aload';
+      const list = out.get(sym) ?? out.set(sym, []).get(sym)!;
+      list.push({
+        width,
+        ...(isLoad ? { signed: accessSignedness(width, op.attrs.signed as boolean | undefined) } : {}),
+      });
+    }
+  }
+  return out;
+}
+
+/** The elements of `obj`'s initial bytes read `width` bytes at a time in its byte order. */
+function elements(obj: LocalObject, width: number, signed: boolean): number[] {
+  const b = obj.bytes!;
+  const out: number[] = [];
+  for (let at = 0; at < obj.size; at += width) {
+    let v = 0;
+    for (let i = 0; i < width; i++) {
+      v = v * 256 + b[obj.bigEndian ? at + i : at + width - 1 - i];
+    }
+    out.push(signed && v >= 2 ** (8 * width - 1) ? v - 2 ** (8 * width) : v);
+  }
+  return out;
+}
+
+/** The width of `obj`'s element: the one its definition's directives write, else the one every
+ *  access agrees on; with no access either, a pointer's where the target relocates a word of it (an
+ *  address table only handed to a callee, on a compiler that writes no directives: mwcc), else the
+ *  whole object where it is aligned below the compiler's aggregate floor, as only a scalar is, and
+ *  a byte where it is not. A relocation the pointer width does not seat is still refused, by the
+ *  caller's check of every relocation's offset. */
+function elementWidth(
+  obj: LocalObject,
+  accesses: readonly Access[],
+  layout: StaticLayout,
+): number | { refused: string } {
+  if (obj.directives?.unit !== undefined) {
+    return obj.directives.unit;
+  }
+  const widths = [...new Set(accesses.map((x) => x.width))];
+  if (widths.length > 1) {
+    return { refused: `whose accesses disagree on its element width (${widths.sort().join(' and ')} bytes)` };
+  }
+  if (widths.length === 1) {
+    return widths[0];
+  }
+  if ((obj.relocs?.length ?? 0) > 0 && obj.size % LOCAL_OBJECT_ADDRESS_BYTES === 0) {
+    return LOCAL_OBJECT_ADDRESS_BYTES;
+  }
+  const shown = obj.directives?.align ?? obj.placement?.align;
+  const scalarOnly = shown !== undefined && shown < layout.aggregateAlign;
+  return scalarOnly && [1, 2, 4].includes(obj.size) ? obj.size : 1;
+}
+
+/** The shape and definition of every static `fn` defines, or the refusal: the static's linker name
+ *  and the tail of the sentence. */
+export function localStaticShapes(
+  fn: Fn,
+  layout: StaticLayout | undefined,
+): LocalStaticShapes | { symbol: string; refused: string } {
+  const objs = fn.localObjects;
+  const infos = new Map<string, SymbolInfo>();
+  const statics: SStatic[] = [];
+  const images: SImage[] = [];
+  if (objs === undefined) {
+    return { infos, statics, images };
+  }
+  if (layout === undefined) {
+    const [first] = objs.keys();
+    return { symbol: first, refused: "whose layout rules this target's compiler does not declare" };
+  }
+  const access = accessesOf(fn, new Set(objs.keys()));
+  const widthOf = (o: LocalObject) => elementWidth(o, access.get(o.symbol) ?? [], layout);
+  /** Declared here as a scalar, or sized and aligned as one — the compiler aligns a scalar to at
+   *  least its width. One declared as an array where only a zero scalar sits is refused below: an
+   *  `s32 = 0` read a byte at a time, or only through its address, lands there as well as four
+   *  bytes used first. */
+  const scalarShaped = (o: LocalObject): boolean =>
+    widthOf(o) === o.size || ([1, 2, 4, 8].includes(o.size) && (o.placement?.align ?? 0) >= o.size);
+  const zeroed =
+    layout.uninitOrder !== undefined
+      ? zeroInitialized([...objs.values()], layout.uninitOrder, scalarShaped)
+      : new Set<string>();
+  if (!(zeroed instanceof Set)) {
+    return { symbol: zeroed.symbol, refused: 'in bss at an offset this input does not show' };
+  }
+  // Declared in the target's declaration order, which the compiler lays the objects out by (mwcc
+  // reverses it in `.sbss` for statics with no initializer), so that the candidate's compiler
+  // places each where the target has it — except mwcc's `.bss` statics with no initializer, which
+  // it places in the order it first uses them: the candidate's code decides that, no declaration.
+  for (const obj of [...objs.values()].sort((a, b) => a.order - b.order)) {
+    const say = (why: string) => ({ symbol: obj.symbol, refused: why });
+    if (obj.anonymous) {
+      // The compiler's own image of a local aggregate's initializer: typed by its directives alone,
+      // since nothing but the copy reads it, and never declared where it sits — l3/constinit.ts
+      // folds it into the local the copy fills, which is the declaration that placed it.
+      const unit = obj.directives?.unit;
+      if (unit === undefined || obj.bytes === undefined) {
+        return say('whose image writes no one element width — a struct, or padding alone');
+      }
+      if (![1, 2, 4].includes(unit) || obj.size % unit !== 0) {
+        return say(`whose ${unit}-byte elements are no integer array of its ${obj.size} bytes`);
+      }
+      const signed = obj.directives!.negative;
+      const count = obj.size / unit;
+      infos.set(obj.symbol, {
+        name: obj.symbol,
+        kind: 'data',
+        size: obj.size,
+        shape: 'array',
+        elemSize: unit,
+        elemSigned: signed,
+        dims: [count],
+        const: true,
+      });
+      // Only the elements the source spelled: an element it left out is a hole, and the holes after
+      // the last value are dropped. Spelled out as zeros, the initializer is a different one to the
+      // compiler, which clears and stores where most of one is zero rather than copy an image
+      // (expr.c `mostly_zeros_p`) — so the printer spells the element after a hole by designator,
+      // where the compiler parses one (`SFn.designators`).
+      const init: (number | InitAddress | null)[] = elements(obj, unit, signed);
+      for (const [from, n] of obj.directives!.gaps ?? []) {
+        if (from % unit !== 0 || n % unit !== 0) {
+          return say(`whose padding at byte ${from} does not fall on its ${unit}-byte elements`);
+        }
+        init.fill(null, from / unit, (from + n) / unit);
+      }
+      // An element the image relocates holds an address, as a static's does — an array of pointers
+      // (agbcc copies one with memcpy from 16 words, compiled).
+      for (const r of obj.relocs ?? []) {
+        if (unit !== LOCAL_OBJECT_ADDRESS_BYTES || r.offset % unit !== 0) {
+          return say(
+            `whose image holds the address '${r.symbol}', which its ${unit}-byte elements cannot — ` +
+              `an address is ${LOCAL_OBJECT_ADDRESS_BYTES}`,
+          );
+        }
+        init[r.offset / unit] = { symbol: r.symbol, addend: r.addend };
+      }
+      // A string literal's image is placed at the compiler's string alignment, which a brace list of
+      // strings is not (agbcc: `.align 2, 0` ahead of a STRING_CST's label, none ahead of
+      // `{"abcde"}`'s) — the same bytes, but spelled as a literal the image moves to a stricter
+      // alignment and shifts the unit's `.rodata`. Nor has it a padding run: one shorter than its
+      // array is copied at the literal's length and the tail cleared (`char a[16] = "abc…hijklm"` is
+      // memcpy 15 + memset 1), so a `.space` after the `.ascii` is a brace list's image copied whole.
+      // So the test is asked before the trailing holes are dropped, not after.
+      const string =
+        obj.directives!.string === true &&
+        unit === 1 &&
+        obj.directives!.align >= layout.stringAlign &&
+        !init.includes(null);
+      while (init.length > 0 && init[init.length - 1] === null) {
+        init.pop();
+      }
+      images.push({
+        name: obj.symbol,
+        type: T.array(T.int(unit * 8, signed), count),
+        init,
+        ...(string ? { string: true as const } : {}),
+      });
+      continue;
+    }
+    const accesses = access.get(obj.symbol) ?? [];
+    const dir = obj.directives;
+    // the alignment the target shows
+    const shown = dir?.align ?? obj.placement?.align;
+    const width = widthOf(obj);
+    if (typeof width !== 'number') {
+      return say(width.refused);
+    }
+    if (![1, 2, 4].includes(width)) {
+      return say(`whose ${width}-byte elements are no integer type`);
+    }
+    if (obj.size % width !== 0) {
+      return say(`whose ${width}-byte elements do not divide its ${obj.size} bytes`);
+    }
+    // an access of another width reads through a cast, and says nothing about these elements
+    const signs = new Set(accesses.filter((x) => x.width === width && x.signed !== undefined).map((x) => x.signed));
+    if (signs.size > 1) {
+      return say('whose loads disagree on whether its elements are signed');
+    }
+    const signed = signs.size > 0 ? signs.has(true) : dir?.negative === true;
+    const count = obj.size / width;
+    const elem = T.int(width * 8, signed);
+    const init: (number | InitAddress)[] | undefined = zeroed.has(obj.symbol)
+      ? [0]
+      : obj.bytes === undefined
+        ? undefined
+        : elements(obj, width, signed);
+    // An element the target relocates holds an address, which only an element of a pointer's width
+    // can: the relocation fills exactly that many bytes.
+    for (const r of obj.relocs ?? []) {
+      if (width !== LOCAL_OBJECT_ADDRESS_BYTES || r.offset % width !== 0) {
+        return say(
+          `whose initializer holds the address '${r.symbol}', which its ${width}-byte elements cannot — ` +
+            `an address is ${LOCAL_OBJECT_ADDRESS_BYTES}`,
+        );
+      }
+      init![r.offset / width] = { symbol: r.symbol, addend: r.addend };
+    }
+    if (zeroed.has(obj.symbol) && count !== 1) {
+      return say(`laid out where only a scalar initialized to zero is, but of ${count} elements`);
+    }
+    // One element is a scalar — unless it is initialized data holding zero on a compiler that
+    // moves a zero scalar to bss, where it can only have been an aggregate, which the compiler
+    // keeps in .data.
+    const scalar =
+      count === 1 && !(layout.zeroScalar === 'bss' && obj.section === 'data' && init!.every((v) => v === 0));
+    const type: IrType = scalar ? elem : T.array(elem, count);
+    const string = dir?.string === true && width === 1 && !scalar && shown !== undefined && shown >= layout.stringAlign;
+    // The alignment the target shows against the one this definition gets from its compiler.
+    const own = scalar ? width : Math.max(width, layout.aggregateAlign, string ? layout.stringAlign : 1);
+    if (shown !== undefined && shown < own) {
+      return say(`whose definition is aligned to ${shown} bytes, less than the ${own} its declaration here would get`);
+    }
+    const align = shown !== undefined && shown > own ? shown : undefined;
+    const isConst = obj.section === 'rodata';
+    infos.set(obj.symbol, {
+      name: obj.symbol,
+      kind: 'data',
+      size: obj.size,
+      ...(scalar
+        ? { shape: 'scalar' as const, signed }
+        : { shape: 'array' as const, elemSize: width, elemSigned: signed, dims: [count] }),
+      ...(isConst ? { const: true } : {}),
+    });
+    statics.push({
+      name: obj.name,
+      type,
+      ...(isConst ? { const: true as const } : {}),
+      ...(align !== undefined ? { align } : {}),
+      ...(init ? { init } : {}),
+      ...(string ? { string: true as const } : {}),
+    });
+  }
+  return { infos, statics, images };
+}
+
+/** `sfn` with each static's linker name replaced by its source name — every reference, assignment
+ *  targets and the typed-global list included — or the refusal. The tree is final here, so what the
+ *  source name would collide with is all in it: every name its body mentions, callees included,
+ *  plus its parameters, locals and own name. */
+export function nameLocalStatics(sfn: SFn, objs: LocalObjects): SFn | { symbol: string; refused: string } {
+  const taken = takenNames(sfn);
+  for (const g of sfn.globals ?? []) {
+    taken.add(g.name);
+  }
+  // The globals an initializer holds the address of are named here as much as the body's: a static
+  // of the same name is in scope from its own declarator on, its initializer included.
+  const addressed = new Map<string, string>();
+  for (const obj of objs.values()) {
+    for (const r of obj.relocs ?? []) {
+      taken.add(r.symbol);
+      addressed.set(r.symbol, obj.symbol);
+    }
+  }
+  const bound = new Set([...sfn.params, ...sfn.locals].map((x) => x.name));
+  // …and the function's own parameters hide one too: a static's initializer is read in their scope.
+  // A local is declared after every static and hides none, but its name is the emitter's to move.
+  for (const [name, holder] of addressed) {
+    if (bound.has(name)) {
+      return {
+        symbol: holder,
+        refused: `whose initializer holds the address of '${name}', which a parameter or local here also names — it would hide that global`,
+      };
+    }
+  }
+  const callees = new Set<string>([sfn.name]);
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'call' && typeof e.fn === 'string') {
+      callees.add(e.fn);
+    }
+  }
+  const rename = new Map<string, string>();
+  const bySource = new Map<string, string>();
+  for (const obj of objs.values()) {
+    if (obj.anonymous) {
+      continue; // no source name: folded into a local's initializer at emission (l3/constinit.ts)
+    }
+    const say = (why: string) => ({ symbol: obj.symbol, refused: `whose source name '${obj.name}' ${why}` });
+    const other = bySource.get(obj.name);
+    if (other !== undefined) {
+      return say(`another static here ('${other}') also has — one block cannot declare both`);
+    }
+    if (callees.has(obj.name) || taken.has(obj.name)) {
+      const what = callees.has(obj.name) ? 'a function' : bound.has(obj.name) ? 'a parameter or local' : 'a global';
+      return say(`is also ${what} this one names — the static would hide it`);
+    }
+    bySource.set(obj.name, obj.symbol);
+    rename.set(obj.symbol, obj.name);
+  }
+  const expr = (e: Expr): Expr => {
+    const r = mapExprChildren(e, expr);
+    return (r.k === 'var' || r.k === 'addr' || r.k === 'postincr') && rename.has(r.name)
+      ? { ...r, name: rename.get(r.name)! }
+      : r;
+  };
+  const assigns = (s: Stmt): Stmt => {
+    const r = mapStmtLists(s, (list) => list.map(assigns));
+    if (r.k === 'for') {
+      return { ...r, init: assigns(r.init), inc: assigns(r.inc) };
+    }
+    return r.k === 'assign' && rename.has(r.name) ? { ...r, name: rename.get(r.name)! } : r;
+  };
+  return {
+    ...sfn,
+    body: sfn.body.map((s) => assigns(mapStmtExprs(s, expr))),
+    ...(sfn.globals
+      ? {
+          globals: sfn.globals
+            .map((g) => ({ ...g, name: rename.get(g.name) ?? g.name }))
+            .sort((a, b) => a.name.localeCompare(b.name)),
+        }
+      : {}),
+  };
+}

package/src/structure/namecoalesce.ts

@@ -86,7 +86,7 @@
 //   • `sitesOf` widens where a loop emitter may MOVE a copy, but the read side does not follow. For
 //     a block parameter `clobbers` falls to `liveIn` of the widened site, and a parameter's SSA def
 //     point is its own block's entry, not the position the emitter actually writes it at — so a
-//     header definition is not seen to clobber a value the sink copies to the top of the body. The
+//     header definition is not seen to clobber a value the sink copies into the body. The
 //     slot that is actually sunk is unreachable (its exit arg is a header parameter, which
 //     `loop-escape` rejects); reaching it needs a second, non-loop predecessor of the exit block
 //     passing the header's definition into the same slot, and no input has been built that does.
@@ -133,7 +133,7 @@ export interface NameCoalesceDeps {
   varName: ReadonlyMap<Value, string>;
   /** name → the type it is declared with */
   varType: ReadonlyMap<string, IrType>;
-  /** every natural loop, as its header and the blocks its body contains (structure/loops.ts) */
+  /** every natural loop, as its header and the blocks its body contains (ir/loops.ts) */
   loops: readonly { header: Block; body: ReadonlySet<Block> }[];
 }