Crusader_Decomp/docs/usecode-debugger-break-state-layout.md

# Usecode Debugger Break-State Layout

## Purpose

This note captures the current class-lift-relevant evidence for the dormant seg1408 debugger-state object.

The retail binary still appears to leave this family orphaned at runtime, but the object model itself is strong enough to justify explicit class authoring in Ghidra.

Current working family name:

- `UsecodeDebuggerBreakState`

## Current Best Class-Level Read

`UsecodeDebuggerBreakState` is a retained debugger object that owns:

- a small breakpoint table
- current interpreted-line state
- single-step / break-armed flags
- a callstack entry stack
- a small vtable-backed break/notify surface used by the interpreter callback lane

The compiled interpreter still calls into this object when the global debugger-state pointer is non-null, even though the retail binary no longer seems to instantiate it during normal play.

## Strongest Evidence Anchors

### Constructor

#### `1408:0000` `Create`

Current verified behavior:

- allocates `0x2f2` bytes when `this == null`
- writes retail vtable offset `0x65ab` at object `+0x00`
- fills the breakpoint-entry region starting at `+0x04` with `0xffff`
- clears `+0x02`, `+0x75`, and `+0x7a`
- returns the object far pointer in `DX:AX`

This is a real constructor-style path, not just a helper wrapper.

### Break gate

#### `1408:0053` `MaybeBreakOnCurrentLine`

Current verified behavior:

- stores the incoming interpreted line minus one at `+0x72`
- resolves the current unit-name pointer through `CurrentEntryGetUnitName`
- checks file+line breakpoints through `HasBreakpoint`
- dispatches through the object vtable when a break condition is met

This is the strongest proof that the hidden debugger lane is object-based and that the interpreter-side callback still expects a live debugger object.

### Breakpoint table helpers

#### `1408:00dd` `BreakpointInsertSorted`

Current verified behavior:

- enforces a maximum of ten breakpoint entries
- scans the `0x0b`-byte breakpoint-entry table rooted at `+0x04`
- compares unit-name strings via the common string helper
- inserts a new `(unit_name, line_number)` pair into the sorted table

#### `1408:01a5` `BreakpointRemove`

Current verified behavior:

- scans the same `0x0b`-byte breakpoint-entry table for an exact `(unit_name, line_number)` match
- compares the stored inline name bytes first, then the stored line word at entry `+0x09`
- compacts the remaining entries downward when a match is found
- decrements `breakpoint_count`

#### `1408:029e` `HasBreakpoint`

Current verified behavior:

- scans the same breakpoint-entry table
- compares the requested line number against entry `+0x09`
- compares the requested unit-name pair against the stored name bytes
- returns a boolean-style `uint` in `AX`

### Callstack helpers

#### `1408:02f5` `CallstackPushFrame`

Current verified behavior:

- computes the current callstack-entry base as `this + 0x7c + callstack_depth * 0x15`
- copies an inline unit-name buffer into entry `+0x00`
- enforces a maximum visible unit-name length of eight characters plus terminator
- stores three trailing far-pointer/state dwords at `+0x09`, `+0x0d`, and `+0x11`
- increments `callstack_depth`

#### `1408:03b0` `CallstackPushEntry`

Current verified behavior:

- uses `+0x7a` as the current callstack depth
- acts as a thinner wrapper over `CallstackPushFrame` when only the inline unit-name payload matters
- increments the depth and asserts when it reaches `0x1e`

#### `1408:03f7` `CallstackPopEntry`

Current verified behavior:

- decrements `+0x7a`
- asserts if the depth underflows below zero

### Step-state helpers

#### `1408:0419` `EnableSingleStep`

- clears `+0x76/+0x78`
- sets `+0x75 = 1`

#### `1408:0432` `ClearStepState`

- clears `+0x74`
- clears `+0x75`

### Current-entry name accessor

#### `1408:0444` `CurrentEntryGetUnitName`

