xenia-rs/audit-runs/phase-c17-keWait-native-object/investigation.md

# Phase C+17 Investigation — KeWait native-object handle synthesis (2026-05-14)

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

C+15-α / C+16 catalog D-2/D-3/D-4 hypothesis: ours's `KeWait*` doesn't emit
`handle.create` when passed a raw native dispatcher object pointer (PKEVENT /
PKSEMAPHORE), while canary's `xeKeWaitForSingleObject` /
`KeWaitForMultipleObjects_entry` call `XObject::GetNativeObject` which
lazy-synthesizes an `XEvent`/`XSemaphore`/`XMutant`/`XTimer` wrapper and
inserts it in the object table — `ObjectTable::AddHandle` fires
`phase_a::EmitHandleCreateAuto` (object_table.cc:191-198).

### Canary's `GetNativeObject` semantics (xobject.cc:397-483)

Triggered by: `KeWait*` (and family) is called with a raw kernel-object
pointer. The first action of `xeKeWaitForSingleObject` is to call
`XObject::GetNativeObject<XObject>(kernel_state, object_ptr)`
(threading.cc:972, threading.cc:1070).

`GetNativeObject(kernel_state, native_ptr, as_type=-1, already_locked=false)`:

1. Read `X_DISPATCH_HEADER` at `native_ptr`. `as_type` defaults to
   `header->type` (the dispatcher-type byte: 0=manual event, 1=auto event,
   2=mutant, 5=semaphore, 8/9=timer).
2. Check the `wait_list.flink_ptr` magic: if it equals `kXObjSignature`
   (`'X','E','N','\0'` = 0x58454E00) the dispatcher has already been adopted;
   read the existing handle from `wait_list.blink_ptr` and return the existing
   `XObject` via `LookupObject<XObject>(handle, true)`.
3. Otherwise FIRST USE — synthesize:
   - case 0 / 1: `new XEvent(kernel_state)` → calls
     `XEvent::InitializeNative(native_ptr, header)` then assigns to result.
   - case 2: `new XMutant` + `InitializeNative` (but body asserts —
     unsupported).
   - case 5: `new XSemaphore` + `InitializeNative` (semaphore->limit /
     signal_state).
   - case 3/4/6/7/8/9/18..24: `assert_always()`. Timer not handled here.
4. After construction, call `StashHandle(header, object->handle())` — writes
   `kXObjSignature` to `wait_list.flink_ptr` and the new handle to
   `wait_list.blink_ptr`. This guarantees idempotency: next call returns the
   same handle.

Crucially, the `XObject` ctor `XObject(KernelState*, Type, host_object)`
(xobject.cc:35-48) **always** calls `kernel_state->object_table()->AddHandle(this, nullptr)`,
which (C+15-α-wired) **emits `handle.create`** via
`phase_a::EmitHandleCreateAuto` (object_table.cc:148-201).

So: first call → 1× `handle.create` emit; subsequent calls (signature
matches) → 0 emits.

### Canary KeWaitForSingleObject entry ordering (threading.cc:969-1013)

```
xeKeWaitForSingleObject(object_ptr, ...):
  auto object = XObject::GetNativeObject<XObject>(kernel_state(), object_ptr);
                ^^^ emits handle.create on first use (object_type=1 / 3 / etc)
  if (!object) { return X_STATUS_ABANDONED_WAIT_0; }
  if (phase_a::IsEnabled()) {
    uint64_t sid = 0;
    if (!object->handles().empty()) {
      sid = phase_a::LookupHandleSemanticId(object->handles()[0]);
    }
    phase_a::EmitWaitBegin(&sid, 1, ...);   // wait.begin with real SID
  }
  result = object->Wait(...);
```

So canary's emit order on first use is: `handle.create` → `wait.begin`,
exactly as observed on the cold log (idx=102171 → 102172).

### Lifetime / refcount

