dasmos 4.2.1__tar.gz → 4.3.0__tar.gz

{dasmos-4.2.1/src/dasmos.egg-info → dasmos-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dasmos
-Version: 4.2.1
+Version: 4.3.0
 Summary: Extensible tracing disassembler for classic CPUs, with CPU, renderer and environment extension points.
 Author-email: Robert Smallshire <rob@sixty-north.com>
 License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
   <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
 </p>
 
-An extensible tracing disassembler for classic CPUs, version `4.2.1`.
+An extensible tracing disassembler for classic CPUs, version `4.3.0`.
 
 <p align="center">
   <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>

{dasmos-4.2.1 → dasmos-4.3.0}/README.md

@@ -2,7 +2,7 @@
   <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
 </p>
 
-An extensible tracing disassembler for classic CPUs, version `4.2.1`.
+An extensible tracing disassembler for classic CPUs, version `4.3.0`.
 
 <p align="center">
   <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>

{dasmos-4.2.1 → dasmos-4.3.0}/pyproject.toml

@@ -108,7 +108,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "4.2.1"
+current_version = "4.3.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 tag = true

{dasmos-4.2.1 → dasmos-4.3.0}/src/dasmos/__init__.py

@@ -4,7 +4,7 @@ The top-level package re-exports the public API. Consumers should import
 from :mod:`dasmos` rather than reaching into sub-modules.
 """
 
-__version__ = "4.2.1"
+__version__ = "4.3.0"
 
 from dasmos.core.annotations import Align, Annotation, AnnotationStore, Banner, Comment
 from dasmos.core.format_hint import FormatHint

{dasmos-4.2.1 → dasmos-4.3.0}/src/dasmos/asm_renderer.py

@@ -19,6 +19,7 @@ subclass's syntax methods.
 
 from __future__ import annotations
 
+import re
 import warnings
 from typing import TYPE_CHECKING
 
@@ -54,7 +55,7 @@ from dasmos.core.expr import (
 from dasmos.core.format_hint import FormatHint
 from dasmos.core.markdown_asm import markdown_to_asm_text, strip_address_uri_links
 from dasmos.core.memory import BinaryAddr
-from dasmos.core.move import Move
+from dasmos.core.move import BASE_MOVE_ID, Move
 from dasmos.cpu import Opcode, OperandKind
 from dasmos.exceptions import MacroRenderError
 from dasmos.output import TextOutput
@@ -220,7 +221,9 @@ class AssemblerRenderer(TextRenderer):
         """
         return None
 
-    def _save_directive(self, load_start, load_end, program=None) -> str | None:
+    def _save_directive(
+        self, load_start, load_end, program=None, name=None,
+    ) -> str | None:
         """A directive writing the loaded range to a binary file, or
         ``None`` when the assembler saves via a command-line flag
         instead. Default: ``None`` (no in-source save). Beebasm
@@ -229,10 +232,76 @@ class AssemblerRenderer(TextRenderer):
 
         ``program`` is the IR's :class:`~dasmos.core.program.ProgramInfo`
         (or ``None``) — load-and-run metadata (exec/reload addresses) a
-        backend may fold into its save directive.
+        backend may fold into its save directive. ``name`` is the
+        single image's declared name (``d.load(name=...)``), or
+        ``None``; an explicit :attr:`output_filename` takes precedence.
         """
         return None
 
+    def _image_save_directive(self, image, start_ref: str, end_ref: str) -> str | None:
+        """A directive saving one of several loaded images as its own
+        file (#49), or ``None`` when the assembler has no in-source save.
+
+        ``image`` is the :class:`~dasmos.core.program.LoadedImage`;
+        ``start_ref`` / ``end_ref`` are the expressions for its range —
+        its boundary labels, or hex literals when those are suppressed.
+        Default ``None``; beebasm overrides with its ``save``.
+        """
+        return None
+
+    def _segment_boundary_labels(
+        self, segments,
+    ) -> list[tuple[str | None, str | None]]:
+        """``(start_label, end_label)`` for each segment of the main walk.
+
+        A single segment uses the familiar ``{prefix}start`` /
+        ``{prefix}end``. Several (one per image) get
+        ``{prefix}{name}_start`` / ``{prefix}{name}_end``, the image
+        name made into an identifier (``Dunjun4`` -> ``dunjun4``, ``Game
+        B`` -> ``game_b``) and kept unique. Suppressed boundary labels
+        (an empty prefix) give ``(None, None)``.
+        """
+        if len(segments) == 1:
+            return [(self.boundary_start_label, self.boundary_end_label)]
+        if not self.emit_boundary_labels:
+            return [(None, None)] * len(segments)
+        prefix = self.boundary_label_prefix
+        return [
+            (f"{prefix}{ident}_start", f"{prefix}{ident}_end")
+            for ident in self._image_identifiers(
+                [image for _start, _end, image in segments],
+            )
+        ]
+
+    @staticmethod
+    def _image_identifiers(images) -> list[str]:
+        """An identifier for each image, from its name — lower-cased,
+        other characters folded to ``_`` (``Game B`` -> ``game_b``) —
+        made unique by a numeric suffix. Used for per-image boundary
+        labels and section names."""
+        identifiers: list[str] = []
+        for image in images:
+            stem = re.sub(r"[^0-9a-z_]+", "_", image.name.lower()).strip("_") or "image"
+            candidate, n = stem, 2
+            while candidate in identifiers:
+                candidate, n = f"{stem}_{n}", n + 1
+            identifiers.append(candidate)
+        return identifiers
+
+    def image_section_declarations(self, section_ids: list[str]) -> list[str]:
+        """Lines declaring one output section per loaded image, emitted
+        near the top when several images are loaded (#49). Default: none
+        — a backend that saves in-source (beebasm) needs no sections."""
+        return []
+
+    def image_section_start(self, section_id: str) -> list[str]:
+        """Lines opening (or reopening) an image's section. Default: none."""
+        return []
+
+    def image_section_end(self, section_id: str) -> list[str]:
+        """Lines closing an image's section. Default: none."""
+        return []
+
     def included_binary_directive(self, path: str) -> list[str]:
         """Lines emitting an external binary include for ``path`` (an
         :class:`~dasmos.core.classification.IncludedBinary` region).
@@ -272,6 +341,10 @@ class AssemblerRenderer(TextRenderer):
         # uses ``b2r`` (most-recent move) and so misses inline anchors
         # from a non-most-recent move's body emission.
         self._inline_emitted_runtime_addrs: set[int] = set()
+        # Every label name emitted inline so far (as ``.name`` or as an
+        # inline ``name = base+offset``), so each is defined exactly
+        # once however many overlays reach its address.
+        self._inline_emitted_names: set[str] = set()
         # Macros invoked *natively* (as a value function or a statement)
         # during this render — only these get a definition emitted; a
         # macro used only via inline-expansion needs none.
@@ -291,6 +364,10 @@ class AssemblerRenderer(TextRenderer):
         # addresses of the labels it names (see :meth:`_render_opcode`);
         # ``None`` otherwise.
         self._operand_label_refs: set[int] | None = None
+        # The images saved as separate files by this render — set when
+        # more than one is loaded (#49), so :meth:`build_command` can
+        # describe one output per image. Empty for a single image.
+        self._saved_images: list = []
 
     def render(self, ir: "IntermediateRepresentation") -> TextOutput:
         """Walk the IR's classifications and emit a beebasm source
@@ -362,21 +439,53 @@ class AssemblerRenderer(TextRenderer):
             for move in [moves_by_src[src]]
         }
 
