> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase22-session06-persistence-lifecycle/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase22-session06-persistence-lifecycle` **Package**: apps/web **Started**: 2026-07-05 11:57 **Last Updated**: 2026-07-05 12:45

***

## Session Progress

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 18 / 18   |
| Estimated Remaining | 0 minutes |
| Blockers            | 0         |

***

### Task T018 - Validate ASCII and LF requirements

**Started**: 2026-07-05 12:38 **Completed**: 2026-07-05 12:40 **Duration**: 2 minutes

**Notes**:

* Validated ASCII encoding and LF line endings for the session artifacts and relevant changed files.

**Files Changed**:

* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T018 complete and completion checklist ready.

**Verification**:

* Command/check: `files=(.spec_system/specs/phase22-session06-persistence-lifecycle/spec.md .spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md .spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md apps/web/src/store/useGameStore.ts apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjectionStore.test.ts apps/web/tests/replayPersist.test.ts); file "${files[@]}"; LC_ALL=C grep -nP '[^\\x00-\\x7F]' "${files[@]}"; grep -n $'\\r' "${files[@]}"`
  * Result: PASS - all listed files are ASCII text with no CRLF matches.
  * Evidence: `file` reported ASCII text/JavaScript source; non-ASCII and CRLF checks returned no matches.
* UI product-surface check: N/A - encoding check only.
* UI craft check: N/A - no UI changes.

***

## Final Implementation Summary

**Completed**: 2026-07-05 12:40 **Tasks Completed**: 18 / 18 **Blockers**: None

**Summary**:

* Added guarded browser-local projection persistence scheduling to `useGameStore.ts`.
* Added 2 second idle debounce, 30 second max-latency flush, synchronous test flush, lifecycle flush handlers, and reset storage removal.
* Extended `gameProjectionStore.test.ts` with debounce, flush, max-latency, replay/mock guard, lifecycle, unavailable-storage, and reset storage coverage.
* Required focused tests, web typecheck, changed-file Biome, and ASCII/LF checks passed.

**BQC Fixes**:

* Resource cleanup: pending projection timers are cleared on flush and reset.
* Resource duplication prevention: lifecycle listeners install once through a global registry and proxy to the latest module flush callbacks.
* Duplicate action prevention: repeated schedules collapse to one latest pending projection while preserving max-latency flush.
* State freshness: `resetToSeed()` clears pending writes and removes persisted projection storage before committing fresh projection state.
* Failure path resilience: unavailable and throwing storage paths are covered without store/lifecycle flush throws.

***

### Task T017 - Run web typecheck and changed-file Biome check

**Started**: 2026-07-05 12:35 **Completed**: 2026-07-05 12:38 **Duration**: 3 minutes

**Notes**:

* Ran the required web package typecheck with Node 26.2.0.
* Ran the changed-file Biome check for the required store/helper/test files.
* Fixed one Biome line-wrap issue in `apps/web/tests/gameProjectionStore.test.ts` and reran the check successfully.

**Files Changed**:

* `apps/web/tests/gameProjectionStore.test.ts` - applied Biome-compliant line wrapping in the max-latency test.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T017 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm --workspace @factionos/web run typecheck`
  * Result: PASS - web TypeScript build check exited 0.
  * Evidence: `tsc -b --noEmit` completed successfully.
* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm exec -- biome check apps/web/src/store/useGameStore.ts apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjectionStore.test.ts apps/web/tests/replayPersist.test.ts`
  * Result: PASS - 4 files checked, no fixes applied.
  * Evidence: rerun passed after the line-wrap correction.
* UI product-surface check: N/A - verification command only.
* UI craft check: N/A - no UI changes.

***

### Task T016 - Run focused projection, reducer, and replay tests

**Started**: 2026-07-05 12:33 **Completed**: 2026-07-05 12:35 **Duration**: 2 minutes

**Notes**:

* Ran the required focused projection persistence, reducer, and replay persistence test command with Node 26.2.0.

**Files Changed**:

* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T016 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts apps/web/tests/gameProjection.test.ts apps/web/tests/replayPersist.test.ts`
  * Result: PASS - 3 test files passed.
  * Evidence: `gameProjectionStore.test.ts` 19 tests, `gameProjection.test.ts` 24 tests, `replayPersist.test.ts` 12 tests; total 55 passed.
* UI product-surface check: N/A - test command only.
* UI craft check: N/A - no UI changes.

***

### Task T015 - Update reset tests for projection storage removal

**Started**: 2026-07-05 12:31 **Completed**: 2026-07-05 12:33 **Duration**: 2 minutes

**Notes**:

