@henols/vice-mcp 0.2.1 → 0.2.3

package/anno-export-asm.ts

@@ -0,0 +1,2396 @@
+// anno-export-asm.ts -- the ONE place annotation-store rows plus image bytes
+// become ACME source text (EXPORT-01).
+//
+// ---------------------------------------------------------------------------
+// WHY THIS FILE EXISTS
+// ---------------------------------------------------------------------------
+// The previous export route was WITHDRAWN in Phase 29 rather than left
+// standing, because it made a reassembly claim nothing verified: it produced
+// something that looked like ACME source and asserted, in effect, that
+// assembling it would reproduce the program. No assembler ever ran. Withdrawing
+// it was the right call and the withdrawal notices in both skill trees are the
+// record that the capability was missing.
+//
+// This module is the rebuild, over the Phase 28 annotation store, and it is
+// allowed to exist only because the claim is now settled somewhere else: a real
+// ACME 0.97 assembles this module's output and the resulting bytes are diffed
+// against the IMAGE bytes. Nothing in this file verifies this file. Re-reading,
+// re-parsing or substring-matching the text below to decide whether the export
+// is correct would be a self-check wearing an oracle's clothes, and this
+// project's own record is that an internally-verified opcode table still
+// shipped fourteen wrong entries.
+//
+// ---------------------------------------------------------------------------
+// WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR
+// ---------------------------------------------------------------------------
+// Turning `(store rows, image bytes)` into `(ACME source text, the exact bytes
+// that source must assemble to)`. The second half of that pair is what makes
+// the round trip a round trip: `expectedBytes` is built from the IMAGE, never
+// from `source`.
+//
+// ---------------------------------------------------------------------------
+// WHAT NOT TO DO
+// ---------------------------------------------------------------------------
+//   - Never re-derive the opcode table. `disasm-opcodes.ts` forbids a second
+//     copy by name, and its `acmeExpressible` column is round-trip-proven
+//     against a real assembler across all 256 opcodes. Decoding here happens
+//     through `decode()` and nowhere else.
+//   - Never write a second `!byte` / `+2` / hex emitter. `disasm-renderer.ts`
+//     owns D-09's `!byte` substitution and D-11's width invariant, both
+//     verified against real ACME. A second emitter would be a second answer to
+//     "how wide is this operand", and the two would drift silently.
+//   - Never restate the eleven auto-name prefixes here. `anno-types.ts:93-99`
+//     forbids a second copy of that vocabulary BY NAME, and names the exact
+//     failure a short reimplementation causes: a five-prefix copy silently
+//     under-counts, which breaks `routine-queue-walker`'s backlog construction
+//     while every test keeps passing. This module DOES need the vocabulary --
+//     it marks auto-generated names in the emitted source -- and it gets it by
+//     IMPORTING `AUTO_NAME_PREFIX_RE` from its one home. A copy made "just to
+//     filter" is how the eleventh prefix goes missing in one of two places.
+//   - Never emit an enum on anything but an IMMEDIATE operand. Measured on ACME
+//     0.97, `sta viccolor_WHITE` with `viccolor_WHITE = $01` encodes as
+//     ZEROPAGE -- `85 01`, two bytes where the absolute original was three --
+//     so the substitution changes both the bytes and the instruction length. A
+//     non-immediate operand is REFUSED by name below, never rendered and hoped
+//     for.
+//   - Never compare a `dataType` string in this module beyond the FOUR
+//     places that already do, each of which says so in its own comment:
+//     `CODE_DATA_TYPE`'s decoder-or-dump branch, `WORD_PAIR_DATA_TYPES`'s
+//     `!word` eligibility check, (phase 47, plan 47-03)
+//     `EXTERNAL_FILE_DATA_TYPE`'s `!binary`-versus-inline branch inside
+//     `emitDataLines()`, and (phase 47, plan 47-06) `isSplitAddressDataType()`'s
+//     paired-symbol-versus-raw-byte branch in the block loop. All four are
+//     questions about the emitted TEXT. `block-class.ts` is the one place in
+//     this tree allowed to INTERPRET that column -- what the data means -- and
+//     everywhere else here the string is copied VERBATIM onto the emitted
+//     block and its trailing comment.
+//   - Never import this tree's host/container path-translation modules
+//     (`hostpath.ts` / `containerpath.ts`). Their consumer set is a closed,
+//     mechanically asserted list of named modules and an exporter has no reason
+//     to join it -- the failure would surface as a test about something else
+//     entirely.
+//   - Never interpolate a read file's own bytes into an error message. A path,
+//     an address and a length are facts ABOUT a file; its contents are not, and
+//     an error text that quotes them turns a refusal into a content-disclosure
+//     oracle (CR-03). Every throw below carries paths, addresses and counts and
+//     nothing read out of the image or the store.
+//   - Never sanitise a label name. `assertLegalAcmeIdentifier()`'s contract is
+//     REJECT: a space-to-underscore substitution silently merges two distinct
+//     names into one, permanently, and the caller-visible name then diverges
+//     from what actually reached the ACME source.
+//
+// ---------------------------------------------------------------------------
+// WHAT THIS FILE DOES NOT CHECK
+// ---------------------------------------------------------------------------
+// Addresses no range covers. `expectedBytes` spans `[minStart,
+// maxEndExclusive)` with `$00` in the gaps between blocks -- which is exactly
+// what ACME `-f plain` emits for those gaps (measured) -- so the padding is
+// never a false disagreement. But an export makes no claim about bytes outside
+// its own blocks, and neither does the byte-diff that settles it.
+//
+// SCOPE, STILL DELIBERATELY NARROW: code ranges, the twelve typed data ranges,
+// comments, mid-instruction inline labels and immediate-operand enum
+// substitution.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+
+import { openStore, closeStore, listRanges, listLabels, listComments, listProjectEnums, listEnumUsage, listExcludedRanges, listScopes } from "./anno-store.ts";
+import { AnnoCommentError, COMMENT_TYPES, DATA_TYPES, assertCommentText, assertDataType, isSplitDataType, parseVariantKey } from "./anno-types.ts";
+import type { CommentRow, DataType, EnumUsageRow, ExcludedRangeRow, LabelRow, ProjectEnumRow, RangeRow, ScopeRow } from "./anno-types.ts";
+import { assertLegalAcmeIdentifier } from "./anno-acme-ident.ts";
+// The eleven typed auto-name prefixes, IMPORTED FROM THEIR ONE HOME rather than
+// restated. This is the first cross-module PRODUCTION importer of that
+// constant; before this the only consumers were `anno-coverage.ts`'s own
+// `computeLabelRatio()` and its test file.
+//
+// WHY THE EXPORTER CARES. `routine-queue-walker`'s SKILL.md reads the typed
+// prefixes as DOCUMENTED VOCABULARY (`s_`, `p_`, `b_`, `zpp_`, `zpf_`, `zpa_`,
+// `f_`, `a_` at :128-181 and :220-226) and never imports the regex, so the
+// coupling between that skill's backlog signal and this repo's definition of
+// "auto-generated name" is by convention and would break in SILENCE. Marking
+// those definitions in the exported source is what keeps the backlog visible to
+// a human reading the generated assembly, which is the one artefact that leaves
+// this tree.
+//
+// WHAT NOT TO DO: do not restate the eleven here, in any form -- not as an
+// array, not as a second regex, not as a doc comment listing them.
+// `anno-types.ts:93-99` forbids it by name, and `EXPORT-02` names the failure
+// mode: a five-prefix copy under-counts silently.
+import { AUTO_NAME_PREFIX_RE } from "./anno-coverage.ts";
+// THE ONE OWNING DECODER (D-16, plan 45-03). This module decodes NOTHING
+// itself -- `decomposeRegisterValue()` is the ONLY place a register value is
+// split into named bit-fields, and `anno_disassemble` (plan 45-05, the other
+// D-16 renderer) calls the SAME function. Never re-derive a per-field bit
+// mask in this file -- a phase-45 verification gate greps this file's own
+// text for that shape and must find none.
+import { decomposeRegisterValue, hasRegBitsEntry, type RegisterDecomposition } from "./anno-enum-gen.ts";
+import { decode } from "./disasm-decoder.ts";
+import type { Instruction } from "./disasm-decoder.ts";
+import { renderLine } from "./disasm-renderer.ts";
+import { parsePrg, flatImageOrigin } from "./prg-image.ts";
+// BUILD-05 (phase 46 plan 01): the ONE reader of `recovery/PROVENANCE.md`'s
+// generated tier. This module never recomputes a verdict -- see
+// `anno-provenance-ledger.ts`'s own header for why reading and recomputing
+// are deliberately kept apart.
+import { provenanceForRange, readProvenanceLedger, type ProvenanceLedger } from "./anno-provenance-ledger.ts";
+
+/** The store's own spelling for an executable range, read out of the one home
+ * of that vocabulary rather than re-typed as a literal. `dataType` is never
+ * COMPARED anywhere else in this module -- `block-class.ts` owns
+ * interpretation; this single equality is the emitter deciding whether to run
+ * a decoder or dump bytes, and it is the only one. */
+const CODE_DATA_TYPE = "code";
+
+/** The store's own spelling for a large binary blob exported AS ITS OWN
+ * FILE rather than inline (phase 47, plan 47-03; `anno_set_data_type`'s
+ * schema calls this "large binary blob to export as-is") -- the eleventh of
+ * `DATA_TYPES`' twelve members, the one vocabulary this module imports
+ * rather than restates. The SAME discipline `CODE_DATA_TYPE` above already
+ * follows: one named constant carries the literal ONCE, so every comparison
+ * below reads the NAME and this is the only place the spelling itself is
+ * written down. `dataType` is never COMPARED anywhere else in this module
+ * for this purpose -- `emitDataLines()`'s `!binary`-versus-inline branch is
+ * the only one. */
+const EXTERNAL_FILE_DATA_TYPE = "external_file";
+
+/** One block as this module emitted it. */
+export interface ExportBlock {
+  /** First address the block covers. */
+  start: number;
+  /** One past the last address the block covers. ACME's `*` sits here after
+   * the block, and the store's own row uses an INCLUSIVE end, so the
+   * conversion is `endExclusive = row.endInclusive + 1`. */
+  endExclusive: number;
+  /** The store's `dataType`, copied VERBATIM off the row. Never compared in
+   * this module beyond the single code/not-code branch the emitter needs. */
+  dataType: string;
+  /** How many CONTENT lines the block emitted -- not its `* =` origin line and
+   * not the two `!if * != ...` assertions that bracket it. */
+  lineCount: number;
+  /** Phase 47, plan 47-01: exactly what `emitBlock()` returned for this block
+   * -- the `* =` origin line, both `!if * != ...` bracket assertions, and
+   * every content line between them, in emitted order. This is FOR a tree
+   * writer to partition an emission that is already proven, rather than a
+   * second description of the block: `exportAsmTree()` writes each scope's
+   * `.a` file by concatenating its contained blocks' `lines` verbatim, never
+   * by re-deriving what a block looks like from `dataType`/`start`/
+   * `endExclusive` a second time. Populated by `exportAsm()` at the same
+   * point it calls `emitBlock()`; empty only before that call runs. */
+  lines: string[];
+}
+
+/**
+ * Phase 47, plan 47-03 (BUILD-02): one `external_file`-typed block's own
+ * `.bin` sibling. `bytes` is the block's own slice of the IMAGE, carried
+ * verbatim -- never a copy that passed through any conversion, on the same
+ * terms `expectedBytes` is derived from the image and never from `source`.
+ *
+ * A caller that writes `source` (or a tree's `.a` files) and not these
+ * bytes to their named files has written a source tree that names files
+ * nobody produced: every `!binary "..."` line `emitDataLines()` emits names
+ * exactly one of these entries, and `exportAsmTree()`'s whole tree-writing
+ * contract exists because of that obligation.
+ */
+export interface ExportBinary {
+  /** The bare file name the emitted `!binary` line names -- `binaryFileName(start)`, never a store-supplied string. */
+  name: string;
+  /** First address the block covers -- same field as `ExportBlock.start`. */
+  start: number;
+  /** One past the last address the block covers -- same field as `ExportBlock.endExclusive`. */
+  endExclusive: number;
+  /** The block's own slice of the image, verbatim. `bytes.length === endExclusive - start`. */
+  bytes: Uint8Array;
+}
+
+export interface ExportAsmOptions {
+  /**
+   * The annotation store to export. `openStore()` below confines it against
+   * `workspaceRoot`; a CLI caller confines the same string a second time
+   * through `storePathWithinWorkspace()` before it ever reaches here, so both
+   * answers agree by construction rather than by a second rule. */
+  storePath: string;
+  /** The program image the store annotates -- a `.prg` (2-byte little-endian
+   * load address then payload) or a flat 64K capture. NOTHING CONFINES THIS
+   * PATH INSIDE THIS MODULE: it reaches `readFileSync` directly, so the CALLER
+   * owns its confinement, exactly as it owns `storePath`'s. That sentence is
+   * present because an absent comment beside a present one is itself a claim,
+   * and a silently-undocumented path field is what a prior review named as the
+   * mechanism of a real defect. */
+  imagePath: string;
+  /** The workspace root the store-path confinement is taken against. REQUIRED
+   * rather than defaulted: `openStore()`'s default behaviour is to CREATE the
+   * file, so an unconfined store path is a store file created wherever the
+   * caller's argument pointed -- and an export of a store this call just
+   * invented would read as "the program has no annotations". */
+  workspaceRoot: string;
+  /**
+   * The provenance ledger to annotate every emitted block from -- `c64-
+   * provenance-diff`'s generated `recovery/PROVENANCE.md`, read (never
+   * re-derived) through `readProvenanceLedger()`. OPTIONAL (assumption A1,
+   * `46-01-PLAN.md`): every existing caller that omits it keeps exporting
+   * exactly as before, byte for byte and comment for comment. NOTHING
+   * CONFINES THIS PATH INSIDE THIS MODULE, on the same terms as `imagePath`
+   * above -- the CALLER owns its confinement. Supplying it and having the
+   * file be unreadable, malformed, or missing a row for some block is a
+   * refusal; omitting it is not.
+   */
+  ledgerPath?: string;
+}
+
+export interface ExportAsmResult {
+  /** The ACME source text. */
+  source: string;
+  /** Phase 47, plan 47-01: the symbol-definition block VERBATIM -- every
+   * enum-variant definition line followed by every store label's own
+   * definition line, in exactly the order `source` carries them. This is FOR
+   * `exportAsmTree()` to write `symbols.a` from, never re-derived: `source`
+   * is still `["!cpu 6510", ...headerLines, ...blockLines].join("\n")` plus
+   * the trailing newline, byte for byte unchanged by this field's addition. */
+  headerLines: string[];
+  /** Phase 47, plan 47-01: every scope the store holds, read by `listScopes()`
+   * as a SEVENTH call inside this function's existing store handle -- there
+   * is still exactly one handle opened for the whole export. `exportAsmTree()`
+   * uses this to decide which scope (or none) each block belongs to; nothing
+   * in `exportAsm()` itself reads a scope's span to change what it emits. */
+  scopes: ScopeRow[];
+  /** The bytes `source` must assemble to, DERIVED FROM THE IMAGE and never
+   * from `source`. Spans `[minStart, maxEndExclusive)` across every emitted
+   * block, with `$00` filling the gaps between them -- which is exactly what
+   * ACME `-f plain` emits for those gaps (measured), so padding can never
+   * register as a disagreement while a wrong byte inside a covered range
+   * still fails. */
+  expectedBytes: Uint8Array;
+  /** The blocks emitted, ascending by start. Passed straight to the verify
+   * primitive as its `expectedSegments`. */
+  blocks: ExportBlock[];
+  /** How many STORE LABELS the export carries, header and inline together --
+   * i.e. `sortedLabels.length`, one per `anno_label` row in range.
+   *
+   * THIS DOC USED TO SAY "how many symbol definitions the header carries",
+   * AND THAT WAS NOT WHAT IT COUNTED (30-REVIEW WR-01, corrected 2026-08-31).
+   * The two readings diverge in BOTH directions: a mid-instruction label is
+   * defined inline and skipped by the header loop yet still counted here,
+   * and every `enumDefinitionLines` entry IS a header definition yet is not.
+   * Reproduced: a store with `start`@$0801 plus `smc_operand`/`smc_alias`
+   * both at the mid-instruction address $0802 emits a header carrying exactly
+   * ONE definition while this field reported 3 -- a number the CLI prints
+   * verbatim to the user as "3 symbol(s)".
+   *
+   * The header count is now its own field (`headerDefinitionCount` below)
+   * rather than this one being redefined, because both numbers have a real
+   * consumer and collapsing them into one is what produced the divergence. */
+  symbolCount: number;
+  /** How many definition lines the HEADER block actually carries -- enum
+   * variant definitions plus every store label NOT defined inline. Computed
+   * from `headerLines` itself, so it cannot drift from the emitted text the
+   * way a separately-maintained count did (30-REVIEW WR-01). */
+  headerDefinitionCount: number;
+  /** How many decoded instructions ACME's `!cpu 6510` cannot express, and
+   * which therefore went out as `!byte` directives with their mnemonic moved
+   * into a trailing comment. */
+  unexpressibleCount: number;
+  /** How many bytes went out through the DATA path -- every byte of every
+   * block whose `dataType` is not `code`. A code block contributes nothing
+   * here, however many bytes it decoded. */
+  dataByteCount: number;
+  /** Phase 47, plan 47-03 (BUILD-02): every `external_file`-typed block's
+   * own sibling data file, ascending by `start`. `dataByteCount` above still
+   * counts these bytes -- they went out through the data path exactly as an
+   * inline `!byte`-typed range's bytes would have, only to a different
+   * destination file, and a count whose name stops matching what it counts
+   * is the WR-01 lesson this module already learned once. See
+   * `ExportBinary`'s own doc-comment for the obligation a caller that reads
+   * this field takes on. */
+  binaries: ExportBinary[];
+  /** How many store comments the source carries. Always the store's FULL
+   * comment count when this function returns: a comment with no emitted line
+   * to attach to is refused by name rather than left out of this number. */
+  commentCount: number;
+  /** How many inline mid-instruction label definitions the source carries --
+   * one per store label whose address falls STRICTLY INSIDE a decoded
+   * instruction. `midInstructionLabelLine()` is the one place that spelling
+   * exists. Equal to the number of labels that were therefore EXCLUDED from the
+   * header definition block, because such a label is defined inline and
+   * defining it twice is ACME's `Symbol already defined.`
+   *
+   * COUNTED PER EMITTED DEFINITION, NOT PER ADDRESS (30-REVIEW WR-02,
+   * corrected 2026-08-31). It used to be `midInstructionLabelAddresses.size`,
+   * a set of ADDRESSES, while the inline loop emits one line per LABEL.
+   * `anno_label` is `unique` on `name` only and `setLabel()` refuses only a
+   * name already bound to a DIFFERENT address, so two names at one address is
+   * a supported store state -- and in it, two inline definitions were emitted
+   * and two labels excluded from the header while this field reported 1,
+   * contradicting the sentence directly above. */
+  midInstructionLabelCount: number;
+  /** How many emitted symbol definitions carry an AUTO-GENERATED name, decided
+   * by `AUTO_NAME_PREFIX_RE` -- the eleven typed prefixes, read from their one
+   * home and never restated here. This is `routine-queue-walker`'s backlog
+   * signal, surfaced in the one artefact that leaves this tree. */
+  autoNamedSymbolCount: number;
+  /** How many instruction operands were rendered through a project enum's
+   * variant name instead of a hex literal. Every one of them is an IMMEDIATE
+   * operand; any other operand role is refused. INCLUDES decomposed writes
+   * (`enumDecompositionCount` below is a SUBSET of this, never added to it --
+   * two named figures, never one combined figure). */
+  enumSubstitutionCount: number;
+  /** How many of `enumSubstitutionCount`'s substitutions were rendered as an
+   * OR-ed multi-bit decomposition (D-16/D-17) rather than a single whole-value
+   * variant name -- one register key `regbits` entry with two or more
+   * fields, decoded through `decomposeRegisterValue()`. A single-field
+   * register, or an enum usage whose name is not a register key at all,
+   * counts toward `enumSubstitutionCount` only, never here. */
+  enumDecompositionCount: number;
+  /** How many RECORDS from `anno_excluded_range` the export emitted a marker
+   * for -- at least one of their addresses overlapping at least one emitted
+   * block. `BUILD-07` (phase 46 plan 05).
+   *
+   * COUNTS RECORDS, NOT MARKER LINES AND NOT EXCLUDED BYTES -- the same
+   * WR-01 lesson this file already learned once about `symbolCount`: a count
+   * whose name does not match what it counts gets printed to a user
+   * verbatim. One exclusion record spanning two emitted blocks emits TWO
+   * marker lines (one per block) and counts ONCE here. And no byte is ever
+   * excluded -- every block a recorded exclusion overlaps is still emitted
+   * in full -- so this field never measures bytes left out, because there
+   * are none. */
+  excludedRangeCount: number;
+}
+
+/** How many raw bytes go on one `!byte` line for a non-code block. */
+const BYTES_PER_DATA_LINE = 16;
+
+/** How many 16-bit values go on one `!word` line. */
+const WORDS_PER_DATA_LINE = 8;
+
+/**
+ * The two `DATA_TYPES` members whose bytes are ADJACENT little-endian pairs,
+ * and therefore the only ones `!word` can emit without changing a byte.
+ *
+ * THIS IS THE ONE PLACE IN THIS MODULE A TYPE NAME IS READ FOR EMISSION, other
+ * than `CODE_DATA_TYPE`'s decoder/dump branch. `block-class.ts` owns
+ * INTERPRETATION of a `dataType`; these two names are read here only to answer
+ * "may this block's bytes be re-grouped into pairs", which is a question about
+ * the emitted TEXT and not about what the data means. Every other type -- the
+ * four split-table layouts included, whose low and high halves are NOT adjacent
+ * pairs -- is copied verbatim onto a `!byte` line and never compared.
+ */
+const WORD_PAIR_DATA_TYPES: readonly string[] = Object.freeze(["word", "address"]);
+
+/**
+ * Phase 47, plan 47-06 (BUILD-03): true iff `dataType` is one of the TWO split
+ * layouts that denote ADDRESSES -- `lo_hi_address` / `hi_lo_address` -- as
+ * opposed to the two that denote WORDS (`lo_hi_word` / `hi_lo_word`), which
+ * stay on the raw-`!byte` fallback below unchanged. This is the branch that
+ * decides whether `emitDataLines()`'s caller reaches `emitSplitAddressLines()`
+ * at all.
+ *
+ * DERIVED, never a fourth hand-written list of layout names -- exactly the
+ * drift `WORD_PAIR_DATA_TYPES`'s own comment warns against. `isSplitDataType()`
+ * (imported from `anno-types.ts`, never re-derived here) answers "is this one
+ * of the four split layouts", and the `_address` suffix is the SAME
+ * ADDRESS-VERSUS-WORD axis the `DATA_TYPES` comment already draws
+ * (`anno-types.ts:350-361`'s worked byte example: the address forms produce
+ * cross-references and the word forms do not).
+ */
+function isSplitAddressDataType(dataType: string): boolean {
+  return isSplitDataType(dataType as DataType) && dataType.endsWith("_address");
+}
+
+/** One emitted data line, with the address span it covers. The span is what
+ * lets a stored comment find its line: a `!byte` line covers up to sixteen
+ * addresses, and a comment on any of them belongs to that line. */
+interface DataLine {
+  text: string;
+  start: number;
+  endExclusive: number;
+}
+
+/**
+ * Emits one non-code block's bytes.
+ *
+ * THE RULE, and its reason: byte-identity is the criterion, and `!byte` is
+ * byte-identical for every type. `!word` is used ONLY where it is provably
+ * identical AND improves readability -- `word` and `address` ranges of even
+ * length, where ACME's `!word` emits little-endian pairs (measured). Everything
+ * else goes out as `!byte`.
+ *
+ * `!text` IS DELIBERATELY NOT EMITTED for `petscii` / `screencode`. `!text`
+ * applies ACME's CURRENT conversion table, and a conversion this exporter does
+ * not control is exactly the way a byte-identical claim stops being true --
+ * silently, on somebody else's machine, with a different ACME build. The type
+ * name goes into the trailing comment instead, so a human reader loses nothing
+ * a converter would have told them about the bytes' meaning.
+ *
+ * `stock-petscii.ts` was checked for a reusable byte-to-text converter and
+ * exports only `asciiToPetscii()` -- the other direction. A second conversion
+ * table is NOT invented here; that would be the same drift hazard wearing a
+ * local name.
+ *
+ * `external_file` (phase 47, plan 47-03) IS THE OPPOSITE CASE from `!text`
+ * above, and for the identical reason. `!text` is refused because ACME's
+ * conversion table is outside this exporter's control; `!binary` is used
+ * here because it applies NO table at all -- the bytes written to the
+ * sibling `.bin` file are the image's own octets for the extent, verbatim,
+ * so nothing can drift between this host's ACME build and anyone else's.
+ * One `!binary` line covers the block's WHOLE extent (never split across
+ * several, the way `!byte`/`!word` chunk at `BYTES_PER_DATA_LINE`/
+ * `WORDS_PER_DATA_LINE`), so a stored comment anywhere in the range attaches
+ * to that one line through the same `withComments()` call every other data
+ * line already goes through.
+ *
+ * OVERLAP: `--strict-segments` is in the verify argv, which promotes ACME's
+ * "Segment starts inside another one, overwriting it." from a Warning to an
+ * Error (measured, exit 1). Without it a store holding two overlapping ranges
+ * would silently overwrite one with the other and the byte-diff would compare
+ * against whichever won.
+ */
+function emitDataLines(slice: Uint8Array, dataType: string, blockStart: number): DataLine[] {
+  if (dataType === EXTERNAL_FILE_DATA_TYPE) {
+    return [
+      {
+        text: `${INDENT}!binary "${binaryFileName(blockStart)}"  ; ${dataType}`,
+        start: blockStart,
+        endExclusive: blockStart + slice.length,
+      },
+    ];
+  }
+
+  const out: DataLine[] = [];
+
+  if (WORD_PAIR_DATA_TYPES.includes(dataType) && slice.length % 2 === 0) {
+    for (let offset = 0; offset < slice.length; offset += WORDS_PER_DATA_LINE * 2) {
+      const chunk = slice.subarray(offset, Math.min(offset + WORDS_PER_DATA_LINE * 2, slice.length));
+      const values: string[] = [];
+      for (let i = 0; i < chunk.length; i += 2) values.push(hex4(chunk[i]! | (chunk[i + 1]! << 8)));
+      out.push({
+        text: `${INDENT}!word ${values.join(", ")}  ; ${dataType}`,
+        start: blockStart + offset,
+        endExclusive: blockStart + offset + chunk.length,
+      });
+    }
+    return out;
+  }
+
+  // The fallback says WHY it happened, because "this word table came out as
+  // bytes" is otherwise indistinguishable from a missing feature.
+  const why = WORD_PAIR_DATA_TYPES.includes(dataType)
+    ? ` (odd byte count ${slice.length} -- !word emits PAIRS, so a byte-identical emission falls back to !byte)`
+    : "";
+  for (let offset = 0; offset < slice.length; offset += BYTES_PER_DATA_LINE) {
+    const chunk = slice.subarray(offset, Math.min(offset + BYTES_PER_DATA_LINE, slice.length));
+    out.push({
+      text: `${INDENT}!byte ${[...chunk].map(hex2).join(", ")}  ; ${dataType}${why}`,
+      start: blockStart + offset,
+      endExclusive: blockStart + offset + chunk.length,
+    });
+  }
+  return out;
+}
+
+/** Phase 47, plan 47-06 (BUILD-03): one split-address block's own contribution
+ * to the export's shared in-tree-reference bookkeeping -- the SAME
+ * `unresolvedReferences`/`inTreeReferenceCount` totals the code path's in-tree
+ * symbol rule feeds inside `exportAsm()`'s block loop. Returned rather than
+ * mutated through a closure so this function stays a plain, explicitly-typed
+ * transform like every other emitter in this file; the caller folds these
+ * into its own running totals. */
+interface SplitAddressEmission {
+  lines: DataLine[];
+  inTreeReferenceCount: number;
+  unresolvedReferences: { referringAddress: number; targetAddress: number }[];
+}
+
+/**
+ * Emits one split ADDRESS-layout block (`lo_hi_address` / `hi_lo_address`,
+ * `isSplitAddressDataType()`'s own membership) as PAIRED low-byte/high-byte
+ * symbol references -- never per-half symbolisation, and never for the two
+ * split WORD layouts, which never reach this function at all (they stay on
+ * `emitDataLines()`'s raw-`!byte` fallback, unchanged).
+ *
+ * ORIENTATION, taken from the `DATA_TYPES` comment's own worked byte example
+ * (`anno-types.ts:350-361`) and never re-derived: the bytes
+ * `10 34 00 ff 08 12 c0 cf` resolve as `$0810 $1234 $c000 $cfff` under
+ * `lo_hi_address` -- the FIRST run is the low bytes, the SECOND run the high
+ * bytes -- and as `$1008 $3412 $00c0 $ffcf` under `hi_lo_address`, where the
+ * order is reversed. `slice` is split into two EQUAL runs at the midpoint,
+ * relying on the store's own even-byte-count guarantee for every split layout
+ * (`assertRangeShape()`, `anno-types.ts`) rather than re-checking it here.
+ *
+ * ONE SYMBOL PER ENTRY, the property this function exists to make true by
+ * construction rather than merely avoid violating: entry `i`'s composed
+ * 16-bit target decides BOTH halves together, through the SAME `isInTree()`/
+ * `labelIndex` lookup the code path's in-tree symbol rule reads (one rule,
+ * two callers, so a table entry and a `jsr` cannot disagree about what counts
+ * as resolvable):
+ *   - in-tree and named: BOTH halves render through ACME's low-byte/high-byte
+ *     operators (`<name` / `>name`) over that ONE symbol -- measured
+ *     byte-identical to the raw octets on real ACME 0.97 "Zem", 2026-09-12
+ *     (`tbl_lo !byte <routine_a, <routine_b` / `tbl_hi !byte >routine_a,
+ *     >routine_b` assembled to `01 02 08 08`, the same bytes the raw form
+ *     would have produced).
+ *   - out-of-tree (D47-F's boundary, applied here to a second kind of
+ *     reference): BOTH halves keep their raw byte, exactly as the unsplit
+ *     fallback would have emitted them, and this is NOT a refusal.
+ *   - in-tree with no symbol: collected into the returned
+ *     `unresolvedReferences`, for the SAME end-of-export refusal the
+ *     instruction path already raises -- never emitted as a hex literal that
+ *     would freeze the target's address into the source.
+ *
+ * Entry `i`'s first-run byte sits at `blockStart + i` and its second-run byte
+ * at `blockStart + half + i` -- so a stored comment on either address still
+ * finds its own line -- and both runs are chunked at `BYTES_PER_DATA_LINE`,
+ * the SAME per-line budget `emitDataLines()`'s raw-byte fallback already uses,
+ * applied to two runs instead of one. The runs are emitted in PHYSICAL order
+ * (first run's lines, then second run's), which is already the layout's own
+ * documented order: `lo_hi_address` therefore emits low halves first,
+ * `hi_lo_address` emits high halves first, with no reordering logic needed
+ * beyond the two runs' own on-disk position.
+ */
+function emitSplitAddressLines(
+  slice: Uint8Array,
+  dataType: string,
+  blockStart: number,
+  blocks: readonly ExportBlock[],
+  labelIndex: ReadonlyMap<number, string>,
+): SplitAddressEmission {
+  const half = slice.length / 2;
+  const isLoHi = dataType.startsWith("lo_hi_");
+
+  let inTreeReferenceCount = 0;
+  const unresolvedReferences: { referringAddress: number; targetAddress: number }[] = [];
+
+  const firstRunTokens: string[] = [];
+  const secondRunTokens: string[] = [];
+  for (let i = 0; i < half; i++) {
+    const firstByte = slice[i]!;
+    const secondByte = slice[half + i]!;
+    const low = isLoHi ? firstByte : secondByte;
+    const high = isLoHi ? secondByte : firstByte;
+    const target = low | (high << 8);
+
+    let lowToken: string;
+    let highToken: string;
+    if (isInTree(target, blocks)) {
+      inTreeReferenceCount++;
+      const symbol = labelIndex.get(target);
+      if (symbol === undefined) {
+        // Referring address is this entry's own FIRST-run byte -- an address
+        // a human reading the generated source can look at, on the same
+        // terms `instr.address` is for the code path. The export throws
+        // before `lines` below is ever used, so the tokens pushed here for
+        // this entry are never read; they exist only so the loop can finish
+        // uniformly.
+        unresolvedReferences.push({ referringAddress: blockStart + i, targetAddress: target });
+        lowToken = hex2(low);
+        highToken = hex2(high);
+      } else {
+        // ONE SYMBOL, BOTH HALVES: `<name`/`>name` over the identical
+        // `symbol` string, never two independently-looked-up names.
+        lowToken = `<${symbol}`;
+        highToken = `>${symbol}`;
+      }
+    } else {
+      // D47-F's boundary, applied to a second kind of reference: fixed
+      // hardware and KERNAL addresses cannot move, and a rule that refused on
+      // them would make every real export impossible.
+      lowToken = hex2(low);
+      highToken = hex2(high);
+    }
+
+    firstRunTokens.push(isLoHi ? lowToken : highToken);
+    secondRunTokens.push(isLoHi ? highToken : lowToken);
+  }
+
+  const lines = [...tokenDataLines(firstRunTokens, blockStart, dataType), ...tokenDataLines(secondRunTokens, blockStart + half, dataType)];
+
+  return { lines, inTreeReferenceCount, unresolvedReferences };
+}
+
+/** Chunks `tokens` (each either `<name`/`>name` or a raw `hex2()` literal) into
+ * `!byte` lines at the SAME `BYTES_PER_DATA_LINE` budget `emitDataLines()`'s
+ * raw-byte fallback uses, each line spanning `startAddress + offset ..
+ * startAddress + offset + chunk.length` -- one physical run of a split-address
+ * block's paired emission (`emitSplitAddressLines()`'s only caller). */
+function tokenDataLines(tokens: readonly string[], startAddress: number, dataType: string): DataLine[] {
+  const out: DataLine[] = [];
+  for (let offset = 0; offset < tokens.length; offset += BYTES_PER_DATA_LINE) {
+    const chunk = tokens.slice(offset, Math.min(offset + BYTES_PER_DATA_LINE, tokens.length));
+    out.push({
+      text: `${INDENT}!byte ${chunk.join(", ")}  ; ${dataType}`,
+      start: startAddress + offset,
+      endExclusive: startAddress + offset + chunk.length,
+    });
+  }
+  return out;
+}
+
+/** ACME source indent for directive lines, matching `disasm-renderer.ts`'s own
+ * cosmetic indent so the two emitters' output reads as one document. */
+const INDENT = "        ";
+
+function hex2(value: number): string {
+  return `$${(value & 0xff).toString(16).padStart(2, "0")}`;
+}
+
+function hex4(value: number): string {
+  return `$${(value & 0xffff).toString(16).padStart(4, "0")}`;
+}
+
+/**
+ * `$XXXX` FOR A BLOCK'S EXCLUSIVE END, WHICH IS `hex4()` -- MASKED, NOT PADDED.
+ *
+ * THIS FUNCTION USED TO DO THE OPPOSITE, AND IT WAS WRONG (30-REVIEW WR-04,
+ * corrected 2026-08-31). It padded without masking, so a range ending at
+ * `$ffff` produced the end assertion `!if * != $10000`. Its doc justified that
+ * by asserting that `hex4()`'s mask "would render that as `$0000` -- an
+ * assertion no assembly can ever satisfy, firing on a correct export". That
+ * claim was never measured, and it is FALSE in exactly the direction that
+ * matters: ACME's `*` is a 16-BIT program counter and WRAPS.
+ *
+ * MEASURED, real ACME 0.97 "Zem" on this host, 2026-08-31:
+ *
+ *   !cpu 6510
+ *   * = $fffe
+ *   !if * != $fffe { !error "origin drifted, expected $fffe" }
+ *           !byte $aa, $bb
+ *   !if * != $0000 { !error "end drifted, expected $0000" }
+ *
+ *   -> exit 0, output file written, bytes `aa bb`.
+ *
+ * The same source with `!if * != $10000` fails: `!error: end drifted` and no
+ * output file. So the UNMASKED form is the one that "fires on a correct
+ * export", for every range touching the top of memory -- and the failure looks
+ * like an exporter bug rather than an arithmetic one.
+ *
+ * WHY THE ASSUMPTION LOOKED SAFE: ACME's own `-v2` diagnostics DO print the
+ * unwrapped extent, `Saving 2 (0x2) bytes (0xfffe - 0x10000 exclusive)`. That
+ * is ACME describing a SEGMENT; `*` is a different thing and wraps. Do not
+ * reintroduce an unmasked extent on the strength of that line.
+ *
+ * THE GUARD STILL BITES AT THE TOP OF MEMORY, measured the same way: the same
+ * source emitting ONE byte instead of two leaves `*` at `$ffff`, the
+ * assertion fires, ACME exits 1 and writes no output file. The mask does not
+ * make the top-of-memory assertion vacuous.
+ *
+ * Kept as a named function rather than folded into `hex4()` so this record has
+ * somewhere to live, and so the ONE value in this module that is not an
+ * address still reads differently at its call site.
+ */
+function hexExtent(value: number): string {
+  return hex4(value);
+}
+
+/**
+ * Wraps one block's content lines in its origin and its `*` assertions.
+ *
+ * THE EXCLUSIVE END IS THE POINT. Measured on ACME 0.97: `* = $0801` followed
+ * by `lda #$00` and `rts` leaves `*` at `$0804`, one past the last emitted
+ * byte. The store's own row uses an INCLUSIVE end, so the conversion is
+ * `endExclusive = row.endInclusive + 1` and it is done in exactly one place
+ * (see `exportAsm()`'s block construction).
+ *
+ * WHY BOTH ENDS. `!cpu 6510` plus correct-looking mnemonics is not enough:
+ * measured, a substitution that changes ONE instruction's length -- dropping
+ * ACME's `+2` size force from an absolute operand below `$0100`, or
+ * forward-referencing a zero-page symbol -- assembles at exit 0 and shifts
+ * every byte after it. The end assertion is what turns that into a refusal:
+ * ACME exits 1, prints the `!error` text below on stderr, and writes NO output
+ * file.
+ *
+ * WHY THE EXPECTED VALUE IS SPELLED OUT IN THE MESSAGE. Interpolating `*` into
+ * an `!error` renders it as `<decimal> (0x<hex>)`, not as `$hex`, so the
+ * expected value is written in `$` form in the message text itself rather than
+ * relying on ACME's rendering.
+ *
+ * WHY NOT `!pseudopc`. It is not an alternative: measured, it errors with
+ * `Program counter undefined.` unless `*` has already been set.
+ */
+function emitBlock(start: number, endExclusive: number, lines: readonly string[]): string[] {
+  return [
+    `* = ${hexExtent(start)}`,
+    `!if * != ${hexExtent(start)} { !error "export-asm: block origin drifted, expected ${hexExtent(start)}" }`,
+    ...lines,
+    `!if * != ${hexExtent(endExclusive)} { !error "export-asm: block end drifted, expected ${hexExtent(endExclusive)}" }`,
+  ];
+}
+
+/**
+ * Reads the image and dispatches its layout, BY EXTENSION FIRST and never by
+ * byte length. That order is a contract copied from the surface's own image
+ * loaders rather than re-derived: a truncated flat capture that falls through
+ * to the `.prg` parser gets a load address read backwards out of its own
+ * payload bytes, and every downstream address is then wrong with no
+ * diagnostic.
+ */
+function loadImage(imagePath: string): { origin: number; bytes: Uint8Array } {
+  let raw: Uint8Array;
+  try {
+    raw = new Uint8Array(readFileSync(imagePath));
+  } catch (err) {
+    // An ERRNO-class failure (ENOENT, EACCES, EISDIR) carries no byte of the
+    // file's content, so it is left interpolated on purpose.
+    throw new Error(`exportAsm: could not read the image at "${imagePath}": ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const ext = extname(imagePath).toLowerCase();
+  if (ext === ".raw" || ext === ".bin") {
+    return { origin: flatImageOrigin(raw), bytes: raw };
+  }
+  if (ext !== ".prg" && raw.length === 65536) {
+    return { origin: flatImageOrigin(raw), bytes: raw };
+  }
+  if (ext === ".prg") {
+    const { origin, body } = parsePrg(raw);
+    return { origin, bytes: new Uint8Array(body) };
+  }
+  throw new Error(
+    `exportAsm: the image at "${imagePath}" has extension "${ext}", which is not one this exporter reads. ` +
+      `Supply a .prg (2-byte load address plus payload) or a flat 64K capture (.raw/.bin, exactly 65536 bytes).`,
+  );
+}
+
+/**
+ * Formats one header symbol definition.
+ *
+ * THE HEX-DIGIT COUNT IS LOAD-BEARING, not cosmetic. Measured on ACME 0.97:
+ * `zpf = $10` then `lda zpf` assembles to `a5 10` (2 bytes, zeropage), while
+ * `zpf = $0010` then the same `lda zpf` assembles to `ad 10 00` (3 bytes,
+ * absolute). The DEFINITION's width decides the OPERAND's width, so an address
+ * below `$0100` must be written with two digits and everything else with four.
+ * Getting this wrong ships an export that ACME accepts and that produces the
+ * wrong bytes -- the single most likely way for this module to be quietly
+ * incorrect.
+ *
+ * THE HEX CASE IS LOWER, MATCHING EVERY OTHER EMITTER IN THIS DOCUMENT
+ * (30-REVIEW IN-03, corrected 2026-08-31). This function used to emit
+ * uppercase (`start = $C000`) while `hex2()`, `hex4()` and `hexExtent()` all
+ * emit lowercase (`* = $0801`, `!byte $a9`), so one generated file carried two
+ * conventions. Both assemble identically -- ACME is case-insensitive for hex
+ * digits, and the round-trip byte-diff is unchanged by this -- so the only
+ * cost was that the artefact read as if two tools had written it. Lower is
+ * chosen because it is what the other three emitters, and the golden witness
+ * disassembly they were matched to, already use: one emitter changes rather
+ * than three.
+ *
+ * The WIDTH rule above is untouched by this and is not a matter of taste.
+ */
+function formatSymbolDefinition(name: string, address: number): string {
+  const digits = address < 0x100 ? 2 : 4;
+  return `${name} = $${address.toString(16).padStart(digits, "0")}`;
+}
+
+/**
+ * One mid-instruction label definition, in the golden witness's own compact
+ * spelling -- no spaces around the `=`, the offset in two hex digits:
+ * `f_0900 =*+$01` [`.planning/notes/dxa-ghidra-pivot-evidence/anno.asm:202`].
+ * That witness carries SIX such labels (lines 51, 81, 135, 145, 202 and 205);
+ * the ROADMAP note saying four is documentation drift, corrected in
+ * `30-RESEARCH.md`.
+ *
+ * `offset` is `label.address - instr.address`, so it is 1 or 2 for every
+ * 6502/6510 instruction -- the value is rendered rather than bounded here
+ * because the caller derives it from a decoded instruction's own length and
+ * cannot produce anything else.
+ */
+function midInstructionLabelLine(name: string, offset: number): string {
+  return `${name} =*+$${offset.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Below this address a mid-instruction label is REFUSED rather than emitted.
+ * See `exportAsm()`'s code-block emitter for the measured reason.
+ */
+const MID_INSTRUCTION_LABEL_FLOOR = 0x100;
+
+/**
+ * The fixed trailing comment that marks an auto-generated symbol name in the
+ * emitted source. ONE spelling, in one place: a second wording would make the
+ * marker ungreppable for the human reading the generated assembly, which is the
+ * only reader it exists for.
+ */
+const AUTO_NAME_MARKER = "  ; auto-generated name -- still in the annotation backlog";
+
+/**
+ * The fixed trailing comment that marks a definition at an address carrying
+ * MORE THAN ONE store label (30-REVIEW WR-02). ONE spelling, in one place, for
+ * the same reason `AUTO_NAME_MARKER` is: a second wording makes it ungreppable
+ * for the only reader it exists for.
+ *
+ * The full marker is this prefix, the colliding names in `sortedLabels` order,
+ * and which of them references actually render through -- so the arbitrary
+ * pick `symbolFor()` used to make in silence is stated in the artefact.
+ */
+const ALIAS_MARKER_PREFIX = "  ; ALIAS: this address also carries ";
+
+/**
+ * The fixed leading comment on every line carrying a provenance ledger row's
+ * Verdict and Confidence (BUILD-05, phase 46 plan 01). ONE spelling, in one
+ * place, for the same reason `AUTO_NAME_MARKER` and `ALIAS_MARKER_PREFIX`
+ * are: a second wording makes it ungreppable for the only reader it exists
+ * for.
+ *
+ * THIS SPELLING WAS CHOSEN, NOT INHERITED. `diff-images.mjs`'s own
+ * `renderLedger()` header prose mentions `; PROVENANCE:` once, as an
+ * unwired, forward-looking remark about THIS PROJECT'S OWN documentation
+ * provenance conventions -- it names no writer, no reader and no format, and
+ * `.planning/ARCHITECTURE.md` (the real one, not `.planning/research/
+ * ARCHITECTURE.md`) never uses the word "provenance" at all. Reusing that
+ * string silently would attribute intent to it that it does not carry
+ * (`46-RESEARCH.md` Pitfall 6). `PROVENANCE_MARKER_PREFIX` is therefore a
+ * deliberately DIFFERENT, prefix-distinct spelling: `; PROVENANCE LEDGER:`,
+ * never `; PROVENANCE:`.
+ */
+const PROVENANCE_MARKER_PREFIX = "  ; PROVENANCE LEDGER: ";
+
+/**
+ * The fixed leading comment recording that MORE THAN ONE ledger row overlaps
+ * one emitted block. Same rationale as `PROVENANCE_MARKER_PREFIX` above: one
+ * spelling, in one place. The ambiguity is RECORDED, exactly as
+ * `ALIAS_MARKER_PREFIX` records a colliding label, never resolved by picking
+ * one row and staying silent about the rest (T-46-03).
+ */
+const PROVENANCE_AMBIGUITY_MARKER_PREFIX = "  ; PROVENANCE LEDGER AMBIGUITY: ";
+
+/**
+ * The fixed leading comment on every line naming a user-requested exclusion
+ * (`BUILD-07`, phase 46 plan 05). ONE spelling, in one place, for the same
+ * reason `AUTO_NAME_MARKER`, `ALIAS_MARKER_PREFIX` and `PROVENANCE_MARKER_PREFIX`
+ * are: a second wording would make it ungreppable for the only reader it
+ * exists for, and criterion 2's own readback -- recovering what was excluded
+ * and why straight out of the exported text -- depends on there being exactly
+ * one spelling to anchor on.
+ *
+ * THIS IS HOW A USER'S REQUEST TO LEAVE A SPAN OUT APPEARS IN THE ARTEFACT,
+ * and it is deliberately a MARKER rather than an OMISSION: `BUILD-07` requires
+ * the export be lossless by default, and any exclusion be "emitted as a
+ * recorded excluded range rather than a hole". The failure this constant's
+ * existence prevents is the obvious wrong implementation -- skipping the
+ * block would satisfy the word "exclude" and lose the bytes, and the
+ * byte-diff oracle downstream could only ever report that as a coverage gap,
+ * never as "the user asked for this". Every block carrying an overlapping
+ * exclusion record is still emitted in full, with this comment prepended,
+ * never in place of any content.
+ */
+export const EXCLUSION_MARKER_PREFIX = "  ; EXCLUDED BY USER REQUEST: ";
+
+/**
+ * The largest value an enum variant may carry to be substitutable into an
+ * IMMEDIATE operand.
+ *
+ * Measured on ACME 0.97: `viccolor_WIDE = $0100` then `lda #viccolor_WIDE`
+ * is `Error ... : Number does not fit in 8 bits.` at exit 1. The exporter
+ * refuses FIRST so the message can name the store row and the enum, rather than
+ * a line number in a temp file the caller never sees.
+ */
+const MAX_IMMEDIATE_VARIANT_VALUE = 0xff;
+
+/**
+ * The SHAPE `registerKeyFor(address).slice(1)` always produces (uppercase,
+ * exactly four hex digits) -- the SAME string `planEnumsForPairing()` uses as
+ * a project enum's own `enumName` (`anno-enum-gen.ts`, D-15). An enum usage
+ * whose `enumName` matches this shape is a CANDIDATE for
+ * `decomposeRegisterValue()`; one that does not (a hand-authored name like
+ * `viccolor`) is never a candidate at all -- this module holds no second
+ * table of which arbitrary names are "really" registers, and guessing would
+ * be exactly the kind of plausible-looking wrong answer this file refuses
+ * everywhere else. Lowercase is deliberately excluded: every writer of this
+ * convention (`registerKeyFor()`) emits uppercase, and matching lowercase too
+ * would accept a shape nothing in this codebase produces.
+ *
+ * SHAPE ALONE IS NOT ENOUGH (45-REVIEW CR-01, fixed 2026-09-11): a candidate
+ * is only ATTEMPTED once `hasRegBitsEntry()` also confirms `anno-regbits.json`
+ * has a table entry for it. `$D020`/`$D021` -- among the most commonly
+ * hand-annotated C64 registers -- are register-shaped and absent from the
+ * table; before this fix, naming either via `anno_create_project_enum` made
+ * the WHOLE export throw instead of falling through to the pre-existing
+ * single-symbol path. See the call site below for the two-part gate.
+ */
+const REGISTER_ENUM_NAME_RE = /^[0-9A-F]{4}$/;
+
+/**
+ * Replaces the `#$XX` immediate literal `renderLine()` produced with `#symbol`.
+ *
+ * WHY A TARGETED TEXT SUBSTITUTION RATHER THAN A `RenderOptions` WIDENING.
+ * D-11 forbids `renderLine()` from substituting a symbol into an immediate
+ * operand at all, because of the `#<`/`#>` high/low-byte ambiguity, and that
+ * rule is verified against a real assembler in `disasm-roundtrip.test.ts`. It
+ * is not relaxed here. What an ENUM adds is a caller-supplied fact the renderer
+ * does not have -- that this particular byte is a member of a named vocabulary
+ * -- so the substitution happens at this boundary, on this module's own output,
+ * for exactly one operand whose width is one byte and therefore cannot change.
+ *
+ * The literal is located and matched EXACTLY. A rendered line that does not
+ * carry the expected literal is a disagreement between this module and the
+ * renderer, and it is refused rather than patched over: a `replace()` that
+ * silently matched nothing would emit the hex literal while the count claimed a
+ * substitution happened.
+ *
+ * THE SEARCH IS CONFINED TO THE DIRECTIVE HALF OF THE LINE, AND THAT IS THE
+ * SECOND HALF OF 30-REVIEW CR-01's FIX (2026-08-31). `renderLine()` emits a
+ * trailing `"  ; "` comment for notes, and for an instruction whose
+ * `acmeExpressible` is false it emits the whole thing as a `!byte` directive
+ * with the mnemonic AND its `#$xx` operand moved INTO that comment
+ * (`disasm-renderer.ts`'s `!instr.acmeExpressible` branch). A bare
+ * `line.indexOf()` therefore found `#$00` in the COMMENT, rewrote it there,
+ * and returned a line whose assembler-visible half still carried the raw
+ * byte -- while the caller counted a substitution and the export exited 0.
+ * Reproduced against the committed code before this fix, for `$eb`
+ * (`sbc #imm`):
+ *
+ *   !byte $eb, $00  ; sbc #viccolor_BLACK  [illegal opcode | not expressible ...]
+ *
+ * The caller now refuses an unexpressible opcode outright, so this confinement
+ * is defence in depth against the same class of mistake arriving by a
+ * different route -- a future renderer that puts a `#$xx` in a comment for any
+ * other reason gets the "does not contain the literal" refusal below instead
+ * of a silent no-op substitution.
+ *
+ * EXPORTED FOR TEST REACH ONLY, on the same terms as
+ * `assertExportableCommentText()` below: no other module calls it, and the one
+ * that would (`anno-cli.ts`) goes through `exportAsm()`. It is exported
+ * because the caller now refuses an unexpressible opcode BEFORE reaching here,
+ * which makes the confinement above unreachable through `exportAsm()` and
+ * therefore untestable at that level -- an untested guard is the thing that
+ * lets the next route in.
+ */
+export function substituteImmediateEnum(line: string, value: number, symbol: string, address: number): string {
+  const literal = `#${hex2(value)}`;
+  // `"  ; "` is `renderLine()`'s own comment separator, in the one place this
+  // module has to know about it. Everything from it onward is prose for a
+  // human and is never assembler input; a substitution there reaches nobody.
+  const directiveHalf = line.split("  ; ")[0];
+  const at = directiveHalf.indexOf(literal);
+  if (at < 0) {
+    throw new Error(
+      `exportAsm: the instruction at ${hex4(address)} carries an enum usage, but the ASSEMBLER-VISIBLE half of its rendered line ` +
+        `does not contain the immediate literal ${literal} this module expected to replace. Refusing to emit a line whose ` +
+        `substitution silently did nothing (or landed in the trailing comment, where the assembler never reads it).`,
+    );
+  }
+  return `${line.slice(0, at)}#${symbol}${line.slice(at + literal.length)}`;
+}
+
+/**
+ * The store's own spellings for the two comment placements, DESTRUCTURED out of
+ * `COMMENT_TYPES` -- the ONE home of that vocabulary -- rather than re-typed as
+ * literals here. The same idiom `anno-memmap-render.ts` uses at its own read
+ * boundary: a re-typed `"line"` is a second copy of a vocabulary that has one
+ * home, and the two diverge in silence the first time the schema's spelling
+ * changes.
+ */
+const [LINE_COMMENT, SIDE_COMMENT] = COMMENT_TYPES;
+
+/**
+ * Re-checks, at the EXPORT boundary, that a stored comment can be emitted.
+ *
+ * WHY THIS EXISTS RATHER THAN TRUSTING THE STORE. `assertCommentText()` is the
+ * one comment-text vocabulary and it now refuses an embedded line break -- but
+ * a store file written BEFORE that refusal existed, or through any route that
+ * did not call it, can still hold one on disk. This boundary is the last place
+ * before those bytes become assembler input, so it asks the question again. It
+ * RE-CHECKS rather than RE-DEFINES: the predicate is `assertCommentText()`'s,
+ * called here, never a second regex that could drift from it.
+ *
+ * The store validator's own message is deliberately DISCARDED and replaced.
+ * That message interpolates the offending text for one of its four cases, and
+ * an exporter error that quotes a file's contents back is a content-disclosure
+ * oracle (CR-03). What survives is the address and which rule fired -- facts
+ * ABOUT the comment, never the comment.
+ */
+export function assertExportableCommentText(text: string, address: number): string {
+  try {
+    return assertCommentText(text);
+  } catch (err) {
+    const reason = err instanceof AnnoCommentError && err.reason !== undefined ? err.reason : "refused by the store's comment-text vocabulary";
+    throw new Error(
+      `exportAsm: the comment at ${hex4(address)} cannot be emitted (${reason}). Every comment this exporter emits is a single line of text ` +
+        `that the store's own comment-text vocabulary accepts; a stored line break would put everything after it into the ACME source at ` +
+        `column zero, as assembler input rather than as a comment. REFUSED rather than repaired -- stripping or truncating here would change ` +
+        `what somebody wrote and report success.`,
+    );
+  }
+}
+
+/**
+ * Re-checks, at the EXPORT boundary, that a stored range's `dataType` is one
+ * the store's own vocabulary defines (30-REVIEW WR-03).
+ *
+ * The sibling of `assertExportableCommentText()` below, on the same terms and
+ * for the same reason: `listRanges()` casts the column with no validator, so
+ * this is the last place before that string is interpolated into ACME source
+ * text. See the call site in `exportAsm()` for the full record.
+ *
+ * The store validator's own message is deliberately DISCARDED and replaced,
+ * again for `assertExportableCommentText()`'s reason: `assertDataType()`
+ * interpolates the offending value, and an exporter error that quotes a
+ * file's contents back is a content-disclosure oracle. What survives is the
+ * ADDRESS RANGE and the valid list -- facts about the row and about this
+ * module's own vocabulary, never a byte read off disk.
+ *
+ * EXPORTED FOR TEST REACH ONLY, on the same terms as
+ * `assertExportableCommentText()`: the state it guards against is reachable
+ * only through a store file edited outside `anno-store.ts`, and
+ * `anno-store.ts` is the ONE module in this repo permitted to name
+ * `node:sqlite` -- so a test cannot manufacture the row and can only drive the
+ * predicate. An unreachable-through-the-type guard with no test is how the
+ * next such column goes unchecked.
+ */
+export function assertDataTypeForExport(row: { start: number; endInclusive: number; dataType: unknown }): DataType {
+  try {
+    return assertDataType(row.dataType);
+  } catch {
+    throw new Error(
+      `exportAsm: the range ${hex4(row.start)}..${hex4(row.endInclusive)} (inclusive) carries a data type that is not one of the ` +
+        `${DATA_TYPES.length} the store defines (${DATA_TYPES.join(", ")}) -- refusing to guess what it meant. This module copies a ` +
+        `range's data type VERBATIM into the emitted source's block comment, so an unvalidated value reaches ACME as text: one ` +
+        `containing a line break would put everything after it at column zero, as assembler input rather than as a comment. ` +
+        `The offending value is deliberately NOT quoted here -- an exporter error that echoes a file's contents is a ` +
+        `content-disclosure oracle.`,
+    );
+  }
+}
+
+/** Where the comments live while a block is being emitted, and which of them
+ * have found a line to attach to. Anything still unplaced when the last block
+ * is done is REFUSED by name rather than dropped. */
+interface CommentPlacement {
+  byAddress: ReadonlyMap<number, CommentRow[]>;
+  placed: Set<number>;
+}
+
+/**
+ * Attaches every stored comment for the addresses `[start, endExclusive)` to
+ * one emitted line: a `line` comment on its own line immediately before it, a
+ * `side` comment appended to it.
+ *
+ * Multiple comments at one address emit in `id` order, which is the order
+ * `listComments()` returns them in -- so two people's notes at one address keep
+ * the order they were written in rather than an order this module invented.
+ *
+ * A COMMENT ON A MULTI-ADDRESS LINE IS QUALIFIED WITH ITS OWN ADDRESS
+ * (30-REVIEW IN-02, added 2026-08-31). The CODE path calls this with a span of
+ * exactly ONE address (`[instr.address, instr.address + 1)`), so a comment
+ * there is unambiguous and is emitted unchanged -- nothing about the existing
+ * output moves. The DATA path calls it with a span of up to
+ * `BYTES_PER_DATA_LINE` addresses, and there `n` comments on `n` DISTINCT data
+ * bytes emitted as `n` indistinguishable lines above one `!byte` directive: a
+ * human reading the generated assembly could not tell which byte each note was
+ * about, and the information was not recoverable from the artefact.
+ *
+ * QUALIFIED RATHER THAN SPLIT. Splitting the `!byte` line at each commented
+ * address was the other candidate and is worse here: it changes the emitted
+ * TEXT's structure for a presentation problem, and every extra directive is
+ * another line whose width and origin the byte-diff has to keep agreeing
+ * about. A prefix changes nothing an assembler reads.
+ *
+ * GATED ON AMBIGUITY, not applied always: prefixing every code-path comment
+ * with an address it already sits next to is noise, and it would rewrite every
+ * existing expected line in the test suite for nothing.
+ *
+ * `generatedSuffix` (D-17, plan 45-05) is this module's OWN mechanical text --
+ * today, only `decomposeRegisterValue()`'s decoded-field comment for an OR-ed
+ * multi-bit enum substitution -- never a second stored comment. It is NEVER
+ * DROPPED and NEVER REORDERED BEHIND authored text: when a stored SIDE
+ * comment exists at the same address, the authored text renders FIRST and
+ * `generatedSuffix` follows a ` -- ` separator on the SAME trailing comment;
+ * when none exists, `generatedSuffix` is appended alone. Only the FIRST side
+ * comment found absorbs it -- a second one at the same address (a supported
+ * but rare store state) still renders, just without the merge, so the
+ * generated text is never silently duplicated across two lines.
+ */
+function withComments(text: string, start: number, endExclusive: number, ctx: CommentPlacement, generatedSuffix?: string): string[] {
+  const before: string[] = [];
+  let line = text;
+  let generatedMerged = false;
+
+  // One emitted line covering more than one address cannot say WHICH address a
+  // comment belongs to unless the comment says so itself.
+  const spanIsAmbiguous = endExclusive - start > 1;
+
+  for (let address = start; address < endExclusive; address++) {
+    for (const row of ctx.byAddress.get(address) ?? []) {
+      const checked = assertExportableCommentText(row.text, row.address);
+      const safe = spanIsAmbiguous ? `${hex4(row.address)}: ${checked}` : checked;
+      ctx.placed.add(row.id);
+      if (row.commentType === LINE_COMMENT) {
+        before.push(`${INDENT}; ${safe}`);
+      } else if (row.commentType === SIDE_COMMENT) {
+        if (generatedSuffix !== undefined && !generatedMerged) {
+          line = `${line}  ; ${safe} -- ${generatedSuffix}`;
+          generatedMerged = true;
+        } else {
+          line = `${line}  ; ${safe}`;
+        }
+      } else {
+        // Unreachable through the type, and reachable through a store file
+        // somebody edited. Refusing beats guessing which of the two placements
+        // an unknown third one meant.
+        throw new Error(
+          `exportAsm: the comment at ${hex4(row.address)} has placement ${JSON.stringify(row.commentType)}, which is not one of the ` +
+            `${COMMENT_TYPES.length} placements the store defines (${COMMENT_TYPES.join(", ")}) -- refusing to guess where it belongs.`,
+        );
+      }
+    }
+  }
+
+  if (generatedSuffix !== undefined && !generatedMerged) {
+    line = `${line}  ; ${generatedSuffix}`;
+  }
+
+  return [...before, line];
+}
+
+/**
+ * Phase 47, plan 47-04 (BUILD-03): the address one decoded instruction's
+ * operand REFERENCES, for the in-tree symbol rule below -- the SAME address
+ * a substitution would substitute, extracted through `resolvedTarget` FIRST
+ * (`disasm-decoder.ts` rule 5 for every relative branch, rule 6 for absolute
+ * `jmp` ($4C) and `jsr` ($20)), and otherwise through the operand's own
+ * `value` for the `absolute`, `zeropage` and `indirect` roles -- the same
+ * three roles `disasm-renderer.ts`'s own `resolveSymbol()` call sites read.
+ *
+ * AN `immediate` OPERAND IS DELIBERATELY NEVER A REFERENCE, and returns
+ * `undefined` here exactly as it falls through every branch below. An
+ * immediate is a BYTE VALUE, not an address: project enums (the
+ * `usageByAddress` branch above) are what give one a name, and treating it as
+ * an address is how `lda #$08` would start demanding a label be recorded at
+ * `$0008`. `disasm-renderer.ts`'s own D-11 comment states the same exclusion
+ * for the identical reason, on the substitution side of this same boundary.
+ */
+function referencedAddress(instr: Instruction): number | undefined {
+  if (instr.resolvedTarget !== undefined) return instr.resolvedTarget;
+  const role = instr.operand?.role;
+  if (role === "absolute" || role === "zeropage" || role === "indirect") return instr.operand!.value;
+  return undefined;
+}
+
+/**
+ * Phase 47, plan 47-04 (BUILD-03, D47-F): true iff `address` falls inside
+ * `[block.start, block.endExclusive)` for SOME block this export emitted --
+ * the half-open interval every other boundary test in this module already
+ * uses. Tested against the `blocks` array `exportAsm()` already built at the
+ * top of the function, never a second range list derived independently of
+ * it: a second list is exactly how the in-tree test and the emitted blocks
+ * could drift apart.
+ *
+ * D47-F'S BOUNDARY, STATED HERE BECAUSE THIS IS WHERE IT IS DECIDED: an
+ * address OUTSIDE every emitted block -- a hardware register like `$d020`,
+ * a KERNAL entry like `$ffd2` -- is NOT in-tree, and a reference to one is
+ * rendered as a hex literal and is never refused. Those addresses are fixed
+ * hardware that cannot move, which is precisely what "so the code can move"
+ * is about; a rule that refused on them would make every real export
+ * impossible and would be measuring the wrong thing.
+ */
+function isInTree(address: number, blocks: readonly ExportBlock[]): boolean {
+  return blocks.some((block) => address >= block.start && address < block.endExclusive);
+}
+
+/**
+ * Exports the annotation store at `options.storePath`, over the image at
+ * `options.imagePath`, as ACME source plus the exact bytes that source must
+ * assemble to.
+ *
+ * The returned `source` is NOT self-verifying and this function makes no claim
+ * that it reassembles: that claim is settled by assembling it with a real ACME
+ * and byte-diffing the result against `expectedBytes`.
+ *
+ * Throws (never returns a degraded result) when the store holds no ranges, when
+ * a range is not covered by the image, or when a label name is not a legal ACME
+ * identifier. Every message is prefixed `exportAsm:` and carries paths,
+ * addresses and counts only.
+ */
+export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
+  const { storePath, imagePath, workspaceRoot, ledgerPath } = options;
+
+  const image = loadImage(imagePath);
+
+  // ONE handle for the whole export, closed in a `finally`. `mustExist` is what
+  // makes "the annotations are gone" and "there are no annotations" refuse
+  // differently: without it a mistyped path would CREATE an empty store and
+  // export as a program with nothing annotated, indistinguishable from a real
+  // one.
+  const handle = openStore(storePath, { workspaceRoot, mustExist: true });
+  let ranges: RangeRow[];
+  let labels: LabelRow[];
+  let comments: CommentRow[];
+  let projectEnums: ProjectEnumRow[];
+  let enumUsage: EnumUsageRow[];
+  let excludedRanges: ExcludedRangeRow[];
+  let scopes: ScopeRow[];
+  try {
+    ranges = listRanges(handle);
+    labels = listLabels(handle);
+    comments = listComments(handle);
+    projectEnums = listProjectEnums(handle);
+    enumUsage = listEnumUsage(handle);
+    // BUILD-07 (phase 46 plan 05): a sixth read in the SAME handle and the
+    // SAME `try`, mirroring the discipline the five siblings above already
+    // follow -- one handle for the whole export, closed once in the
+    // `finally` below. There is no second store opened for this.
+    excludedRanges = listExcludedRanges(handle);
+    // Phase 47, plan 47-01: a SEVENTH read in the SAME handle and the SAME
+    // `try`, on the same terms as the sixth above -- still one handle for
+    // the whole export, closed once in the `finally` below. There is no
+    // second store opened for this either.
+    scopes = listScopes(handle);
+  } finally {
+    closeStore(handle);
+  }
+
+  if (ranges.length === 0) {
+    throw new Error(
+      `exportAsm: the annotation store at "${storePath}" holds no ranges -- refusing to emit an empty ACME source, ` +
+        `because "nothing is annotated" and "the export produced nothing" must not read the same.`,
+    );
+  }
+
+  const sortedRanges = [...ranges].sort((a, b) => a.start - b.start);
+
+  // The store's end is INCLUSIVE; ACME's `*` after a block sits one past the
+  // last byte. This conversion is a documented carried hazard in this project
+  // with several boundaries -- it is done ONCE, here.
+  const blocks: ExportBlock[] = sortedRanges.map((row) => ({
+    start: row.start,
+    endExclusive: row.endInclusive + 1,
+    // THE STORE'S `dataType` IS RE-CHECKED AT THIS BOUNDARY (30-REVIEW WR-03,
+    // fixed 2026-08-31), for exactly the reason `withComments()` re-checks
+    // `commentType` a few functions up: "Unreachable through the type, and
+    // reachable through a store file somebody edited. Refusing beats
+    // guessing." That reasoning applies here and had not been applied.
+    //
+    // `listRanges()` casts `row.data_type as DataType` with no validator call
+    // (`anno-store.ts`), so a store whose `anno_range.data_type` column was
+    // edited on disk carried an ARBITRARY string into `emitDataLines()`, which
+    // interpolates it verbatim into the emitted block comment. A value
+    // containing a line break would put everything after it into the ACME
+    // source at COLUMN ZERO, as assembler input rather than as a comment --
+    // the same mechanism `assertExportableCommentText()` refuses for comment
+    // text, arriving through a column nobody had checked.
+    //
+    // The block-end `!if` assertion would catch the resulting drift at
+    // ASSEMBLY time, but the `anno export-asm` CLI verb assembles nothing: it
+    // would write the corrupted file and exit 0. This is the last boundary
+    // before those bytes become assembler input, so it asks the question here.
+    //
+    // RE-CHECKS rather than RE-DEFINES: the predicate is `assertDataType()`'s,
+    // called here, never a second list of the twelve types that could drift
+    // from it.
+    dataType: assertDataTypeForExport(row) as string,
+    lineCount: 0,
+    // Populated below, at the same point `emitBlock()` is called for this
+    // block -- empty only before that call runs.
+    lines: [],
+  }));
+
+  const imageStart = image.origin;
+  const imageEndExclusive = image.origin + image.bytes.length;
+  for (const block of blocks) {
+    if (block.start < imageStart || block.endExclusive > imageEndExclusive) {
+      throw new Error(
+        `exportAsm: the range ${hex4(block.start)}..${hex4(block.endExclusive - 1)} (inclusive) is not covered by the ` +
+          `image at "${imagePath}", which covers ${hex4(imageStart)}..${hex4(imageEndExclusive - 1)} (inclusive). ` +
+          `Refusing to export a range whose bytes the image does not contain.`,
+      );
+    }
+  }
+
+  // BUILD-05 (phase 46 plan 01): ONE read for the whole export, mirroring the
+  // one-store-handle discipline directly above. `ledgerPath === undefined` is
+  // the ONLY question asked of the caller's intent here -- everything after
+  // this line either has a ledger to join against or does not, and no branch
+  // anywhere below (here or in the per-block loop) ever reads a Verdict,
+  // Confidence or Kind VALUE to decide anything.
+  const ledger: ProvenanceLedger | undefined = ledgerPath === undefined ? undefined : readProvenanceLedger(ledgerPath);
+
+  // The label index the renderer's `symbolFor` hook reads. Every name is
+  // validated BEFORE it can reach the source text -- REJECT, never sanitise.
+  const sortedLabels = [...labels].sort((a, b) => a.address - b.address);
+  const labelIndex = new Map<number, string>();
+  /** Every address carrying MORE THAN ONE store label, with all their names in
+   * `sortedLabels` order. See the loop below for why this is recorded rather
+   * than refused. */
+  const aliasedAddresses = new Map<number, string[]>();
+  for (const label of sortedLabels) {
+    assertLegalAcmeIdentifier(label.name, `exportAsm: label at ${hex4(label.address)}`);
+    // TWO NAMES AT ONE ADDRESS IS RECORDED IN THE EMITTED SOURCE, NOT RESOLVED
+    // IN SILENCE (30-REVIEW WR-02, second half, fixed 2026-08-31).
+    //
+    // `labelIndex` is a `Map<number, string>` while `anno_label` is `unique`
+    // on NAME only -- `setLabel()` refuses only a name already bound to a
+    // DIFFERENT address -- so two names at one address is a SUPPORTED store
+    // state (an alias). In it, this `set()` silently overwrote the first and
+    // `symbolFor()` returned whichever name sorted last. Reproduced: with
+    // `smc_operand` and `smc_alias` both at $0802, the emitted `inc`
+    // referenced `smc_alias` with no diagnostic anywhere.
+    //
+    // NOT REFUSED, DELIBERATELY, and this is the one place in this module that
+    // records rather than refuses. Every other refusal here is for something
+    // the exporter CANNOT express; an alias it CAN -- both definitions go into
+    // the header (or inline), ACME accepts two symbols with one value, and the
+    // bytes are unaffected. The only thing that was wrong is that the arbitrary
+    // pick for REFERENCES was invisible. Refusing instead would delete a
+    // supported store state to fix a diagnostic problem.
+    //
+    // FIRST NAME WINS, not last: `sortedLabels` is ascending by address and
+    // otherwise in `listLabels()` order, so keeping the first makes the pick
+    // stable rather than an artefact of a sort that never promised a
+    // tiebreak. The comment emitted with the definitions names every
+    // candidate, so a human reading the source can see what was chosen and
+    // what was not.
+    const existing = labelIndex.get(label.address);
+    if (existing === undefined) {
+      labelIndex.set(label.address, label.name);
+    } else {
+      const names = aliasedAddresses.get(label.address);
+      if (names) names.push(label.name);
+      else aliasedAddresses.set(label.address, [existing, label.name]);
+    }
+  }
+  const symbolFor = (address: number): string | undefined => labelIndex.get(address);
+
+  /** EVERY store label's NAME, whether it ends up defined in the header or
+   * inline. `labelIndex` cannot serve this: it is keyed by address and holds
+   * only the first name at each, so an ALIASED label would be invisible to a
+   * collision check reading it. ACME has ONE symbol namespace, so an enum
+   * variant symbol colliding with any of these is `Symbol already defined.`
+   * (30-REVIEW WR-10). */
+  const labelSymbolNames = new Set(sortedLabels.map((label) => label.name));
+
+  // Comments indexed by the address they annotate, each address's list left in
+  // `listComments()`'s own `id` order.
+  const commentsByAddress = new Map<number, CommentRow[]>();
+  for (const row of comments) {
+    const at = commentsByAddress.get(row.address);
+    if (at) at.push(row);
+    else commentsByAddress.set(row.address, [row]);
+  }
+  const placement: CommentPlacement = { byAddress: commentsByAddress, placed: new Set<number>() };
+
+  // Enum usages indexed by the address they annotate. `listEnumUsage()` already
+  // resolves the enum's NAME through a join on `anno_enum.id`, so this module
+  // never holds a second on-disk copy of it; the row set is turned into an
+  // address lookup here and the enum's own variants are joined on by name from
+  // `listProjectEnums()`.
+  const enumsByName = new Map<string, ProjectEnumRow>();
+  for (const row of projectEnums) enumsByName.set(row.name, row);
+  const usageByAddress = new Map<number, EnumUsageRow>();
+  for (const row of enumUsage) usageByAddress.set(row.address, row);
+  const appliedEnumUsage = new Set<number>();
+  /** `<enumName>_<VARIANT> = $XX` definition lines, in first-emitted order.
+   * They join the header block for the same reason label definitions do. */
+  const enumDefinitionLines: string[] = [];
+  /** Every emitted enum-derived symbol name (single-value or OR-ed term) to
+   * the ONE value it was defined with. A Map, not a Set (D-17, plan 45-05):
+   * a term name defined by one instruction with one value and referenced by a
+   * SECOND instruction with a DIFFERENT value is a genuine collision in
+   * ACME's one symbol namespace, and the value is what makes that collision
+   * detectable rather than merely a duplicate-looking string. */
+  const definedEnumSymbols = new Map<string, number>();
+
+  let unexpressibleCount = 0;
+  let dataByteCount = 0;
+  let enumDecompositionCount = 0;
+  /** Phase 47, plan 47-03 (BUILD-02): every `external_file`-typed block's
+   * own `.bin` sibling, populated at the same point `dataByteCount` above
+   * is incremented for that block -- see `ExportAsmResult.binaries`'s own
+   * doc-comment for what a caller reading this field is obliged to do. */
+  const binaries: ExportBinary[] = [];
+
+  /** Phase 47, plan 47-04 (BUILD-03): one in-tree reference this export could
+   * not resolve to a symbol -- collected across the WHOLE block loop and
+   * refused ONCE at the end, in the shape the unapplied-enum-usage and
+   * unplaced-comment refusals below already use. */
+  interface UnresolvedReference {
+    referringAddress: number;
+    targetAddress: number;
+  }
+  const unresolvedReferences: UnresolvedReference[] = [];
+  /** How many in-tree references this export encountered, resolved or not --
+   * the denominator for the refusal's own "N of M" count, on the same terms
+   * `enumUsage.length` is the denominator for the unapplied-enum-usage
+   * refusal below. */
+  let inTreeReferenceCount = 0;
+
+  // AUTO-GENERATED NAMES ARE MARKED, not filtered. Every store label reaches
+  // the source either way; the marker is the backlog signal, carried into the
+  // one artefact that leaves this tree. The predicate is
+  // `AUTO_NAME_PREFIX_RE`'s, imported -- never a second copy. It is applied at
+  // BOTH definition sites, header and inline, so an auto-named self-modifying
+  // code operand is as visible in the backlog as any other.
+  let autoNamedSymbolCount = 0;
+  const markIfAutoNamed = (name: string, line: string): string => {
+    if (!AUTO_NAME_PREFIX_RE.test(name)) return line;
+    autoNamedSymbolCount++;
+    return `${line}${AUTO_NAME_MARKER}`;
+  };
+
+  // THE ALIAS PICK IS MADE VISIBLE IN THE SOURCE (30-REVIEW WR-02, second
+  // half). Two store labels at one address are BOTH defined -- ACME accepts
+  // two symbols with one value and the bytes are unaffected -- but a
+  // REFERENCE to that address can render through only one of them. Which one
+  // was previously invisible. Marking both definitions with the same fixed
+  // wording means the human reading the generated assembly can see the
+  // collision and the choice, from either definition line, without having to
+  // reconstruct the exporter's sort order. Applied at BOTH definition sites,
+  // header and inline, for the reason `markIfAutoNamed()` is: an aliased
+  // self-modifying-code operand is exactly the shape this was reproduced on.
+  const markIfAliased = (address: number, line: string): string => {
+    const names = aliasedAddresses.get(address);
+    if (names === undefined) return line;
+    return `${line}${ALIAS_MARKER_PREFIX}${names.join(", ")} -- references render through ${labelIndex.get(address)}`;
+  };
+
+  // The addresses of every label emitted INLINE as `name =*+$NN`. They are
+  // collected during block emission and read afterwards by the header, which
+  // is why the header is built AFTER this loop even though it is emitted
+  // BEFORE it: a label defined inline must not ALSO be defined in the header,
+  // or ACME refuses the whole source with `Symbol already defined.`
+  const midInstructionLabelAddresses = new Set<number>();
+
+  // ONE PER EMITTED INLINE DEFINITION, not one per address (30-REVIEW WR-02).
+  // The set above answers the HEADER's question ("is this address defined
+  // inline already?"), which is per-address by nature. This counter answers
+  // the RESULT's question ("how many inline definitions does the source
+  // carry?"), which is per-label -- and two labels at one address is a
+  // supported store state, so the two questions have different answers.
+  // Incremented beside the `content.push()` that emits the line it counts,
+  // so it cannot drift from the emitted text.
+  let midInstructionLabelCount = 0;
+
+  const blockLines: string[] = [];
+
+  /** RECORDS, not lines -- one entry per `anno_excluded_range.id` that has
+   * had at least one marker line emitted for it, across every block. Read at
+   * the end for `excludedRangeCount`; see that field's own doc comment for
+   * why a record spanning two blocks must count once, not twice. */
+  const excludedRangeIdsEmitted = new Set<number>();
+
+  for (const block of blocks) {
+    const slice = image.bytes.subarray(block.start - imageStart, block.endExclusive - imageStart);
+    const content: string[] = [];
+
+    if (block.dataType === CODE_DATA_TYPE) {
+      // D-11 is inherited UNCHANGED: `renderLine()` decides operand width and
+      // refuses to substitute a symbol into an immediate or zeropage-family
+      // operand. Do not widen `RenderOptions` and do not bypass `renderLine()`.
+      // `end` IS INCLUSIVE, SO IT IS HANDED AN INCLUSIVE VALUE (30-REVIEW
+      // WR-07, corrected 2026-08-31). This used to pass `block.endExclusive`.
+      // `DecodeOptions.end` is compared with `if (end !== undefined && address
+      // > end) break` and documented as "an instruction starting past `end` is
+      // dropped ... an instruction starting AT OR BEFORE `end` is emitted in
+      // full" -- an INCLUSIVE bound. Passing the exclusive end therefore
+      // permitted one instruction more than intended.
+      //
+      // It was INERT, and that is exactly why it needed fixing rather than
+      // leaving: `slice` is exactly the block's bytes and `decode()`'s own
+      // `offset < bytes.length` loop condition bounds it first, so the `end`
+      // guard was doing nothing at all. The next maintainer who passes a WIDER
+      // slice -- to give `decode()` lookahead across a block boundary, say --
+      // inherits a silent one-instruction overrun with no test to catch it.
+      //
+      // THE SLICE IS THE AUTHORITY AND `end` IS THE BELT-AND-BRACES SECOND
+      // BOUND, stated here so the two are not read as one mechanism. Both now
+      // describe the same last byte, `block.endExclusive - 1`.
+      const instructions = decode(slice, block.start, { end: block.endExclusive - 1 });
+      for (const instr of instructions) {
+        if (!instr.acmeExpressible) unexpressibleCount++;
+
+        // A store label whose address falls STRICTLY INSIDE this instruction
+        // names one of its operand bytes -- a self-modifying-code write target.
+        // It is emitted as `name =*+$NN` on its own line IMMEDIATELY BEFORE the
+        // instruction that owns the byte, and NEVER after it.
+        //
+        // PLACEMENT IS LOAD-BEARING AND WAS MEASURED IN BOTH DIRECTIONS ON ACME
+        // 0.97. With `smc_operand =*+$01` above `lda #$00` at $0801, a later
+        // `sta smc_operand` assembles as `8d 02 08` -- $0802, the `lda`'s own
+        // operand byte. Move the same line BELOW its host and the symbol takes
+        // the value of the NEXT instruction's operand ($0804), producing
+        // `8d 04 08`. ACME exits 0 in BOTH cases and prints nothing to
+        // distinguish them: only a byte-diff tells the two apart, which is why
+        // `anno-export-asm.test.ts` carries that move as a negative control
+        // rather than trusting an exit status.
+        for (const label of sortedLabels) {
+          if (label.address <= instr.address || label.address >= instr.address + instr.bytes.length) continue;
+
+          // A mid-instruction label below $0100 is REFUSED. This is the ONE
+          // hole `disasm-renderer.ts`'s `+2` width force does not already close
+          // FOR THIS MODULE, in the precise sense that it is the one place this
+          // module has no mitigation of its own and depends entirely on the
+          // renderer's.
+          //
+          // For an ORDINARY label this module owns the mitigation: it writes
+          // the header definition with TWO hex digits below $0100 (see
+          // `formatSymbolDefinition()`), which is what makes ACME encode the
+          // reference at the original width. A `=*+$NN` label cannot use it --
+          // it is defined INLINE by construction, so its width is decided by
+          // whatever the referencing instruction's own rendering forced.
+          //
+          // MEASURED, ACME 0.97, a label at $0081 named by an earlier
+          // `lda #$00` at $0080:
+          //   `inc+2 smc_operand`  -> `ee 81 00`, EXIT 0, no diagnostic  (correct)
+          //   `inc   smc_operand`  -> `e6 81`,    EXIT 0, NO DIAGNOSTIC AT ALL
+          // Two bytes where the original was three, silently, with the whole
+          // rest of the block shifted. (The same reference placed BEFORE the
+          // definition widens instead, and does at least emit
+          // `Warning (Zone <untitled>): Using oversized addressing mode.` --
+          // still exit 0.) The only thing standing between this exporter and
+          // that shift is a `disasm-renderer.ts` invariant this module does not
+          // own, so the case is refused BY NAME rather than emitted and hoped
+          // for.
+          if (label.address < MID_INSTRUCTION_LABEL_FLOOR) {
+            throw new Error(
+              `exportAsm: label ${JSON.stringify(label.name)} names address ${hex4(label.address)} inside an instruction, and a ` +
+                `mid-instruction label below ${hex4(MID_INSTRUCTION_LABEL_FLOOR)} cannot be emitted -- it must be defined INLINE, ` +
+                `relative to the program counter at its host instruction, which forgoes this exporter's own two-hex-digit ` +
+                `header-definition width rule, and a reference to it ` +
+                `then encodes at whatever width the renderer forced. Measured on ACME 0.97: the unforced form shrinks a three-byte ` +
+                `absolute instruction to a two-byte zeropage one at exit 0 with NO diagnostic, shifting every byte after it. ` +
+                `REFUSED rather than emitted.`,
+            );
+          }
+
+          midInstructionLabelAddresses.add(label.address);
+          content.push(markIfAliased(label.address, markIfAutoNamed(label.name, midInstructionLabelLine(label.name, label.address - instr.address))));
+          midInstructionLabelCount++;
+          block.lineCount++;
+        }
+
+        let rendered = renderLine(instr, { showSymbols: true, symbolFor });
+
+        // Phase 47, plan 47-04 (BUILD-03): THE IN-TREE SYMBOL RULE, beside
+        // the `renderLine()` call it has to agree with. `rendered` above
+        // already went through `symbolFor` -- the SAME `labelIndex` map read
+        // here -- so a reference this check calls unresolved is a reference
+        // `renderLine()` also had no name for, and one this check calls
+        // resolved is a reference `renderLine()` already substituted. Reading
+        // a SECOND index here, or re-scanning `sortedLabels`, is exactly how
+        // a refusal could disagree with what the renderer actually did: it
+        // could refuse an export the renderer would have substituted
+        // correctly, or silently pass one it would not.
+        //
+        // Collected here and refused ONCE, after every block has been
+        // processed -- see the throw below the block loop for the message
+        // and D47-F's own boundary.
+        const referenced = referencedAddress(instr);
+        if (referenced !== undefined && isInTree(referenced, blocks)) {
+          inTreeReferenceCount++;
+          if (labelIndex.get(referenced) === undefined) {
+            unresolvedReferences.push({ referringAddress: instr.address, targetAddress: referenced });
+          }
+        }
+
+        // The mechanical decode text (D-17), set only by the OR-ed
+        // decomposition branch below and merged into this instruction's
+        // trailing comment by `withComments()` after the enum-substitution
+        // block finishes.
+        let decompositionComment: string | undefined;
+
+        // ENUM SUBSTITUTION, IMMEDIATE OPERAND ONLY.
+        const usage = usageByAddress.get(instr.address);
+        if (usage !== undefined) {
+          const role = instr.operand?.role;
+          if (role !== "immediate") {
+            throw new Error(
+              `exportAsm: enum ${JSON.stringify(usage.enumName)} is bound to ${hex4(usage.address)}, whose operand role is ` +
+                `${JSON.stringify(role ?? "none")} -- an enum renders on the IMMEDIATE operand only. Emitting it on any other operand ` +
+                `changes both the bytes and the instruction length while ACME exits 0 (measured on ACME 0.97: \`sta\` on a symbol below ` +
+                `$0100 encodes as zeropage, 2 bytes instead of 3). REFUSED rather than rendered.`,
+            );
+          }
+
+          // ROLE IS NOT ENOUGH: THE OPERAND MUST ALSO BE ASSEMBLER-VISIBLE
+          // (30-REVIEW CR-02, fixed 2026-08-31). `decode()` assigns
+          // `role: "immediate"` from the ADDRESSING MODE alone, independently
+          // of `acmeExpressible`. Six opcodes in `disasm-opcodes.ts` are
+          // `mode: "immediate"` AND `acmeExpressible: false` -- $2b (`anc`),
+          // $82/$89/$c2/$e2 (`nop #imm`) and $eb (`sbc #imm`). For those,
+          // `renderLine()` emits a `!byte` DIRECTIVE and moves the mnemonic
+          // and its `#$xx` operand into the trailing comment
+          // (`disasm-renderer.ts`'s `!instr.acmeExpressible` branch), so the
+          // substitution below reached the COMMENT and never the assembler:
+          // the operand stayed a raw byte in the `!byte` list, an unreferenced
+          // `viccolor_BLACK = $00` was emitted into the header, the usage was
+          // counted as applied, and the CLI printed "1 enum substitution(s)"
+          // and exited 0. The bytes stay correct, so the byte-diff oracle
+          // cannot see it either -- a round-trip test goes green on it.
+          //
+          // Reproduced against the committed code, store: one `code` range
+          // $0801..$0803 over `eb 00 60`, enum `viccolor { $00: BLACK }`
+          // applied at $0801 through the ordinary public `applyEnumUsage()`
+          // route (which performs no opcode validation, so this needs no
+          // hand-edited store):
+          //
+          //   !byte $eb, $00  ; sbc #viccolor_BLACK  [illegal opcode | ...]
+          //   === enumSubstitutionCount: 1
+          //
+          // This is D-30's "an annotation the exporter cannot express is
+          // REFUSED loudly and by name, never silently dropped while the
+          // export reports success" exactly inverted. It is refused now.
+          if (!instr.acmeExpressible) {
+            throw new Error(
+              `exportAsm: enum ${JSON.stringify(usage.enumName)} is bound to the immediate operand at ${hex4(usage.address)}, but that ` +
+                `opcode (${hex2(instr.bytes[0])}, ${instr.mnemonic}) is NOT EXPRESSIBLE in ACME's !cpu 6510 dialect. An unexpressible ` +
+                `opcode goes out as a \`!byte\` directive with its mnemonic and operand in a TRAILING COMMENT, so an enum symbol ` +
+                `substituted there would reach the comment and never the assembler -- the operand would stay a raw byte while this ` +
+                `export reported the substitution as applied. REFUSED rather than counted as applied.`,
+            );
+          }
+
+          const project = enumsByName.get(usage.enumName);
+          if (project === undefined) {
+            // Unreachable through `applyEnumUsage()`, which resolves the enum
+            // inside its own transaction, and reachable through a store file
+            // somebody edited. Refusing beats emitting an operand with no
+            // vocabulary behind it.
+            throw new Error(
+              `exportAsm: the enum usage at ${hex4(usage.address)} names enum ${JSON.stringify(usage.enumName)}, which the store holds ` +
+                `no definition for. Refusing to emit an operand whose vocabulary is missing.`,
+            );
+          }
+
+          // D-16 (plan 45-05): THE ONE OWNING DECODER. Attempted ONLY when
+          // BOTH (45-REVIEW CR-01, fixed 2026-09-11):
+          //   1. `usage.enumName` has the exact shape `registerKeyFor().slice(1)`
+          //      produces -- see `REGISTER_ENUM_NAME_RE`'s own comment for why a
+          //      name that does not have this shape (e.g. `viccolor`) is never
+          //      a candidate at all; AND
+          //   2. `anno-regbits.json` actually has a table entry for that
+          //      register (`hasRegBitsEntry()`) -- a register-shaped name for a
+          //      register the table does not cover (e.g. `D020`) is not a
+          //      decomposition failure, it is simply not a decomposable
+          //      register, and falls through to the existing single-symbol
+          //      path below with NO substitution counted.
+          // Once BOTH hold, the table DOES claim this register, and a throw
+          // here is a genuine, non-collateral data/coverage error (e.g. the
+          // disclosed `$DD00` incomplete-bitfield-table case) -- it is NEVER
+          // swallowed to fall back to the hex literal while still counting a
+          // substitution that did not happen (T-45-21). It propagates with the
+          // usage address prepended, so the store row that caused it is always
+          // nameable.
+          let decomposition: RegisterDecomposition | undefined;
+          if (REGISTER_ENUM_NAME_RE.test(usage.enumName) && hasRegBitsEntry(`$${usage.enumName}`)) {
+            try {
+              decomposition = decomposeRegisterValue(parseInt(usage.enumName, 16), instr.operand!.value);
+            } catch (err) {
+              throw new Error(
+                `exportAsm: decomposing the enum usage at ${hex4(usage.address)} (enum ${JSON.stringify(usage.enumName)}, value ` +
+                  `${hex2(instr.operand!.value)}) against its bit-name table failed: ${err instanceof Error ? err.message : String(err)}`,
+              );
+            }
+          }
+
+          if (decomposition !== undefined && decomposition.multiField) {
+            // D-17: OR-ED NAMED CONSTANTS AND THE DECODED COMMENT -- BOTH,
+            // never either alone. A bare hex constant with a comment still
+            // "emits one hex constant"; bare constants with no comment are
+            // not readable.
+            for (const term of decomposition.terms) {
+              const existingValue = definedEnumSymbols.get(term.name);
+              if (existingValue !== undefined) {
+                if (existingValue !== term.value) {
+                  // ACME has ONE symbol namespace: two register writes that
+                  // decode the SAME field name to TWO different values cannot
+                  // both be `<name> = $XX`. Refusing names the symbol and
+                  // BOTH values, so the conflicting rows are findable.
+                  throw new Error(
+                    `exportAsm: the enum term symbol ${JSON.stringify(term.name)} (enum ${JSON.stringify(usage.enumName)}, field ` +
+                      `${JSON.stringify(term.fieldName)}, bound at ${hex4(usage.address)}) would be defined as ${hex2(term.value)} here, ` +
+                      `but was already defined as ${hex2(existingValue)} by an earlier instruction in this export. ACME has one symbol ` +
+                      `namespace, so one name cannot carry two values. REFUSED -- reconcile the two register writes or bind them to ` +
+                      `distinct enum names.`,
+                  );
+                }
+                // Same name, same value, already defined by an earlier
+                // instruction -- no second definition line (30-REVIEW WR-10's
+                // own "only what the source references" discipline, extended
+                // to terms).
+              } else {
+                // THE SAME LABEL COLLISION CHECK 30-REVIEW WR-10 ADDED FOR A
+                // SINGLE ENUM SYMBOL, EXTENDED HERE -- not a second check.
+                if (labelSymbolNames.has(term.name)) {
+                  throw new Error(
+                    `exportAsm: the enum term symbol ${JSON.stringify(term.name)} (enum ${JSON.stringify(usage.enumName)}, field ` +
+                      `${JSON.stringify(term.fieldName)}, bound at ${hex4(usage.address)}) is ALSO the name of a store label. ACME has ` +
+                      `one symbol namespace, so emitting both definitions is \`Symbol already defined.\` and exit 1 -- and this verb ` +
+                      `assembles nothing, so without this refusal the export would exit 0 here and fail wherever you assembled it. ` +
+                      `REFUSED -- rename the label or the enum term.`,
+                  );
+                }
+                definedEnumSymbols.set(term.name, term.value);
+                enumDefinitionLines.push(formatSymbolDefinition(term.name, term.value));
+              }
+            }
+
+            const orExpression = decomposition.terms.map((term) => term.name).join(" | ");
+            rendered = substituteImmediateEnum(rendered, instr.operand!.value, orExpression, instr.address);
+            appliedEnumUsage.add(usage.id);
+            enumDecompositionCount++;
+            decompositionComment = decomposition.comment;
+          } else {
+            // THE EXISTING SINGLE-SYMBOL PATH (D-16: unchanged, not
+            // replaced) -- a single-field register, an enum usage whose name
+            // is not register-shaped at all, OR (45-REVIEW CR-01) a
+            // register-shaped name for a register `anno-regbits.json` simply
+            // has no entry for (e.g. `D020`) -- reached here with no
+            // substitution counted above, never a throw.
+            //
+            // EVERY variant of the enum is checked, not only the one this
+            // operand matched. An enum carrying a variant above $ff is not a
+            // BYTE vocabulary, and binding it to a byte operand is a
+            // modelling error whose only symptom would otherwise be a
+            // variant that silently never renders. Refusing here names the
+            // enum and the variant; ACME's own refusal for the same shape is
+            // `Number does not fit in 8 bits.` at exit 1, and names a line in
+            // a temp file instead.
+            let matched: string | undefined;
+            for (const [key, variantName] of Object.entries(project.variants)) {
+              const value = parseVariantKey(key);
+              if (value > MAX_IMMEDIATE_VARIANT_VALUE) {
+                throw new Error(
+                  `exportAsm: enum ${JSON.stringify(usage.enumName)} is bound to the immediate operand at ${hex4(usage.address)}, but its ` +
+                    `variant ${JSON.stringify(variantName)} has the value ${value}, above ` +
+                    `${MAX_IMMEDIATE_VARIANT_VALUE} -- an immediate operand is ONE byte, so this enum is not a byte vocabulary. ` +
+                    `Real ACME refuses the same shape with "Number does not fit in 8 bits." and exit 1; this refusal happens first so it ` +
+                    `can name the enum and the variant rather than a temp-file line number.`,
+                );
+              }
+              if (value === instr.operand!.value) matched = variantName;
+            }
+
+            if (matched === undefined) {
+              throw new Error(
+                `exportAsm: enum ${JSON.stringify(usage.enumName)} is bound to the immediate operand at ${hex4(usage.address)}, whose ` +
+                  `value is ${hex2(instr.operand!.value)}, and the enum has no variant for that value. Refusing to emit the hex literal ` +
+                  `while reporting an enum substitution that did not happen.`,
+              );
+            }
+
+            const symbol = `${usage.enumName}_${matched}`;
+            // REJECT, never sanitise -- the same contract every other name this
+            // module emits passes through, applied to the COMPOSED name because
+            // that is what actually reaches the ACME source.
+            assertLegalAcmeIdentifier(symbol, `exportAsm: enum variant symbol for ${hex4(usage.address)}`);
+
+            // THE COLLISION THE COMMENT BELOW NAMES IS NOW CHECKED FOR
+            // (30-REVIEW WR-10, fixed 2026-08-31). That comment identified the
+            // hazard exactly -- "every extra emitted symbol is one more chance to
+            // collide with a label name and turn a correct export into ACME's
+            // `Symbol already defined.`" -- and then did not look.
+            // `definedEnumSymbols` dedupes enum symbols against EACH OTHER but
+            // never against the store's labels.
+            //
+            // Since the `anno export-asm` CLI verb runs no assembler, the
+            // collision produced a file that exited 0 here and failed wherever
+            // the user actually assembled it, with no pointer back to the store
+            // row that caused it. Refusing here names BOTH the enum and the
+            // label, which is what makes it fixable.
+            //
+            // Checked against `labelSymbolNames` -- every store label's name,
+            // whether it ends up defined in the header or inline -- because ACME
+            // has ONE symbol namespace and an inline `=*+$NN` definition
+            // collides exactly as a header one does.
+            if (labelSymbolNames.has(symbol)) {
+              throw new Error(
+                `exportAsm: the enum variant symbol ${JSON.stringify(symbol)} (enum ${JSON.stringify(usage.enumName)}, variant ` +
+                  `${JSON.stringify(matched)}, bound at ${hex4(usage.address)}) is ALSO the name of a store label. ACME has one symbol ` +
+                  `namespace, so emitting both definitions is \`Symbol already defined.\` and exit 1 -- and this verb assembles ` +
+                  `nothing, so without this refusal the export would exit 0 here and fail wherever you assembled it, with no pointer ` +
+                  `back to the rows that caused it. REFUSED -- rename the label or the enum variant.`,
+              );
+            }
+
+            // ONLY THE MATCHED VARIANT IS DEFINED, not the whole vocabulary. A
+            // definition the source never references is clutter a human reader
+            // has to discount, and every extra emitted symbol is one more chance
+            // to collide with a label name and turn a correct export into ACME's
+            // `Symbol already defined.`
+            if (!definedEnumSymbols.has(symbol)) {
+              definedEnumSymbols.set(symbol, instr.operand!.value);
+              enumDefinitionLines.push(formatSymbolDefinition(symbol, instr.operand!.value));
+            }
+            rendered = substituteImmediateEnum(rendered, instr.operand!.value, symbol, instr.address);
+            appliedEnumUsage.add(usage.id);
+          }
+        }
+
+        // The span is the instruction's FIRST address only, not its whole
+        // length: a comment stored against an operand byte belongs to no
+        // emitted line, and attaching it to the instruction that happens to
+        // contain that byte would move a human's note onto a different address
+        // than the one they chose. It stays unplaced and is refused below.
+        const emitted = withComments(rendered, instr.address, instr.address + 1, placement, decompositionComment);
+        content.push(...emitted);
+        block.lineCount += emitted.length;
+      }
+    } else if (isSplitAddressDataType(block.dataType)) {
+      // Phase 47, plan 47-06 (BUILD-03): the two split ADDRESS layouts get
+      // PAIRED symbol emission, never the raw-`!byte` fallback -- see
+      // `emitSplitAddressLines()`'s own doc-comment for the orientation and
+      // the one-symbol-per-entry rule. Read the SAME `blocks`/`labelIndex`
+      // the code path's in-tree symbol rule above reads, and fold its
+      // contribution into the SAME `unresolvedReferences`/
+      // `inTreeReferenceCount` totals, so a table entry and a `jsr` are
+      // refused (or not) by ONE rule, never two that could disagree.
+      const split = emitSplitAddressLines(slice, block.dataType, block.start, blocks, labelIndex);
+      inTreeReferenceCount += split.inTreeReferenceCount;
+      unresolvedReferences.push(...split.unresolvedReferences);
+      for (const dataLine of split.lines) {
+        const emitted = withComments(dataLine.text, dataLine.start, dataLine.endExclusive, placement);
+        content.push(...emitted);
+        block.lineCount += emitted.length;
+      }
+      dataByteCount += slice.length;
+    } else {
+      // The `dataType` reaching `emitDataLines()` is the store's own string,
+      // copied off the row and passed through -- this module never branches on
+      // it beyond the code/not-code test above, the `!word` eligibility check,
+      // and the `!binary` check, all three inside the emitter.
+      for (const dataLine of emitDataLines(slice, block.dataType, block.start)) {
+        const emitted = withComments(dataLine.text, dataLine.start, dataLine.endExclusive, placement);
+        content.push(...emitted);
+        block.lineCount += emitted.length;
+      }
+      dataByteCount += slice.length;
+
+      // Phase 47, plan 47-03 (BUILD-02): an `external_file` block's bytes
+      // also go out as their own sibling data file. `bytes` is `slice`
+      // itself -- the same bytes `dataByteCount` above just counted, carried
+      // verbatim and never re-read from anywhere else.
+      if (block.dataType === EXTERNAL_FILE_DATA_TYPE) {
+        binaries.push({ name: binaryFileName(block.start), start: block.start, endExclusive: block.endExclusive, bytes: slice });
+      }
+    }
+
+    // BUILD-05 (phase 46 plan 01): when ledger mode is on, every block gets a
+    // provenance comment BEFORE it is bracketed -- never as a threshold, never
+    // gating which blocks reach `emitBlock()` below. The only conditionals
+    // here are "is ledger mode on", "did zero rows come back" (refuse) and
+    // "did more than one come back" (record the ambiguity, choose neither) --
+    // none of which reads a Verdict, Confidence or Kind VALUE.
+    if (ledger !== undefined) {
+      const overlapping = provenanceForRange(ledger, block.start, block.endExclusive - 1);
+      if (overlapping.length === 0) {
+        throw new Error(
+          `exportAsm: the ledger at "${ledgerPath}" carries no row overlapping the block ${hexExtent(block.start)}..` +
+            `${hexExtent(block.endExclusive - 1)} (inclusive) -- refusing to emit this block unannotated or with an invented ` +
+            `verdict. Regenerate the ledger with c64-provenance-diff's "ledger" verb so it covers this range, or omit --ledger.`,
+        );
+      }
+      const provenanceLines: string[] = [];
+      for (const row of overlapping) {
+        // The ONLY free-text field here (Evidence/Reason) goes through the
+        // EXISTING comment-text validator -- never a second one. Verdict,
+        // Confidence and Kind are the ledger's own short controlled-ish
+        // strings, carried verbatim without re-validation, exactly as
+        // `dataType` is copied onto the block comment elsewhere in this file.
+        const checkedEvidence = assertExportableCommentText(row.evidence, block.start);
+        provenanceLines.push(
+          `${PROVENANCE_MARKER_PREFIX}${hex4(row.start)}..${hex4(row.endInclusive)} verdict=${row.verdict} ` +
+            `confidence=${row.confidence} kind=${row.kind} agreeing=${row.agreeingReleases} evidence=${checkedEvidence}`,
+        );
+      }
+      if (overlapping.length > 1) {
+        // Multiplicity is RECORDED, never resolved by picking one (T-46-03) --
+        // the same posture `ALIAS_MARKER_PREFIX` already takes for two store
+        // labels at one address.
+        provenanceLines.push(
+          `${PROVENANCE_AMBIGUITY_MARKER_PREFIX}${overlapping.length} ledger rows overlap this block; none was chosen -- see above.`,
+        );
+      }
+      // Prepended, not counted in `block.lineCount`: `lineCount` counts
+      // CONTENT lines by its own doc-comment, and a provenance comment is
+      // bookkeeping ABOUT the block -- the two `!if * != ...` assertions in
+      // `emitBlock()` are what actually police its extent.
+      content.unshift(...provenanceLines);
+    }
+
+    // BUILD-07 (phase 46 plan 05): every recorded exclusion overlapping this
+    // block gets a marker naming ITS OWN extent (never the block's) and its
+    // checked reason -- NEVER a skipped block, a shortened slice, or a
+    // shrunk `expectedBytes`. `block.start`/`block.endExclusive` above are
+    // completely untouched by this: the slice was already taken, the code
+    // was already decoded or the data lines already emitted, and every one
+    // of those bytes stays in `content`. This is bookkeeping ABOUT the block,
+    // exactly as the provenance comment above is -- prepended, and not
+    // counted in `block.lineCount`, which by its own doc-comment counts
+    // CONTENT lines only.
+    //
+    // THE OVERLAP TEST IS THE SAME PREDICATE `provenanceForRange()` and
+    // `addExcludedRange()` BOTH USE (`row.start <= blockEndInclusive &&
+    // row.endInclusive >= blockStart`, addExcludedRange's own predicate
+    // transposed) -- textually the same test at all three sites, so they
+    // agree by construction and not by three separate authors reaching the
+    // same answer by coincidence. Sorted ascending by `start`: this plan's
+    // own recorded (backstop) choice for two disjoint exclusions inside one
+    // block, never derived from a written contract.
+    const blockEndInclusive = block.endExclusive - 1;
+    const overlappingExclusions = excludedRanges
+      .filter((row) => row.start <= blockEndInclusive && row.endInclusive >= block.start)
+      .sort((a, b) => a.start - b.start);
+    if (overlappingExclusions.length > 0) {
+      const exclusionLines: string[] = [];
+      for (const row of overlappingExclusions) {
+        // RE-CHECKED, NOT RE-DEFINED -- the same predicate
+        // `assertExportableCommentText()` already applies to every stored
+        // comment and to the ledger's own free-text evidence cell, on
+        // EXACTLY the grounds `assertDataTypeForExport()`'s own comment a
+        // few dozen lines above states: the store validated this reason at
+        // write time, and a store file somebody edited on disk reaches this
+        // point through a column nobody re-checked. A stored line break
+        // would put everything after it into the ACME source at column
+        // zero, as assembler input rather than as a comment.
+        const checkedReason = assertExportableCommentText(row.reason, block.start);
+        // THE EXCLUSION'S OWN EXTENT, NOT THE BLOCK'S -- a row narrower than
+        // the block it lands in says so here, because the user asked about
+        // a span, not about whatever block that span happened to land in.
+        exclusionLines.push(`${EXCLUSION_MARKER_PREFIX}${hex4(row.start)}..${hex4(row.endInclusive)} ${checkedReason}`);
+        excludedRangeIdsEmitted.add(row.id);
+      }
+      content.unshift(...exclusionLines);
+    }
+
+    // EVERY block goes through `emitBlock()`, code and data alike, so there is
+    // exactly one place that brackets a block and no route that emits an
+    // unbracketed one. Captured onto `block.lines` (Phase 47, plan 47-01) at
+    // the SAME point it is pushed onto `blockLines` -- one call, two
+    // destinations, never a second bracketing.
+    const emittedBlockLines = emitBlock(block.start, block.endExclusive, content);
+    block.lines = emittedBlockLines;
+    blockLines.push(...emittedBlockLines);
+  }
+
+  // Phase 47, plan 47-04 (BUILD-03): an in-tree reference this export could
+  // not resolve to a symbol is REFUSED BY NAME, once, across the whole
+  // export -- never emitted as a hex literal that freezes the target's
+  // address into the source while the export reports success. In the same
+  // shape the unapplied-enum-usage and unplaced-comment refusals below
+  // already use: name the first offender, state the "N of M" count, and say
+  // plainly what is refused.
+  //
+  // A reference OUTSIDE every emitted block -- a hardware register, a
+  // KERNAL entry -- is rendered as a hex literal and is NOT a refusal
+  // (D47-F, `isInTree()`'s own doc-comment): that address is fixed hardware
+  // which cannot move, which is precisely what "so the code can move" is
+  // about, and this refusal never fires on one.
+  //
+  // No image byte, no mnemonic and no store comment text is ever
+  // interpolated here -- only addresses and counts, on the same discipline
+  // `assertDataTypeForExport()`'s own comment states.
+  if (unresolvedReferences.length > 0) {
+    const first = unresolvedReferences[0]!;
+    throw new Error(
+      `exportAsm: the instruction at ${hex4(first.referringAddress)} references ${hex4(first.targetAddress)}, an address inside an ` +
+        `emitted block, but no label names that address -- every reference that has to move with the code goes through a symbol, and ` +
+        `this one has none to go through. ${unresolvedReferences.length} of ${inTreeReferenceCount} in-tree reference(s) are in this ` +
+        `state. Refusing to emit a hex literal that freezes the target's address into the source while reporting success -- the whole ` +
+        `point of the symbol is that the code can move. Record a label at ${hex4(first.targetAddress)} to fix this.`,
+    );
+  }
+
+  // EVERY store label is defined here, in a block BEFORE the first `* =`, not
+  // only the ones a substitution happened to use -- EXCEPT the mid-instruction
+  // ones, which the loop above already defined inline and which ACME would
+  // refuse as `Symbol already defined.` if they appeared twice.
+  //
+  // Measured on ACME 0.97: a symbol defined AFTER its first reference widens
+  // the referencing instruction from zeropage to absolute -- `a5 10` becomes
+  // `ad 10 00`, three bytes where the original was two -- and it does so with
+  // the WARNING `Using oversized addressing mode.` and exit status 0.
+  // Everything after it shifts. Defining first is the mitigation; the per-block
+  // `*` assertions are the backstop for a future change that ever drops this
+  // block, and the byte-diff is what settles the whole claim.
+  //
+  // THIS BLOCK IS BUILT AFTER THE BLOCK LOOP AND EMITTED BEFORE IT. Which
+  // labels are defined inline is only knowable once the code blocks have been
+  // decoded, and the header must not restate those; the assembled order below
+  // is what the source actually carries.
+  const headerLines: string[] = [...enumDefinitionLines];
+  for (const label of sortedLabels) {
+    if (midInstructionLabelAddresses.has(label.address)) continue;
+    headerLines.push(markIfAliased(label.address, markIfAutoNamed(label.name, formatSymbolDefinition(label.name, label.address))));
+  }
+
+  // An enum usage this export never reached is REFUSED BY NAME, for the reason
+  // an unplaceable comment is: its address is inside an instruction rather than
+  // at its start, or is not covered by any CODE range, and in both cases the
+  // honest answer is that this export does not carry it, said out loud.
+  if (appliedEnumUsage.size !== enumUsage.length) {
+    const unapplied = enumUsage.filter((row) => !appliedEnumUsage.has(row.id));
+    const first = unapplied[0]!;
+    throw new Error(
+      `exportAsm: the enum usage at ${hex4(first.address)} (enum ${JSON.stringify(first.enumName)}) has no decoded instruction to ` +
+        `attach to -- that address is inside an instruction rather than at its start, or is not covered by any \`code\` range. ` +
+        `${unapplied.length} of ${enumUsage.length} enum usage(s) are in this state. Refusing to export while silently dropping them.`,
+    );
+  }
+
+  const lines: string[] = ["!cpu 6510", ...headerLines, ...blockLines];
+
+  // An annotation this exporter cannot express is REFUSED BY NAME, never
+  // dropped from the output while the export reports success. A comment is
+  // unplaceable when its address is inside an instruction rather than at its
+  // start, or outside every annotated range -- and in both cases the honest
+  // answer is that this export does not carry it, said out loud.
+  if (placement.placed.size !== comments.length) {
+    const unplaced = comments.filter((row) => !placement.placed.has(row.id));
+    const first = unplaced[0]!;
+    throw new Error(
+      `exportAsm: the ${first.commentType} comment at ${hex4(first.address)} has no emitted line to attach to -- that address is inside an ` +
+        `instruction rather than at its start, or is not covered by any annotated range. ` +
+        `${unplaced.length} of ${comments.length} comment(s) are in this state. Refusing to export while silently dropping them.`,
+    );
+  }
+
+  // `expectedBytes` is built from the IMAGE, never from `lines`. Gaps between
+  // blocks stay `$00`, matching ACME `-f plain`'s measured zero-fill.
+  const minStart = blocks[0]!.start;
+  const maxEndExclusive = blocks.reduce((acc, b) => Math.max(acc, b.endExclusive), blocks[0]!.endExclusive);
+  const expectedBytes = new Uint8Array(maxEndExclusive - minStart);
+  for (const block of blocks) {
+    expectedBytes.set(image.bytes.subarray(block.start - imageStart, block.endExclusive - imageStart), block.start - minStart);
+  }
+
+  return {
+    source: `${lines.join("\n")}\n`,
+    headerLines,
+    scopes,
+    expectedBytes,
+    blocks,
+    symbolCount: sortedLabels.length,
+    headerDefinitionCount: headerLines.length,
+    unexpressibleCount,
+    dataByteCount,
+    binaries: [...binaries].sort((a, b) => a.start - b.start),
+    commentCount: placement.placed.size,
+    midInstructionLabelCount,
+    autoNamedSymbolCount,
+    enumSubstitutionCount: appliedEnumUsage.size,
+    enumDecompositionCount,
+    excludedRangeCount: excludedRangeIdsEmitted.size,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Phase 47, plan 47-01: the TREE writer (D47-A). `exportAsm()` above stays the
+// proven EMITTER -- this is the primary shape a caller reaches for, built by
+// PARTITIONING `exportAsm()`'s already-proven emission, never by emitting a
+// second time through a second route. See `exportAsmTree()`'s own doc-comment
+// below for the one claim it is NOT allowed to make.
+// ---------------------------------------------------------------------------
+
+/** D47-B: the tree's three fixed file names. DERIVED from nothing but this
+ * module's own naming convention -- never from a store row -- so a store's
+ * free text can never reach one of these three names. */
+export const ROOT_FILE_NAME = "root.a";
+export const SYMBOLS_FILE_NAME = "symbols.a";
+export const UNSCOPED_FILE_NAME = "unscoped.a";
+
+/**
+ * D47-B: the `.a` file name for the scope starting at `start` --
+ * `scope_XXXX.a`, four LOWERCASE hex digits, no `$`, no store free text
+ * anywhere in it.
+ *
+ * DERIVED FROM `start`, an integer this project already controls (a scope
+ * row's own `start` field, itself validated by `addScope()` before it ever
+ * reached the store) -- never from a label name, a comment or any other
+ * store free text (T-47-01). This is what makes a re-export a REVIEWABLE
+ * DIFF instead of full-tree churn: the same scope always gets the same file
+ * name, so an unrelated edit elsewhere in the store does not rename files a
+ * human may have opened.
+ */
+export function scopeFileName(start: number): string {
+  return `scope_${(start & 0xffff).toString(16).padStart(4, "0")}.a`;
+}
+
+/**
+ * Phase 47, plan 47-03 (BUILD-02): the `.bin` sibling file name for the
+ * `external_file`-typed block starting at `start` -- `data_XXXX.bin`, four
+ * LOWERCASE hex digits, no `$`, no store free text anywhere in it. Module-
+ * private: nothing outside this file needs the name computed independently
+ * of `ExportBinary.name`/`emitDataLines()`'s own emitted `!binary` argument,
+ * both of which already carry it.
+ *
+ * DERIVED FROM `start`, an integer this project already controls, on
+ * exactly the same terms `scopeFileName()` above already states for `.a`
+ * siblings (T-47-01) -- never from a label name, a comment or any other
+ * store free text. This is what makes the emitted `!binary "..."` argument
+ * safe to trust: it can only ever be four hex digits and a fixed prefix/
+ * suffix, never a string a store row supplied.
+ */
+function binaryFileName(start: number): string {
+  return `data_${(start & 0xffff).toString(16).padStart(4, "0")}.bin`;
+}
+
+export interface ExportAsmTreeOptions extends ExportAsmOptions {
+  /** The directory the tree is written into. NOTHING CONFINES THIS PATH
+   * INSIDE THIS MODULE, on exactly the same terms `imagePath`/`storePath`
+   * above already carry (T-47-03) -- that sentence is present because an
+   * absent comment beside a present one is itself a claim, and a silently-
+   * undocumented path field is what a prior review named as the mechanism of
+   * a real defect. The CALLER owns confining it (the CLI does, through
+   * `storePathWithinWorkspace()`, plan 47-05). Within the directory, every
+   * name this function writes is DERIVED (`scopeFileName()`, the three fixed
+   * constants above), so nothing the caller supplies can escape it a second
+   * time. */
+  outDir: string;
+  /**
+   * Phase 47, plan 47-02, Task 2: what the CALLER IS ASKING FOR, not a
+   * switch that widens what this function is willing to destroy. Set, it
+   * means "this directory already holds a tree I exported before -- replace
+   * it." It deliberately does NOT mean "remove whatever is in my way": a
+   * directory entry that is not one of this export's own file names is
+   * refused by name even with `force: true`, never deleted to make room for
+   * the write. See `exportAsmTree()`'s own doc-comment for the two-rule
+   * contract this field gates.
+   */
+  force?: boolean;
+}
+
+export interface ExportAsmTreeResult extends ExportAsmResult {
+  outDir: string;
+  /** Every file this call wrote, ASCENDING -- exactly the tree's on-disk
+   * file-name set. */
+  files: string[];
+  /** The `!source` order `root.a` carries, D47-B: `symbols.a` first, then
+   * each populated scope file ascending by scope start, then `unscoped.a`
+   * last (only when non-empty). */
+  sourceOrder: string[];
+}
+
+/**
+ * Phase 47, plan 47-02: decides which file ONE block belongs to, given the
+ * store's own scopes -- the ONE containment predicate, applied ONCE, so the
+ * tree writer's placement answer can never drift from a second copy of this
+ * question (see `blocks`'s own `.map()` above for the sibling boundary this
+ * project already carries the same discipline for).
+ *
+ * A scope WHOLLY CONTAINS a block when `scope.start <= block.start` AND
+ * `block.endExclusive - 1 <= scope.endInclusive`. That subtraction is the
+ * inclusive/exclusive conversion, done HERE and only here -- a second
+ * conversion site elsewhere in this function is exactly how the two answers
+ * would drift.
+ *
+ * A block no scope contains, and that overlaps no scope AT ALL, belongs to
+ * the unscoped group (D47-D). This is a genuine "goes somewhere, never
+ * nowhere" answer rather than a refusal-in-disguise: `listScopes()` was read
+ * by nothing in the export path before this plan, so every store that exists
+ * today has zero scopes, and refusing here would make the tree export
+ * unreachable for every one of them. Losslessness is this project's
+ * governing constraint.
+ *
+ * A block that OVERLAPS a scope WITHOUT being wholly contained by it is
+ * REFUSED (D47-C) -- scopes cannot themselves overlap (`addScope()`'s own
+ * overlap refusal), so this is genuinely ambiguous rather than a case this
+ * function could resolve by trying harder. The export refuses to CHOOSE a
+ * file for it rather than guess what a straddling range means: `emitBlock()`
+ * brackets every block with a single `* =` origin and a single
+ * `!if * != ...` end assertion, and a block emitted in two pieces has no
+ * single extent for that pair to assert. The fix belongs to the user --
+ * move the scope boundary, or split the range -- never to this exporter.
+ */
+function placeBlockInScope(block: ExportBlock, sortedScopes: readonly ScopeRow[]): ScopeRow | "unscoped" {
+  const blockEndInclusive = block.endExclusive - 1;
+  for (const scope of sortedScopes) {
+    const whollyContained = scope.start <= block.start && blockEndInclusive <= scope.endInclusive;
+    if (whollyContained) return scope;
+
+    const overlaps = block.start <= scope.endInclusive && scope.start <= blockEndInclusive;
+    if (overlaps) {
+      throw new Error(
+        `exportAsmTree: the range ${hex4(block.start)}..${hex4(blockEndInclusive)} (inclusive) overlaps the scope ` +
+          `${hex4(scope.start)}..${hex4(scope.endInclusive)} (inclusive) without being wholly contained by it -- refusing to choose ` +
+          `which file it belongs in, because that would be this tool deciding what your range means. Splitting the range across two ` +
+          `files is not offered instead: emitBlock() brackets every block with a single \`* =\` origin and a single ` +
+          `\`!if * != ...\` end assertion, and a block emitted in two pieces has no single extent left for that pair to assert. ` +
+          `Move the scope boundary, or split the range -- the fix belongs to you, not this export.`,
+      );
+    }
+  }
+  return "unscoped";
+}
+
+/**
+ * Writes `exportAsm()`'s already-proven emission as a TREE of real files on
+ * disk, rather than emitting a second time through a second route --
+ * `root.a` (D47-B order), `symbols.a`, one `scope_XXXX.a` per scope that
+ * contains at least one block, and `unscoped.a` only when at least one block
+ * lies inside no scope (D47-D).
+ *
+ * ASSIGNMENT RULE (D47-C/D47-D, both now implemented): every block is placed
+ * by `placeBlockInScope()` above -- the scope that wholly contains it, the
+ * unscoped group when no scope contains it at all, or a thrown refusal when
+ * it overlaps a scope without being wholly contained. There is no fourth
+ * outcome and no path that silently discards a block.
+ *
+ * Every `!source` argument this function emits is a bare filename -- no
+ * directory component, no absolute path, no host-machine path anywhere in
+ * the generated text, so the tree assembles on a machine that has never
+ * seen this one (hard scope fence 2).
+ *
+ * `root.a` is written LAST, through a temp name in the same directory
+ * followed by a `renameSync` into place -- the same atomic-publish
+ * discipline `build.ts` already uses for every artifact it emits. A tree
+ * whose root exists is a tree every file it sources exists for, so an
+ * interrupted export leaves nothing an assembler would happily turn into a
+ * wrong program.
+ *
+ * `exportAsmTree()` SPAWNS NOTHING AND ASSEMBLES NOTHING. Writing the tree is
+ * not the same claim as the tree being able to reassemble, and nothing this
+ * function writes, prints or returns may be read as an assembly verdict
+ * (P-01) -- that claim is settled elsewhere, by a real ACME reached through
+ * `runHostTool()`.
+ */
+export function exportAsmTree(options: ExportAsmTreeOptions): ExportAsmTreeResult {
+  const result = exportAsm(options);
+  const { outDir } = options;
+
+  const sortedScopes = [...result.scopes].sort((a, b) => a.start - b.start);
+  // Keyed by scope START (D47-B's own file-naming key), never by scope id --
+  // the file name is a function of `start`, so the grouping key matches it.
+  //
+  // THIS WHOLE PASS RUNS BEFORE ANY FILE IS WRITTEN, on purpose: a refusal
+  // that has already written half a tree has left an artefact a later
+  // assemble might succeed on. `placeBlockInScope()` either returns a
+  // placement or throws; nothing below this loop runs until every block has
+  // been placed.
+  const scopeBlocks = new Map<number, ExportBlock[]>();
+  const unscopedBlocks: ExportBlock[] = [];
+  for (const block of result.blocks) {
+    const placement = placeBlockInScope(block, sortedScopes);
+    if (placement === "unscoped") {
+      unscopedBlocks.push(block);
+      continue;
+    }
+    const existing = scopeBlocks.get(placement.start);
+    if (existing) existing.push(block);
+    else scopeBlocks.set(placement.start, [block]);
+  }
+
+  // The FULL set of names this call will write, computed BEFORE any write and
+  // BEFORE the directory-contract check below reads it: the placement pass
+  // above already knows exactly which scopes are populated and whether any
+  // block is unscoped, so this is arithmetic over what is already decided,
+  // never a guess revised after the fact.
+  const populatedScopeStarts = [...scopeBlocks.keys()].sort((a, b) => a - b);
+  const hasUnscoped = unscopedBlocks.length > 0;
+  // Phase 47, plan 47-03 (T-47-08): every `.bin` sibling this call will write
+  // joins the SAME name set the directory contract below evaluates, so a
+  // re-export with `force: true` may replace a previously-exported `.bin`
+  // exactly as it may replace a previously-exported `.a` file -- and, without
+  // `force`, a directory holding one is refused by name like anything else.
+  const binaryNames = result.binaries.map((binary) => binary.name);
+  const namesToWrite = [
+    SYMBOLS_FILE_NAME,
+    ...populatedScopeStarts.map((start) => scopeFileName(start)),
+    ...(hasUnscoped ? [UNSCOPED_FILE_NAME] : []),
+    ...binaryNames,
+    ROOT_FILE_NAME,
+  ];
+
+  // ---------------------------------------------------------------------
+  // Phase 47, plan 47-02, Task 2: the output-directory contract. Two rules,
+  // both evaluated BEFORE the first write below -- a refusal that has
+  // already written half a tree has left an artefact a later assemble might
+  // succeed on (the same reason the placement pass above runs to completion
+  // before any write).
+  //
+  // Rule one, without `force`: a directory holding ANY entry at all is
+  // refused by name, unconditionally. An export writes a whole tree and will
+  // not mix its files with whatever the directory already held.
+  //
+  // Rule two, with `force`: the caller is asking "this directory already
+  // holds a tree I exported before, replace it" -- never "remove whatever is
+  // in my way". Anything in the directory that is NOT one of `namesToWrite`
+  // is refused by name; nothing is ever deleted to make room for it. The
+  // `.bin` files this export writes are the ones a person is expected to
+  // edit by hand, so replacing them is something the user has to ask for,
+  // and a directory the user pointed at by mistake must not lose a file this
+  // tool never created.
+  // ---------------------------------------------------------------------
+  const existingEntries = existsSync(outDir) ? readdirSync(outDir) : [];
+  if (existingEntries.length > 0) {
+    if (!options.force) {
+      throw new Error(
+        `exportAsmTree: the output directory "${outDir}" already holds ${existingEntries.length} ` +
+          `${existingEntries.length === 1 ? "entry" : "entries"} -- refusing to write into it. An export writes a whole tree and will ` +
+          `not mix its files with whatever is already there. Pass \`force: true\` to ask for the overwrite explicitly if this directory ` +
+          `holds a previous export of this same store.`,
+      );
+    }
+    const namesToWriteSet = new Set(namesToWrite);
+    const unexpected = existingEntries.filter((entry) => !namesToWriteSet.has(entry));
+    if (unexpected.length > 0) {
+      throw new Error(
+        `exportAsmTree: the output directory "${outDir}" holds ${JSON.stringify(unexpected)}, which this export would NOT write -- ` +
+          `refusing the overwrite. \`force: true\` means "replace the tree I exported here before", never "remove whatever is in my ` +
+          `way": every name this export itself produces may be overwritten, but any other entry is left untouched. Remove it yourself, ` +
+          `or point --out at an empty directory.`,
+      );
+    }
+  }
+  mkdirSync(outDir, { recursive: true });
+
+  const files: string[] = [];
+  const sourceOrder: string[] = [];
+
+  // symbols.a -- ALWAYS written, sourced FIRST (D47-B). Measured live this
+  // session: a zero-page symbol defined AFTER its first use widens the
+  // referencing instruction, so every scope file depends on this one having
+  // already run.
+  const symbolsFileLines = [
+    `; ${SYMBOLS_FILE_NAME} -- every symbol definition this export carries. Sourced FIRST by ${ROOT_FILE_NAME}: a symbol defined after its first use widens the referencing instruction (measured against real ACME 0.97), so every other file in this tree depends on this one having already run.`,
+    ...result.headerLines,
+  ];
+  writeFileSync(join(outDir, SYMBOLS_FILE_NAME), `${symbolsFileLines.join("\n")}\n`, "utf8");
+  files.push(SYMBOLS_FILE_NAME);
+  sourceOrder.push(SYMBOLS_FILE_NAME);
+
+  // One scope_XXXX.a per POPULATED scope, ascending by scope start (D47-B).
+  // `populatedScopeStarts` was already computed above, for `namesToWrite`.
+  for (const scopeStart of populatedScopeStarts) {
+    const name = scopeFileName(scopeStart);
+    const blocksInScope = [...scopeBlocks.get(scopeStart)!].sort((a, b) => a.start - b.start);
+    const fileLines = [`; ${name} -- one scope of this export's tree, addresses ${hex4(scopeStart)} upward.`, ...blocksInScope.flatMap((b) => b.lines)];
+    writeFileSync(join(outDir, name), `${fileLines.join("\n")}\n`, "utf8");
+    files.push(name);
+    sourceOrder.push(name);
+  }
+
+  // unscoped.a -- only when at least one block lies inside no scope (D47-D):
+  // losslessness is the governing constraint, so every existing store (which
+  // has zero scopes today, since nothing reads listScopes() yet) still
+  // exports every block somewhere, never nowhere.
+  if (unscopedBlocks.length > 0) {
+    const sortedUnscoped = [...unscopedBlocks].sort((a, b) => a.start - b.start);
+    const fileLines = [`; ${UNSCOPED_FILE_NAME} -- every block this export emitted that lies inside no scope.`, ...sortedUnscoped.flatMap((b) => b.lines)];
+    writeFileSync(join(outDir, UNSCOPED_FILE_NAME), `${fileLines.join("\n")}\n`, "utf8");
+    files.push(UNSCOPED_FILE_NAME);
+    sourceOrder.push(UNSCOPED_FILE_NAME);
+  }
+
+  // .bin siblings (T-47-08/T-47-09/T-47-10, phase 47 plan 47-03) -- one per
+  // `external_file`-typed block, written in the SAME pass as every `.a`
+  // file above and, like them, BEFORE root.a: data files precede the root
+  // for the identical interruption-safety reason the `.a` files already do
+  // -- a partial tree must have no root an assembler could start from.
+  // These are NOT `!source`d, so `sourceOrder` is untouched; they are only
+  // ever reached through the `!binary` line `emitDataLines()` already wrote
+  // into their owning scope/unscoped `.a` file.
+  for (const binary of result.binaries) {
+    writeFileSync(join(outDir, binary.name), Buffer.from(binary.bytes.buffer, binary.bytes.byteOffset, binary.bytes.byteLength));
+    files.push(binary.name);
+  }
+
+  // root.a -- LAST, and atomically: a temp name in the SAME directory (so
+  // `renameSync` is a same-filesystem rename, never EXDEV), then renamed into
+  // place. A tree whose root exists is a tree every file it sources exists
+  // for.
+  const rootPath = join(outDir, ROOT_FILE_NAME);
+  const rootTmpPath = join(outDir, `${ROOT_FILE_NAME}.tmp-${process.pid}`);
+  const rootFileLines = [`; ${ROOT_FILE_NAME} -- this tree's entry point.`, "!cpu 6510", ...sourceOrder.map((name) => `!source "${name}"`)];
+  writeFileSync(rootTmpPath, `${rootFileLines.join("\n")}\n`, "utf8");
+  renameSync(rootTmpPath, rootPath);
+  files.push(ROOT_FILE_NAME);
+  files.sort();
+
+  return { ...result, outDir, files, sourceOrder };
+}