// Commander X16 Emulator — disassembly-accuracy core ("code map").

// See code_map.h for the rationale. This file is deliberately dependency-light

// (no SDL / glue.h) so it stays warning-clean under /W3 /WX and is easy to unit

// test in isolation: it leans on just disasm(), dbg_info, and the two core

// symbols declared directly below.

#include "code_map.h"

#include "disasm.h"

#include "dbg_info.h"

#include "cpu/registers.h"   // FLAG_* bits + struct regs layout

#include <string.h>

#include <stdlib.h>

#include <stdio.h>   // snprintf, for rendering a cut-short line as data bytes

// --- Core symbols, declared directly to avoid pulling in memory.h/glue.h ---

// The global CPU register file (defined in fake6502.c) and the non-intrusive

// memory read used by disasm(). Signatures match memory.h / glue.h exactly.

extern struct regs regs;

extern bool        is_gen2;

uint8_t real_read6502(uint16_t address, uint8_t bank, bool debugOn, int16_t x16Bank);

#define CM_X16_CURRENT_BANK ((int16_t)-1)

#define CM_READ(a, b, xb) real_read6502((uint16_t)(a), (uint8_t)(b), true, (int16_t)(xb))

// Longest instruction we ever have to back up over when self-syncing (the

// 65C816 tops out at 4 bytes).

#define CM_MAX_INSN_LEN 4

// ---------------------------------------------------------------------------

//  Coverage + flag storage, keyed by the bank context backing the address.

// ---------------------------------------------------------------------------

//  Each context is a 64K bit coverage map (1 bit per address = 8 KB) plus a

//  per-address effective-status byte. Contexts are allocated lazily and capped;

//  the least-recently-used one is recycled once the cap is reached.

//

//  The key is deliberately NOT the full live bank state. Only part of the

//  address space is banked, so keying every address by (rambank, rombank) would

//  file the same unbanked low-memory code under a fresh context for every bank

//  combination the program happens to be in. With 32 ROM banks and 256 RAM

//  banks that exhausts the context cache during ROM boot alone (measured: the

//  cap is hit before BASIC is ready), and worse, coverage recorded at $0801

//  under one ROM bank could no longer be found once the program switched banks

//  -- so the disassembler lost the very ground truth it exists to collect.

//

//  Instead each address is keyed by what actually backs it, mirroring the

//  decode in real_read6502():

//    - gen2 with a non-zero program bank: the whole 64K is flat bank RAM and

//      the window registers select nothing, so only the program bank keys it;

//    - otherwise the program bank selects nothing (read6502() forces it to 0 on

//      gen1, even with -c816), and the key is the RAM bank for $A000-$BFFF, the

//      ROM bank for $C000-$FFFF, and nothing at all below $A000.

//  Anchors are never deleted when the memory under them changes -- there is no

//  write hook, and an overlay LOAD or a decompressor replaces code wholesale --

//  so each anchor also stores the opcode byte that was executing. An anchor is

//  only believed while that byte is still there. Without this, running a second

//  program over the first leaves stale "instruction starts" mid-instruction in

//  the new code, and they outrank the .dbg info that would have been right.

#define CM_ADDR_SPACE   0x10000

#define CM_COVER_BYTES  (CM_ADDR_SPACE / 8)   // 8 KB: one bit per address

// Contexts cost ~136 KB each. Keying by backing memory (above) means a real ROM

// boot settles at four, so a cap of 16 leaves ample headroom at ~2.2 MB total.

#define CM_MAX_CONTEXTS 16

typedef struct {

	bool     used;

	uint8_t  pbank;

	uint8_t  rambank;

	uint8_t  rombank;

	uint64_t lru;

	uint8_t  cover[CM_COVER_BYTES];

	uint8_t  status[CM_ADDR_SPACE];       // valid only where the cover bit is set

	uint8_t  opcode[CM_ADDR_SPACE];       // ditto: the byte that was executing

} cm_context_t;

static cm_context_t *g_ctx[CM_MAX_CONTEXTS];

static uint64_t       g_lru_clock;

static cm_context_t  *g_last_ctx;   // fast-path cache for the hot record loop

// Which banked window a given address reads from, for the disasm/real_read6502

// x16Bank argument. Low memory ($0000-$9FFF) is not banked (the CPU program

// bank handles gen2), so it follows the current bank.