* Updated the reset test expectation from Session 05's deferred storage behavior to Session 06 storage removal.
* Added coverage proving pending projection writes are cleared by reset and cannot be flushed afterward.

**Files Changed**:

* `apps/web/tests/gameProjectionStore.test.ts` - updated reset storage test and added pending-write reset test.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T015 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - 19 projection store tests passed.
  * Evidence: includes `resets in-memory projection and removes browser projection storage` and `clears pending projection writes during reset`.
* BQC check: PASS - state freshness and resource cleanup on reset covered by storage-removal and pending-write assertions.
* UI product-surface check: N/A - test-only non-UI coverage.
* UI craft check: N/A - no UI changes.

***

### Checkpoint 2 - Store and Test Coverage

**At**: 2026-07-05 12:33 **Tasks Completed**: 15 / 18 **Checks**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - 1 test file passed, 19 tests passed.
* Re-read spec objectives and success criteria; implemented scope remains browser-local projection persistence lifecycle only.
* Targeted inspection confirms no UI, protocol, server, hosted persistence, audio, or second projection authority was introduced.
* Next task: T016 run the full focused projection/reducer/replay test set.

***

### Task T014 - Add lifecycle and unavailable-storage tests

**Started**: 2026-07-05 12:29 **Completed**: 2026-07-05 12:31 **Duration**: 2 minutes

**Notes**:

* Added lifecycle flush coverage for hidden `visibilitychange`, `pagehide`, and `beforeunload`.
* Added visible `visibilitychange` coverage proving it does not flush pending writes.
* Added unavailable-storage and throwing-storage coverage proving explicit and lifecycle flush paths do not throw.

**Files Changed**:

* `apps/web/tests/gameProjectionStore.test.ts` - added lifecycle and storage failure tests.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T014 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - 19 projection store tests passed.
  * Evidence: includes lifecycle flush, visible no-flush, unavailable storage, and throwing storage cases.
* BQC check: PASS - resource cleanup and failure-path resilience covered at the public store seam.
* UI product-surface check: N/A - test-only non-UI coverage.
* UI craft check: N/A - no UI changes.

***

### Task T013 - Add replay and mock no-write tests

**Started**: 2026-07-05 12:27 **Completed**: 2026-07-05 12:29 **Duration**: 2 minutes

**Notes**:

* Added replay-mode coverage where in-memory projection changes but storage remains absent after explicit flush and timer advancement.
* Added mock-mode coverage where enemy projection state changes in memory but persistence remains guarded off.

**Files Changed**:

* `apps/web/tests/gameProjectionStore.test.ts` - added replay and mock persistence guard tests.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T013 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - 19 projection store tests passed.
  * Evidence: includes `does not persist changed projection state while replaying` and `does not persist changed projection state when mock mode is enabled`.
* BQC check: PASS - trust boundary and contract alignment stay delegated to replay/mock guard context.
* UI product-surface check: N/A - test-only non-UI coverage.
* UI craft check: N/A - no UI changes.

***

### Task T012 - Add max-latency burst flush tests

**Started**: 2026-07-05 12:25 **Completed**: 2026-07-05 12:27 **Duration**: 2 minutes

**Notes**:

* Added burst coverage that repeatedly re-arms the idle debounce just before expiry.
* Verified the first max-latency timer still flushes the latest pending projection at `GAME_PROJECTION_PERSIST_MAX_LATENCY_MS`.
* Corrected the test expectation to match fake-timer-driven reducer timestamps for the latest burst event.

**Files Changed**:

* `apps/web/tests/gameProjectionStore.test.ts` - added max-latency persistence test.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T012 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - 19 projection store tests passed.
  * Evidence: includes `flushes a burst by max latency even when idle debounce keeps resetting`.
* BQC check: PASS - scheduler concurrency behavior covered by repeated debounce reset plus max-latency write of latest projection.
* UI product-surface check: N/A - test-only non-UI coverage.
* UI craft check: N/A - no UI changes.

***

### Task T011 - Add debounce and synchronous flush tests

**Started**: 2026-07-05 12:19 **Completed**: 2026-07-05 12:25 **Duration**: 6 minutes

**Notes**:

* Added focused coverage proving changed projection state does not write immediately.
* Covered both explicit `__flushGameProjectionPersist()` and timer-driven flush after `GAME_PROJECTION_PERSIST_DEBOUNCE_MS`.
* Added a no-op event test proving unchanged projection references do not schedule projection persistence.

**Files Changed**:

