> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_35/session_05_persistence_schema_contracts.md). # Session 05: Persistence Schema Contracts **Session ID**: `phase35-session05-persistence-schema-contracts` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Stabilize AI Rogue durable state, wallet, ledger, save-slot, and storage contracts before larger module splits. *** ## Scope ### In Scope (MVP) * Ensure claim writes parse through schema-owned validation or one shared normalized claim path before wallet and ledger mutation. * Ensure durable runtime snapshot naming cannot be confused with live runtime snapshots. * Move durable-to-runtime hydration behind schema-owned helpers or explicitly named adapter functions. * Add migration/default tests, oversized-claim tests, save/load e2e coverage, reset compensation checks, claim idempotency checks, and blocked or quota IndexedDB coverage where feasible. ### Out of Scope * Hosted persistence, remote sync, or account-backed AI Rogue saves. * Changing AI Rogue economy rules without a separate product requirement. *** ## Prerequisites * [ ] Session 01 has confirmed which D5 work is already fixed. * [ ] Session 02 has preserved current durable claim and save hydration coverage. *** ## Deliverables 1. Persistence and `save-schema.ts` changes for any remaining AR-D5-001 and AR-D5-002 hardening. 2. Focused tests for wallet-ledger parity, durable save conversion, migrations, storage failure, and reset behavior. 3. Refined split notes for `save-schema.ts` and `persistence.ts` if they remain oversized. *** ## Success Criteria * [ ] Direct oversized claims cannot write inconsistent wallet and ledger records. * [ ] Durable and live snapshot types have distinct names and tested conversion. * [ ] Existing saved-run, wallet, ledger, preference, and migration tests pass. * [ ] Storage failure behavior is tested or explicitly documented as a source-inspection limitation. ## Folded Audit Detail Routed To This Session ### Finding IDs Owned * AR-D5-001: durable claim validation can drift wallet and ledger amounts if direct calls accept oversized claims. * AR-D5-002: live and durable runtime snapshot APIs are easy to confuse. * AR-D8-002 storage portion: browser-level blocked/quota IndexedDB coverage is desirable where feasible. * High-priority coverage gaps: direct durable claim normalization/rejection and durable-to-runtime saved-run conversion helper coverage. ### Source Locations From Audit * `src/extensions/ai-rogue/persistence.ts:1006`: direct claim validation drift. * `src/extensions/ai-rogue/runtime/types.ts:635`: live runtime snapshot type. * `save-schema.ts:667`: durable runtime snapshot type noted in the audit. * `views/runtime-canvas.tsx`: durable type alias and saved run-state cast noted in the audit. ### Schema And Persistence Contracts * Claims should parse through `aiRogueClaimEntrySchema` or one normalized claim path before both wallet and ledger writes. * Direct oversized claims such as `amount: 250` must not write wallet balance 100 with ledger amount 250. * Durable saved-run snapshots need distinct names from live runtime snapshots. * Durable-to-runtime conversion should be owned by schema helpers or explicitly named adapter functions, with focused save/load tests. ### Acceptance Evidence Required * [ ] Direct oversized-claim regression proves wallet and ledger parity. * [ ] Durable snapshot naming and hydration helpers are covered. * [ ] Migration/default, reset compensation, claim idempotency, save/load, and storage failure behavior are tested or explicitly caveated. * [ ] `save-schema.ts` and `persistence.ts` split recommendations are updated if file size or ownership remains a follow-up. --- # 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://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_35/session_05_persistence_schema_contracts.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.