Current verified behavior:

- returns null when `callstack_depth <= 0`
- otherwise returns a far pointer to the current callstack entry's inline unit-name buffer

## Recovered Entry Schemas

The live debugger-state model is now strong enough to split the old table blobs into concrete fixed-size entry records.

### `UsecodeDebuggerBreakpointEntry` (`0x0b` bytes)

| Offset | Current name | Confidence | Current meaning |
|---|---|---|---|
| `+0x00..+0x08` | `unit_name_inline[9]` | High | Inline unit-name buffer, consistent with eight visible characters plus terminator. |
| `+0x09` | `line_number` | High | Breakpoint line number compared by `BreakpointInsertSorted`, `BreakpointRemove`, and `HasBreakpoint`. |

### `UsecodeDebuggerCallstackEntry` (`0x15` bytes)

| Offset | Current name | Confidence | Current meaning |
|---|---|---|---|
| `+0x00..+0x08` | `unit_name_inline[9]` | High | Inline unit-name buffer for the active frame. |
| `+0x09` | `source_stream_cursor_farptr` | High | Far pointer to the current debugger/source descriptor stream cursor. `Debugump_13a0_0291` passes this lane into `13a0:045c`, which reads descriptor bytes and inline strings directly from it. This field name is now promoted into the live datatype in `CRUSADER.EXE`, not just the note set. |
| `+0x0d` | `current_frame_payload_farptr` | High | Far pointer to the current frame payload/evaluation context at `frame_base + 0x04`. `13a0:045c` dereferences this lane while formatting debugger dump/watch text. |
| `+0x11` | `aux_farptr` | Low | Trailing auxiliary far pointer slot; still zero in the only verified `CallstackPushFrame` caller and still lacks a confirmed current-entry consumer. |

## Current Working Layout

The live datatype `/Remorse/UsecodeDebuggerBreakState` now exists in-session with the currently safest anchors:

| Offset | Current name | Confidence | Current meaning |
|---|---|---|---|
| `+0x00` | `vtable_offset` | High | Retail debugger-state vtable offset `0x65ab`. |
| `+0x02` | `breakpoint_count` | High | Count of `0x0b`-byte breakpoint entries. |
| `+0x04..+0x71` | `breakpoint_entries[10]` | High | Ten inline `UsecodeDebuggerBreakpointEntry` records. |
| `+0x72` | `current_line` | High | Current interpreted line minus one. |
| `+0x74` | `break_armed` | Medium | Break/armed flag cleared by `ClearStepState`. |
| `+0x75` | `single_step_enabled` | High | Single-step flag set by `EnableSingleStep`. |
| `+0x76/+0x78` | `step_state_lo/hi` | Medium | Step-state pair cleared by `EnableSingleStep`. |
| `+0x7a` | `callstack_depth` | High | Current callstack depth. |
| `+0x7c..+0x2f1` | `callstack_entries[30]` | High | Thirty inline `UsecodeDebuggerCallstackEntry` records. |

## Live Ghidra Authoring Status

Verified first live class batch landed on 2026-04-06.

- Created class owner `Remorse::UsecodeDebuggerBreakState`.
- Created `/Remorse/UsecodeDebuggerBreakpointEntry` (`0x0b`) and `/Remorse/UsecodeDebuggerCallstackEntry` (`0x15`) in the live data-type manager.
- Rewrote `/Remorse/UsecodeDebuggerBreakState` in-session so the old blob regions are now explicit `UsecodeDebuggerBreakpointEntry[10]` and `UsecodeDebuggerCallstackEntry[30]` arrays at the recovered offsets.
- Moved the main seg1408 helpers under the class owner:
	- `1408:0000` -> `Create`
	- `1408:0053` -> `MaybeBreakOnCurrentLine`
	- `1408:00dd` -> `BreakpointInsertSorted`
	- `1408:01a5` -> `BreakpointRemove`
	- `1408:0230` -> `BreakpointFindFirstForUnitAtOrAfterLine`
	- `1408:029e` -> `HasBreakpoint`
	- `1408:02f5` -> `CallstackPushFrame`
	- `1408:03b0` -> `CallstackPushEntry`
	- `1408:03f7` -> `CallstackPopEntry`
	- `1408:0419` -> `EnableSingleStep`
	- `1408:0432` -> `ClearStepState`
	- `1408:0444` -> `CurrentEntryGetUnitName`
