> 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-session08-erasure-docs-and-validation/spec.md). # Session Specification **Session ID**: `phase22-session08-erasure-docs-and-validation` **Phase**: 22 - Projection Foundation **Status**: Not Started **Created**: 2026-07-05 **Base Commit**: `985c8b8bf77b58248b6c32037254c0fd99b0ec12` **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session closes Phase 22 by adding the projection persistence key to browser-local erasure coverage and proving both browser erasure and `resetToSeed()` clear `localStorage["factionos-game-v1"]`. Sessions 01-07 already established the projection contract, reducer slices, store folding, persistence lifecycle, and replay/mock honesty guards; the remaining implementation work is the browser erasure inventory, targeted docs reconciliation, and final validation. It is next because the analyzer reports Phase 22 has 7 of 8 sessions complete, Session 07 validation passed, and the only unfinished candidate is Session 08. The session keeps Phase 22's foundation boundary intact: no new battlefield rendering, no audio or ceremony, no protocol events, no hosted persistence, and no second game state authority. The docs pass should reconcile source-backed implementation choices that became concrete during Sessions 01-07: `suggestion_update` is an explicit projection snapshot no-op for camps in Phase 22, legacy permissions plus guarded-action and Command Center permissions share one projection gate attention authority, pending flare/gate refs persist through the `attention` aggregate, and camp links remain dormant unless a caller supplies real `campId`, `heroId`, and verbatim `prompt`. *** ## 2. Objectives 1. Add `factionos-game-v1` to browser-local erasure cleanup under the existing browser storage boundary without creating a new protocol boundary. 2. Extend tests so browser erasure preview/confirmation and store reset prove projection storage is removed without exposing raw storage values. 3. Reconcile Phase 22 game-design docs and change logs only where the implemented projection choices differ from older design text. 4. Run and record the Phase 22 closeout validation commands, broadening store tests where touched files warrant it. *** ## 3. Prerequisites ### Required Sessions * [x] `phase22-session07-honesty-regression-tests` - Provides replay, reconnect, mock-mode, serialization, and store-level honesty regressions for the projection. ### Required Tools Or Knowledge * Node 26.2.0 and npm 11.16.0, using the project-supported runner when the ambient shell differs. * Vitest, TypeScript `tsc`, and Biome through npm workspace scripts. * Existing browser erasure protocol boundaries in `packages/protocol/src/erasure.ts`. * Existing projection storage helpers in `apps/web/src/lib/gameProjection.ts`. ### Environment Requirements * Local browser storage behavior from the Vitest happy-dom test environment. * No database, migration, hosted-service credential, Cloudflare credential, Worker deploy, audio asset, or browser automation dependency applies. *** ## 4. Scope ### In Scope (MVP) * Browser-local erasure must clear `GAME_PROJECTION_STORAGE_KEY` through the existing erasure cleanup inventory - implement by extending `apps/web/src/lib/localErasure.ts`. * Tests must prove erasure preview counts the projection key, erasure confirmation removes it, raw projection storage values stay out of summaries, and `resetToSeed()` removes the same key - implement in `apps/web/tests/localErasure.test.ts` and reuse existing store reset coverage when possible. * Game-design docs must describe the actual Phase 22 implementation choices for `suggestion_update`, Command Center gates, persisted attention refs, camp-link dormancy, local erasure, and no-claim boundaries - update `docs/game-design/10-technical-design-and-game-projection.md`, `docs/game-design/11-open-questions-and-change-log.md`, and `docs/game-design/14-implemented-phases.md` where needed. * Closeout notes must capture validation commands, any broadened test coverage, and the remaining trusted-unified-erasure no-claim - record in this session's implementation notes. ### Out Of Scope (Deferred) * New battlefield rendering, camp buttons, Quest Board filtering, effects, SFX, barks, animation, XP/level UI, Battle Report reskin, War Council UI, Dawn Report composer, hosted/cross-device persistence, and new protocol events - Reason: Phase 22 is projection foundation only. * New erasure protocol boundary ids or trusted unified erasure claims - Reason: the Phase 22 scope is browser-local cleanup for one derived projection key, while cumulative trusted erasure remains no-claim. * Codebase issue accept-as-camp mission flow - Reason: current Quest Board codebase issue cards can dismiss, not launch real camp missions with `campId`, `heroId`, and verbatim `prompt`. * Server, CLI, hook, War Room, public website, database, or package-protocol behavior changes - Reason: Session 08 is an `apps/web` closeout and validation slice. *** ## 5. Technical Approach ### Architecture Extend the existing browser-local erasure inventory instead of adding a new protocol boundary. `packages/protocol/src/erasure.ts` already owns browser boundary ids, and the Session 08 stub explicitly says not to invent a web-only erasure boundary. The projection key is browser-local, derived, aggregate storage, so it should be removed by the current web erasure plan alongside other browser-owned durable app state. Use `GAME_PROJECTION_STORAGE_KEY` from `apps/web/src/lib/gameProjection.ts` so erasure and persistence stay bound to one constant. Tests should seed a raw projection value, assert preview and confirmation summaries do not leak it, assert confirmation removes it, and keep duplicate idempotency behavior intact. Existing `resetToSeed()` already calls `removePersistedGameProjection()`; implementation should add or cite focused coverage rather than refactor the store unless a gap is found. Docs reconciliation should be evidence-led. Older game-design text describes `suggestion_update` as camp reconciliation, but the implemented Phase 22 reducer intentionally keeps it as an explicit snapshot no-op for camps. The docs update should preserve future design intent while naming the Phase 22 shipped behavior and keeping all rendering, camp mission, hosted persistence, and broad erasure claims deferred. ### Design Patterns * Constant reuse: Import and use `GAME_PROJECTION_STORAGE_KEY` instead of repeating `"factionos-game-v1"`. * Boundary-preserving erasure: Add the storage key to the existing browser erasure cleanup plan, not to protocol boundary vocabularies. * Test-first closeout: Add focused Vitest coverage before relying on final validation commands. * Docs as contract: Update stable game-design docs only with source-backed implementation choices and no-claim language. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase22-session08-erasure-docs-and-validation/implementation-notes.md` | Record task evidence, validation outputs, and no-claim boundary notes during implementation. | \~160 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/localErasure.ts` | Include the projection storage key in browser-local erasure cleanup without changing protocol boundary ids. | \~10 | | `apps/web/tests/localErasure.test.ts` | Seed projection storage and assert preview, confirmation, raw-value redaction, removal, and idempotency behavior. | \~35 | | `apps/web/tests/gameProjectionStore.test.ts` | Add or verify reset coverage proving `resetToSeed()` clears `factionos-game-v1` if existing assertions are insufficient. | \~20 | | `docs/game-design/10-technical-design-and-game-projection.md` | Align Phase 22 shipped behavior for `suggestion_update`, gate attention, persisted attention refs, camp-link dormancy, and erasure cleanup. | \~35 | | `docs/game-design/11-open-questions-and-change-log.md` | Add a source-backed Session 08 closeout change-log entry. | \~20 | | `docs/game-design/14-implemented-phases.md` | Record Phase 22 implementation evidence after focused validation passes. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Browser-local erasure removes `localStorage["factionos-game-v1"]`. * [ ] Browser erasure preview and confirm summaries count projection storage without exposing raw projection values. * [ ] `resetToSeed()` removes `localStorage["factionos-game-v1"]`. * [ ] Docs reflect implemented Phase 22 choices and do not claim rendering, hosted persistence, codebase-issue camp launch, new protocol events, or trusted unified erasure. * [ ] The implementation still has exactly one projection state authority and no new rendering surface. ### Testing Requirements * [ ] `npm test -- apps/web/tests/gameProjection.test.ts` passes. * [ ] `npm test -- apps/web/tests/replayPersist.test.ts apps/web/tests/localErasure.test.ts` passes. * [ ] Store or replay regression tests are broadened if `useGameStore.ts`, `gameProjectionStore.test.ts`, or shared event handling changes. * [ ] `npm --workspace @factionos/web run typecheck` passes. ### Non-Functional Requirements * [ ] Browser erasure remains idempotent for duplicate confirmation keys. * [ ] No raw prompts, broad absolute paths, terminal output, file contents, provider payloads, tokens, secrets, or raw projection storage values enter erasure summaries or docs examples. * [ ] Trusted unified erasure remains explicitly no-claim outside the browser-local projection key cleanup. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Biome check passes for changed application, test, and docs files. * [ ] Primary user-facing surfaces are unchanged or N/A. *** ## 8. Implementation Notes ### Working Assumptions * Use the existing browser storage erasure boundary for the projection key: `packages/protocol/src/erasure.ts` owns browser erasure boundary ids, `apps/web/src/lib/localErasure.ts` maps those ids to storage keys, and the Session 08 stub says not to invent a web-only erasure boundary. Planning can proceed because this is a browser-local key inventory change, not a protocol contract change. * Keep documentation updates narrow: `.spec_system/PRD/phase_22/PRD_phase_22.md`, `apps/web/src/lib/gameProjection.ts`, Session 01-07 artifacts, and game-design docs provide enough evidence to reconcile implementation choices without user arbitration. ### Conflict Resolutions * Master PRD summary table vs. workflow state: `.spec_system/PRD/PRD.md` still lists Phase 22 as Not Started in the planned phase table, while the analyzer, `.spec_system/state.json`, and `.spec_system/PRD/phase_22/PRD_phase_22.md` show Phase 22 in progress with 7 of 8 sessions complete. The analyzer and Phase 22 PRD win for session selection because `plansession` treats analyzer JSON as authoritative state. * Older game-design technical text vs. reducer implementation: `docs/game-design/10-technical-design-and-game-projection.md` describes `suggestion_update` camp reconciliation, while `apps/web/src/lib/gameProjection.ts` currently implements `reduceSuggestionUpdate()` as a no-op and the Phase 22 PRD allows explicit snapshot no-op. The implementation wins for Phase 22 closeout; docs should preserve future intent while naming the shipped no-op. ### Key Considerations * This session must close a browser-local erasure gap without implying full trusted erasure across logs, backups, archives, hosted surfaces, or workspace files. * The projection is derived aggregate state; losing it is acceptable and should not delete or mutate work source-of-truth data. * Docs should distinguish shipped Phase 22 foundation from future game presentation phases. ### Potential Challenges * Erasure boundary naming: Mitigate by reusing existing protocol boundary ids and limiting the change to web storage key inventory. * Existing reset coverage may already prove `resetToSeed()` removal: Mitigate by reusing or minimally extending existing focused tests rather than duplicating large store fixtures. * Docs may contain future design intent that still matters: Mitigate by adding Phase 22 implementation notes instead of deleting future-roadmap behavior. ### Relevant Considerations * \[P08] **Full trusted erasure remains no-claim**: Browser projection key cleanup must not become a broad trusted erasure claim. * \[P03] **Stable docs are the current contract**: Use README files, stable docs, PRD, and live specs as current truth. * \[P18-apps/server+apps/web] **`suggestion_update` is canonical**: Preserve Quest Board snapshot authority and avoid parallel event authority; Phase 22 projection camps remain no-op until a later scoped reconciliation. * \[P20] **Broad privacy gates are release-critical**: Erasure summaries, docs, and tests must keep raw commands, output, diffs, file contents, provider payloads, tokens, secrets, broad absolute paths, and raw storage payloads out of broad surfaces. * \[P21] **Archived phase snapshots can lag live state**: Prefer state/live specs and current Phase 22 PRD over stale archived or summary text. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Browser erasure is a destructive local state mutation and must preserve confirmation, idempotency, unavailable-storage, and partial-failure behavior. * Projection reset and erasure must clear the same storage key without creating a second state authority or deleting non-projection user data. * Docs must avoid overstating trusted erasure, hosted persistence, camp execution, or rendering behavior. *** ## 9. Testing Strategy ### Unit Tests * Extend `apps/web/tests/localErasure.test.ts` to cover projection-key preview counts, confirmation removal, raw-value redaction, and duplicate idempotency behavior. * Use or extend `apps/web/tests/gameProjectionStore.test.ts` to prove `resetToSeed()` removes the projection key when existing coverage is insufficient. ### Integration Tests * Run focused projection, replay persistence, and local erasure tests together to prove the storage key remains compatible with existing persistence behavior. * Run store/replay/Quest Board/orchestration regressions if shared store files or event handling are touched. ### Runtime Verification * Run `npm --workspace @factionos/web run typecheck` for the web package. * Run Biome on changed files and session docs. ### Edge Cases * Storage unavailable or throwing on read/write/remove. * Duplicate browser erasure idempotency key after state has been reseeded. * Raw projection storage containing sensitive sentinel strings. * Docs describing future reconciliation without claiming it shipped in Phase 22. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase22-session07-honesty-regression-tests` * Depended by: Phase Transition `audit` after Session 08 validates and `updateprd` marks Phase 22 complete. *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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-session08-erasure-docs-and-validation/spec.md?ask=&goal= ``` `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.