static int16_t

cm_x16bank_for(uint16_t addr, uint8_t rambank, uint8_t rombank)

{

	if (addr >= 0xC000)

		return (int16_t)rombank;

	if (addr >= 0xA000)

		return (int16_t)rambank;

	return CM_X16_CURRENT_BANK;

}

// Reduce the live bank state to the part that actually selects the memory

// behind `addr`. See the note above.

static void

cm_key_for(uint16_t addr, uint8_t pbank, uint8_t rambank, uint8_t rombank,

           uint8_t *key_pb, uint8_t *key_ram, uint8_t *key_rom)

{

	if (is_gen2 && pbank != 0) {

		*key_pb  = pbank;

		*key_ram = 0;

		*key_rom = 0;

		return;

	}

	*key_pb  = 0;

	*key_ram = (addr >= 0xA000 && addr < 0xC000) ? rambank : 0;

	*key_rom = (addr >= 0xC000) ? rombank : 0;

}

static cm_context_t *

cm_ctx_find(uint8_t pbank, uint8_t rambank, uint8_t rombank)

{

	for (int i = 0; i < CM_MAX_CONTEXTS; i++) {

		cm_context_t *c = g_ctx[i];

		if (c && c->used && c->pbank == pbank && c->rambank == rambank && c->rombank == rombank)

			return c;

	}

	return NULL;

}

static cm_context_t *

cm_ctx_get_or_create(uint8_t pbank, uint8_t rambank, uint8_t rombank)

{

	cm_context_t *c = cm_ctx_find(pbank, rambank, rombank);

	if (c)

		return c;

	// Prefer a free slot; otherwise evict the least-recently-used context.

	int slot = -1;

	for (int i = 0; i < CM_MAX_CONTEXTS; i++) {

		if (!g_ctx[i] || !g_ctx[i]->used) { slot = i; break; }

		if (slot < 0 || g_ctx[i]->lru < g_ctx[slot]->lru) slot = i;

	}

	if (slot < 0)

		slot = 0;

	if (!g_ctx[slot]) {

		g_ctx[slot] = (cm_context_t *)calloc(1, sizeof(cm_context_t));

		if (!g_ctx[slot])

			return NULL;

	} else {

		// Recycling: only the coverage bits must be cleared — status bytes are

		// never read unless their cover bit is set. The evicted context may be

		// the one g_last_ctx points at, so drop that cache too rather than let

		// it name a context that now holds different banks.

		memset(g_ctx[slot]->cover, 0, sizeof(g_ctx[slot]->cover));

		if (g_last_ctx == g_ctx[slot])

			g_last_ctx = NULL;

	}

	g_ctx[slot]->used    = true;

	g_ctx[slot]->pbank   = pbank;

	g_ctx[slot]->rambank = rambank;

	g_ctx[slot]->rombank = rombank;

	g_ctx[slot]->lru     = ++g_lru_clock;

	return g_ctx[slot];

}

static bool

cm_bit(const cm_context_t *c, uint16_t addr)

{

	return c && (c->cover[addr >> 3] & (uint8_t)(1u << (addr & 7))) != 0;

}

// True if `addr` is a recorded instruction start AND the opcode byte recorded

// there still matches memory.

//

// Anchors are only ever added; nothing removes them when memory changes, and on

// this machine memory under code changes all the time -- an overlay LOAD, a

// second program loaded over the first, a decompressor unpacking over its own

// loader, self-modifying code. A stale anchor is worse than no anchor, because

// live-execution evidence outranks the .dbg spans that would have been right,

// so it can confidently place an instruction boundary in the middle of a real

// instruction.

//

// Comparing the recorded opcode byte against memory catches most of those for

// the price of one byte per address, and it keeps the DETECTION off the hot

// path -- staleness is noticed when an anchor is *used*, not when memory is

// written, so no write hook is needed. (Recording still pays one read and one

// store per executed instruction to capture the byte.) It is a heuristic, not a

// proof: replacement code that repeats the same opcode byte at the same address

// slips through. See the note in code_map.h and the KNOWN LIMITATION checks in

// tests/test_code_map.c.

static bool

cm_anchor_ok(const cm_context_t *c, uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank)

{

	if (!cm_bit(c, addr))

		return false;

	return c->opcode[addr] == (uint8_t)CM_READ(addr, bank, cm_x16bank_for(addr, rambank, rombank));

}