* `apps/web/tests/gameProjectionStore.test.ts` - added projection persistence scheduling tests and helpers.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T011 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - 19 projection store tests passed.
  * Evidence: includes `persists changed projection state only after synchronous flush or debounce expiry` and `does not schedule persistence for projection no-op events`.
* BQC check: PASS - mutation safety covered by no immediate write and no-op no-schedule assertions.
* UI product-surface check: N/A - test-only non-UI coverage.
* UI craft check: N/A - no UI changes.

***

### Task T010 - Clear pending projection writes and remove storage on reset

**Started**: 2026-07-05 12:17 **Completed**: 2026-07-05 12:19 **Duration**: 2 minutes

**Notes**:

* Added `removePersistedGameProjection()` with disabled-storage tolerance.
* Updated `resetToSeed()` to clear pending projection persist state, remove `GAME_PROJECTION_STORAGE_KEY`, and then create a fresh in-memory projection.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added storage removal helper and reset integration.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T010 complete.

**Verification**:

* Command/check: `rg -n "removePersistedGameProjection|resetToSeed|GAME_PROJECTION_STORAGE_KEY|clearPendingGameProjectionPersist" apps/web/src/store/useGameStore.ts`
  * Result: PASS - reset path clears pending writes and removes the projection storage key.
  * Evidence: `resetToSeed()` calls `clearPendingGameProjectionPersist()` and `removePersistedGameProjection()` before setting `gameProjection: createInitialGameProjection()`.
* BQC check: PASS - state freshness on reset and resource cleanup are handled before new seed state is committed.
* UI product-surface check: N/A - store-only reset behavior.
* UI craft check: N/A - no UI changes.

***

### Task T009 - Preserve replay buffer, event switch, and selector behavior

**Started**: 2026-07-05 12:15 **Completed**: 2026-07-05 12:17 **Duration**: 2 minutes

**Notes**:

* Verified replay persistence tests still pass after projection scheduling was added.
* Verified existing projection store tests still cover selector behavior, one-event folding, replay capture avoidance, mock context, and reset memory under pre-T010 semantics.

**Files Changed**:

* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T009 complete.

