# Session storage guide
Owns JSONL events, reads, metadata, retention, scope, and export.
## Where to look
| Event kinds and local-only classification | `event.rs` |
| Session creation/open/list | `manager.rs` |
| Exclusive writer admission | `writer.rs` |
| Id validation and bounded reads | `read.rs` |
| Append outcomes and record helpers | `write.rs` |
| Usage totals and rotation checkpoints | `usage.rs` |
| Sidecar validation and compaction lookup | `metadata.rs` |
| Retention and worktree scope | `prune.rs`, `scope.rs` |
| Storage preparation | `store.rs` |
| Export archive and destination checks | `export.rs` |
| Prompt targets and recoverable rewind forks | `rewind.rs` |
## Local rules
- Validate session ids before constructing paths. A new session may have no JSONL file until its first append.
- Use `Session::append_with_outcome`; `append_owned_batch` owns validation, redaction, locking, writes, rollback and metadata updates. Distinguish rolled-back from uncertain outcomes.
- Metadata markers include session id, schema, file length and modification time. Rebuild stale sidecars from JSONL.
- Read limits count original line bytes. Tolerant diagnostics report line numbers and safe errors, never malformed line contents. Unknown event kinds stay readable; provider replay selection belongs to `../context/replay.rs`.
- Writer leases are separate from retention protection. Admission retains them in `Session` clones through worker cleanup. Lock order is writer, activation, append; nested work reuses admission. Pruning removes metadata sidecars only after successful session deletion.
- Keep linked-worktree normalization in `scope.rs` and deletion in `prune.rs`.
- Title recording belongs here, provider/background work in `../session_titles.rs`. Best-effort title/cache failures cannot replace required append outcomes.
- Export owns cancellation and destination checks; do not bypass them with direct archive writes.
- Usage checkpoints cover only removed JSONL prefixes. Retain active-run records so suffix snapshots replace partial usage without double counting. Missing/unfinished request usage stays incomplete.
- Rewind forks copy the ordered prefix before a retained prompt, remap top-level session ids and use normal durable batches. Preserve event-count compaction cutoffs; prompt numbering follows compaction aggregate counts. Never truncate source JSONL. Unsent rewind prompts are local diagnostic metadata, not provider replay.