// ---------------------------------------------------------------------------

//  Recording

// ---------------------------------------------------------------------------

void

code_map_record(uint16_t pc, uint8_t pbank, uint8_t rambank, uint8_t rombank, uint8_t status)

{

	uint8_t k_pb, k_ram, k_rom;

	cm_key_for(pc, pbank, rambank, rombank, &k_pb, &k_ram, &k_rom);

	// Fast path: this is called for every executed instruction, so avoid the

	// context scan -- and the LRU bookkeeping -- when the bank context has not

	// changed since last time, which is overwhelmingly the common case.

	cm_context_t *c = g_last_ctx;

	if (!c || !c->used || c->pbank != k_pb || c->rambank != k_ram || c->rombank != k_rom) {

		c = cm_ctx_get_or_create(k_pb, k_ram, k_rom);

		if (!c)

			return;

		c->lru     = ++g_lru_clock;

		g_last_ctx = c;

	}

	c->cover[pc >> 3] |= (uint8_t)(1u << (pc & 7));

	c->status[pc]      = status;

	c->opcode[pc]      = (uint8_t)CM_READ(pc, pbank, cm_x16bank_for(pc, rambank, rombank));

}

// Locate the context holding coverage for `addr` under the given live banks.

static cm_context_t *

cm_ctx_for_addr(uint16_t addr, uint8_t pbank, uint8_t rambank, uint8_t rombank)

{

	uint8_t k_pb, k_ram, k_rom;

	cm_key_for(addr, pbank, rambank, rombank, &k_pb, &k_ram, &k_rom);

	return cm_ctx_find(k_pb, k_ram, k_rom);

}

bool

code_map_is_recorded_start(uint16_t pc, uint8_t pbank, uint8_t rambank, uint8_t rombank)

{

	return cm_anchor_ok(cm_ctx_for_addr(pc, pbank, rambank, rombank), pc, pbank, rambank, rombank);

}

uint8_t

code_map_recorded_status(uint16_t pc, uint8_t pbank, uint8_t rambank, uint8_t rombank, uint8_t fallback)

{

	cm_context_t *c = cm_ctx_for_addr(pc, pbank, rambank, rombank);

	if (cm_anchor_ok(c, pc, pbank, rambank, rombank))

		return c->status[pc];

	return fallback;

}

void

code_map_reset(void)

{

	for (int i = 0; i < CM_MAX_CONTEXTS; i++) {

		if (g_ctx[i]) {

			g_ctx[i]->used = false;

			memset(g_ctx[i]->cover, 0, sizeof(g_ctx[i]->cover));

		}

	}

	g_lru_clock = 0;

	g_last_ctx  = NULL;

}

// ---------------------------------------------------------------------------

//  Decoding helpers

// ---------------------------------------------------------------------------

static int

cm_decode(uint16_t addr, uint8_t bank, int16_t x16bank, uint8_t status,

          char *line, unsigned line_sz, int32_t *eff)

{

	int32_t e  = -1;

	int     sz = disasm(addr, bank, NULL, line, line_sz, x16bank, status, &e);

	if (sz < 1)

		sz = 1;

	if (eff)

		*eff = e;

	return sz;

}

// Predict the implied status of the NEXT instruction from the current opcode.

// Only used to fill gaps where live coverage is missing; recorded status always

// takes precedence over this estimate.

//

// Just five instructions change the register widths -- REP, SEP, XCE, PLP and

// RTI. REP and SEP apply their own status bits exactly, since the bits are in

// the operand; the WIDTHS they imply are still only as good as the E estimate

// below, because emulation mode overrides them.

//

// XCE is exact only when BOTH of its inputs are right, and neither is

// guaranteed. It swaps the carry and emulation flags, so it needs the incoming

// carry -- which is carried through the instructions handled in this switch

// (CLC, SEC, and whatever REP/SEP/XCE themselves do to it), but NOT through any

// data-dependent change: ADC, SBC, the compares, the shifts and rotates all

// move the carry without this estimate noticing. It also needs the incoming E,

// which anchors do not record at all.

//

// PLP and RTI restore a status byte from the stack, so this deliberately leaves

// the estimate alone for them rather than inventing a value.

//