+        # The main walk runs one segment per saved image. A single image
+        # (the usual case) is one segment spanning the whole load range.
+        # Several separately-loaded images (#49) are each their own
+        # segment — own ``org``, boundary labels and save — so the gaps
+        # between them are never assembled or saved; a backend that
+        # saves per section (64tass) also gets each image's content,
+        # moved blocks included, wrapped in that image's section.
+        images = sorted(ir.images, key=lambda image: image.start)
+        if len(images) > 1:
+            segments = [(image.start, image.end, image) for image in images]
+            section_ids = self._image_identifiers(images)
+            self._saved_images = images
+            if self.output_filename is not None:
+                warnings.warn(
+                    f"output_filename {self.output_filename!r} is ignored: "
+                    f"{len(images)} images are loaded and each is saved "
+                    f"under its own name (see d.load(name=...))",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            lines.extend(self.image_section_declarations(section_ids))
+        else:
+            segments = [(int(load_start), int(load_end), None)]
+            section_ids = [None]
+        boundary_labels = self._segment_boundary_labels(segments)
+
+        def section_of(binary_addr: int):
+            """The section id of the image holding ``binary_addr``."""
+            for (start, end, _image), section_id in zip(segments, section_ids):
+                if start <= binary_addr < end:
+                    return section_id
+            return None
+
         # PHASE 1: emit move regions first, in source-binary-address
         # order. Each move's emission is self-contained: org-to-src,
         # source label, move-enter, body, move-exit.
         for src_addr in sorted(moves_by_src):
             move = moves_by_src[src_addr]
+            section_id = section_of(int(src_addr))
+            if section_id is not None:
+                lines.extend(self.image_section_start(section_id))
             lines.extend(
                 self._emit_move_section(ir, move, moves_by_src, move_ids)
             )
+            if section_id is not None:
+                lines.extend(self.image_section_end(section_id))
 
-        # PHASE 2: main code. ``org`` to the load start (resetting
-        # PC after the moves' restore-to-source positions left it
-        # somewhere arbitrary) plus the boundary start marker.
-        lines.extend(self.code_start(load_start, load_end, first=True))
-        if self.boundary_start_label is not None:
-            lines.append(self.inline_label(self.boundary_start_label))
 
         # Skip ranges: any binary address covered by ANY move's
         # source range was emitted in phase 1.
@@ -384,39 +493,67 @@ class AssemblerRenderer(TextRenderer):
             (src, src + mv.length) for src, mv in moves_by_src.items()
         ]
 
