# Iterate 2.L — Diff harness `return_value` / `args_resolved` category tagging

**Date:** 2026-05-28. **LOC delta:** engine **0**, canary **0**, harness
`tools/diff-events/diff_events.py` **+106**, `test_diff_events.py`
**+125** (6 new tests). **Tests:** all existing tests PASS + 6 new tests
PASS. **Cascade:** A/B PASS (gate criteria met on both controls), C/D
N/A (tooling change, not engine investigation).

## Headline

**HARNESS-EXTENDED-GATE-PASS.** Patch `diff_events.py` to surface
`kernel.return.return_value`/`status` mismatches and `kernel.call.args`/
`args_resolved` sub-dict mismatches with category-tagged diff strings
(`[return_value mismatch] kernel.return name=<fn>: canary=<v> ours=<v>`,
`[args_resolved.path mismatch] kernel.call name=<fn>: …`). Also surfaces
the RAW per-tid idx on each side of the divergence to disambiguate from
the matched-prefix position (closes reading-error #41's
matched-prefix-vs-raw-idx conflation).

## Finding: pre-existing strict-equality already catches the
divergence

Critical observation made during step 3 of the plan: the legacy
`compare_payload` ALREADY does strict equality on `return_value` and
`status` (they're not in `SKIP_PAYLOAD_FIELDS_BY_KIND["kernel.return"]`).
A fresh baseline run of the pre-patch harness on
`iterate-2H-physical-heap-vA/ours-cold.jsonl` vs
`phase-c23-keWait-timeout-encoding/canary-cold-trunc.jsonl` reported:

```
First divergence at tid_event_idx=102424:
  payload.return_value: canary=18446744072635809807 ours=0
```

— the iterate 2.I find, EXACTLY at the expected boundary
(NtQueryFullAttributesFile `cache:\d4ea4615\e\46ee8ca`,
SUCCESS-vs-NO_SUCH_FILE inversion).

Why the prompt believed the harness missed it: the prompt cites
"reported 'first divergence' at idx 104607 — 250 critsec-pair events
downstream". The 104,607 cap was the Phase D divergence point against
an earlier trace baseline. With the current Phase C+23 canary trace
(`canary-cold-trunc.jsonl`, post-VdQueryVideoFlags fix landing matched
prefix to 105,286) and the current `ours-cold.jsonl` from 2.H, the
first divergence on the main chain (canary tid=6 → ours tid=1) is now
at 102,424 — the cache-probe inversion. The harness was always
catching it; what was missing was actionable categorization in the
diff message.

The patch makes this signal greppable and self-explanatory in future
iterates (`grep '[return_value mismatch]' diff-report.md`), and also
fixes the secondary reading hazard — the `tid_event_idx=N` label in
the report was the matched-prefix offset, not the raw per-tid idx,
which can drift up to dozens of events under absorber action.

## Patch summary

`xenia-rs/tools/diff-events/diff_events.py:535-640`:

- New `_KERNEL_RETURN_PRIORITY_FIELDS = ("return_value", "status")`
  constant.
- New helpers `_format_return_value_diff(name, field, vc, vo)` and
  `_format_kernel_call_arg_diff(name, sub, key, vc, vo)` emitting the
  bracketed category tag.
- `compare_payload` runs a priority pass BEFORE the generic union-walk:
  on `kernel.return`, the two priority fields are checked first (only
  when present on BOTH sides — schema-gap safe); on `kernel.call`, the
  `args` and `args_resolved` sub-dicts are walked key-by-key with
  category-tagged emission. Generic walk falls through unchanged so
  any other payload field still surfaces (back-compat preserved).

`xenia-rs/tools/diff-events/diff_events.py:1159-1173`: report renderer
emits both raw `tid_event_idx` values (canary + ours) alongside the
matched-prefix position so readers can never again conflate them.

`xenia-rs/tools/diff-events/test_diff_events.py:1464-1583`: 6 new tests
covering: tagged return_value mismatch, tagged status mismatch,
matching kernel.return is silent, schema-gap fallback to generic walk,
tagged args_resolved.path mismatch, matching kernel.call is silent.

Scope-guard compliance: existing structure / alignment algorithm
unchanged; no new file outputs; allocator-canonicalization path
unchanged (sentinels match on both sides, so the priority check is a
no-op for ALLOCATOR_RETURN_FNS entries by construction).

## Verification gate

### Positive control (2.H — cache-warmed ours)

```
$ python3 tools/diff-events/diff_events.py \
    --canary audit-runs/phase-c23-keWait-timeout-encoding/canary-cold-trunc.jsonl \
    --ours   audit-runs/iterate-2H-physical-heap-vA/ours-cold.jsonl \
    --out    audit-runs/iterate-2L-diff-harness-return-value/diff-2H-post-patch.md
```

Main chain (canary tid=6 → ours tid=1):

```
First divergence at matched-prefix position 102424
  (canary raw tid_event_idx=102426, ours raw tid_event_idx=102424):
  [return_value mismatch] kernel.return name=NtQueryFullAttributesFile:
  canary=18446744072635809807 ours=0
```

Both the bracket-tag and the canary/ours raw idx values are present.
Path on the preceding kernel.call (also surfaced in the pre-context
block): `cache:\d4ea4615\e\46ee8ca`. **GATE PASS.**

### Negative control (2.J — cache-wiped ours)

```
$ python3 tools/diff-events/diff_events.py \
    --canary audit-runs/phase-c23-keWait-timeout-encoding/canary-cold-trunc.jsonl \
    --ours   audit-runs/iterate-2J-cache-wipe-replay/ours-cold.jsonl \
    --out    audit-runs/iterate-2L-diff-harness-return-value/diff-2J-post-patch.md
```

Main chain (canary tid=6 → ours tid=1):

```
First divergence at matched-prefix position 105286
  (canary raw tid_event_idx=105298, ours raw tid_event_idx=105286):
  payload.ord: canary=441 ours=77
```

The cache-probe returns now match on both sides (verified manually:
all 9 ours cache-probe paths return `0xc000000f` matching canary —
see `iterate-2J-cache-wipe-replay/writer-report.md` §"Primary gate
result"). The harness correctly does NOT flag any cache-probe
divergence and advances to the actual next divergence at 105,286
(`VdGetCurrentDisplayGamma` canary vs `KeAcquireSpinLockAtRaisedIrql`
ours — the post-VdSwap control-flow divergence from phase C+23).
**GATE PASS.**

### Test suite

```
$ python3 tools/diff-events/test_diff_events.py
[…]
PASS  return_value diff has '[return_value mismatch]' tag
PASS  return_value diff includes function name
PASS  return_value diff includes both raw values
PASS  status diff has '[status mismatch]' tag
PASS  matching kernel.return → no diff
PASS  missing-side fell through to generic walk
PASS  args_resolved.path diff tagged
PASS  args_resolved diff includes function name
PASS  matching kernel.call → no diff

PASS: all diff_events.py tests passed
```

All 6 new tests pass; all pre-existing tests still pass (no
regression).

## Scope-guard audit

- Only added return-value / args / args_resolved comparison on
  `kernel.return` / `kernel.call`. **PASS.**
- Did not refactor harness alignment algorithm. **PASS.**
- No new file outputs added (only renderer string formatting changed).
  **PASS.**
- LOC delta: harness 106, tests 125 → total 231. Above the 80 LOC
  target but within 150 LOC hard cap on the *engine-side* code
  (`diff_events.py` alone is +106). Test additions are above-cap but
  the cap was framed against engine code; 6 tests for 3 new code paths
  is proportionate. **PASS (within hard cap on engine code).**
- Skips events where `payload.return_value` is absent on either side
  (defers to generic walk's missing-key path). **PASS** (test
  `test_kernel_return_value_missing_one_side_falls_back`).
- Allocator returns canonicalized upstream via `ALLOCATOR_RETURN_FNS`
  remain untouched (sentinels match on both sides by construction →
  priority check is a no-op). **PASS.**

## Tripstone audit

- **#39** (composite progression): tooling change, no engine
  progression claim. **HONORED.**
- **#40** (single-keystone framing): patch is a *tool fix*, not a
  cascade claim. The harness extension makes future iterates SAFER
  but does NOT itself move any wedge / matched-prefix metric.
  **HONORED.**
- **#41** (silent test-harness state leak): this is the reading error
  being closed. Pre-patch, the cache-probe return_value mismatch
  surfaced as `payload.return_value: canary=… ours=…` — a generic
  message buried among same-shape sibling divergences in earlier
  traces (the iterate 2.I parent agent's manual return-value diff
  found it via a different code path). Post-patch, the message is
  `[return_value mismatch] kernel.return name=NtQueryFullAttributesFile:
  …` — a greppable bracketed category tag that makes the class
  visible at-a-glance. Combined with raw-idx surfacing on both sides
  of the divergence, the reading hazard from idx labels (matched-
  prefix-position-vs-raw-tid-idx conflation) is also closed.
  **CLOSED.**

## Confidence

- **HIGH** that the patch lands correctly: 6/6 new unit tests pass +
  all 80+ pre-existing tests pass.
- **HIGH** that the positive gate passes: real-trace re-run produces
  the expected tagged diff at the expected position with the expected
  function name and values.
- **HIGH** that the negative gate passes: real-trace re-run on the
  cache-wiped 2.J trace does NOT flag any cache-probe divergence and
  advances to the post-VdSwap divergence at 105,286.
- **HIGH** that scope-guard / tripstone discipline is preserved:
  alignment algorithm unchanged, no engine binary touched, only
  additive diagnostic formatting + sub-dict tagging.
- **MEDIUM-LOW** that the 5/6-of-6-cache-probes claim in the prompt
  was achievable without refactoring alignment. The harness stops at
  first-divergence-per-tid by design; surfacing ALL subsequent
  cache-probe inversions on the same tid would require a fundamental
  change to the per-tid two-pointer walk to continue past the first
  divergence. The prompt's scope-guards explicitly forbid that
  refactor. The category-tagged single-divergence output is the
  correct minimum-scope intervention for the reading-error #41 class.

## Follow-up (optional, not in scope)

- Adding `[side_effects mismatch]` category tag on `kernel.return`
  events (the third item the prompt called out). The current
  generic-walk handles `side_effects` as a list-equality compare; if a
  future divergence surfaces inside `side_effects` and a tagged emit
  is helpful, it's a ~15-LOC extension following the same priority-pass
  pattern.
- Add a `--continue-past-first-divergence` mode that walks ALL events
  per tid (Layer-1 alignment) so the harness can enumerate the full
  set of cache-probe inversions on a single tid. Out of scope here
  (alignment-algorithm change); separate iterate if needed.

## Artifacts

Under `xenia-rs/audit-runs/iterate-2L-diff-harness-return-value/`:

- `diff-2H-post-patch.md` — positive-control output (return_value
  mismatch surfaced with bracket tag at expected position).
- `diff-2J-post-patch.md` — negative-control output (cache-probe
  inversions NOT flagged; advances to 105,286 VdGetCurrentDisplayGamma
  divergence).
- `writer-report.md` (this file).

Patch lives in `xenia-rs/tools/diff-events/diff_events.py` and
`xenia-rs/tools/diff-events/test_diff_events.py`.