// HOW WELL EACH GAP IS BOUNDED differs, and none is bounded unconditionally:

//   - a wrong STATUS estimate can be corrected when an accurate, believed

//     anchor is reached. Not "the next recorded anchor": a same-opcode stale

//     anchor is still believed and hands back its old status, there may be no

//     accurate anchor ahead at all, and even an accurate one only fixes its OWN

//     line -- an anchor on a PLP or RTI gives the status going INTO it, and the

//     byte it restores is still unmodelled, so the next line can be wrong again;

//   - a wrong E is weaker again, because anchors do not store E. An anchor

//     fixes the width of its own line, and propagation folds the stale E back

//     in (`if (e) status |= INDEX|MEMORY`), which can mis-size the next

//     unanchored line wherever the stale E and the real one imply different

//     widths. It is not unrecoverable: an XCE decoded with an accurate carry

//     writes a correct E (that is exactly what the real instruction does), as

//     does an explicit CLC/SEC before one -- but nothing guarantees such a

//     sequence appears.

// That fold-in also means "emulation mode is always right" holds for the real

// CPU but NOT for this estimate: a diverged E sizes operands as though native

// while the machine is really in emulation mode.

// Either way every line drawn from the estimate reports recorded = false, so a

// consumer is never told a guess is ground truth. All of this is pinned by

// tests.

static uint8_t

cm_propagate(uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank,

             uint8_t status, uint8_t *e_inout)

{

	if (!regs.is65c816)

		return status;

	// The operand is read through the window backing the OPERAND's address,

	// not the opcode's. They differ for an instruction whose opcode is the last

	// byte of a window: a REP at $BFFF takes its operand from $C000, which is

	// banked ROM, and reading that through the RAM window yields some other

	// bank's byte. Getting it wrong here mis-sizes the following instructions

	// until an accurate anchor is reached -- the exact drift this file exists

	// to prevent.

	uint16_t argp   = (uint16_t)((addr + 1) & 0xFFFF);

	int16_t  xb_op  = cm_x16bank_for(addr, rambank, rombank);

	int16_t  xb_arg = cm_x16bank_for(argp, rambank, rombank);

	uint8_t opcode = (uint8_t)CM_READ(addr, bank, xb_op);

	uint8_t e      = *e_inout;

	switch (opcode) {

		case 0x18: // CLC

			status &= (uint8_t)~FLAG_CARRY;

			break;

		case 0x38: // SEC

			status |= FLAG_CARRY;

			break;

		case 0xC2: // REP #imm — clears the given status bits

			status &= (uint8_t)~CM_READ(argp, bank, xb_arg);

			break;

		case 0xE2: // SEP #imm — sets the given status bits

			status |= (uint8_t)CM_READ(argp, bank, xb_arg);

			break;

		case 0xFB: { // XCE — exchange carry and emulation flags

			uint8_t carry = (uint8_t)(status & FLAG_CARRY);

			status = (uint8_t)((status & (uint8_t)~FLAG_CARRY) | (e ? FLAG_CARRY : 0));

			e = carry ? 1 : 0;

			break;

		}

		// TODO: PLP (0x28) and RTI (0x40) also change the widths, by restoring a

		// status byte from the stack. Nothing is done for them because the byte

		// is not knowable from the instruction stream -- see the header note on

		// where the widths are still a guess. Two avenues if this is ever worth

		// closing, both of which recover a real value rather than guessing:

		//   - PLP is almost always the tail of a PHP/PLP save-restore pair. Walk

		//     back to the matching PHP within the same routine; if the status

		//     there is known, so is the status the PLP restores.

		//   - RTI restores what the interrupt pushed, which is the status at the

		//     moment the interrupt was taken. The emulator sees every interrupt,

		//     so that value could simply be recorded when it happens.

		// Both need a notion of "known vs unknown" per status bit so a failed

		// attempt reports uncertainty instead of substituting another guess.

		default:

			break;

	}

	// In emulation mode the 65C816 forces 8-bit memory/index widths.

	if (e)

		status |= (uint8_t)(FLAG_INDEX_WIDTH | FLAG_MEMORY_WIDTH);

	*e_inout = e;

	return status;

}

// Fill one line at `addr`, decoded with an explicit status.

//

// The size the decode produces is clamped twice, and both clamps exist because

// a decode is the weakest evidence in this file:

//