-        # Track PC through the walk so we can emit ``org &<addr>``
-        # whenever we resume after a skipped (move-source) range —
-        # the main walk needs to resume at the byte just after the
-        # last move source.
-        expected_pc = int(load_start)
-        for binary_addr, classification in ir.classifications.iter_classified_starts():
-            ba = int(binary_addr)
-            if not (int(load_start) <= ba < int(load_end)):
-                continue
-            if any(s <= ba < e for s, e in move_src_ranges):
-                continue
-            if ba != expected_pc:
-                lines.extend(self.set_origin(ba))
-                expected_pc = ba
-            lines.extend(self._emit_classification_at(
-                ir, ba, classification,
-                active_move=None, active_move_id=None,
-            ))
-            expected_pc = ba + classification.length()
-
-        # Position PC at load_end before emitting the boundary end
-        # marker so the label takes the load_end value (otherwise the
-        # marker lands wherever the last classification's last byte
-        # ended, which can be earlier when a move source extends to
-        # load_end).
-        if self.boundary_end_label is not None:
-            if expected_pc != int(load_end):
-                lines.extend(self.set_origin(int(load_end)))
-            lines.append(self.inline_label(self.boundary_end_label))
-        save = self._save_directive(load_start, load_end, ir.program)
-        if save is not None:
+        for index, (seg_start, seg_end, _image) in enumerate(segments):
+            start_label, end_label = boundary_labels[index]
+            if section_ids[index] is not None:
+                lines.extend(self.image_section_start(section_ids[index]))
+            # ``org`` to the segment start (resetting PC after the moves'
+            # restore-to-source positions left it somewhere arbitrary)
+            # plus the boundary start marker.
+            lines.extend(self.code_start(seg_start, seg_end, first=index == 0))
+            if start_label is not None:
+                lines.append(self.inline_label(start_label))
+
+            # Track PC through the walk so we can emit ``org &<addr>``
+            # whenever we resume after a skipped (move-source) range —
+            # the main walk needs to resume at the byte just after the
+            # last move source.
+            expected_pc = seg_start
+            for binary_addr, classification in ir.classifications.iter_classified_starts():
+                ba = int(binary_addr)
+                if not (seg_start <= ba < seg_end):
+                    continue
+                if any(s <= ba < e for s, e in move_src_ranges):
+                    continue
+                if ba != expected_pc:
+                    lines.extend(self.set_origin(ba))
+                    expected_pc = ba
+                lines.extend(self._emit_classification_at(
+                    ir, ba, classification,
+                    active_move=None, active_move_id=None,
+                ))
+                expected_pc = ba + classification.length()
+
+            # Position PC at the segment end before emitting the boundary
+            # end marker so the label takes that value (otherwise the
+            # marker lands wherever the last classification's last byte
+            # ended, which can be earlier when a move source extends to
+            # the end).
+            if end_label is not None:
+                if expected_pc != seg_end:
+                    lines.extend(self.set_origin(seg_end))
+                lines.append(self.inline_label(end_label))
+            if section_ids[index] is not None:
+                lines.extend(self.image_section_end(section_ids[index]))
+
+        if len(segments) > 1:
+            saves = [
+                self._image_save_directive(
+                    image,
+                    boundary_labels[index][0] or self.hex4(seg_start),
+                    boundary_labels[index][1] or self.hex4(seg_end),
+                )
+                for index, (seg_start, seg_end, image) in enumerate(segments)
+            ]
+        else:
+            # A single image's declared name names its save, unless the
+            # renderer was given an explicit output filename.
+            name = images[0].name if images and images[0].name_declared else None
+            saves = [self._save_directive(load_start, load_end, ir.program, name)]
+        saves = [save for save in saves if save is not None]
+        if saves:
             lines.append("")