- Promoted the remaining bounded breakpoint-table helper `1408:0230` under the class owner as `BreakpointFindFirstForUnitAtOrAfterLine`; it now reads as the lower-bound search over `breakpoint_entries` for a given `(unit_name, line_number)` query instead of an anonymous seg1408 utility.
- Resolved the retail debugger vtable root at `1478:65ab` one step further: slot 0 points to `1408:046f` and slot 1 points to `1408:0474`, and both entries are now class-owned as `OnBreakTriggeredNoop` and `VtableSlot1ReturnZero` with explicit comments that the shipped retail implementations are inert stubs.
- Tightened the live method signatures to explicit object-style forms, including:
	- `UsecodeDebuggerBreakState * __cdecl16far Create(UsecodeDebuggerBreakState * this, dword init_spec)`
	- `void __cdecl16far MaybeBreakOnCurrentLine(UsecodeDebuggerBreakState * this, word current_line)`
	- `byte __cdecl16far BreakpointInsertSorted(UsecodeDebuggerBreakState * this, dword unit_name_farptr, word line_number)`
	- `void __cdecl16far BreakpointRemove(UsecodeDebuggerBreakState * this, dword unit_name_farptr, word line_number)`
	- `int __cdecl16far BreakpointFindFirstForUnitAtOrAfterLine(UsecodeDebuggerBreakState * this, dword unit_name_farptr, word line_number)`
	- `uint __cdecl16far HasBreakpoint(UsecodeDebuggerBreakState * this, dword unit_name_farptr, word line_number)`
	- `void __cdecl16far CallstackPushFrame(UsecodeDebuggerBreakState * this, dword unit_name_farptr, dword source_stream_target_farptr, dword current_frame_payload_farptr, dword aux_farptr)`
	- `byte __cdecl16far CallstackPushEntry(UsecodeDebuggerBreakState * this, dword unit_name_farptr)`
	- `void __cdecl16far CallstackPopEntry(UsecodeDebuggerBreakState * this)`
	- `void __cdecl16far EnableSingleStep(UsecodeDebuggerBreakState * this)`
	- `void __cdecl16far ClearStepState(UsecodeDebuggerBreakState * this)`
	- `dword __cdecl16far CurrentEntryGetUnitName(UsecodeDebuggerBreakState * this)`
- The only verified `CallstackPushFrame` caller at `1418:051d` is now constrained a little more tightly in-session too: the trailing payload is still best kept as `source_stream_target_farptr`, `current_frame_payload_farptr`, and `aux_farptr`, but the raw stack setup now confirms that the last slot is literal zero in retail, the middle slot is pushed from `frame_base + 0x04`, and the first slot is pushed from the interpreter `+0xd6/+0xd8` source-stream lane plus a local offset.
- The next seg109 consumer pass closed the main follow-up from that batch. `13a0:0291 Debugump_13a0_0291` now has a decompiler comment showing that it resolves the current callstack entry as `this + 0x67 + depth * 0x15`, passes entry `+0x09` as the descriptor/source-stream cursor, and passes entry `+0x0d` as the frame payload context into `13a0:045c`.
- `13a0:045c FUN_13a0_045c` now also carries a decompiler comment recording the same split from the consumer side: it reads descriptor bytes and inline strings directly from the `+0x09` lane and dereferences the `+0x0d` lane as the evaluation context while formatting debugger dump/watch text into the shared output buffer at `0x45a6`.
- The `CallstackPushFrame` comment in seg1408 was updated to reflect that narrower live read: `+0x09` is no longer just a generic source-derived far pointer, but a real source-stream cursor used by the seg109 formatter path.
- That naming decision is now applied live too. `/Remorse/UsecodeDebuggerCallstackEntry` now exposes `source_stream_cursor_farptr` at offset `+0x09` with a matching field comment in the datatype manager, and `CallstackPushFrame` now uses `source_stream_cursor_farptr` in its parameter list instead of the older `source_stream_target_farptr` wording.
- The seg109 consumer helpers are now named live as stable free functions rather than left comment-only:
	- `13a0:0291` -> `usecode_debugger_format_expression_to_shared_buffer`
	- `13a0:045c` -> `usecode_debugger_format_descriptor_expression`
