t2-demo-parser 2.1.0 → 3.0.0

package/dist/DemoParser.js

@@ -1,15 +1,31 @@
-import { inflate } from "fflate";
+import { inflate, Inflate } from "fflate";
 import createDebug from "debug";
 import { BitStream } from "./BitStream.js";
 import { PacketParser } from "./PacketParser.js";
-import { ClassRegistry } from "./ClassRegistry.js";
-import { GhostTracker, registerGhostParsers } from "./GhostManager.js";
-import { registerEventParsers } from "./EventParsers.js";
-import { registerDataBlockParsers } from "./DataBlockParsers.js";
-import { BlockTypePacket, BlockTypeSendPacket, BlockTypeMove, BlockTypeInfo, MaxTriggerKeys, NetEventClassBitSize, NetEventClassFirst, NetObjectClassBitSize, NetObjectClassFirst, GhostIdBitSize, DataBlockClassFirst, DataBlockClassNames, NetObjectClassNames, NetEventClassNames, SimDBEventObjectIdBits, SimDBEventClassIdBits, SimDBEventIndexBits, SimDBEventTotalBits, } from "./types.js";
+import { createDefaultRegistry } from "./defaultRegistry.js";
+import { GhostTracker } from "./GhostManager.js";
+import { BlockTypePacket, BlockTypeSendPacket, BlockTypeMove, BlockTypeInfo, DemoIdentString, DemoProtocolVersion, MaxTriggerKeys, NetEventClassBitSize, NetEventClassFirst, NetObjectClassBitSize, NetObjectClassFirst, GhostIdBitSize, DataBlockClassFirst, DataBlockClassNames, SimDBEventObjectIdBits, SimDBEventClassIdBits, SimDBEventIndexBits, SimDBEventTotalBits, } from "./types.js";
 const debug = createDebug("t2-demo-parser");
+/**
+ * Sequence numbers assigned to ordered events carried in the demo start
+ * block: past every 32-bit sequence, so they stay queued without ever
+ * matching `nextRecvEventSeq` (see setupPacketParser).
+ */
+const START_BLOCK_EVENT_SEQ_BASE = 0x1_0000_0000;
 const debugInitial = createDebug("t2-demo-parser:initial");
 const debugBlocks = createDebug("t2-demo-parser:blocks");
