Storage owns persisted file schemas.
Assume storage files on disk may be missing, malformed, stale, or partially corrupted, and recover gracefully.
That means:
- storage owns recovery for persisted data
- callers should not need to guess how to repair on-disk shapes
- once storage returns decoded data, callers should trust it
- Storage owns on-disk shapes. If a value is persisted in
meta.jsonor another storage file, its canonical schema lives inpackages/storage. - Effect Schema is canonical. Storage defines the persisted contract as an Effect schema and exports the inferred type for callers.
- Reads are lenient at the schema boundary. Old, partial, or malformed files can be normalized during schema decode, or recovered with storage-level fallbacks.
- Callers trust decoded data. CLI/agent code should consume decoded storage types, not re-validate fields that storage already normalized.
- Define the raw persisted shape in
src/types/...withSchema.Struct(...). - Keep the decoded schema strict for the shape callers should receive.
- Use schema transforms when decode-time normalization depends on Effect context or service dependencies.
- Read files through storage helpers, then decode to the canonical stored type.
- Keep fallback/normalization in storage schemas and helpers, not in callers.
StoredSessionMetaSchema is the canonical meta.json schema.
- It uses
Schema.transformOrFailand requires theVersionservice during decode. - Missing
initialVersionandlastActiveVersionfields default fromVersion. - Nullable fields like
gitBranch,firstUserMessage, andlastMessageare normalized tostring | nullin the decode transform. - Callers receive a fully decoded
StoredSessionMetaand should use it directly.