The synthesized `XObject` lives until its `handle_ref_count` reaches 0. Since
`AddHandle` initializes it to 1, and there's no balancing `RemoveHandle`
elsewhere in the lazy-wrap path, the wrapper survives for the rest of the
session (no `handle.destroy` is emitted by canary either — confirmed by
absence in canary's log post-102171). This is structurally consistent with
canary's "stash the handle in the dispatcher; reuse forever" pattern.

For ours we mirror this: emit one `handle.create` on first
`ensure_dispatcher_object` adoption; no `handle.destroy` thereafter.

### Object-type mapping

| dispatcher header.type | canary symbol           | ours `KernelObject` variant | ours object_type code (event_log) |
|------------------------|-------------------------|------------------------------|------------------------------------|
| 0 (manual event)       | XEvent (notification)   | Event { manual_reset=true }  | EVENT = 1                          |
| 1 (auto event)         | XEvent (synchronization)| Event { manual_reset=false } | EVENT = 1                          |
| 5 (semaphore)          | XSemaphore              | Semaphore { .. }             | SEMAPHORE = 3                      |
| 8 (notif timer)        | XTimer (canary asserts) | Timer { manual_reset=true }  | TIMER = 4                          |
| 9 (sync timer)         | XTimer (canary asserts) | Timer { manual_reset=false } | TIMER = 4                          |
| 2 (mutant)             | XMutant (canary asserts)| (no shadow — return early)   | n/a                                |

Note canary's `GetNativeObject` `assert_always()`s for timer types 8/9 — it
panics on unsupported dispatcher types. Sylpheed apparently never hits these
in canary (canary keeps running, so the assert is never tripped in our cold
log). Ours's `ensure_dispatcher_object` historically supports timer/8/9 via
the shadow path; we keep that for ours's robustness and emit
`object_type=TIMER` for them. Cross-engine SID matching only matters for
codes both engines emit; ours's extra timer emits would surface as new
divergences (acceptable per the catalog).

## Ours's pre-fix behavior

- `resolve_pseudo_handle` (exports.rs:4321): only translates the magic
  `0xFFFF_FFFF` / `0xFFFF_FFFE` self-handle. For any other value it's a
  pass-through. Native dispatcher pointers and real handles both reach the
  next step unchanged.
- `ensure_dispatcher_object` (exports.rs:4363): on first encounter of a guest
  pointer (`ptr >= 0x1_0000` and not already in `state.objects`), reads the
  dispatcher header, creates the shadow `KernelObject::{Event, Semaphore,
  Timer}`, inserts into `state.objects`, stamps `kXObjSignature` at
  `+0x08/+0x0C`. **Does NOT emit `handle.create`.** **Does NOT bump
  `handle_refcount`** (entry stays absent).
- `ke_wait_for_single_object` (exports.rs:4954): calls `resolve_pseudo_handle`
  → `ensure_dispatcher_object` → `refresh_pkevent_shadow_from_guest` →
  emits `wait.begin` with `lookup_handle_semantic_id(handle) = 0`
  (since no SID was ever registered) → calls `do_wait_single`.

Result observed at idx=102171: ours emits `wait.begin
handles_semantic_ids=['0000000000000000']` and zero `handle.create` events.

## Fix shape

Symmetric: extend `ensure_dispatcher_object` to do the equivalent of
canary's `XObject::AddHandle` post-construction emit. Specifically:

1. After inserting the shadow into `state.objects` (existing line ~4409),
   **and** when this is a fresh adoption (the inserted-before check is the
   guard at line 4367), seed `handle_refcount.insert(ptr, 1)` for lifecycle
   symmetry (no canary-side `handle.destroy` is expected, but consistency
   with `alloc_handle_for` is worth ~1 LOC).
2. When `event_log::is_enabled()`, call
   `event_log::emit_handle_create_auto(tid, cycle, /* pc */ 0, object_type,
   raw_handle_id=ptr, object_name=None)`. The chosen `object_type` matches
   the variant: Event=1, Semaphore=3, Timer=4. This both emits the event AND
   registers the SID in the registry so the subsequent `wait.begin` resolves
   non-zero.

Order in `ke_wait_for_single_object` already matches canary: synth (now
emits `handle.create`) before `wait.begin`. No re-ordering needed.

For `ke_wait_for_multiple_objects` the same applies — the loop already calls
`ensure_dispatcher_object` per pointer (exports.rs:5022). Each first
adoption emits one `handle.create` and the SID array used by `wait.begin`
becomes non-zero per element.

### Idempotency / refcount lifecycle

- First-touch: shadow inserted + `handle_refcount[ptr] = 1` + emit
  `handle.create`.
- Re-touch (same pointer): early return at the `contains_key` guard → no
  emit, no refcount change. Matches canary's "already-initialized" branch.
- Destroy: there is no path that destroys these shadows in ours today
  (parity with canary). If someone later wires `handle.destroy` on
  shadow-removal, the refcount will be present and decrement-to-zero will
  fire the symmetric event. Not in scope here.

### Scope

C+17 strictly addresses D-2/D-3/D-4. We **do not** touch:

- `NtWait*` (handle-based; already SID-resolves through the registry once
  the underlying `Nt*Create*` emit fires `handle.create`).
- `Ke{Set,Reset,Pulse}Event` / `KeReleaseSemaphore` paths that also call
  `ensure_dispatcher_object`. These will now emit `handle.create` on their
  first-touch — that's EXPECTED engine-symmetric behavior, and matches
  canary (every entry into `GetNativeObject` may emit). The wait-side has
  pre-context emits in both engines, so observable order is preserved.

## Tripstone register

- Reading-error #28 (canary semantics first): VERIFIED.
- Reading-error #23 (widely-used primitive flip): MITIGATED via cold-vs-cold
  gate and HARD-REVERT-IF-MAIN-REGRESSES discipline.
- Reading-error #19 (host-side emits): event_log::is_enabled() guard
  preserved on every new emit — default-off zero cost.
- Refcount semantics: matches canary's "stash forever" lazy-wrap pattern;
  not symmetric with `alloc_handle_for`'s NtClose-balanced lifecycle (which
  is correct — these are different kinds of handles).

## Cascade prediction (for the run)

A=verify canary's GetNativeObject semantics: DONE.
B=land symmetric ~30-50 LOC fix: PENDING.
C=main matched-prefix > 102,171: ~75%.
D=sister chains advance (4 chains): ~75%.
E=NEW divergences surface (downstream): ~80% (intended).