> 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/phases/phase_22/session_06_persistence_lifecycle.md).

# Session 06: Persistence Lifecycle

**Session ID**: `phase22-session06-persistence-lifecycle` **Package**: apps/web **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add debounced local projection persistence, lifecycle flushing, replay/mock write guards, and storage-clearing reset behavior.

***

## Scope

### In Scope (MVP)

* Mirror the replay-buffer debounce posture for projection persistence: 2s idle debounce, 30s max-latency flush, and an explicit synchronous test flush helper.
* Schedule projection persistence only when store folding changes projection state and `shouldPersistGameProjection(ctx)` allows a write.
* Add page lifecycle flushing for hidden `visibilitychange`, `pagehide`, and `beforeunload`.
* Ensure persistence is skipped when replaying or when `mockEnabled` is true.
* Ensure `resetToSeed()` resets the projection and removes `localStorage["factionos-game-v1"]`.
* Add focused persistence tests for debounce/flush behavior, replay/mock no-write behavior, page lifecycle flush behavior, unavailable storage handling, and reset storage removal.

### Out of Scope

* Follow the explicit out-of-scope and deferred-work boundaries in the Dependencies / Notes section below.
* Do not add rendering, audio, hosted persistence, protocol changes, or a second game state authority unless this session explicitly lists that work as in scope.

***

## Dependencies / Notes

* Depends on Session 05.
* Storage helpers stay in `gameProjection.ts`; scheduling and browser lifecycle ownership stay in `useGameStore.ts`.
* Because `mockEnabled` may default true in development settings, tests that expect writes should explicitly set it false.
* Out of scope: browser-local erasure inventory, hosted persistence, cross-device sync, rendering, and new protocol events.

***

## Prerequisites

* [ ] Session 05 completed and validated.

***

## Deliverables

1. Store-level projection persistence cadence and lifecycle flushing.
2. A synchronous test flush seam equivalent to the existing replay persistence flush posture.

***

## Success Criteria

* [ ] `localStorage["factionos-game-v1"]` is written only through the projection persistence path and only when replay/mock guards allow it.
* [ ] Page lifecycle flushes drain the pending projection write without throwing when storage or document APIs are unavailable.
* [ ] `resetToSeed()` leaves a fresh initial projection in memory and removes the persisted projection key.
* [ ] Persistence tests can flush pending writes synchronously without relying on wall-clock delays.


---

# 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/phases/phase_22/session_06_persistence_lifecycle.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.