-            lines.append(save)
+            lines.extend(saves)
         lines.extend(self.disassembly_end())
 
         # End-of-file label-reference frequency table.
@@ -626,7 +763,10 @@ class AssemblerRenderer(TextRenderer):
         end = src_addr + length
         move_id = move_ids.get(id(move))
         src_label = self._first_explicit_name(ir, src_addr)
-        dest_label = self._first_explicit_name(ir, dest_addr)
+        # The anchor for the trailer's copyblock / clear: a name this
+        # move's own body defines (or one belonging to no overlay), never
+        # another overlay's name from a later section.
+        dest_label = self._first_explicit_name(ir, dest_addr, move.move_id)
 
         # Position PC at the move's source binary address. Every
         # move emits this so the moves can appear in any order in
@@ -635,6 +775,7 @@ class AssemblerRenderer(TextRenderer):
         if src_label is not None:
             lines.append(self.inline_label(src_label))
             self._inline_emitted_runtime_addrs.add(src_addr)
+            self._inline_emitted_names.add(src_label)
 
         # Switch PC into the relocated destination range via the
         # backend's pseudo-PC hook (beebasm ``org``+``copyblock`` idiom;
@@ -699,31 +840,33 @@ class AssemblerRenderer(TextRenderer):
         for ann in ir.annotations.get_for_align(binary_addr, Align.BEFORE_LABEL):
             lines.extend(self._render_annotation(ann))
 
-        # Inline labels at this runtime address. Skip if a previous
-        # body walk has already emitted the inline anchor — this
-        # happens for multi-source-same-destination moves: the label
-        # at the shared destination is emitted once (during the move
-        # whose body walk reaches the address first), and the
-        # subsequent moves' body walks hit the same runtime address
-        # and would otherwise re-emit ``.<name>`` (which beebasm
-        # rejects with "Symbol already defined"). The ``copyblock``
-        # / ``clear`` directives in the per-move trailers still
-        # resolve the name correctly via the single inline definition.
+        # Inline labels at this runtime address. A name is emitted once:
+        # moves that overlay the same run range (ADFS's three NMI
+        # handlers at &0D0A) each walk the shared addresses, and beebasm
+        # rejects a second ``.<name>`` (D-023). Each overlay emits the
+        # names visible from it — its own (declared with ``move=``, or
+        # made for its references) plus any belonging to no overlay — so
+        # a name lands in the section of the move it describes (#53),
+        # and a name belonging to no overlay lands in the first section
+        # to reach it. The ``copyblock`` / ``clear`` directives in the
+        # per-move trailers resolve names wherever they are defined.
         label = ir.labels.get_label(runtime_addr)
