Dashboard v1 phase 2 (#280): atomic StoredWorkspaceV1 persistence + legacy migration

[BorisTyshkevich]

Part of #280 (Dashboard as a first-class module). Phase 2 of 6, after Phase 1 (contracts). Normative spec in #280.

Goal

Browser persistence moves from flat per-feature localStorage keys to one atomic StoredWorkspaceV1 aggregate behind WorkspaceRepository, with one-shot migration from legacy keys.

Scope (from #280 "Phase 2: atomic persistence and migration")

• WorkspaceRepository with atomic replacement semantics: validate the complete candidate before writing; publish committed state only after persistence succeeds; failed persistence leaves the previous stored workspace intact, the draft dirty, and revision unchanged; never partially replace queries/dashboard/layout/metadata.
• Legacy migration exactly per Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 "Legacy migration marker": runs only when no aggregate exists; builds the initial Dashboard from legacy favorites; converts legacy layout preferences (asb:dashLayout, asb:dashCols, …) to flow@1; validates the whole candidate; persists atomically; legacy keys untouched until the aggregate write succeeds.
• Workspace operation semantics (rename, new-workspace, replace-from-bundle, reload) per Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280.
• Multi-tab policy: last successful commit wins; documented; test proving a commit never produces a partially mixed workspace.

Decisions to settle in this phase

• Storage mechanism for the aggregate. Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 doesn't name it. Single localStorage key collides with the ~5 MB origin quota vs maxDecodedJsonBytes = 10 MiB; IndexedDB (already required for Phase 6 token handoff) gives real atomicity and headroom. Decide here, and reconcile Phase-1 limits.
• spec.favorite dual-write removal path. Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 allows a temporary dual-write during migration "with a documented removal path" — define that path concretely here (what flips membership reads to dashboard.tiles, which release deletes the dual-write) so it cannot become permanent.

Dependencies

Phase 1 (schemas/validation/canonical encoder). Coordinate with #276 phase 4 (AppPreferences service) so preference persistence isn't extracted twice.

Tests

Per #280 "Workspace persistence and migration": atomic commit; failed write preserves prior workspace + dirty draft + revision; migration runs once keyed on aggregate existence; legacy keys survive until successful commit; multi-tab last-write-wins never mixes aggregates.

Acceptance

• Reload loads StoredWorkspaceV1; Dashboard state is no longer recomputed from favorites.
• Migration is one-shot, atomic, and lossless for existing users.
• Storage-mechanism and favorite-removal decisions recorded here and in Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280.

[BorisTyshkevich]

Decision record (phase-2 pin, /ship-phase 2026-07-17)

Aggregate storage mechanism: IndexedDB. The WorkspaceRepository persists the StoredWorkspaceV1 aggregate in IndexedDB (single record, atomic replacement via one readwrite transaction). Rationale: last-successful-commit-wins semantics need genuine transactional replacement; maxDecodedJsonBytes = 10 MiB exceeds the ~5 MB localStorage origin quota; and Phase 6's one-time session-bundle token handoff already requires IndexedDB, so this adds no new platform dependency. #283's limit constants stay as specced in #280.

The spec.favorite dual-write removal path is to be defined concretely by the phase-2 implementation and recorded here when it lands.

[BorisTyshkevich]

Decision record (phase-2, /ship-phase 2026-07-17)

Aggregate storage: IndexedDB, one record, one readwrite transaction per op — implemented behind an injected WorkspaceStore env seam (src/workspace/workspace-store.types.ts) so the repository/migration logic is pure and unit-tested against an in-memory fake; the concrete adapter is src/workspace/indexeddb-workspace-store.ts. Multi-tab policy is last-successful-commit-wins via atomic replacement (not compare-and-swap), proven by an interleaved-commit test that shows exactly one complete aggregate survives.

spec.favorite dual-write removal path (concrete):

During phases 2–4, spec.favorite stays the membership source the existing favorites-driven Dashboard render reads, while dashboard.tiles becomes the canonical membership going forward; phase 3's star command dual-writes both. Membership reads flip to dashboard.tiles when phase 4's DashboardViewerSession + flow@1 viewer replace src/ui/dashboard.ts's state.savedQueries.filter(queryFavorite) render. The spec.favorite dual-write is then deleted in the v1 Dashboard GA release (the release closing #280), after phase 5 lands and the last favorites-reading paths (src/ui/dashboard.ts, sortedSaved, toggleFavorite) are removed — the query-spec-v1 schema keeps favorite only as an ignored legacy-compat field readable by old migrations.

Migration keys on aggregate record existence (not validity), so a present-but-corrupt record is never clobbered and migration never re-runs; legacy keys are untouched until the aggregate write succeeds.