{"record":{"id":"a41303101923b517","repo":"Hmbown/CodeWhale","slug":"the-recording-segment-is-missing-its-starting-checkpoint","errorCode":null,"errorMessage":"The recording segment is missing its starting checkpoint.","messagePattern":"The recording segment is missing its starting checkpoint\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tui/pet_watch/pet-native.js","lineNumber":260,"sourceCode":"            ...(this.origin ? { start: { ...structuredClone(this.origin), hasTelemetry: this.hasTelemetry, history } } : {}),\n            ...(withCheckpoint ? { checkpoint: { ...this.checkpoint(), history } } : {}) };\n    }\n    static fromRecording(points, value) {\n        const r = value;\n        if (!r || ![1, 2].includes(r.petReplayVersion) || !Array.isArray(r.tape) || !Array.isArray(r.interactions))\n            throw new Error('Invalid pet recording.');\n        const version = r.expressionVersion === undefined ? 1 : r.expressionVersion;\n        if (![1, 2].includes(version))\n            throw new Error('Unsupported pet expression version.');\n        if (r.checkpoint !== undefined && !r.checkpoint || r.start !== undefined && !r.start)\n            throw new Error('Invalid pet checkpoint.');\n        for (const c of [r.start, r.checkpoint])\n            if (c && (c.sim?.expressionVersion ?? 1) !== version)\n                throw new Error('Pet expression version does not match its checkpoint.');\n        if (r.petReplayVersion === 1 && (r.start || r.checkpoint && r.checkpoint.petCheckpointVersion !== 1))\n            throw new Error('Invalid legacy pet recording.');\n        if (r.petReplayVersion === 2 && (!r.start || r.start.petCheckpointVersion !== 2 || r.start.historyStart !== r.start.tick))\n            throw new Error('The recording segment is missing its starting checkpoint.');\n        const first = r.start && PetWorld.restore(points, r.tape, r.interactions, r.start);\n        const world = r.checkpoint ? PetWorld.restore(points, r.tape, r.interactions, r.checkpoint) : first ?? new PetWorld(points, r.tape, r.interactions, version);\n        if (first) {\n            if (!world.segmented || world.tick < first.tick || r.checkpoint && r.checkpoint.historyStart !== first.tick)\n                throw new Error('Pet segment checkpoints do not agree.');\n            world.origin = first.checkpoint();\n        }\n        return world;\n    }\n    /** Retire only consumed input. The exact origin makes each archived segment\n     * independently replayable; no particle, random stream or score is reset. */\n    prepareSegment() {\n        const dropTape = Math.max(0, this.bucketIndex), dropInputs = this.interactionIndex, previous = this.origin;\n        const tape = this.tapeLog.slice(dropTape), interactions = this.interactionLog.slice(dropInputs);\n        const points = this.sim.p.map(p => [p.hx, p.hy]);\n        const c = this.checkpoint();\n        c.petCheckpointVersion = 2;\n        c.historyStart = this.tick;","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tui/pet_watch/pet-native.js#L242-L278","documentation":"Version 2 recordings are segmented: they must include a start checkpoint with petCheckpointVersion 2 whose historyStart equals its tick, proving the segment records where its replay history begins. A v2 recording missing start, with a wrong checkpoint version, or with a start whose historyStart does not match its tick cannot be replayed from its origin and is rejected.","triggerScenarios":"Calling `PetWorld.fromRecording(points, r)` with r.petReplayVersion === 2 where r.start is absent, r.start.petCheckpointVersion is not 2, or r.start.historyStart !== r.start.tick.","commonSituations":"Truncating or trimming a segment file and dropping its start checkpoint; a producer bug failing to stamp petCheckpointVersion or historyStart; hand-editing ticks without updating historyStart.","solutions":["Restore the missing/malformed start checkpoint from the archive or producer that created the segment.","Ensure start.petCheckpointVersion === 2 and start.historyStart === start.tick before restoring.","Re-export the segment via prepareSegment()/recording() from a live world.","If the recording is truly unsegmented, export it with petReplayVersion 1 instead."],"exampleFix":"// before\n{ petReplayVersion: 2, start: { petCheckpointVersion: 2, tick: 120, historyStart: 0, ... } } // historyStart mismatch\n// after\n{ petReplayVersion: 2, start: { petCheckpointVersion: 2, tick: 120, historyStart: 120, ... } }","handlingStrategy":"validation","validationCode":"if (r.petReplayVersion === 2) {\n  if (!r.start || r.start.petCheckpointVersion !== 2 || r.start.historyStart !== r.start.tick)\n    throw new Error('Segment lacks a valid v2 start checkpoint');\n}","typeGuard":"const hasV2Start = (r) =>\n  r.petReplayVersion !== 2 || (!!r.start &&\n    r.start.petCheckpointVersion === 2 &&\n    r.start.historyStart === r.start.tick);","tryCatchPattern":"try {\n  world = PetWorld.fromRecording(points, r);\n} catch (err) {\n  if (err.message === 'The recording segment is missing its starting checkpoint.')\n    throw new Error('Segment file truncated: start checkpoint missing.');\n  throw err;\n}","preventionTips":["Never trim or truncate a v2 segment ahead of its start checkpoint.","Verify start.petCheckpointVersion === 2 and historyStart === tick after export.","Keep segments and their archives together so the start can be recovered.","Use unsegmented (v1) export when the recording starts at tick 0."],"tags":["replay","checkpoint","deserialization"],"backgroundTag":"missing-required-argument","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-22T16:17:23.217Z"}