Skip to content

feat(persistence): add versioned validated data schema#256

Merged
chhoumann merged 1 commit into
masterfrom
feat/versioned-persistence
Jul 10, 2026
Merged

feat(persistence): add versioned validated data schema#256
chhoumann merged 1 commit into
masterfrom
feat/versioned-persistence

Conversation

@chhoumann

Copy link
Copy Markdown
Owner

Introduce a versioned, validated persistence boundary for PodNotes data without changing the existing flat data.json shape.

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:

  • Adds flat schemaVersion: 1; an absent marker is treated as legacy v0.
  • Migrates v0 data field by field, salvaging valid values and warning on invalid fields rather than discarding the whole vault state.
  • Rejects invalid or future schema versions before store hydration or any write, leaving the original file untouched.
  • Preserves safe unknown root fields for forward-compatible extensions while rejecting prototype-sensitive keys at interpreted object and record boundaries.
  • Keeps Date as 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.
  • Splits persistence into best-effort saves for existing UI/store callers and strict saves for migrations/imports. The save queue coalesces snapshots without resolving callers before their state is durable.
  • Persists imported settings before mutating live stores and performs an ordered durable rollback if the write fails.

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:

  • The first successful save of legacy data writes schema v1 and canonical date strings.
  • Deliberately empty v1 note settings round-trip unchanged; only v0 receives the legacy default-note migration.
  • The production bundle is 423.25 kB, about 12.4 kB larger than master, due to explicit validation. A later bundle-budget task will track this rather than hiding the cost.
  • Focus review on load failure semantics, unknown-field preservation, save ordering, and settings-import rollback.

Verification:

  • npm run lint
  • npm run format:check
  • npm run build
  • npm test - 73 files, 936 tests
  • MkDocs production build
  • npm audit --audit-level=high - 0 vulnerabilities
  • Real Obsidian E2E - 13 scenarios passed in the isolated worktree vault

The 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 NotSupportedError entries from existing text placeholders used as unsupported audio fixtures; the focused persistence scenarios are diagnostic-clean.

@chhoumann chhoumann force-pushed the feat/versioned-persistence branch from b9ca41d to fcf81b1 Compare July 10, 2026 09:36
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jul 10, 2026

Copy link
Copy Markdown

Deploying podnotes with  Cloudflare Pages  Cloudflare Pages

Latest commit: fcf81b1
Status: ✅  Deploy successful!
Preview URL: https://0d4fb8ae.podnotes.pages.dev
Branch Preview URL: https://feat-versioned-persistence.podnotes.pages.dev

View logs

@chhoumann chhoumann marked this pull request as ready for review July 10, 2026 09:44
@chhoumann chhoumann merged commit 95f4215 into master Jul 10, 2026
5 checks passed
@chhoumann chhoumann deleted the feat/versioned-persistence branch July 10, 2026 09:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant