@henols/vice-mcp 0.2.2 → 0.2.3

package/anno-export-asm.ts

@@ -53,13 +53,17 @@
 //     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 TWO places
-//     that already do, each of which says so in its own comment:
-//     `CODE_DATA_TYPE`'s decoder-or-dump branch, and `WORD_PAIR_DATA_TYPES`'s
-//     `!word` eligibility check. Both 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 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
@@ -87,12 +91,12 @@
 // SCOPE, STILL DELIBERATELY NARROW: code ranges, the twelve typed data ranges,
 // comments, mid-instruction inline labels and immediate-operand enum
 // substitution.
-import { readFileSync } from "node:fs";
-import { extname } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
 
-import { openStore, closeStore, listRanges, listLabels, listComments, listProjectEnums, listEnumUsage } from "./anno-store.ts";
-import { AnnoCommentError, COMMENT_TYPES, DATA_TYPES, assertCommentText, assertDataType, parseVariantKey } from "./anno-types.ts";
-import type { CommentRow, DataType, EnumUsageRow, LabelRow, ProjectEnumRow, RangeRow } from "./anno-types.ts";
+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
@@ -113,9 +117,22 @@ import { assertLegalAcmeIdentifier } from "./anno-acme-ident.ts";
 // `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
@@ -124,6 +141,18 @@ import { parsePrg, flatImageOrigin } from "./prg-image.ts";
  * 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. */
@@ -138,6 +167,39 @@ export interface ExportBlock {
   /** 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 {
@@ -161,11 +223,36 @@ export interface ExportAsmOptions {
    * 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
@@ -206,6 +293,15 @@ export interface ExportAsmResult {
    * 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. */
@@ -233,8 +329,30 @@ export interface ExportAsmResult {
   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. */
+   * 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. */
@@ -257,6 +375,26 @@ const WORDS_PER_DATA_LINE = 8;
  */
 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. */
@@ -287,6 +425,18 @@ interface DataLine {
  * 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
@@ -294,6 +444,16 @@ interface DataLine {
  * 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) {
@@ -326,6 +486,143 @@ function emitDataLines(slice: Uint8Array, dataType: string, blockStart: number):
   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 = "        ";
@@ -524,6 +821,57 @@ const AUTO_NAME_MARKER = "  ; auto-generated name -- still in the annotation bac
  */
 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.
@@ -535,6 +883,29 @@ const ALIAS_MARKER_PREFIX = "  ; ALIAS: this address also carries ";
  */
 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`.
  *
@@ -714,10 +1085,22 @@ interface CommentPlacement {
  * 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): string[] {
+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.
@@ -731,7 +1114,12 @@ function withComments(text: string, start: number, endExclusive: number, ctx: Co
       if (row.commentType === LINE_COMMENT) {
         before.push(`${INDENT}; ${safe}`);
       } else if (row.commentType === SIDE_COMMENT) {
-        line = `${line}  ; ${safe}`;
+        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
@@ -744,9 +1132,58 @@ function withComments(text: string, start: number, endExclusive: number, ctx: Co
     }
   }
 
+  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
@@ -762,7 +1199,7 @@ function withComments(text: string, start: number, endExclusive: number, ctx: Co
  * addresses and counts only.
  */
 export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
-  const { storePath, imagePath, workspaceRoot } = options;
+  const { storePath, imagePath, workspaceRoot, ledgerPath } = options;
 
   const image = loadImage(imagePath);
 
@@ -777,12 +1214,24 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
   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);
   }
@@ -827,6 +1276,9 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
     // 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;
@@ -841,6 +1293,14 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
     }
   }
 
+  // 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);
@@ -918,10 +1378,37 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
   /** `<enumName>_<VARIANT> = $XX` definition lines, in first-emitted order.
    * They join the header block for the same reason label definitions do. */
   const enumDefinitionLines: string[] = [];
-  const definedEnumSymbols = new Set<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
@@ -971,6 +1458,12 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
 
   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[] = [];
@@ -1063,6 +1556,34 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
 
         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) {
@@ -1126,81 +1647,169 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
             );
           }
 
-          // 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) {
+          // 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: 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.`,
+                `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 (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.`,
-            );
-          }
+          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 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.`,
-            );
-          }
+            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.`,
+              );
+            }
 
-          // 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.add(symbol);
-            enumDefinitionLines.push(formatSymbolDefinition(symbol, instr.operand!.value));
+            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);
           }
-          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
@@ -1208,27 +1817,173 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
         // 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);
+        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 and the `!word` eligibility
-      // check inside the emitter.
+      // 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.
-    blockLines.push(...emitBlock(block.start, block.endExclusive, content));
+    // 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
@@ -1296,15 +2051,346 @@ export function exportAsm(options: ExportAsmOptions): ExportAsmResult {
 
   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 };
+}