+/**
+ * Read a U32 count and reject it unless `minBitsPerEntry × count` bits
+ * remain: exhausted reads return 0 without throwing, so a corrupt count
+ * would otherwise spin allocating until memory ran out.
+ */
+function readCheckedCount(bs, minBitsPerEntry, what) {
+    const count = bs.readU32();
+    if (count > bs.getRemainingBits() / minBitsPerEntry) {
+        throw new Error(`Invalid ${what}: ${count}`);
+    }
+    return count;
+}
 export class DemoParser {
     buffer;
     view;
@@ -26,40 +42,36 @@ export class DemoParser {
     _blockStreamOffset = 0;
     _blockCount;
     _blockCursor = 0;
-    constructor(buffer) {
+    // Incremental mode: the compressed block stream arrives in chunks via
+    // push() and is inflated as it goes; nextBlock() treats the end of the
+    // decompressed data as a frontier (more may arrive) until finish().
+    _incremental;
+    _complete = true;
+    _inflator;
+    /** The zlib stream announced its own end (final deflate block seen) —
+     *  later bytes are trailing garbage and further pushes would throw. */
+    _streamEnded = false;
+    /** Backing store for the growing decompressed stream (incremental
+     *  mode). `_decompressedData` is always a length-exact subarray of
+     *  this, so every existing `.length`-based read stays correct. */
+    _backing;
+    _decompressedLength = 0;
+    // Buffered-time scan state (see bufferedMoveTicks).
+    _scanOffset = 0;
+    _bufferedMoveTicks = 0;
+    _ignoreProtocolVersion;
+    _haltOnFault;
+    constructor(buffer, options) {
         this.buffer = buffer;
         this.view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         this.offset = 0;
-        this.registry = new ClassRegistry();
+        this._incremental = options?.incremental === true;
+        this._ignoreProtocolVersion = options?.ignoreProtocolVersion === true;
+        this._haltOnFault = options?.haltOnFault;
+        // Parser catalogs bound to their deterministic classIds (derived from
+        // binary analysis of the Tribes 2 executable).
+        this.registry = createDefaultRegistry();
         this.ghostTracker = new GhostTracker();
-        // Register parser catalogs
-        registerEventParsers(this.registry);
-        registerGhostParsers(this.registry);
-        registerDataBlockParsers(this.registry);
-        // Bind DataBlock parsers deterministically using the known class name
-        // mapping derived from binary analysis of the Tribes 2 executable.
-        // ClassIds are assigned alphabetically (C strcmp) starting at
-        // DataBlockClassFirst (128).
-        const { bound: dbBound, missing: dbMissing } = this.registry.bindDeterministicDataBlocks(DataBlockClassNames, DataBlockClassFirst);
-        if (dbMissing.length > 0) {
-            debug("DataBlock binding: %d/%d bound, missing parsers: %s", dbBound, DataBlockClassNames.length, dbMissing.join(", "));
-        }
-        // Bind ghost (NetObject) parsers deterministically using the known
-        // class name mapping derived from binary analysis. The 53 NetObject
-        // classes are sorted alphabetically (C strcmp) and assigned sequential
-        // classIds starting at NetObjectClassFirst (0).
-        const { bound: ghostBound, missing: ghostMissing } = this.registry.bindDeterministicGhosts(NetObjectClassNames, NetObjectClassFirst);
-        if (ghostMissing.length > 0) {
-            debug("Ghost binding: %d/%d bound, missing parsers: %s", ghostBound, NetObjectClassNames.length, ghostMissing.join(", "));
-        }
-        // Bind event (NetEvent) parsers deterministically using the known
-        // class name mapping derived from binary analysis. The 26 NetEvent
-        // classes are sorted alphabetically (C strcmp) and assigned sequential
-        // classIds starting at NetEventClassFirst (255).
-        const { bound: eventBound, missing: eventMissing } = this.registry.bindDeterministicEvents(NetEventClassNames, NetEventClassFirst);
-        if (eventMissing.length > 0) {
-            debug("Event binding: %d/%d bound, missing parsers: %s", eventBound, NetEventClassNames.length, eventMissing.join(", "));
-        }
         this.packetParser = new PacketParser(this.registry, this.ghostTracker);
     }
     getRegistry() {
@@ -90,22 +102,35 @@ export class DemoParser {
             throw new Error("must call load() first");
         if (this._blockCount === undefined) {
             // Lazy scan: walk decompressed buffer counting U16 headers
-            const data = this._decompressedData;
-            const view = this._decompressedView;
             let count = 0;
-            let off = 0;
-            while (off + 2 <= data.length) {
-                const typeSize = view.getUint16(off, true);
-                const size = typeSize & 0xfff;
-                off += 2 + size;
-                if (off > data.length)
-                    break;
+            this._walkBlockHeaders(0, () => {
                 count++;
-            }
+            });
             this._blockCount = count;
         }
         return this._blockCount;
     }
+    /**
+     * Walk complete block headers from byte offset `from`, calling `visit`
+     * for each; returns the offset of the first incomplete block (or the
+     * end of the data).
+     */
+    _walkBlockHeaders(from, visit) {
+        const data = this._decompressedData;
+        const view = this._decompressedView;
+        if (!data || !view)
+            return from;
+        let off = from;
+        while (off + 2 <= data.length) {
+            const typeSize = view.getUint16(off, true);
+            const size = typeSize & 0xfff;
+            if (off + 2 + size > data.length)
+                break;
+            visit(typeSize >> 12, size);
+            off += 2 + size;
+        }
+        return off;
+    }
     get blockCursor() {
         if (!this._loaded)
             throw new Error("must call load() first");
@@ -129,23 +154,52 @@ export class DemoParser {
         // Phase 1: header + initial block
         const header = this.readHeader();
         debug('header: "%s" version=0x%s length=%dms (%smin) initialBlockSize=%d', header.identString, header.protocolVersion.toString(16), header.demoLengthMs, (header.demoLengthMs / 1000 / 60).toFixed(1), header.initialBlockSize);
+        if (this.buffer.length < this.offset + header.initialBlockSize) {
+            if (this._incremental) {
+                throw new RangeError(`incremental parser needs the full initial block up front: have ${this.buffer.length - this.offset} bytes, need ${header.initialBlockSize}`);
+            }
+            throw new RangeError(`truncated demo: initial block needs ${header.initialBlockSize} bytes, have ${this.buffer.length - this.offset}`);
+        }
         const initialBlockData = this.buffer.subarray(this.offset, this.offset + header.initialBlockSize);
         const initialBlock = this.readInitialBlock(initialBlockData);
         this.offset += header.initialBlockSize;
-        // Phase 2: async decompress block stream
-        const compressedData = this.buffer.subarray(this.offset);
-        debug("compressed block stream: %d bytes", compressedData.length);
-        const decompressedData = await new Promise((resolve, reject) => {
-            inflate(compressedData, (err, data) => {
-                if (err)
-                    reject(err);
-                else
-                    resolve(data);
+        if (this._incremental) {
+            // Phase 2 (incremental): streaming inflate. Compressed bytes
+            // arrive via push(); whatever tail the constructor buffer already
+            // holds past the initial block is the first chunk. fflate's
+            // Inflate emits decompressed output synchronously during push.
+            this._complete = false;
+            this._decompressedLength = 0;
+            this._backing = new Uint8Array(1 << 20);
+            this._decompressedData = this._backing.subarray(0, 0);
+            this._decompressedView = new DataView(this._backing.buffer, 0, 0);
+            this._inflator = new Inflate((chunk, final) => {
+                this._appendDecompressed(chunk);
+                if (final)
+                    this._streamEnded = true;
             });
-        });
-        debug("decompressed block stream: %d bytes", decompressedData.length);
-        this._decompressedData = decompressedData;
-        this._decompressedView = new DataView(decompressedData.buffer, decompressedData.byteOffset, decompressedData.byteLength);
+            const tail = this.buffer.subarray(this.offset);
+            // The prefix buffer has served its purpose (header + initial block
+            // are parsed); don't retain arbitrary compressed tail bytes twice.
+            if (tail.length > 0)
+                this._inflator.push(tail);
+        }
+        else {
+            // Phase 2: async decompress block stream
+            const compressedData = this.buffer.subarray(this.offset);
+            debug("compressed block stream: %d bytes", compressedData.length);
+            const decompressedData = await new Promise((resolve, reject) => {
+                inflate(compressedData, (err, data) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve(data);
+                });
+            });
+            debug("decompressed block stream: %d bytes", decompressedData.length);
+            this._decompressedData = decompressedData;
+            this._decompressedView = new DataView(decompressedData.buffer, decompressedData.byteOffset, decompressedData.byteLength);
+        }
         // Phase 3: set up PacketParser with seeded ghost tracker
         this.setupPacketParser(initialBlock);
         // Cache results
@@ -156,6 +210,143 @@ export class DemoParser {
         this._loaded = true;
         return { header, initialBlock };
     }
+    /**
+     * Parse just the fixed-size demo header from a byte prefix, without
+     * constructing a parser. Throws RangeError when `bytes` is too short —
+     * callers streaming a download retry as more data arrives. The
+     * returned `byteLength` is where the initial block begins; the block
+     * stream begins at `byteLength + header.initialBlockSize`.
+     */
+    static peekHeader(bytes) {
+        if (bytes.length < 1)
+            throw new RangeError("incomplete header");
+        const strLen = bytes[0];
+        const byteLength = 1 + strLen + 12;
+        if (bytes.length < byteLength)
+            throw new RangeError("incomplete header");
+        const identString = new TextDecoder("ascii").decode(bytes.subarray(1, 1 + strLen));
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        const protocolVersion = view.getUint32(1 + strLen, true);
+        const demoLengthMs = view.getUint32(1 + strLen + 4, true);
+        const initialBlockSize = view.getUint32(1 + strLen + 8, true);
+        return {
+            header: { identString, protocolVersion, demoLengthMs, initialBlockSize },
+            byteLength,
+        };
+    }
+    /**
+     * Incremental mode only: feed the next chunk of raw (compressed) block
+     * stream bytes as they arrive. Inflation happens synchronously; any
+     * blocks completed by this chunk become readable via nextBlock().
+     * The chunk is not retained.
+     */
+    push(chunk) {
+        if (!this._incremental)
+            throw new Error("not an incremental parser");
+        if (!this._loaded)
+            throw new Error("must call load() first");
+        if (this._complete)
+            throw new Error("already finished");
+        if (chunk.length === 0 || this._streamEnded)
+            return;
+        this._inflator.push(chunk);
+    }
+    /**
+     * Incremental mode only: signal that the download is complete. Flushes
+     * the inflator; after this, running out of blocks means the true end
+     * of the demo rather than the frontier.
+     */
+    finish() {
+        if (!this._incremental)
+            throw new Error("not an incremental parser");
+        if (!this._loaded)
+            throw new Error("must call load() first");
+        if (this._complete)
+            return;
+        if (!this._streamEnded) {
+            try {
+                this._inflator.push(new Uint8Array(0), true);
+            }
+            catch (err) {
+                // A truncated zlib stream: the blocks inflated so far remain
+                // valid (nextBlock bounds-checks the tail) — degrade to a
+                // shorter demo rather than failing the whole load.
+                debug("finish(): inflate flush failed: %o", err);
+            }
+        }
+        this._inflator = undefined;
+        this._complete = true;
+        // Trim: the doubling backing store can overshoot by up to 2× —
+        // release the slack now that the final length is known.
+        if (this._backing && this._backing.length > this._decompressedLength) {
+            const exact = this._backing.slice(0, this._decompressedLength);
+            this._backing = exact;
+            this._decompressedData = exact;
+            this._decompressedView = new DataView(exact.buffer, exact.byteOffset, exact.byteLength);
+        }
+    }
+    /**
+     * False only in incremental mode before finish(): nextBlock()
+     * returning undefined then means "frontier — more data may arrive",
+     * not the end of the demo.
+     */
+    get isComplete() {
+        return this._complete;
+    }
+    /**
+     * Bytes of decompressed block stream available so far. Grows during
+     * an incremental feed; consumers that latched an "out of blocks"
+     * state can compare against it to know new data has arrived.
+     */
+    get decompressedByteLength() {
+        return this._incremental
+            ? this._decompressedLength
+            : (this._decompressedData?.length ?? 0);
+    }
+    /**
+     * Move-tick blocks in the decompressed stream so far — each is one
+     * fixed 32ms simulation tick, so this measures buffered DEMO TIME
+     * exactly (compressed bytes don't: quiet stretches pack far denser).
+     * Independent of the read cursor; unaffected by reset(). Maintained
+     * incrementally as data arrives; a full lazy scan on first access
+     * covers the one-shot mode.
+     */
+    get bufferedMoveTicks() {
+        this._scanBufferedTicks();
+        return this._bufferedMoveTicks;
+    }
+    _scanBufferedTicks() {
+        let ticks = this._bufferedMoveTicks;
+        this._scanOffset = this._walkBlockHeaders(this._scanOffset, (type) => {
+            if (type === BlockTypeMove)
+                ticks++;
+        });
+        this._bufferedMoveTicks = ticks;
+    }
+    _appendDecompressed(chunk) {
+        if (chunk.length === 0)
+            return;
+        const needed = this._decompressedLength + chunk.length;
+        let backing = this._backing;
+        if (needed > backing.length) {
+            let capacity = backing.length;
+            while (capacity < needed)
+                capacity *= 2;
+            const grown = new Uint8Array(capacity);
+            grown.set(backing.subarray(0, this._decompressedLength));
+            backing = grown;
+            this._backing = grown;
+        }
+        backing.set(chunk, this._decompressedLength);
+        this._decompressedLength = needed;
+        // Refresh the exact-length views; subarray shares memory, so this is
+        // cheap and keeps every `.length`-based reader (nextBlock,
+        // blockCount) correct without touching them.
+        this._decompressedData = backing.subarray(0, needed);
+        this._decompressedView = new DataView(backing.buffer, 0, needed);
+        // The lazily-cached block count no longer covers the new bytes.
+        this._blockCount = undefined;
+    }
     /**
      * Read and parse the next block from the decompressed buffer.
      * Returns the parsed block, or undefined when all blocks are exhausted.
@@ -186,32 +377,26 @@ export class DemoParser {
             data: blockData,
         };
         this._blockCursor++;
-        if (type === BlockTypePacket) {
-            try {
+        // PacketParser reports problems through parseFault rather than
+        // throwing; anything that does escape is a parser bug, and the raw
+        // block plus the error text is kept for diagnosis.
+        try {
+            if (type === BlockTypePacket) {
                 block.parsed = this.packetParser.parsePacket(blockData);
             }
-            catch {
-                // Skip unparseable packets
+            else if (type === BlockTypeSendPacket) {
+                this.packetParser.onSendPacketTrigger();
             }
-        }
-        else if (type === BlockTypeSendPacket) {
-            this.packetParser.onSendPacketTrigger();
-        }
-        else if (type === BlockTypeMove && size === 64) {
-            try {
+            else if (type === BlockTypeMove && size === 64) {
                 block.parsed = this.readRawMove(blockData);
             }
-            catch {
-                // Skip unparseable moves
-            }
-        }
-        else if (type === BlockTypeInfo && size === 8) {
-            try {
+            else if (type === BlockTypeInfo && size === 8) {
                 block.parsed = this.readInfoBlock(blockData);
             }
-            catch {
-                // Skip unparseable info blocks
-            }
+        }
+        catch (e) {
+            block.parseError = e instanceof Error ? e.message : String(e);
+            debugBlocks("block %d (type %d, %d bytes) threw: %s", block.index, type, size, block.parseError);
         }
         return block;
     }
@@ -271,6 +456,20 @@ export class DemoParser {
             connectionProtocolState: initialBlock.connectionState,
             nextRecvEventSeq: initialBlock.nextRecvEventSeq,
             compressionPoint: initialBlock.initialCompressionPoint,
+            // NetConnection::eventReadStartBlock (FUN_00583ac0) appends the
+            // start block's in-flight ordered events to the wait queue without
+            // a sequence number (the field is never written; NetEvent's
+            // constructor leaves it uninitialized), so in the engine they can
+            // only ever dispatch by accident of heap contents. The deterministic
+            // stand-in keeps them queued behind every possible real sequence
+            // number, where they neither dispatch nor block dispatch.
+            pendingGuaranteedEvents: initialBlock.initialEvents
+                .filter((event) => !event.failed)
+                .map((event, i) => ({
+                absoluteSequenceNumber: START_BLOCK_EVENT_SEQ_BASE + i,
+                event,
+            })),
+            haltOnFault: this._haltOnFault,
         });
         this.ghostTracker = gt;
         this.packetParser = pp;
@@ -286,22 +485,25 @@ export class DemoParser {
             blocks.push(block);
         return { header, initialBlock, blocks };
     }
+    /**
+     * Read and validate the header the way GameConnection's demo playback
+     * does: the ident string must match and the protocol version must be
+     * the one this build speaks (unless `ignoreProtocolVersion` is set).
+     */
     readHeader() {
-        // Read the identification string: U8 length + string
-        const strLen = this.view.getUint8(this.offset);
-        this.offset += 1;
-        const identString = new TextDecoder("ascii").decode(this.buffer.subarray(this.offset, this.offset + strLen));
-        this.offset += strLen;
-        // U32 protocol version
-        const protocolVersion = this.view.getUint32(this.offset, true);
-        this.offset += 4;
-        // U32 demo length in ms
-        const demoLengthMs = this.view.getUint32(this.offset, true);
-        this.offset += 4;
-        // U32 initial block size
-        const initialBlockSize = this.view.getUint32(this.offset, true);
-        this.offset += 4;
-        return { identString, protocolVersion, demoLengthMs, initialBlockSize };
+        const { header, byteLength } = DemoParser.peekHeader(this.buffer.subarray(this.offset));
+        this.offset += byteLength;
+        if (header.identString !== DemoIdentString) {
+            throw new Error(`not a Tribes 2 recording: ident string ${JSON.stringify(header.identString)}`);
+        }
+        if (header.protocolVersion !== DemoProtocolVersion) {
+            const detail = `protocol version 0x${header.protocolVersion.toString(16)} (expected 0x${DemoProtocolVersion.toString(16)})`;
+            if (!this._ignoreProtocolVersion) {
+                throw new Error(`unsupported demo ${detail}; the game rejects it too. Pass { ignoreProtocolVersion: true } to try anyway.`);
+            }
+            debug("parsing demo with unexpected %s", detail);
+        }
+        return header;
     }
     /** Parse the initial block: DataBlocks, scores, targets, connection state,
      *  events, ghosts, control object, and mission name. */
@@ -365,7 +567,8 @@ export class DemoParser {
         for (let i = 0; i < 16; i++)
             stateArray.push(bs.readU32());
         // --- B.6 U32 score entry count ---
-        const scoreCount = bs.readU32();
+        // A score entry is at least 3 + 18 + 1 + 6 = 28 bits (FUN_00601800).
+        const scoreCount = readCheckedCount(bs, 28, "score entry count");
         // --- B.7 Score entries × count (FUN_00601800) ---
         const scoreEntries = [];
         for (let i = 0; i < scoreCount; i++) {
@@ -394,6 +597,22 @@ export class DemoParser {
         // The reader allocates notify nodes in memory but does not consume
         // per-notify records from the bitstream in this phase.
         const notifyCount = bs.readU32();
+        // Engine invariant (verified in build 25034): the start block carries
+        // one PacketNotify per in-flight packet, i.e. exactly
+        // lastSendSeq - highestAckedSeq of them. checkPacketSend
+        // (FUN_005877e0) refuses to queue a notify while windowFull
+        // (FUN_0043d720: lastSendSeq - highestAckedSeq > 0x1d), and
+        // handleNotify (FUN_005874d0) pops the queue head with no null check on
+        // every newly acked sequence, so a mismatched seed crashes playback on
+        // the first ack. Every Tribes2.exe recording satisfies this exactly.
+        const warnings = [];
+        const inFlight = (connectionState.lastSendSeq - connectionState.highestAckedSeq) >>> 0;
+        if (notifyCount !== inFlight) {
+            warnings.push(`notify count ${notifyCount} does not match in-flight packets ` +
+                `(lastSendSeq ${connectionState.lastSendSeq} - highestAckedSeq ` +
+                `${connectionState.highestAckedSeq} = ${inFlight}); Tribes2.exe ` +
+                `dereferences an empty notify queue on the first ack`);
+        }
         debugInitial("after notify count bit=%d notifyCount=%d", bs.getCurPos(), notifyCount);
         // --- B.10f through B.15: events, ghosts, control object, mission ---
         // Uses a temporary ghost tracker for initial-block ghost parsing only.
@@ -421,41 +640,50 @@ export class DemoParser {
             const ghostResult = this.readGhostStartBlock(bs, dataBlocks);
             ghostingSequence = ghostResult.ghostingSequence;
             initialGhosts = ghostResult.ghosts;
+            const lastInitialGhost = initialGhosts[initialGhosts.length - 1];
+            if (lastInitialGhost?.failed) {
+                // The engine sets "Invalid packet." here and drops the connection
+                // once the start block is done; the fields below are still read,
+                // misaligned, exactly as it reads them.
+                phase2Error ??= `initial ghost ${lastInitialGhost.index} (classId ${lastInitialGhost.classId}) failed: ${lastInitialGhost.error}`;
+            }
             debugInitial("after initial ghosts bit=%d count=%d seq=%d", bs.getCurPos(), initialGhosts.length, ghostingSequence);
             // B.11 controlObjectGhostIndex
             controlObjectGhostIndex = bs.readS32();
             debugInitial("after control ghost index bit=%d control=%d", bs.getCurPos(), controlObjectGhostIndex);
             // B.12 If != -1: controlObject readPacketData
             if (controlObjectGhostIndex !== -1) {
+                // The engine resolves the ghost and calls its readPacketData with
+                // no fallback; if we cannot, every later read in the initial
+                // block (mission name, CRC) would be misaligned, so fail phase 2.
                 const ghost = ibGhostTracker.getGhost(controlObjectGhostIndex);
-                if (ghost) {
-                    const parser = this.registry.getGhostParser(ghost.classId);
-                    if (parser?.readPacketData) {
-                        // getGhostParser enables the nested vehicle readPacketData
-                        // when the recorder was piloting at recording start — without
-                        // it those bytes go unread and every later read in the
-                        // initial block (mission name, CRC) is misaligned.
-                        const conn = {
-                            compressionPoint: { x: 0, y: 0, z: 0 },
-                            ghostTracker: ibGhostTracker,
-                            getGhostParser: (classId) => this.registry.getGhostParser(classId),
-                        };
-                        controlObjectData = parser.readPacketData(bs, conn);
-                        // The control object's readPacketData establishes the
-                        // connection's compression point (its position) — carry it
-                        // into the packet parser seed.
-                        initialCompressionPoint = conn.compressionPoint;
-                        debugInitial("after control readPacketData bit=%d parser=%s", bs.getCurPos(), parser.name);
-                    }
+                if (!ghost) {
+                    throw new Error(`control object ghost ${controlObjectGhostIndex} not found among initial ghosts`);
                 }
+                const parser = this.registry.getGhostParser(ghost.classId);
+                if (!parser?.readPacketData) {
+                    throw new Error(`control object ghost ${controlObjectGhostIndex} (${ghost.className}) has no readPacketData parser`);
+                }
+                // getGhostParser enables the nested vehicle readPacketData when
+                // the recorder was piloting at recording start.
+                const conn = {
+                    compressionPoint: { x: 0, y: 0, z: 0 },
+                    ghostTracker: ibGhostTracker,
+                    getGhostParser: (classId) => this.registry.getGhostParser(classId),
+                };
+                controlObjectData = parser.readPacketData(bs, conn);
+                // The control object's readPacketData establishes the
+                // connection's compression point (its position) — carry it
+                // into the packet parser seed.
+                initialCompressionPoint = conn.compressionPoint;
+                debugInitial("after control readPacketData bit=%d parser=%s", bs.getCurPos(), parser.name);
             }
             // B.13 $MissionName
             missionName = bs.readString();
             // B.14 mMissionCRC
             missionCRC = bs.readU32();
-            // Byte-align (validate) before SimpleTargetManagers
-            bs.setCurPos(((bs.getCurPos() + 7) >> 3) << 3);
-            // B.15 Simple TargetManager ×2
+            // B.15 Simple TargetManager ×2. FUN_006021b0 reads U8 + 4×U32 at the
+            // current bit position; the binary does not byte-align here.
             this.readSimpleTargetManager(bs);
             this.readSimpleTargetManager(bs);
             debugInitial('after sequential tail bit=%d mission="%s" CRC=0x%s', bs.getCurPos(), missionName, missionCRC.toString(16));
@@ -477,6 +705,9 @@ export class DemoParser {
             missionPrintableRatio >= 0.8 &&
             phase2Error === undefined;
         debug('initial block: events=%d ghosts=%d ghostingSeq=%d controlObj=%d mission="%s" CRC=0x%s valid=%s%s', initialEvents.length, initialGhosts.length, ghostingSequence, controlObjectGhostIndex, missionName, missionCRC.toString(16), phase2Valid, phase2Error ? ` error=${phase2Error}` : "");
+        for (const warning of warnings) {
+            debug("initial block warning: %s", warning);
+        }
         return {
             taggedStrings,
             dataBlockHeaders,
@@ -506,6 +737,7 @@ export class DemoParser {
             phase2TrailingBits: remaining,
             phase2Valid,
             phase2Error,
+            warnings,
         };
     }
     /**
@@ -639,10 +871,10 @@ export class DemoParser {
      */
     readPathManager(bs) {
         const entries = [];
-        const entryCount = bs.readU32();
+        const entryCount = readCheckedCount(bs, 64, "PathManager entry count");
         for (let i = 0; i < entryCount; i++) {
             const entryId = bs.readU32();
-            const recordCount = bs.readU32();
+            const recordCount = readCheckedCount(bs, 128, "PathManager record count");
             const records = [];
             for (let j = 0; j < recordCount; j++) {
                 records.push({
@@ -747,10 +979,9 @@ export class DemoParser {
         const ghostingSequence = bs.readU32();
         const ghosts = [];
         debugInitial("ghost block: seq=%d bit=%d", ghostingSequence, bs.getCurPos());
-        const ghostCatalog = this.registry.getGhostCatalog();
         const totalBits = bs.getBuffer().length * 8;
-        // Build DataBlock data lookup for ghost parsers that need it
-        // (e.g., WheeledVehicle needs shape name to determine wheel count).
+        // DataBlock data lookup for ghost parsers that resolve datablock
+        // fields during unpack.
         const dataBlockDataMap = new Map();
         for (const [objectId, db] of dataBlocks) {
             dataBlockDataMap.set(objectId, db.data);
@@ -761,154 +992,66 @@ export class DemoParser {
             const index = bs.readInt(GhostIdBitSize);
             const classId = bs.readInt(NetObjectClassBitSize) + NetObjectClassFirst;
             const updateBitsStart = bs.getCurPos();
-            // Build ordered list of parser candidates.
-            // Registry binding (from deterministic classId) is preferred over
-            // DataBlock-based identification because the classId is authoritative
-            // while the DataBlock type may be a base class (e.g., StaticShapeData
-            // used by a BeaconObject, which extends StaticShape with extra fields).
-            const candidates = [];
-            const seen = new Set();
-            // Peek at DataBlock flag to identify ghost via DataBlock type
-            const { entry: dbEntry } = this.identifyGhostViaDataBlock(bs, dataBlocks, ghostCatalog);
-            // Candidate 1: registry binding (deterministic classId)
-            const regEntry = this.registry.getGhostParser(classId);
-            if (regEntry) {
-                candidates.push({ entry: regEntry, method: "registry" });
-                seen.add(regEntry);
-            }
-            // Candidate 2: DataBlock-based identification (fallback)
-            if (dbEntry && !seen.has(dbEntry)) {
-                candidates.push({ entry: dbEntry, method: "datablock" });
-                seen.add(dbEntry);
+            // NetConnection::ghostReadStartBlock (FUN_00585220): create the
+            // object from the class id, call its unpackUpdate, register it.
+            // An unknown class id or a failed registration is "Invalid packet."
+            // — the engine stops reading ghosts and the connection is dead.
+            // There is no second candidate and no plausibility check.
+            const entry = this.registry.getGhostParser(classId);
+            if (!entry) {
+                debugInitial("  ghost idx=%d classId=%d NO CLASS (stopping at bit=%d)", index, classId, updateBitsStart);
+                ghosts.push({
+                    index,
+                    type: "create",
+                    classId,
+                    updateBitsStart,
+                    updateBitsEnd: updateBitsStart,
+                    failed: true,
+                    error: `no ghost class bound to classId ${classId}`,
+                });
+                break;
             }
-            // Try each candidate with alignment validation
-            const connOverrides = {
-                getDataBlockData: (objectId) => dataBlockDataMap.get(objectId),
-                getDataBlockParser: (cid) => this.registry.getDataBlockParser(cid),
-            };
-            let parsed = false;
-            for (const { entry, method } of candidates) {
-                const isTrusted = method === "registry";
-                const result = this.tryGhostParser(bs, entry, updateBitsStart, totalBits, false, connOverrides, isTrusted);
-                if (result !== false) {
-                    this.ghostTracker.createGhost(index, classId, entry.name);
-                    debugInitial("  ghost idx=%d classId=%d parser=%s bits=%d via=%s", index, classId, entry.name, bs.getCurPos() - updateBitsStart, method);
-                    ghosts.push({
-                        index,
-                        type: "create",
-                        classId,
-                        updateBitsStart,
-                        updateBitsEnd: bs.getCurPos(),
-                        parsedData: result,
-                    });
-                    parsed = true;
-                    break;
+            let parsedData;
+            try {
+                parsedData =
+                    entry.unpackUpdate(bs, true, {
+                        compressionPoint: { x: 0, y: 0, z: 0 },
+                        ghostTracker: this.ghostTracker,
+                        getDataBlockData: (objectId) => dataBlockDataMap.get(objectId),
+                        getDataBlockParser: (cid) => this.registry.getDataBlockParser(cid),
+                    }) ?? {};
+                if (bs.isError()) {
+                    throw new Error("ran past the end of the initial block");
                 }
             }
-            if (parsed)
-                continue;
-            // No candidate worked — stop parsing ghosts
-            debugInitial("  ghost idx=%d classId=%d NO PARSER (stopping at bit=%d, remaining=%d)", index, classId, updateBitsStart, totalBits - updateBitsStart);
-            break;
+            catch (e) {
+                const error = `${entry.name}: ${e instanceof Error ? e.message : String(e)}`;
+                debugInitial("  ghost idx=%d classId=%d parser=%s FAILED at bit=%d: %s", index, classId, entry.name, bs.getCurPos(), error);
+                ghosts.push({
+                    index,
+                    type: "create",
+                    classId,
+                    updateBitsStart,
+                    updateBitsEnd: bs.getCurPos(),
+                    failed: true,
+                    error,
+                });
+                break;
+            }
+            this.ghostTracker.createGhost(index, classId, entry.name);
+            debugInitial("  ghost idx=%d classId=%d parser=%s bits=%d", index, classId, entry.name, bs.getCurPos() - updateBitsStart);
+            ghosts.push({
+                index,
+                type: "create",
+                classId,
+                updateBitsStart,
+                updateBitsEnd: bs.getCurPos(),
+                parsedData,
+            });
         }
         debugInitial("ghost loop ended at bit=%d remaining=%d count=%d", bs.getCurPos(), totalBits - bs.getCurPos(), ghosts.length);
         return { ghostingSequence, ghosts };
     }
-    /**
-     * Try parsing a ghost with a given parser and validate alignment.
-     * Returns true if parsing succeeded and alignment is valid.
-     * On success, the BitStream is positioned after the parsed ghost data.
-     * On failure, the BitStream is restored to updateBitsStart.
-     */
-    tryGhostParser(bs, entry, updateBitsStart, totalBits, silent = false, connOverrides, trusted = false) {
-        const savedPos = bs.savePos();
-        if (!silent) {
-            debugInitial("    try %s: startBit=%d", entry.name, updateBitsStart);
-        }
-        try {
-            const parsedData = entry.unpackUpdate(bs, true, {
-                compressionPoint: { x: 0, y: 0, z: 0 },
-                ghostTracker: this.ghostTracker,
-                ...connOverrides,
-            });
-            const bitsConsumed = bs.getCurPos() - updateBitsStart;
-            const remaining = totalBits - bs.getCurPos();
-            if (bs.isError() || (!trusted && bitsConsumed < 3)) {
-                if (!silent) {
-                    debugInitial("    reject %s: bits=%d isError=%s", entry.name, bitsConsumed, bs.isError());
-                }
-                bs.restorePos(savedPos);
-                return false;
-            }
-            // Validate alignment: if substantial data remains, the next
-            // continuation flag must be 1 (more ghosts in the snapshot).
-            if (remaining > 1000) {
-                const peekPos = bs.getCurPos();
-                const nextFlag = bs.readFlag();
-                bs.setCurPos(peekPos);
-                if (!nextFlag) {
-                    if (!silent) {
-                        debugInitial("    reject %s: bits=%d misaligned (remaining=%d)", entry.name, bitsConsumed, remaining);
-                    }
-                    bs.restorePos(savedPos);
-                    return false;
-                }
-            }
-            return parsedData ?? {};
-        }
-        catch (e) {
-            if (!silent) {
-                debugInitial("    reject %s: error at bit=%d: %s", entry.name, bs.getCurPos(), e instanceof Error ? e.message : String(e));
-            }
-            bs.restorePos(savedPos);
-            return false;
-        }
-    }
-    /**
-     * Peek at the GameBase DataBlock prefix to identify a ghost's parser.
-     * GameBase subclass ghost creates always start with:
-     *   flag(1b) + if flag: DataBlockId(11b)
-     * The DataBlock type (e.g., "PlayerData") maps to the ghost parser
-     * (e.g., "Player") by stripping the "Data" suffix.
-     *
-     * Returns { entry, dbFlag } where entry is the parser (if found) and
-     * dbFlag indicates whether the first bit was 1 (DataBlock flag set).
-     * In the initial block (mask=0xFFFFFFFF), dbFlag=false means the ghost
-     * is definitely NOT a GameBase subclass.
-     * The BitStream position is always restored after peeking.
-     */
-    identifyGhostViaDataBlock(bs, dataBlocks, ghostCatalog) {
-        if (!dataBlocks)
-            return { entry: undefined, dbFlag: false };
-        const savedPos = bs.savePos();
-        let entry;
-        let dbFlag = false;
-        try {
-            dbFlag = bs.readFlag();
-            if (dbFlag) {
-                const dbId = bs.readInt(11);
-                const db = dataBlocks.get(dbId);
-                if (db) {
-                    const ghostName = db.className.replace(/Data$/, "");
-                    entry = ghostCatalog.get(ghostName);
-                    if (!entry) {
-                        debugInitial("    identifyGhostViaDataBlock: dbId=%d className=%s ghostName=%s (no ghost parser)", dbId, db.className, ghostName);
-                    }
-                }
-                else {
-                    debugInitial("    identifyGhostViaDataBlock: dbId=%d (no DataBlock found)", dbId);
-                }
-            }
-            else {
-                debugInitial("    identifyGhostViaDataBlock: DataBlock flag=0");
-            }
-        }
-        catch {
-            // Ignore errors during peek
-        }
-        bs.restorePos(savedPos);
-        return { entry, dbFlag };
-    }
     /**
      * Parse a raw 64-byte Move struct from a type 2 block.
      *
@@ -970,8 +1113,10 @@ export class DemoParser {
     readInfoBlock(data) {
         const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
         return {
-            value1: dv.getUint32(0, true),
-            value2: dv.getFloat32(4, true),
+            // GameConnection::handleRecordedBlock (FUN_005fb170) case 3 reads
+            // only byte 0 as firstPerson and the F32 at +4 as the camera FOV.
+            firstPerson: data[0] !== 0,
+            cameraFov: dv.getFloat32(4, true),
         };
     }
 }