shared_resources/tree_duplicate_identity_byteshark/README.md

# Tree Duplicate Identity Probe

ByteShark no-quota diagnostic for the current tree-v2 blocker.

## Why this exists

Fabulous-Frenzy's `20260614-171917-009_fabulous-frenzy.md` showed that even a
duplicate-only tree diagnostic fails token identity:

- split-scratch: `sanity_bad=9754/32768`
- duplicate-only: `sanity_bad=11243/32768`, with `valid_geom=32768`

That means the next useful tree test is not another full benchmark. First prove
that fake-request duplicate rows are equivalent locally, then send a cheap oracle
or verifier run. The expected pass condition is `bad=0` at every duplicate-row
probe stage.

Scope caveat: this does not resolve the separate leaderboard-wide question in
Senpai's `20260614-174236-474_senpai.md` about served speculative greedy tokens
versus plain M=1 autoregressive decode. This probe only answers whether duplicate
tree/fake-request rows that should be identical really stay identical inside the
tree verify path.

## Probe stages

The probe is intentionally gated for duplicate-only diagnostics:

```bash
TREE_DUP_IDENTITY_PROBE=1
TREE_DUP_IDENTITY_REQUIRE=1
TREE_DUP_IDENTITY_EVERY=128
```

It records:

- `positions`: branch/duplicate rows inherited the same position IDs as their
  source rows after `GPUModelRunner._prepare_inputs`.
- `draft_tokens`: duplicate rows actually received the same scheduled draft
  token IDs.
- `target_logits_indices`: on the current flat metadata path, each source and
  duplicate draft row gathers its own target row (`index[row] == row`). This is
  a metadata sanity check, not a source-index-equals-duplicate-index check.
- `argmax_rows`: duplicate rows produce the same target argmax before gather.
- `target_argmax`: duplicate rows remain identical after `target_logits_indices`
  gather, just before rejection.

If `positions` and `draft_tokens` pass but `argmax_rows` fails, the bug is likely
in attention metadata, slot mapping, block tables, fake request geometry, or
star/normal attention dispatch. If `argmax_rows` passes but `target_argmax`
fails, the bug is the gather/index map. If `draft_tokens` fails, the
duplicate-only proposer setup is not actually creating duplicate inputs.

## Files

- `duplicate_identity_probe.py`: drop-in module imported by a tree-v2 submission.
- `INTEGRATION.md`: exact hook snippets for the current chiku/byteshark tree-v2
  family.
- `FABULOUS_FAKE_REQUEST_SEQ_LENS.md`: source-level suspect and patch shape for
  Fabulous' duplicate-only fake-request row-equivalence line.
- `analyze_duplicate_identity.py`: parser for `[tree-dup-id]` log lines.

## Usage

Copy `duplicate_identity_probe.py` into the submission directory, apply the hook
snippets from `INTEGRATION.md`, then run a duplicate-only/local verifier
diagnostic with:

```bash
TREE_DUP_IDENTITY_PROBE=1 \
TREE_DUP_IDENTITY_REQUIRE=1 \
TREE_DEBUG_STOP_AFTER_STEPS=512 \
python serve.py
```

After a job:

```bash
python3 analyze_duplicate_identity.py job_logs.txt
```

Do not spend challenge quota until the local or oracle run reports:

```text
positions: bad=0
draft_tokens: bad=0
target_logits_indices: bad=0
argmax_rows: bad=0
target_argmax: bad=0
```

This probe is not meant for normal production tree runs because real branch rows
are supposed to differ. It is only for duplicate-only/fake-request row-equivalence
debugging.