xenia-rs/audit-runs/phase-c16-XamTaskCloseHandle-refcount/investigation.md

# Phase C+16 Investigation — XamTaskCloseHandle refcount (2026-05-14)

## Framing verification (reading-error #28 discipline)

C+15-α's catalog D-1 hypothesis was: "canary's spawned thread keeps an
additional ref on the thread handle (`object->Retain()` in `XThread::Create`
line 408 via `RetainHandle()`)". Verified against canary source.

### Canary's refcount model (xobject.cc + util/object_table.cc)

Two separate refcounts on `XObject`:

1. **`pointer_ref_count_`** — the C++ object pointer refcount.
   - Bumped by `XObject::Retain()` / dropped by `XObject::Release()`.
   - `AddHandle()` calls `object->Retain()` once when inserting into table.
2. **`handle_ref_count`** in `ObjectTableEntry` — the per-handle (per-slot)
   refcount that determines when the object is removed from the object
   table.
   - Initialized to 1 in `AddHandle()` (object_table.cc:164).
   - Bumped by `RetainHandle()` (object_table.cc:218-228 → `entry->handle_ref_count++`).
   - Decremented by `ReleaseHandle()` (object_table.cc:230-249).
   - On reaching 0, calls `RemoveHandle()` which emits `handle.destroy`
     and releases the pointer ref (`object->Release()`).

### Canary's XThread lifecycle

- `XObject` ctor → `AddHandle(this)` → `handle_ref_count = 1`,
  emits `handle.create`.
- `XThread::Create()` (xthread.cc:414) → `RetainHandle()` →
  `handle_ref_count = 2`. Comment: *"Always retain when starting - the
  thread owns itself until exited."*
- User calls `NtClose(handle)` → `ReleaseHandle()` → `handle_ref_count = 1`.
  Object SURVIVES; no `handle.destroy` emitted.
- Thread exits via `XThread::Exit()` (xthread.cc:524) → `ReleaseHandle()`
  → `handle_ref_count = 0` → `RemoveHandle()` → emits `handle.destroy`
  + drops pointer ref → object destroyed.

### Canary's XAM task lifecycle (xam/xam_task.cc:43-94)

`XamTaskSchedule_entry` creates an `XThread` (which adds it to the
object table) then calls `thread->Create()` (xthread.cc:315) which adds
the self-ref via `RetainHandle()`. The handle written to `handle_ptr`
is `12345` (a stub!), not the real thread handle. The actual thread
handle lives on the `XThread` object.

`XamTaskCloseHandle_entry` calls `xboxkrnl::NtClose(obj_handle)`. Even
when `obj_handle=12345` (stub), `NtClose` of an invalid handle returns
`X_STATUS_INVALID_HANDLE` and the function returns false. But our test
data shows it returns 1 (success) on both engines, indicating the
SHIM-VS-GAME handle plumbing produces a valid handle in practice on
the main chain. (Possibly the game passes the actual thread handle.)

The crucial behavior is: after `NtClose`, canary's refcount went 2→1,
so no `handle.destroy` event. Ours's refcount went 1→0, emitting the
extra `handle.destroy`. **Hypothesis confirmed.**

## Ours's pre-fix state

- `alloc_handle_for` → `handle_refcount.insert(h, 1)`.
- `ex_create_thread` / `xam_task_schedule` after spawn → no retain.
- `nt_close` / `xam_task_close_handle` → decrement, destroy on 0.
- `ex_terminate_thread` → marks scheduler Exited, wakes joiners, does
  NOT release the (missing) self-ref.
- Main thread (`install_initial_thread`) — refcount=1, never closed.

So ours's spawned threads had `handle_refcount = 1` (creator only). Any
guest `NtClose` on a thread handle destroyed it.

## Fix design

Mirror canary precisely:

1. After successful spawn in `ex_create_thread` + `xam_task_schedule`:
   call `state.retain_handle(handle)` (refcount 1 → 2).
2. In `ex_terminate_thread` (explicit `ExTerminateThread`) and in the
   main-loop LR-sentinel implicit-exit path (`main.rs`): call
   `state.release_handle(handle)` after the scheduler `exit_current`
   bookkeeping.
3. Main thread (`install_initial_thread`): symmetric retain (canary's
   main also goes through `Create()::RetainHandle()`). Released at the
   LR-sentinel path on main thread shutdown.

New helpers in `state.rs`:

- `KernelState::retain_handle(handle) -> u32` — saturating increment;
  returns new refcount.
- `KernelState::release_handle(handle) -> bool` — saturating decrement;
  on hitting zero: removes object, scrubs async_file_handles +
  disarm_timer, emits `handle.destroy`, returns true. False if other
  refs remain.

The implicit-exit path in `main.rs` also gained the missing
`thread.exit` schema event (previously only `ex_terminate_thread`
emitted it; canary's `XThread::Exit` covers both explicit and implicit
paths, so this is a symmetry fix even though it didn't cause the C+16
divergence directly).

## Code summary

~75 LOC additive across 4 files; pure additive, no refactor:

- `crates/xenia-kernel/src/state.rs` — `retain_handle` + `release_handle`
  helpers. +50 LOC.
- `crates/xenia-kernel/src/exports.rs` — retain in `ex_create_thread`,
  release in `ex_terminate_thread`. +20 LOC.
- `crates/xenia-kernel/src/xam.rs` — retain in `xam_task_schedule`.
  +10 LOC.
- `crates/xenia-app/src/main.rs` — implicit-exit path: emit `thread.exit`,
  release self-ref; `install_initial_thread` post-call retain. +20 LOC.

Tests: +5 (181 → 186 total).

- `xam_task_schedule_close_then_thread_exit_destroys_handle` —
  refcount lifecycle balance (close-first).
- `xam_task_thread_exit_then_close_destroys_handle` —
  refcount lifecycle balance (exit-first).
- `xam_task_schedule_then_close_round_trip_returns_one` — extended
  with refcount asserts (post-spawn=2, post-close=1).
- `ex_create_thread_installs_self_reference` — verifies refcount=2
  after spawn.
- `ex_terminate_thread_releases_self_reference` — verifies refcount=1
  after terminate.
- `ex_create_then_close_then_exit_balances_refcount` — end-to-end
  three-step lifecycle.