feat(persistence): add versioned validated data schema#256
Merged
Conversation
This was referenced Jul 10, 2026
b9ca41d to
fcf81b1
Compare
Deploying podnotes with
|
| Latest commit: |
fcf81b1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0d4fb8ae.podnotes.pages.dev |
| Branch Preview URL: | https://feat-versioned-persistence.podnotes.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduce a versioned, validated persistence boundary for PodNotes data without changing the existing flat
data.jsonshape.PodNotes currently hydrates raw persisted objects directly into runtime stores. That makes malformed fields, stale date strings, partial imports, prototype-sensitive keys, and future schema versions capable of failing far away from the load boundary. This PR adds explicit codecs so disk data is decoded once into trusted runtime state and encoded back into a canonical representation.
Key behavior:
schemaVersion: 1; an absent marker is treated as legacy v0.Dateas the runtime invariant and canonical ISO strings on disk across current episode, queues, favorites, local files, playlists, downloads, feed cache, settings import/export, parsing, sorting, and templates.The flat schema was retained instead of introducing an envelope because existing installations and third-party extensions may read unknown top-level fields. This gives us an explicit migration boundary while minimizing compatibility risk. It is also the foundation for the follow-up schema-v2 SecretStorage migration.
Migration and review notes:
Verification:
npm run lintnpm run format:checknpm run buildnpm test- 73 files, 936 testsnpm audit --audit-level=high- 0 vulnerabilitiesThe runtime proof covers legacy ISO-date revival, user-path note creation, schema-v1 persistence with unknown-field preservation, future-schema refusal with exact file preservation, and successful recovery. The full suite records two known
NotSupportedErrorentries from existing text placeholders used as unsupported audio fixtures; the focused persistence scenarios are diagnostic-clean.