-        if (
-            label is not None
-            and runtime_addr not in self._inline_emitted_runtime_addrs
-        ):
-            xref = self._format_inline_xref_summary(label, runtime_addr)
-            if xref is not None:
-                lines.append(xref)
+        overlay = active_move.move_id if active_move is not None else BASE_MOVE_ID
+        if label is not None:
+            visible = ir.labels.names_in_overlay(runtime_addr, overlay)
+            names = [n for n in visible if n not in self._inline_emitted_names]
+            first_visit = runtime_addr not in self._inline_emitted_runtime_addrs
+            if first_visit and (names or not label.explicit_name_texts()):
+                xref = self._format_inline_xref_summary(label, runtime_addr)
+                if xref is not None:
+                    lines.append(xref)
             # Insertion order, not alphabetical — preserves the label
             # author's intended sequence at addresses with multiple
             # names. The first-registered name is the structural one
             # and should lead.
-            names = label.explicit_names_in_insertion_order()
             for name in names:
                 lines.append(self.inline_label(name))
+                self._inline_emitted_names.add(name)
             if names:
                 self._inline_emitted_runtime_addrs.add(runtime_addr)
             # Mid-instruction labels INSIDE this classification's span
@@ -735,9 +878,8 @@ class AssemblerRenderer(TextRenderer):
             # against the inline anchor's PC, which IS at the base's
             # runtime. (Example: ``tube_cmd_lo = tube_dispatch_cmd+1``
             # inside move 1 of NFS-3.65.)
-            base_names = label.explicit_names_in_insertion_order()
-            if base_names:
-                base_name = base_names[0]
+            if visible:
+                base_name = visible[0]
                 for off in range(1, classification.length()):
                     inner_binary = binary_addr + off
                     if active_move is not None:
@@ -750,6 +892,19 @@ class AssemblerRenderer(TextRenderer):
                     inner_label = ir.labels.get_label(inner_runtime)
                     if inner_label is None:
                         continue
+                    inner_names = [
+                        name for name in ir.labels.names_in_overlay(
+                            inner_runtime, overlay,
+                        )
+                        if name not in self._inline_emitted_names
+                    ]
+                    # A nameless inner label (references only) still gets
+                    # its xref summary and annotations, once. Names that
+                    # are already defined, or that belong to another
+                    # overlay of this run range, are left alone.
+                    nameless = not inner_label.explicit_name_texts()
+                    if not inner_names and not (nameless and first_visit):
+                        continue
                     # Mid-instruction labels live inside an opcode's
                     # operand bytes — the addr the human cares about
                     # is the BINARY one (where the byte sits in the
@@ -781,8 +936,9 @@ class AssemblerRenderer(TextRenderer):
                         inner_binary, Align.BEFORE_LINE,
                     ):
                         lines.extend(self._render_annotation(ann))
-                    for inner_name in inner_label.explicit_names_in_insertion_order():
+                    for inner_name in inner_names:
                         lines.append(f"{inner_name} = {base_name}+{off}")
+                        self._inline_emitted_names.add(inner_name)
                     self._inline_emitted_runtime_addrs.add(inner_runtime)
 
         for ann in ir.annotations.get_for_align(binary_addr, Align.AFTER_LABEL):
@@ -971,29 +1127,35 @@ class AssemblerRenderer(TextRenderer):
             # emission yet (e.g. user added them after rendering
             # started — currently impossible but the codepath is
             # defensive).
