# Keyed user-command codec

Scope: RE-393–395 / F-154–156. Evidence: verified disassembly and file-backed mask bytes from both Linux ELF64 engines, recorded in [message-usercmd.json](message-usercmd.json). Reproduce with `python3 scripts/analyze_message_usercmd.py`; verify with `python3 scripts/test_message_usercmd.py`.

## CMD-001 — Timestamp dispatch and key derivation

`MSG_WriteDeltaUsercmdKey` subtracts baseline time from new time modulo 32 bits and compares the signed result with 255. Values at or below 255 emit a one-bit 1 followed by the low eight delta bits; greater values emit a one-bit 0 followed by the complete new 32-bit time. The reader adds an eight-bit delta to baseline time modulo 32 bits, or takes the full time. This is a signed comparison, not a verified requirement that deltas be nonnegative.

Synthetic -1 delta fixtures therefore decode baseline+255 rather than the supplied new timestamp. A wrap from 0xfffffffe to 1 produces delta 3 and recovers 1. These results describe instruction behavior; actual callers' monotonicity, reset and legal time ranges remain open.

After the timestamp, a one-bit aggregate flag controls the remaining fields. The writer derives the effective key from supplied key XOR **new** timestamp; the reader uses supplied key XOR **decoded** timestamp. Thus a synthetic short-time discrepancy can also change subsequent keyed fields. There are no calls to the scalar keyed-delta helpers in these graphs: field encoding is inlined through WriteBits/ReadBits.

Evidence anchors: writer entries dedicated `0x4422d2`, client `0x453c92`; signed delta comparisons `0x4422e9` / `0x453ca9`. Reader entries `0x44200c` / `0x4539cc`.

## CMD-002 — Record layout, flags and narrowing

The observed record spans 24 bytes. Semantic labels below are inferred user-command interpretations; offsets, sizes and wire order come directly from native loads/stores and child requests.

| Record offset | Stored bytes | Inferred field | Changed payload bits | Wire order after aggregate flag |
| --- | --- | --- | --- | --- |
| 0 | 4 | server time | 8-bit delta or full 32-bit time | Before aggregate flag |
| 4 | 4 | angle 0 | 16 | 1 |
| 8 | 4 | angle 1 | 16 | 2 |
| 12 | 4 | angle 2 | 16 | 3 |
| 21 | 1 | forward movement | 8 | 4 |
| 22 | 1 | right movement | 8 | 5 |
| 23 | 1 | up movement | 8 | 6 |
| 16 | 4 | buttons | 16 | 7 |
| 20 | 1 | weapon | 8 | 8 |

Aggregate equality compares the full word fields, the three movement bytes and the weapon byte. A word load at +20 clears its low byte through XORB to compare movement separately from weapon. Each field then has its own one-bit flag. Equality emits only 0 and copies the complete stored baseline field during reading. Changes emit 1 and the low width bits of new value XOR effective key. Movement bytes are sign-extended before XOR; weapon is zero-extended.

The reader uses actual `kbitmask[8]=0x1ff` and `kbitmask[16]=0x1ffff`, consistent with [keyed scalar findings](MESSAGE_DELTA_KEY.md). The word fields store a full 32-bit result, preserving the extra key bit at bit 16. Changed movement/weapon results store only a byte, discarding bit 8. None of these field paths index mask32; the full timestamp is read directly without the keyed mask. For matching decoded/new timestamps, changed word output is `(new & 0xffff) | (effective_key & 0x10000)`; changed bytes recover the supplied byte. This alone does not establish which high key bits are reachable during gameplay.

File-backed masks: dedicated addresses `0x6cf620` / `0x6cf640`, client `0x7a4680` / `0x7a46a0` for widths 8 / 16. Source identities, mask symbol and file offsets are in the report. If the aggregate flag is zero, the reader retains the decoded timestamp and copies all remaining 20 baseline bytes.

## CMD-003 — Bounded compressed compositions

Per engine, 102 streams cover deltas 0, 1, 255, 256 and -1; unchanged fields, each of eight individual field changes and all-field changes; keys 0 and 0x10100. Two additional wrap fixtures use keys 0 and 0xffffffff and start at bit 7. This is 204 streams total, using 18 verified graphs across the two images.

The script composes native usercmd, bit and Huffman instruction slices against relocated **MODEL-DERIVED** seeded trees. An independent test oracle builds the timestamp/aggregate/per-field requests, packs raw remainder bits and modeled codewords, and predicts the complete decoded record using separate writer/reader timestamp-derived keys. Checks cover exact bytes, final bit/size/readcount, unchanged source records, destination and buffer canaries, diagnostics and paired engine outcomes.

An unchanged command emits three requests (timestamp flag, timestamp payload, aggregate flag) and then adds seven directly to global `oldsize` (`0x44258a` / `0x453f4a`). A changed command emits eleven plus the number of changed fields. `oldsize` otherwise sums requested widths, rather than compressed lengths; XOR payloads and negative short deltas can increment the existing range diagnostic without setting message overflow in these ample-buffer fixtures.

The shared evaluator adds low-byte XORB support, preserving other register bytes and handling zero-flag dispatch. Its focused check exercises that instruction independently.

## Remaining work and compatibility limits

No original executable or native callee runs. PUSH/POP and stack save/restores are omitted; synthetic frames and explicit caller-register restoration compose stopped child boundaries. Training remains model-derived, not a complete native seed run. The fixtures use ample initialized buffers and disjoint records. They do not validate truncated/EOF/overflow packets, overlapping pointers, caller key provenance/time invariants, real multiplayer traffic, or other platforms.

RE-392 remains open for broader keyed callers. RE-396 must trace actual usercmd callers and key provenance, confirm field semantics against QVM/native consumers, recover packet bundling/baselines and entity/player/snapshot field tables, establish legal high-key/timestamp behavior, and compare runtime captures before Rust codec compatibility decisions. Bevy/Solari rendering and macOS/Linux game execution remain separate open milestones.

Follow-up: [usercmd callers](USERCMD_CALLERS.md) recovers bounded outer key derivation, count/opcode gates and zero/previous command chains. Producer/time legality, complete packet composition and runtime validation remain open.