//   * `max_size`, when positive, is a boundary the caller has already committed

//     to -- the address the next line starts at. The backward walk resolves

//     that boundary from evidence the fill does not have (and its last-resort

//     fallback does not decode at all, it just backs off a byte), so a decode

//     that disagrees has to give way rather than emit a line overlapping the

//     next one.

//   * a recorded anchor inside the instruction is live-execution evidence that

//     a real instruction starts there, which outranks a width ESTIMATE;

//     truncate onto it rather than stepping over the very ground truth this

//     file exists to collect. This applies only when the line being decoded is

//     itself a guess. When the line is recorded too, its width came from the

//     status captured as it executed and is evidence of the same rank, so

//     the two anchors are simply two real, overlapping instruction starts --

//     the `.byte $2C` skip idiom -- and the one the caller asked for wins.

//     Clipping it there would discard a whole known instruction to display a

//     different execution path than the one requested.

//

// Either clamp can leave the line shorter than the decode wanted. Such a line

// no longer describes a whole instruction, so it is not reported as one: it

// comes back with `recorded == false`, no effective address, and `text`

// rewritten as the raw data bytes it actually owns, so `size`, `bytes` and

// `text` always agree. Covering the leftover bytes is the caller's job; see the

// tiling loop in code_map_disasm_window().

static int

cm_fill(uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank,

        uint8_t st, bool recorded, int max_size, code_map_line_t *ln)

{

	int16_t xb = cm_x16bank_for(addr, rambank, rombank);

	int32_t eff;

	int     sz      = cm_decode(addr, bank, xb, st, ln->text, (unsigned)sizeof(ln->text), &eff);

	int     decoded = sz;

	if (max_size > 0 && sz > max_size)

		sz = max_size;

	// Only a guessed width gives way to an interior anchor. A recorded line's

	// width came from the status captured as it executed, so it is evidence of

	// the same rank -- two overlapping real instruction starts, not a bad guess

	// straddling a good one.

	//

	// The exemption is re-derived here rather than taken from the `recorded`

	// argument, because it is only sound while `st` really is the status the

	// anchor recorded: a caller that passed `recorded` with some other status

	// would be decoding at a guessed width and would then be allowed to step

	// over the very ground truth this clamp protects. The one caller does

	// satisfy that today; checking it locally means a second one cannot quietly

	// break it. (Defensive: no current path violates it, so this is not

	// exercised by a test.)

	cm_context_t *self  = cm_ctx_for_addr(addr, bank, rambank, rombank);

	bool          truth = cm_anchor_ok(self, addr, bank, rambank, rombank) &&

	                      self->status[addr] == st;

	if (!truth) {

		for (int i = 1; i < sz; i++) {

			uint16_t p = (uint16_t)((addr + i) & 0xFFFF);

			if (cm_anchor_ok(cm_ctx_for_addr(p, bank, rambank, rombank), p, bank, rambank, rombank)) {

				sz = i;

				break;

			}

		}

	}

	// A line the decode did not get to finish is not an instruction, and must

	// not be dressed as one: `text` would describe more bytes than `size`

	// covers, and `eff` was computed from bytes the line does not own -- for a

	// clamped line those bytes are the NEXT instruction's opcode. Render the

	// bytes it does own as data instead, so size, bytes and text agree and a

	// consumer (the panel, or DAP's instruction/instructionBytes pair) cannot

	// be handed a self-contradictory row.

	//

	// This is the honest rendering of a genuine ambiguity rather than a

	// failure: the `.byte $2C` skip idiom really does put two overlapping

	// instruction starts in memory, both real and both executed, and no linear

	// non-overlapping tiling can show both whole. The policy is that the start

	// the caller selected wins -- forward from the outer one shows the outer

	// instruction, forward from the inner one shows the inner -- and only a

	// guessed decode, or one crossing a boundary the window already committed

	// to, is reduced to the bytes it owns on that path.

	if (sz < decoded) {

		recorded = false;

		eff      = -1;

		int used = 0;

		for (int b = 0; b < sz && b < 4; b++) {

			uint16_t p = (uint16_t)((addr + b) & 0xFFFF);

			int      w = snprintf(ln->text + used, sizeof(ln->text) - (size_t)used,

			                      "%s$%02x", b == 0 ? ".byte " : ",",

			                      (unsigned)CM_READ(p, bank, cm_x16bank_for(p, rambank, rombank)));

			if (w < 0 || (size_t)(used + w) >= sizeof(ln->text))

				break;

			used += w;

		}

	}

	ln->addr     = addr;

	ln->size     = (uint8_t)sz;

	ln->status   = st;

	ln->eff_addr = eff;

	ln->recorded = recorded;

	ln->kind     = (uint8_t)(sz < decoded ? CM_LINE_DATA : CM_LINE_INSTRUCTION);

	// Whether the ADDRESS was executed is separate from whether this row could

	// be shown as a whole instruction: a boundary can force a recorded start to

	// be emitted as data, and a consumer still wants to know it is real code.

	ln->start_recorded = cm_anchor_ok(self, addr, bank, rambank, rombank);

	memset(ln->bytes, 0, sizeof(ln->bytes));

	// Each byte is read through the window that backs its own address, so an

	// instruction straddling $BFFF/$C000 shows the ROM bank's bytes for the part

	// that lives there rather than the RAM bank's.

	for (int b = 0; b < sz && b < 4; b++) {

		uint16_t p = (uint16_t)((addr + b) & 0xFFFF);

		ln->bytes[b] = (uint8_t)CM_READ(p, bank, cm_x16bank_for(p, rambank, rombank));

	}

	return sz;

}