-            if runtime_addr in self._inline_emitted_runtime_addrs:
-                continue
-            inline_anchor = (
-                in_range
-                and self._label_address_is_classification_start(ir, runtime_addr)
-            )
-            if inline_anchor:
-                continue
-            # Mid-instruction labels with a named base are emitted
-            # inline under the base as ``name = base+offset`` — skip
-            # the equate table to avoid double-definition.
-            if (
-                in_range
-                and self._label_has_inline_offset_base(ir, runtime_addr)
-            ):
-                continue
+            #
+            # The test is per name: where several moves overlay the
+            # address, each overlay anchors only its own names (#53), so
+            # one name can be anchored while another at the same address
+            # still needs its equate here.
             explicit_names = sorted({
                 name.text
                 for name_list in label.explicit_names.values()
                 for name in name_list
-            })
+            } - self._inline_emitted_names)
             if not explicit_names:
                 continue
+            if runtime_addr not in self._inline_emitted_runtime_addrs:
+                inline_anchor = (
+                    in_range
+                    and self._label_address_is_classification_start(
+                        ir, runtime_addr,
+                    )
+                )
+                if inline_anchor:
+                    continue
+                # Mid-instruction labels with a named base are emitted
+                # inline under the base as ``name = base+offset`` — skip
+                # the equate table to avoid double-definition.
+                if (
+                    in_range
+                    and self._label_has_inline_offset_base(ir, runtime_addr)
+                ):
+                    continue
             if (
                 not in_range
                 and not label.required
@@ -1085,16 +1247,16 @@ class AssemblerRenderer(TextRenderer):
         return out
 
     @staticmethod
-    def _first_explicit_name(ir, runtime_addr: int) -> str | None:
-        """First (alphabetically) explicit name on the label at this
-        runtime address, or ``None``. Used as the symbolic anchor for
-        relocation directives — beebasm's ``copyblock`` / ``clear`` /
-        ``org`` need named anchors to reference.
+    def _first_explicit_name(
+        ir, runtime_addr: int, move_id: int = BASE_MOVE_ID,
+    ) -> str | None:
+        """First-registered explicit name at this runtime address as seen
+        from the overlay laid out by ``move_id``, or ``None``. Used as
+        the symbolic anchor for relocation directives — beebasm's
+        ``copyblock`` / ``clear`` / ``org`` need named anchors to
+        reference.
         """
-        label = ir.labels.get_label(runtime_addr)
-        if label is None:
-            return None
-        names = label.explicit_names_in_insertion_order()
+        names = ir.labels.names_in_overlay(runtime_addr, move_id)
         return names[0] if names else None
 
     def _build_stats_block(self, ir) -> list[str]:
@@ -2011,11 +2173,17 @@ class AssemblerRenderer(TextRenderer):
 
         if kind is OperandKind.ADDRESS_8:
             v = ir.memory.get_u8(operand_addr)
-            return self._addr_text(ir, v, width=8, using_binary_addr=using_addr)
+            return self._addr_text(
+                ir, v, width=8, using_binary_addr=using_addr,
+                active_move=active_move,
+            )
 
         if kind in (OperandKind.ADDRESS_16, OperandKind.ADDRESS_16_INDIRECT):
             v = ir.memory.get_u16_le(operand_addr)
-            return self._addr_text(ir, v, width=16, using_binary_addr=using_addr)
+            return self._addr_text(
+                ir, v, width=16, using_binary_addr=using_addr,
+                active_move=active_move,
+            )
 
         if kind is OperandKind.RELATIVE_OFFSET:
             offset = ir.memory.get_u8(operand_addr)
@@ -2041,6 +2209,7 @@ class AssemblerRenderer(TextRenderer):
             target = base_runtime + opcode.length() + offset
             return self._addr_text(
                 ir, target, width=16, using_binary_addr=using_addr,
+                active_move=active_move,
             )
 
         # Defensive — the mode-name dispatch in _render_operand
@@ -2054,6 +2223,7 @@ class AssemblerRenderer(TextRenderer):
         *,
         width: int,
         using_binary_addr: int | None = None,
+        active_move=None,
     ) -> str:
         """Render an address operand: a label name if one is
         registered, otherwise the appropriate hex literal.
@@ -2086,7 +2256,18 @@ class AssemblerRenderer(TextRenderer):
             # they flow through this path naturally. Insertion order
             # picks the structural / first-registered name when an
             # address has multiple aliases.
-            names = label.explicit_names_in_insertion_order()
+            # Inside a move that overlays a shared run range, prefer the
+            # names that overlay sees (its own, then any belonging to no
+            # overlay) over another overlay's (#53); every name at the
+            # address has the same value, so this is about readability.
+            overlay = (
+                active_move.move_id if active_move is not None else BASE_MOVE_ID
+            )
+            visible = ir.labels.names_in_overlay(addr, overlay)
+            names = visible + [
+                n for n in label.explicit_names_in_insertion_order()
+                if n not in visible
+            ]
             if names:
                 if not self._label_address_is_in_range(ir, addr):
                     self._used_external_labels.add(addr)
@@ -2658,7 +2839,9 @@ class AssemblerRenderer(TextRenderer):
     def _render_ref_node(self, ir, node: Ref, active_move) -> str:
         """Resolve a :class:`Ref` to its label's best name, or a hex
         literal when the address has no name."""
-        return self._addr_text(ir, int(node.runtime_addr), width=16)
+        return self._addr_text(
+            ir, int(node.runtime_addr), width=16, active_move=active_move,
+        )
 
     #: Unary operators rendered as a *function-like* form that brackets
     #: its own operand (so operand precedence is irrelevant and no

{dasmos-4.2.1 → dasmos-4.3.0}/src/dasmos/core/labels.py

@@ -216,6 +216,15 @@ class Label:
             for name in name_list
         }
 