- Those names are still intentionally conservative. They record the verified behavior now visible in both producer-side and consumer-side comments: `13a0:0291` resolves the current debugger callstack entry and writes the formatted result into the shared output buffer, while `13a0:045c` interprets the descriptor/source-stream cursor plus frame payload context rather than merely dumping raw bytes.
- Added decompiler comments on the breakpoint and callstack helpers so the recovered inline-record layout is visible in-session even before every field is formally typed.
- Added decompiler comments on the only verified `Interpreter_NextUsecodeOp` caller of `CallstackPushFrame`, which confirms the current live read of the three trailing callstack dwords:
	- `source_stream_target_farptr` is source-stream-derived from the interpreter `+0xd6/+0xd8` lane plus one fetched word
	- `current_frame_payload_farptr` is current-frame-derived from the `frame_base + 0x04` lane
	- `aux_farptr` is still zero in the only verified caller
- A second caller pass on 2026-04-08 still did not widen that lane: `get_callers(1408:02f5)` still reports only `1418:051d Interpreter_NextUsecodeOp`, and the live `CallstackPushFrame` comment now records that the trailing `aux_farptr` slot remains literal zero in retail while the current seg109 consumers still only read `+0x09` and `+0x0d`.

## Current Cautions

- The retail instantiation path still appears absent; no normal caller currently reaches `Create` in the unpatched retail binary.
- The record boundaries inside both tables are now landed in the live datatype, and the first two trailing callstack dwords now have both producer-side and seg109 consumer-side structural evidence plus live datatype names/comments. The remaining uncertainty is no longer whether those lanes are meaningful, but whether they should ever become more subsystem-specific than `source_stream_cursor_farptr` and `current_frame_payload_farptr`.
- The retail vtable root is no longer an open slot-map question for the first two entries. What remains open is whether any non-retail or UI-side build ever installed non-stub behavior behind those same callback positions.
- `init_spec` on `Create` and `unit_name_farptr` on the breakpoint/callstack helpers are intentionally neutral names; the live signatures are object-correct, but the payload semantics should stay conservative.

## Best Next Moves

1. Cross-check the seg1408 class note against the interpreter callback site at `1418:04b5` so the dormant-orphan lifecycle remains explicit in the live notes now that slot 0 is confirmed to land on an inert retail stub.
2. Decide whether `aux_farptr` should remain neutral or can be promoted after one more caller or consumer pass.
3. If the debugger family is revisited again, prioritize non-retail callback behavior or instantiation evidence before spending more time on the already-stable retail formatter lane.
4. If the debugger family stalls there, switch to the next planned class-lift family instead of overworking this orphaned subsystem.

## Bottom Line

`UsecodeDebuggerBreakState` is now past the “interesting orphan subsystem” stage and into real class territory.

The live database now has a bounded debugger-state class with a constructor, breakpoint gate, breakpoint table helpers, callstack helpers, explicit recovered `0x0b` / `0x15` entry schemas, and step-state helpers, even though the retail game still appears to leave that object dormant.