// Emit one line at `addr` and advance the running status estimate. Recorded

// status wins; otherwise *run_status is used. `max_size` is passed through to

// cm_fill. Returns the number of bytes the emitted row covers (always >= 1),

// which is the instruction's size unless a clamp cut the row short.

static int

cm_emit(uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank,

        uint8_t *run_status, uint8_t *run_e, int max_size, code_map_line_t *ln)

{

	cm_context_t *c  = cm_ctx_for_addr(addr, bank, rambank, rombank);

	bool     recorded = cm_anchor_ok(c, addr, bank, rambank, rombank);

	uint8_t  st       = recorded ? c->status[addr] : *run_status;

	int sz = cm_fill(addr, bank, rambank, rombank, st, recorded, max_size, ln);

	*run_status = cm_propagate(addr, bank, rambank, rombank, st, run_e);

	return sz;

}

// ---------------------------------------------------------------------------

//  Anchored alignment

// ---------------------------------------------------------------------------

// The decision the backward walk made about one instruction: where it starts,

// how long it is, and the status it was sized with. Phase B seeds itself from

// this rather than re-deriving the boundary from a propagated estimate, which

// is what used to make the walk step over `center`. It does NOT render the line

// verbatim -- cm_emit re-resolves the evidence at each address, and on the

// fallback path can reach a different answer; see the note in phase B.

typedef struct {

	uint16_t addr;

	uint8_t  status;

	uint8_t  size;

	bool     recorded;

} cm_anchor_t;

static bool

cm_prev_anchor(uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank, cm_anchor_t *out)

{

	cm_context_t *ac            = cm_ctx_for_addr(addr, bank, rambank, rombank);

	uint8_t       anchor_status = cm_anchor_ok(ac, addr, bank, rambank, rombank)

	                                  ? ac->status[addr]

	                                  : regs.status;

	cm_anchor_t best_recorded = { 0, 0, 0, false };

	cm_anchor_t best_span     = { 0, 0, 0, false };

	cm_anchor_t best_sync     = { 0, 0, 0, false };

	bool        has_recorded = false, has_span = false, has_sync = false;

	for (int backoff = 1; backoff <= CM_MAX_INSN_LEN; backoff++) {

		uint16_t p  = (uint16_t)((addr - backoff) & 0xFFFF);

		int16_t  xb = cm_x16bank_for(p, rambank, rombank);

		// A candidate may sit in a different window than the anchor (a window

		// boundary can fall mid-instruction), so resolve its context itself.

		cm_context_t *c        = cm_ctx_for_addr(p, bank, rambank, rombank);

		bool          recorded = cm_anchor_ok(c, p, bank, rambank, rombank);

		uint8_t       st       = recorded ? c->status[p] : anchor_status;

		char    scratch[48];

		int32_t eff;

		int     sz = cm_decode(p, bank, xb, st, scratch, (unsigned)sizeof(scratch), &eff);

		// A candidate is only valid if it decodes to land exactly on `addr`.

		if (sz != backoff)

			continue;

		cm_anchor_t cand = { p, st, (uint8_t)sz, recorded };

		if (!has_recorded && recorded) {

			best_recorded = cand;

			has_recorded  = true;

		}

		// The .dbg address space is a flat 24-bit one, so the program bank has

		// to be folded in -- otherwise bank-K code never matches its own spans,

		// and a bank-0 span at the same offset matches when it should not.

		if (!has_span && dbg_info_is_span_start(((dbg_addr_t)bank << 16) | p)) {

			best_span = cand;

			has_span  = true;

		}

		if (!has_sync) {

			best_sync = cand;

			has_sync  = true;

		}

	}

	if (has_recorded) { *out = best_recorded; return true; } // (1) live coverage

	if (has_span)     { *out = best_span;     return true; } // (2) cc65 .dbg spans

	if (has_sync)     { *out = best_sync;     return true; } // (3) self-sync

	// Nothing aligned cleanly. Back up a single byte so callers still make

	// progress, and say the size that implies.

	out->addr     = (uint16_t)((addr - 1) & 0xFFFF);

	out->status   = anchor_status;

	out->size     = 1;

	out->recorded = false;

	return true;

}