**Verification**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm test -- apps/web/tests/gameProjectionStore.test.ts apps/web/tests/replayPersist.test.ts`
  * Result: PASS - 2 test files passed.
  * Evidence: `apps/web/tests/replayPersist.test.ts` 12 tests passed; `apps/web/tests/gameProjectionStore.test.ts` 9 tests passed; total 21 passed.
* BQC check: PASS - existing replay feedback-loop prevention and selector contracts remain covered by passing tests.
* UI product-surface check: N/A - non-UI store/test verification.
* UI craft check: N/A - no UI changes.

***

### Task T008 - Schedule projection persistence from guarded changed projection folds

**Started**: 2026-07-05 12:13 **Completed**: 2026-07-05 12:15 **Duration**: 2 minutes

**Notes**:

* Updated `applyEvent(e)` so projection persistence is considered only after `foldGameProjection()` returns a different projection reference.
* Delegated replay/mock persistence eligibility to `shouldPersistGameProjection(persistContext)`.
* Scheduled the changed projection after the Zustand state update, keeping the in-memory projection fold as the authoritative state transition.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added guarded projection scheduling from `applyEvent`.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T008 complete.

**Verification**:

* Command/check: `sed -n '2478,2495p' apps/web/src/store/useGameStore.ts`
  * Result: PASS - scheduling is gated by reference change and `shouldPersistGameProjection(persistContext)`.
  * Evidence: unchanged projections return the existing state; only a non-null `projectionToPersist` is passed to `scheduleGameProjectionPersist()`.
* BQC check: PASS - duplicate-trigger prevention is handled by scheduler collapse; trust boundary stays aligned with `gameProjection.ts` guard rules.
* UI product-surface check: N/A - store-only write scheduling.
* UI craft check: N/A - no UI changes.

***

### Task T007 - Add page lifecycle listener installation

**Started**: 2026-07-05 12:08 **Completed**: 2026-07-05 12:45 **Duration**: 37 minutes

**Notes**:

* Added an idempotent lifecycle installer backed by a global registry so module reloads keep one listener set while proxying to the latest flush callbacks.
* Hidden `visibilitychange` flushes only when `document.hidden` is true; `pagehide` and `beforeunload` always drain pending projection writes.
* Installer returns without side effects when `window` or `document` is unavailable.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added lifecycle handlers and module initialization call.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T007 complete.

**Verification**:

* Command/check: `rg -n "installGameProjectionPersistLifecycle|visibilitychange|pagehide|beforeunload|flushGameProjectionPersistWhenHidden" apps/web/src/store/useGameStore.ts`
  * Result: PASS - lifecycle installer and all required event hooks are present.
  * Evidence: installer checks browser globals before adding listeners and uses `__factionosGameProjectionPersistLifecycle` for reload-safe listener registration.
* BQC check: PASS - resource duplication risk addressed through idempotent registry-backed listener installation; unavailable globals no-op.
* UI product-surface check: N/A - store-only lifecycle behavior.
* UI craft check: N/A - no UI changes.

***

## Checkpoints

### Checkpoint 1 - Foundation Helpers

**At**: 2026-07-05 12:10 **Tasks Completed**: 7 / 18 **Checks**:

* Command/check: `source ~/.nvm/nvm.sh && nvm use 26.2.0 >/dev/null && npm exec -- biome check apps/web/src/store/useGameStore.ts`
  * Result: PASS - targeted Biome check passed after correcting reducer-context indentation.
* Targeted inspection confirms no UI, protocol, server, hosted persistence, or second projection authority was introduced.
* Re-read spec objectives and success criteria; current changes are limited to store persistence helper foundations.
* Next task: T008 schedule projection persistence from `applyEvent(e)` only when projection state changes and guard rules allow writes.

***

### Task T006 - Implement projection persistence flush helper

**Started**: 2026-07-05 12:07 **Completed**: 2026-07-05 12:08 **Duration**: 1 minute

**Notes**:

* Added `flushGameProjectionPersist()` to synchronously drain pending projection writes and clear both timers before writing.
* Exported `__flushGameProjectionPersist()` for tests, matching the existing replay flush helper pattern.
* Storage failure tolerance stays centralized in `persistGameProjection()`.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added projection flush helper and test-only flush export.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T006 complete.

**Verification**:

* Command/check: `sed -n '500,550p' apps/web/src/store/useGameStore.ts`
  * Result: PASS - flush clears pending state/timers and calls `persistGameProjection()` only when a pending projection exists.
  * Evidence: exported `__flushGameProjectionPersist()` delegates to the same flush path as scheduled timers.
* BQC check: PASS - resource cleanup covered by clearing idle and max-latency timers on every flush.
* UI product-surface check: N/A - store-only helper.
* UI craft check: N/A - no UI changes.

***

### Task T005 - Add projection persistence pending state and timers

**Started**: 2026-07-05 12:03 **Completed**: 2026-07-05 12:07 **Duration**: 4 minutes

**Notes**:

* Added module-local pending projection state, idle debounce timer, and max-latency timer.
* Added timer cleanup and scheduling support that keeps the latest changed projection while preserving one max-latency timer per burst.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added projection persistence pending state and timer helpers.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T005 complete.

**Verification**:

* Command/check: `rg -n "_gameProjectionPersist|_pendingGameProjection|scheduleGameProjectionPersist|GAME_PROJECTION_PERSIST" apps/web/src/store/useGameStore.ts`
  * Result: PASS - pending state, both timers, and scheduler helper are present.
  * Evidence: scheduler uses `GAME_PROJECTION_PERSIST_DEBOUNCE_MS` for idle re-arming and `GAME_PROJECTION_PERSIST_MAX_LATENCY_MS` only when no max-latency timer is active.
* BQC check: PASS - duplicate write triggers collapse to one latest pending projection while a burst is in flight.
* UI product-surface check: N/A - store-only persistence scheduler internals.
* UI craft check: N/A - no UI changes.

***

### Task T004 - Refactor projection fold helper to return projection and context

**Started**: 2026-07-05 12:00 **Completed**: 2026-07-05 12:03 **Duration**: 3 minutes

**Notes**:

* Added `FoldGameProjectionResult` so the store-local fold helper returns `nextProjection` plus the `GameProjectionPersistContext`.
* Derived `isReplaying` from `replayingSinceMs` and `mockEnabled` from `useSettingsStore`, preserving the existing reducer context source.
* Updated the existing `applyEvent` fold call to consume `nextProjection`; no persistence write behavior was introduced in this task.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - refactored projection fold helper and call site.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T004 complete.

**Verification**:

* Command/check: `sed -n '480,525p' apps/web/src/store/useGameStore.ts; sed -n '2472,2488p' apps/web/src/store/useGameStore.ts`
  * Result: PASS - helper returns `nextProjection` and `persistContext`; `applyEvent` consumes `nextProjection`.
  * Evidence: reducer context includes `now`, `isReplaying`, and `mockEnabled` from the same store/settings sources used before.
* BQC check: PASS - contract alignment preserved; no new write path, timers, or lifecycle resources added yet.
* UI product-surface check: N/A - store-only refactor.
* UI craft check: N/A - no UI changes.

***

### Task T003 - Add projection persistence imports

**Started**: 2026-07-05 11:59 **Completed**: 2026-07-05 12:00 **Duration**: 1 minute

**Notes**:

* Added the Phase 22 projection persistence key, debounce/max-latency constants, write helper, guard helper, and persistence context type to the store imports.
* No behavior changed in this task; imports are used by subsequent scheduler tasks.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added projection persistence imports.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T003 complete.

**Verification**:

* Command/check: `rg -n "GAME_PROJECTION_PERSIST|GAME_PROJECTION_STORAGE_KEY|persistGameProjection|shouldPersistGameProjection|GameProjectionPersistContext" apps/web/src/store/useGameStore.ts`
  * Result: PASS - import names are present in the store module.
  * Evidence: store imports now include persistence constants, write helper, guard helper, and context type from `gameProjection.ts`.
* UI product-surface check: N/A - import-only store change.
* UI craft check: N/A - no UI changes.

***

### Task T002 - Review existing replay persistence test patterns and teardown requirements

**Started**: 2026-07-05 11:58 **Completed**: 2026-07-05 11:59 **Duration**: 1 minute

**Notes**:

* Confirmed projection store tests use `vi.resetModules()`, `vi.doUnmock()`, fake timers, and `localStorage.clear()` to isolate module-local store state.
* Confirmed replay persistence tests expose the expected local pattern: schedule writes from `applyEvent`, verify storage remains empty before flush, and drain pending state with `__flushReplayPersist()`.

**Files Changed**:

* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T002 complete.

**Verification**:

* Command/check: `sed -n '1,360p' apps/web/tests/gameProjectionStore.test.ts`
  * Result: PASS - projection store tests have fresh import helpers, fake-clock setup, reducer-spy mocking, and cleanup hooks.
  * Evidence: `importFreshStoreModules()`, `importFreshStoreModulesWithReducerSpy()`, `useFixedClock()`, and `afterEach()` cover module/storage cleanup.
* Command/check: `sed -n '1,360p' apps/web/tests/replayPersist.test.ts`
  * Result: PASS - replay persistence tests demonstrate debounce, flush, no-write replay guard, and clear behavior.
  * Evidence: tests use `__flushReplayPersist()` after scheduled writes and in teardown.
* UI product-surface check: N/A - test-pattern review only.
* UI craft check: N/A - no UI changes.

***

### Task T001 - Verify Session 05 store integration artifacts and current projection helper exports

**Started**: 2026-07-05 11:57 **Completed**: 2026-07-05 11:58 **Duration**: 1 minute

**Notes**:

* Confirmed Session 05 validation passed and established the current store projection field, hydration, selectors, folding, and reset-memory seams.
* Confirmed `gameProjection.ts` already exports the storage key, cadence constants, reducer, persistence helper, and persistence guard needed by this session.

**Files Changed**:

* `.spec_system/specs/phase22-session06-persistence-lifecycle/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase22-session06-persistence-lifecycle/tasks.md` - marked T001 complete.

**Verification**:

* Command/check: `sed -n '1,260p' .spec_system/specs/phase22-session05-store-folding-and-selectors/validation.md`
  * Result: PASS - Session 05 validation result is PASS with 18/18 tasks complete.
  * Evidence: Validation names `apps/web/src/store/useGameStore.ts`, `apps/web/src/lib/gameProjection.ts`, and `apps/web/tests/gameProjectionStore.test.ts` as verified deliverables.
* Command/check: `sed -n '1,280p' apps/web/src/lib/gameProjection.ts`
  * Result: PASS - required projection constants and helpers are exported.
  * Evidence: exports include `GAME_PROJECTION_STORAGE_KEY`, `GAME_PROJECTION_PERSIST_DEBOUNCE_MS`, `GAME_PROJECTION_PERSIST_MAX_LATENCY_MS`, `persistGameProjection`, and `shouldPersistGameProjection`.
* UI product-surface check: N/A - store/helper inspection only.
* UI craft check: N/A - no UI changes.

***

## Task Log

### 2026-07-05 - Session Start

**Environment verified**:

* [x] Project state resolved to `phase22-session06-persistence-lifecycle`
* [x] Package context resolved to `apps/web`
* [x] Prerequisites confirmed with `.spec_system`, `jq`, `git`, npm workspace, and package manifest checks
* [x] Tools available with Node 26.2.0, npm 11.16.0, and Vitest 4.1.8 via nvm and local workspace binaries
* [x] Directory structure ready
* [x] Database requirements N/A

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase22-session06-persistence-lifecycle/implementation-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.