+    def names_for_move(self, move_id: int) -> list[str]:
+        """The explicit names recorded for ``move_id``, de-duplicated,
+        in registration order."""
+        out: list[str] = []
+        for name in self.explicit_names.get(move_id, []):
+            if name.text not in out:
+                out.append(name.text)
+        return out
+
     def explicit_names_in_insertion_order(self) -> list[str]:
         """The explicit-name strings, de-duplicated but in registration
         order. Use this when rendering the visible label sequence at
@@ -314,6 +323,39 @@ class LabelManager:
     def get_label(self, runtime_addr) -> Label | None:
         return self._labels.get(RuntimeAddr(runtime_addr))
 
+    def names_in_overlay(self, runtime_addr, move_id: int) -> list[str]:
+        """The explicit names at ``runtime_addr`` as seen from the
+        overlay laid out by ``move_id`` (``BASE_MOVE_ID`` for unmoved
+        code), in registration order.
+
+        Several moves can share a run range — alternative overlays of
+        the same RAM. A name recorded for one of the moves covering
+        ``runtime_addr`` names that move's layout, so the other
+        overlays don't see it (#53); a name recorded for no covering
+        move is visible from all of them. Where at most one move covers
+        the address there is nothing to tell apart and every name is
+        returned.
+        """
+        label = self.get_label(runtime_addr)
+        if label is None:
+            return []
+        covering = self._move_manager.move_ids_for_runtime_addr(runtime_addr)
+        if len(covering) <= 1:
+            return label.explicit_names_in_insertion_order()
+        out: list[str] = []
+        for bucket, name_list in label.explicit_names.items():
+            if bucket != move_id and bucket in covering:
+                continue
+            for name in name_list:
+                if name.text not in out:
+                    out.append(name.text)
+        return out
+        covering = self._move_manager.move_ids_for_runtime_addr(runtime_addr)
+        for bucket, name_list in label.explicit_names.items():
+            if bucket in covering and any(n.text == name for n in name_list):
+                return bucket
+        return None
+
     def addr_for_name(self, name: str) -> RuntimeAddr | None:
         """Find the runtime address of a label by one of its names.