uint16_t

code_map_prev_instruction(uint16_t addr, uint8_t bank, uint8_t rambank, uint8_t rombank)

{

	cm_anchor_t an;

	if (!cm_prev_anchor(addr, bank, rambank, rombank, &an))

		return (uint16_t)((addr - 1) & 0xFFFF);

	return an.addr;

}

int

code_map_disasm_window(uint16_t center, uint8_t bank, uint8_t rambank, uint8_t rombank,

                       int lines_before, int lines_after,

                       code_map_line_t *out, int max_out, int *out_center_index)

{

	if (out_center_index)

		*out_center_index = -1;

	if (!out || max_out <= 0)

		return 0;

	if (lines_before < 0)

		lines_before = 0;

	if (lines_after < 1)

		lines_after = 1; // always include the center line itself

	// Phase A — walk backward, keeping the decision made about each instruction

	// rather than just its address. Re-deriving these on a forward pass would

	// use a different (propagated) status estimate, and where the two disagree

	// the walk drifts: it steps over `center`, loses the current-line marker and

	// renders every following line at the wrong offset.

	cm_anchor_t before[256];

	int         nbefore   = lines_before > 255 ? 255 : lines_before;

	int         collected = 0;

	uint16_t    a         = center;

	for (int i = 0; i < nbefore; i++) {

		cm_anchor_t an;

		if (!cm_prev_anchor(a, bank, rambank, rombank, &an))

			break;

		if (an.addr == a)

			break;

		before[collected++] = an;

		a                   = an.addr;

	}

	// Phase B — render the preceding instructions, tiling the range the backward

	// walk resolved: each line must start exactly where the previous one ended,

	// or the caller cannot draw the result.

	//

	// The walk fixes where each instruction ENDS (the next line's start), but

	// the fill can still land short of it or, left unchecked, past it:

	//   * the walk's last-resort fallback backs off one byte without decoding,

	//     so the byte there can decode wider than the one byte allowed for;

	//   * the fill truncates onto a recorded start found inside the

	//     instruction, which is right but leaves the remaining bytes uncovered.

	// Capping each fill at the distance to the boundary kills the overlap, and

	// looping until the boundary is reached exactly kills the gap.

	//

	// run_status is seeded from the walk's decision, but cm_emit re-resolves

	// the evidence at each address rather than taking before[i] verbatim, so

	// the first line is not guaranteed to match what the walk decided. It can

	// differ on the fallback path: the walk rejects a candidate whose decode

	// does not land on the anchor and stores the anchor's status, while cm_emit

	// looks up that address and may find a recorded anchor of its own. Where

	// they differ, cm_emit's answer is the better one -- it is live-execution

	// evidence recorded at that exact address -- and it cannot drift, because

	// the fallback has one byte of room and phase C reseeds independently.

	//

	// Because one resolved instruction can now need more than one line, this

	// resolves them NEAREST-THE-CENTER FIRST and places them backwards from the

	// end of the reserved region. Filling forwards would spend the buffer on

	// the furthest context and push `center` -- the address the caller asked to

	// be centered on -- off the end of a full buffer, which is the one row every