> 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/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md). # Implementation Notes **Session ID**: `phase18-session02-server-suggestion-manager-and-persistence` **Package**: apps/server **Started**: 2026-06-09 23:36 **Last Updated**: 2026-06-09 23:51 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 21 / 21 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ### Task T021 - Run validation and record evidence **Started**: 2026-06-09 23:48 **Completed**: 2026-06-09 23:51 **Duration**: 3 minutes **Notes**: * Ran focused server Vitest for `apps/server/tests/suggestionManager.test.ts` and `apps/server/tests/suggestionManagerLifecycle.test.ts`: 2 files passed, 7 tests passed. * Ran `npm --workspace apps/server run typecheck`: passed. * Ran Biome check/write on touched TypeScript files; it formatted two files and subsequent validation still passed. * Ran ASCII/LF validation on touched implementation, test, README, task, and notes files: passed. **Files Changed**: * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T021 complete, closed progress, and checked completion checklist. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged validation evidence. **BQC Fixes**: * N/A - validation task. *** ### Task T020 - Write server lifecycle shutdown flush test **Started**: 2026-06-09 23:59 **Completed**: 2026-06-09 23:50 **Duration**: 1 minute **Notes**: * Added a server lifecycle test with injected Notice Board and SuggestionManager state roots. * The test creates pending suggestion state with a long debounce and verifies `stop()` flushes `suggestions.json`. **Files Changed**: * `apps/server/tests/suggestionManagerLifecycle.test.ts` - added shutdown flush coverage. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T020 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T020 evidence. **BQC Fixes**: * Resource cleanup: lifecycle coverage verifies server shutdown calls manager destroy/flush. *** ### Task T019 - Write manager persistence tests **Started**: 2026-06-09 23:58 **Completed**: 2026-06-09 23:59 **Duration**: 1 minute **Notes**: * Added persistence tests for debounce timing, temp cleanup after successful save, restart round-trip, corrupt and malformed store recovery, write-failure temp cleanup, and destroy flush. **Files Changed**: * `apps/server/tests/suggestionManager.test.ts` - added persistence coverage. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T019 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T019 evidence. **BQC Fixes**: * Resource cleanup: tests assert timers and temp files are cleaned up. * Failure path completeness: tests assert corrupt/malformed stores recover to empty state with stable errors. *** ### Task T018 - Write manager state tests **Started**: 2026-06-09 23:54 **Completed**: 2026-06-09 23:58 **Duration**: 4 minutes **Notes**: * Added state tests for idle suggestion replacement/caps, accept/dismiss idempotency, dismissed-ID FIFO caps, issue dedupe/query/clear, summary counts, freshness boundaries, and `suggestion_update` emission. **Files Changed**: * `apps/server/tests/suggestionManager.test.ts` - replaced scaffold with focused manager state coverage. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T018 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T018 evidence. **BQC Fixes**: * Contract alignment: tests assert protocol event emission and protocol freshness behavior. * Duplicate action prevention: tests cover idempotent repeated accept/dismiss paths. *** ### Task T017 - Update server README **Started**: 2026-06-09 23:53 **Completed**: 2026-06-09 23:54 **Duration**: 1 minute **Notes**: * Documented `suggestions.json` local persistence, manual deletion path, route deferral, and no analytics/hosted storage boundaries. * Kept README language explicit that `/suggestions/*` routes are not shipped in this session. **Files Changed**: * `apps/server/README_server.md` - added Quest Board Suggestion Manager runtime notes. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T017 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T017 evidence. **BQC Fixes**: * Error information boundaries: documentation describes local deletion without exposing runtime paths beyond configured state roots. *** ### Task T016 - Wire SuggestionManager into server lifecycle **Started**: 2026-06-09 23:52 **Completed**: 2026-06-09 23:53 **Duration**: 1 minute **Notes**: * Added `suggestionManager` options to `createFactionOsServer` for injected test state. * Instantiated `SuggestionManager` during server creation and exposed it on `ServerHandles` for lifecycle tests. * Destroyed the suggestion manager during shutdown without adding `/suggestions/*` routes or WebSocket hydration. **Files Changed**: * `apps/server/src/server.ts` - added manager instantiation, handle exposure, options, and shutdown cleanup. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T016 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T016 evidence. **BQC Fixes**: * Resource cleanup: server shutdown now flushes pending suggestion-manager writes. *** ### Task T015 - Implement suggestion\_update emission **Started**: 2026-06-09 23:51 **Completed**: 2026-06-09 23:52 **Duration**: 1 minute **Notes**: * Added `emitUpdate()` as the single manager path for building and broadcasting `suggestion_update` snapshots. * Kept REST routes and WebSocket hydration untouched for Session 03. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added canonical update emission. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T015 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T015 evidence. **BQC Fixes**: * Contract alignment: emitted update event uses the active protocol `SuggestionUpdateEvent`. *** ### Task T014 - Implement debounced persistence lifecycle **Started**: 2026-06-09 23:50 **Completed**: 2026-06-09 23:51 **Duration**: 1 minute **Notes**: * Added startup load from `suggestions.json` with corrupt JSON and malformed snapshot recovery. * Added debounced saves, atomic temp-file write plus rename, and temp cleanup on failed writes. * Added `flush()` and `destroy()` for shutdown persistence and timer cleanup. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added load/save/flush/destroy persistence lifecycle. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T014 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T014 evidence. **BQC Fixes**: * Resource cleanup: pending save timers are cleared before flush and during destroy. * Failure path completeness: load/write failures record stable persistence errors and recover or retry without crashing. *** ### Task T013 - Implement summary, analysis, project scan, and status setters **Started**: 2026-06-09 23:49 **Completed**: 2026-06-09 23:50 **Duration**: 1 minute **Notes**: * Added setters for session summaries, analysis result, project scan, and scan status. * Setters validate protocol shape before mutating and return cloned values. * Session summaries are replaced per session and capped through protocol constants. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added setter APIs for non-idle suggestion state. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T013 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T013 evidence. **BQC Fixes**: * Trust boundary enforcement: setter inputs are protocol-validated before mutation. * State freshness on re-entry: setters return cloned output. *** ### Task T012 - Implement incremental codebase issue APIs **Started**: 2026-06-09 23:48 **Completed**: 2026-06-09 23:49 **Duration**: 1 minute **Notes**: * Added issue add, type query, severity query, and clear-by-type APIs. * Dedupe uses `type`, `filePath`, and `line`; bounded issue caps use the shared protocol helper. * Query results are sorted and cloned before return. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added codebase issue mutation/query APIs. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T012 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T012 evidence. **BQC Fixes**: * Contract alignment: issue type/severity inputs are validated with protocol parsers. * State freshness on re-entry: queries return cloned issue objects. *** ### Task T011 - Implement accept and dismiss APIs **Started**: 2026-06-09 23:47 **Completed**: 2026-06-09 23:48 **Duration**: 1 minute **Notes**: * Added `acceptSuggestion()`, `dismissSuggestion()`, and `dismissIssue()`. * Dismissed suggestion and issue IDs are deduped and capped through protocol FIFO helpers. * Mutations snapshot the prior store and restore it if a mutation throws. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added accept/dismiss APIs and mutation rollback helper. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T011 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T011 evidence. **BQC Fixes**: * Failure path completeness: failed mutations roll back to the previous cloned state. * Duplicate action prevention: repeated accept/dismiss calls are idempotent. *** ### Task T010 - Implement idle suggestion APIs **Started**: 2026-06-09 23:46 **Completed**: 2026-06-09 23:47 **Duration**: 1 minute **Notes**: * Added `createIdleSuggestion()` and `listIdleSuggestions()` with generated IDs, clock-backed timestamps, session/hero linkage, and clone-on-read returns. * Enforced one active idle suggestion per session and deterministic ordering. * Added in-flight mutation guards keyed by session to prevent duplicate concurrent creates. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added idle suggestion mutation and listing APIs. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T010 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T010 evidence. **BQC Fixes**: * Duplicate action prevention: idle suggestion creates are guarded by an in-flight mutation key. * State freshness on re-entry: list returns cloned active suggestions. *** ### Task T009 - Implement freshness predicates **Started**: 2026-06-09 23:45 **Completed**: 2026-06-09 23:46 **Duration**: 1 minute **Notes**: * Added analysis, project scan, and codebase scan freshness predicates using the protocol freshness helpers. * Freshness methods use the injected `now` clock for deterministic boundary tests. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added protocol-backed freshness methods. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T009 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T009 evidence. **BQC Fixes**: * Contract alignment: freshness windows are not redefined locally. *** ### Task T008 - Implement summary counts and severity buckets **Started**: 2026-06-09 23:44 **Completed**: 2026-06-09 23:45 **Duration**: 1 minute **Notes**: * Added `getSummary()` with counts for idle suggestions, codebase issues, summaries, analysis items, project scan items, and dismissed IDs. * Added deterministic severity buckets for active codebase issues. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added summary count and severity bucket generation. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T008 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T008 evidence. **BQC Fixes**: * Contract alignment: summary output uses the shared protocol `SuggestionSummary` type. *** ### Task T007 - Implement snapshot cloning and getCurrentState **Started**: 2026-06-09 23:43 **Completed**: 2026-06-09 23:44 **Duration**: 1 minute **Notes**: * Added clone helpers for all snapshot branches. * `getCurrentState()` validates the cloned snapshot through `parseSuggestionSnapshot` before returning it. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added snapshot clone helpers and protocol-validated state read. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T007 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T007 evidence. **BQC Fixes**: * Contract alignment: returned snapshots are checked against the shared protocol parser. * State freshness on re-entry: callers receive cloned state rather than internal references. *** ### Task T006 - Implement protocol-backed normalization helpers **Started**: 2026-06-09 23:42 **Completed**: 2026-06-09 23:43 **Duration**: 1 minute **Notes**: * Added parser-backed normalization for idle suggestions, codebase issues, session summaries, analysis result, project scan, and scan status. * Added safe ID normalization for generated IDs and dismiss/query inputs. * Added capped dismissed-ID handling through protocol helper. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added parser-backed helpers and validation error mapping. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T006 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T006 evidence. **BQC Fixes**: * Trust boundary enforcement: all manager state inputs pass explicit protocol validation before mutation. *** ### Task T005 - Implement storage path resolution **Started**: 2026-06-09 23:41 **Completed**: 2026-06-09 23:42 **Duration**: 1 minute **Notes**: * Added `resolveStoragePath` for explicit storage path, injected `stateDir`, `FACTIONOS_HOME`, or `~/.factionos`. * Kept persistence error payloads to code, operation, and stable message only. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - added local storage resolution and compact persistence error recording. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T005 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T005 evidence. **BQC Fixes**: * Error information boundaries: persistence errors do not expose raw local paths. *** ### Task T004 - Create manager foundation types and defaults **Started**: 2026-06-09 23:40 **Completed**: 2026-06-09 23:41 **Duration**: 1 minute **Notes**: * Added `SuggestionManager`, `SuggestionManagerOptions`, persistence error types, and validation error mapping. * Added protocol-shaped empty store creation and constructor defaults for clock, debounce, storage path, and ID generation. **Files Changed**: * `apps/server/src/managers/suggestionManager.ts` - created manager state, options, errors, constructor, and empty store factory. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T004 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T004 evidence. **BQC Fixes**: * Contract alignment: store uses protocol `SuggestionSnapshot` and imported suggestion types. *** ### Task T003 - Create SuggestionManager test scaffold **Started**: 2026-06-09 23:39 **Completed**: 2026-06-09 23:40 **Duration**: 1 minute **Notes**: * Added a focused Vitest file for SuggestionManager coverage. * Added temporary state root tracking and `vi.useRealTimers()` cleanup for fake-timer safety. **Files Changed**: * `apps/server/tests/suggestionManager.test.ts` - created test scaffold with temp directory lifecycle cleanup. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T003 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T003 evidence. **BQC Fixes**: * Resource cleanup: temp directories and fake timers are reset after each test. *** ### Task T002 - Verify server persistence, broadcaster, and shutdown patterns **Started**: 2026-06-09 23:35 **Completed**: 2026-06-09 23:38 **Duration**: 3 minutes **Notes**: * Reviewed `NoticeBoard` load, debounced save, atomic temp-plus-rename write, corrupt-store fallback, stable persistence errors, and `destroy()` cleanup. * Reviewed `Broadcaster.emit` and confirmed it accepts protocol `ServerEvent` values including `SuggestionUpdateEvent`. * Reviewed `createFactionOsServer().stop()` and identified the existing `finally` cleanup block where the suggestion manager flush should run. **Files Changed**: * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T002 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T002 evidence. **BQC Fixes**: * N/A - evidence review only. *** ### Task T001 - Verify prerequisites and exclusions **Started**: 2026-06-09 23:34 **Completed**: 2026-06-09 23:37 **Duration**: 3 minutes **Notes**: * Confirmed Session 01 protocol exports exist in `packages/protocol/src/suggestions.ts` and are re-exported by `packages/protocol/src/index.ts`. * Confirmed Session 02 scope excludes suggestion REST routes, WebSocket hydration, generation engines, scanners, UI, telemetry, and entitlement gates. * Confirmed `suggestion_update` is already part of the active protocol `ServerEvent` union. **Files Changed**: * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/tasks.md` - marked T001 complete and updated progress. * `.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.md` - logged T001 evidence. **BQC Fixes**: * N/A - evidence review only. *** ## Task Log ### 2026-06-09 - Session Start **Environment verified**: * [x] Prerequisites confirmed with bundled apex-spec scripts * [x] Package context confirmed as `apps/server` * [x] Tools available: node, npm, jq, git * [x] Directory structure ready * [x] Database prerequisites not applicable *** --- # 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/phase18-session02-server-suggestion-manager-and-persistence/implementation-notes.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.