merge #284: Dashboard v1 phase 2 — atomic StoredWorkspaceV1 persistence + legacy migration

Author: BorisTyshkevich

CHANGELOG.md

@@ -31,6 +31,37 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
   whole-workspace cross-resource semantic validation. No persistence, no UI,
   no import planner yet (later phases of #280).
 
+- **Atomic `StoredWorkspaceV1` persistence and one-shot legacy migration**
+  (#284, phase 2 of #280). New pure `src/workspace/` modules: a
+  `WorkspaceRepository` (`loadCurrent`/`commit`/`clearCurrent`) that
+  validates the complete candidate through phase-1 whole-workspace validation
+  **before** writing and then atomically replaces the aggregate in one
+  transaction — a failed write leaves the previously stored workspace intact,
+  never increments Dashboard revision, and never produces a partially-mixed
+  workspace (multi-tab policy: last successful commit wins, atomic replacement,
+  not compare-and-swap). Persistence is **IndexedDB** (chosen over a single
+  localStorage key: the 10 MiB `maxDecodedJsonBytes` aggregate exceeds the
+  ~5 MB localStorage quota, and phase 6 needs IndexedDB anyway) behind an
+  injected `WorkspaceStore` seam (`env.indexedDB`, mirroring the crypto/storage
+  seams) so the repository unit-tests against a plain in-memory fake. The
+  one-shot legacy migration builds one candidate `StoredWorkspaceV1` from the
+  flat `asb:*` keys — the initial Dashboard from `spec.favorite` (panel-role
+  favorites become tiles in catalog order), `asb:dashLayout`/`asb:dashCols`
+  converted to a valid `flow@1` layout — validates the whole candidate, and
+  persists it atomically; it runs only when no aggregate record exists and
+  never deletes or modifies legacy keys. Repository + operation semantics only;
+  no authoring commands, viewer, or import UI yet (later phases of #280).
+  - **`spec.favorite` dual-write removal path.** 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 `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 — the
+    schema keeps `favorite` only as an ignored legacy-compat field readable by
+    old migrations.
+
 ### Changed
 - **The app.ts → services refactor is complete** (#276, Phase 5). The
   temporary `App` delegates from Phases 2–4 are deleted — consumers read

src/env.types.ts

@@ -19,6 +19,13 @@ export interface CreateAppEnv {
   fetch?: typeof fetch;
   crypto?: Crypto;
   sessionStorage?: Storage;
+  /** IndexedDB factory seam (#280 Phase 2 / #284) — injected like crypto/
+   * sessionStorage so the atomic `WorkspaceRepository` (app.workspace) has a
+   * real backing store in the browser and an in-memory fake in tests.
+   * Resolves to `win.indexedDB` when omitted; may be absent entirely on a
+   * platform without IndexedDB, in which case workspace operations reject
+   * (caught by the repository) rather than throwing at construction. */
+  indexedDB?: IDBFactory;
   root?: Element | null;
   Chart?: unknown; // Chart.js constructor — new app.Chart(canvas, cfg)
   cssVar?: (name: string) => string;

src/ui/app.ts

@@ -72,6 +72,8 @@ import { createExportService } from '../application/export-service.js';
 import type { ExportSink, FileHandleLike, DirectoryHandleLike } from '../application/export-service.js';
 import { createSchemaGraphSession, SchemaGraphAuthRequiredError } from '../application/schema-graph-session.js';
 import { createAppPreferences } from '../application/app-preferences.js';
+import { createWorkspaceRepository } from '../workspace/workspace-repository.js';
+import { createIndexedDbWorkspaceStore } from '../workspace/indexeddb-workspace-store.js';
 import { createWorkbenchSession } from './workbench/workbench-session.js';
 import { createQueryDocumentSession } from '../application/query-document-session.js';
 import { createSavedQueryService } from '../application/saved-query-service.js';
@@ -190,6 +192,16 @@ export function createApp(env: CreateAppEnv = {}): App {
   app.prefs = prefs;
   app.saveJSON = saveJSON;
   app.saveStr = saveStr;
+  // Atomic StoredWorkspaceV1 persistence (#280 Phase 2 / #284): the injected
+  // IndexedDB factory seam (mirrors crypto/sessionStorage) backs a single-record
+  // WorkspaceStore, behind which the pure WorkspaceRepository does validate-then-
+  // atomically-replace commits. Constructed lazily — no database is opened until
+  // a workspace operation runs — so this never touches IndexedDB during
+  // bootstrap. The favorites-driven Dashboard render still reads legacy keys in
+  // this phase; wiring reads onto the aggregate is Phases 3-6 of #280.
+  app.workspace = createWorkspaceRepository({
+    store: createIndexedDbWorkspaceStore(env.indexedDB || win.indexedDB),
+  });
   // The `{name:Type}` var-value/filter-active/recent-value persistence
   // wrappers (saveVarValues/saveFilterActive/saveVarRecent/
   // saveVarRecentDisabled) + the recent-value policy that sits on top of them

src/ui/app.types.ts

@@ -18,6 +18,7 @@ import type { ConnectionSession, SessionChCtx } from '../application/connection-
 import type { SchemaCatalogService } from '../application/schema-catalog-service.js';
 import type { SchemaGraphSession } from '../application/schema-graph-session.js';
 import type { AppPreferences } from '../application/app-preferences.js';
+import type { WorkspaceRepository } from '../workspace/workspace-repository.js';
 import type { SavedQueryV2 } from '../generated/json-schema.types.js';
 import type { DynamicSources } from '../core/spec-completion.js';
 import type { WorkbenchSession } from './workbench/workbench-session.js';
@@ -238,6 +239,12 @@ export interface App {
    *  `App.savePref` delegate); `toggleTheme`'s preference-write half also
    *  delegates here, the DOM half stays in app.ts. */
   prefs: AppPreferences;
+  /** Atomic StoredWorkspaceV1 aggregate persistence (#280 Phase 2 / #284),
+   *  behind the injected IndexedDB seam (`env.indexedDB`). Pure/testable — no
+   *  App/AppState/DOM dependency. In this phase it is constructed but the
+   *  favorites-driven Dashboard render still reads legacy keys; Phases 3-6 of
+   *  #280 route reads/commits through it and retire the legacy keys. */
+  workspace: WorkspaceRepository;
   saveJSON(key: string, value: unknown): void;
   saveStr(key: string, value: string): void;
   /** The one deliberate delegate survivor of #276 Phase 5's params-group

src/workspace/indexeddb-workspace-store.ts

@@ -0,0 +1,110 @@
+// Concrete IndexedDB adapter behind the injected `WorkspaceStore` seam (#280
+// Phase 2 / issue #284). This is the one place a real IndexedDB is touched;
+// the repository/migration logic never sees it. The pinned Phase-2 decision:
+// persist the StoredWorkspaceV1 aggregate as a SINGLE record and replace it
+// atomically via ONE readwrite transaction (IndexedDB was chosen over a single
+// localStorage key because a 10 MiB `maxDecodedJsonBytes` aggregate exceeds the
+// ~5 MB localStorage origin quota, and because Phase 6's cross-tab token
+// handoff needs IndexedDB anyway).
+//
+// The `IDBFactory` is injected (createApp resolves `env.indexedDB` /
+// `win.indexedDB`), so tests drive this with a minimal in-memory fake factory
+// instead of a real browser database — the same seam pattern as fetch/crypto.
+
+import type { WorkspaceStore } from './workspace-store.types.js';
+
+export interface IndexedDbWorkspaceStoreOptions {
+  /** IndexedDB database name. */
+  dbName?: string;
+  /** Object-store name inside the database. */
+  storeName?: string;
+  /** Fixed key of the single aggregate record. */
+  recordKey?: string;
+}
+
+const DEFAULTS = {
+  dbName: 'asb-workspace',
+  storeName: 'workspace',
+  recordKey: 'current',
+} as const;
+
+// Promisify one IDBRequest.
+function requestResult<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+  });
+}
+
+// Resolve when a readwrite transaction durably completes (the atomicity point).
+function transactionDone(tx: IDBTransaction): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error('IndexedDB transaction failed'));
+    tx.onabort = () => reject(tx.error ?? new Error('IndexedDB transaction aborted'));
+  });
+}
+
+/** Build a `WorkspaceStore` backed by IndexedDB. The database is opened lazily
+ *  on first use (and the open promise cached), so constructing the store with a
+ *  not-yet-available factory never throws — the failure surfaces only when an
+ *  operation actually runs, where the repository catches it. */
+export function createIndexedDbWorkspaceStore(
+  factory: IDBFactory | undefined, options: IndexedDbWorkspaceStoreOptions = {},
+): WorkspaceStore {
+  const dbName = options.dbName ?? DEFAULTS.dbName;
+  const storeName = options.storeName ?? DEFAULTS.storeName;
+  const recordKey = options.recordKey ?? DEFAULTS.recordKey;
+  let dbPromise: Promise<IDBDatabase> | null = null;
+
+  function openDb(): Promise<IDBDatabase> {
+    if (dbPromise) return dbPromise;
+    const pending = new Promise<IDBDatabase>((resolve, reject) => {
+      if (!factory) {
+        reject(new Error('IndexedDB is unavailable'));
+        return;
+      }
+      const request = factory.open(dbName, 1);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName);
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error ?? new Error('IndexedDB open failed'));
+      // Dormant at version 1 (no upgrade can block a fresh open), but an
+      // unhandled `blocked` event would hang the open forever — reject so the
+      // no-cache-on-failure path below reopens on the next call.
+      request.onblocked = () => reject(new Error('IndexedDB open blocked'));
+    });
+    // Cache only a SUCCESSFUL open. A rejected open must not poison the store
+    // for the page's lifetime (one createApp() builds one long-lived store):
+    // drop the cached promise on failure so a same-session retry can reopen,
+    // matching the repository's "failed write leaves a draft to retry" contract.
+    dbPromise = pending;
+    pending.catch(() => { if (dbPromise === pending) dbPromise = null; });
+    return pending;
+  }
+
+  async function read(): Promise<string | null> {
+    const db = await openDb();
+    const tx = db.transaction([storeName], 'readonly');
+    const value = await requestResult(tx.objectStore(storeName).get(recordKey));
+    return typeof value === 'string' ? value : null;
+  }
+
+  async function write(text: string): Promise<void> {
+    const db = await openDb();
+    const tx = db.transaction([storeName], 'readwrite');
+    tx.objectStore(storeName).put(text, recordKey);
+    await transactionDone(tx);
+  }
+
+  async function clear(): Promise<void> {
+    const db = await openDb();
+    const tx = db.transaction([storeName], 'readwrite');
+    tx.objectStore(storeName).delete(recordKey);
+    await transactionDone(tx);
+  }
+
+  return { read, write, clear };
+}

src/workspace/legacy-migration.ts

@@ -0,0 +1,131 @@
+// Legacy migration marker (#280 "Legacy migration marker", Phase 2 of #280 /
+// issue #284). One-shot conversion of the pre-aggregate flat localStorage
+// state into one atomic StoredWorkspaceV1:
+//
+//   1. read legacy values (the caller supplies them — this module is pure);
+//   2. build one candidate StoredWorkspaceV1;
+//   3. create the initial Dashboard from legacy favorites (`spec.favorite`);
+//   4. convert the legacy layout preferences (asb:dashLayout/asb:dashCols) to a
+//      valid flow@1 layout;
+//   5. validate the WHOLE candidate (via the repository's commit);
+//   6. persist it atomically;
+//   7. treat a successful aggregate write as migration completion.
+//
+// The marker is aggregate RECORD EXISTENCE — migration runs only when the
+// store holds no record (checked via `store.read()`), never keyed on
+// loadCurrent validity, so a present-but-corrupt aggregate is never clobbered
+// by a re-run. Legacy keys are NEVER deleted or modified here: Phase 2 still
+// serves the favorites-driven UI off them, and #280 forbids touching them
+// before the aggregate write succeeds. Removing the legacy reads (and the
+// `spec.favorite` dual-write) is the documented Phase 3-5 removal path, not
+// this phase.
+//
+// Pure over injected seams: the query-collection is decoded by the caller, the
+// ID generator is injected, and persistence goes through the injected
+// WorkspaceStore/WorkspaceRepository — no DOM, no storage, no crypto import.
+
+import { queryFavorite } from '../core/saved-query.js';
+import { activeDashboardView } from '../core/dashboard.js';
+import { queryDashboardRole } from '../dashboard/model/workspace-semantics.js';
+import { CURRENT_STORAGE_VERSION, DEFAULT_WORKSPACE_NAME } from './workspace-operations.js';
+import type { WorkspaceIdGen } from './workspace-operations.js';
+import type { WorkspaceStore } from './workspace-store.types.js';
+import type { WorkspaceRepository, WorkspaceCommitResult } from './workspace-repository.js';
+import type { WorkspaceDiagnostic } from '../dashboard/model/workspace-diagnostics.js';
+import type {
+  FlowPresetV1, SavedQueryV2, StoredWorkspaceV1,
+} from '../generated/json-schema.types.js';
+
+/** The flat legacy persistence the caller reads out of localStorage before
+ *  migrating: the decoded saved-query collection (asb:saved), the Library name
+ *  (asb:libraryName), and the two Dashboard layout preferences
+ *  (asb:dashLayout/asb:dashCols). */
+export interface LegacyWorkspaceInput {
+  name: string;
+  queries: readonly SavedQueryV2[];
+  dashLayout: string;
+  dashCols: number;
+}
+
+/** Map the legacy Dashboard layout preferences to a normative flow@1 preset.
+ *  Reuses the existing `activeDashboardView` derivation (core/dashboard.ts) and
+ *  remaps its `wide` value to the flow preset name `full-width`; `report`,
+ *  `columns-2`, and `columns-3` already match the flow preset names. */
+export function legacyLayoutToFlowPreset(dashLayout: string, dashCols: number): FlowPresetV1 {
+  const view = activeDashboardView({ dashLayout, dashCols });
+  return view === 'wide' ? 'full-width' : view;
+}
+
+/** Build the one candidate StoredWorkspaceV1 from the legacy state (steps 2-4).
+ *  The initial Dashboard's tiles are the PANEL-role favorites in catalog order:
+ *  a favorited filter/setup-role query cannot be a tile by the #280 contract,
+ *  so it is not turned into one (it stays in the query collection). The
+ *  Dashboard is always created so the legacy layout preference is preserved
+ *  even for a user with no favorites yet; it starts at revision 1. `genId` is
+ *  called once for the workspace ID, once for the Dashboard ID, and once per
+ *  tile. The candidate is NOT validated here — the caller validates the whole
+ *  thing through `repository.commit`. */
+export function buildLegacyMigrationCandidate(
+  legacy: LegacyWorkspaceInput, genId: WorkspaceIdGen,
+): StoredWorkspaceV1 {
+  const name = legacy.name.trim() ? legacy.name : DEFAULT_WORKSPACE_NAME;
+  const queries = [...legacy.queries];
+  const workspaceId = genId();
+  const dashboardId = genId();
+  const tiles = queries
+    .filter((query) => queryFavorite(query) && queryDashboardRole(query) === 'panel')
+    .map((query) => ({ id: genId(), queryId: query.id }));
+  return {
+    storageVersion: CURRENT_STORAGE_VERSION,
+    id: workspaceId,
+    name,
+    queries,
+    dashboard: {
+      documentVersion: 1,
+      id: dashboardId,
+      title: name,
+      revision: 1,
+      layout: {
+        type: 'flow',
+        version: 1,
+        preset: legacyLayoutToFlowPreset(legacy.dashLayout, legacy.dashCols),
+        items: {},
+      },
+      filters: [],
+      tiles,
+    },
+  };
+}
+
+/** The outcome of `migrateLegacyWorkspaceIfNeeded`. `migrated: false` with
+ *  `reason: 'aggregate-exists'` means the marker found a record and skipped;
+ *  `reason: 'commit-failed'` carries the whole-candidate validation or
+ *  persistence diagnostics (legacy keys were left intact). */
+export type MigrationResult =
+  | { migrated: true; result: Extract<WorkspaceCommitResult, { ok: true }> }
+  | { migrated: false; reason: 'aggregate-exists' }
+  | { migrated: false; reason: 'commit-failed'; diagnostics: WorkspaceDiagnostic[] };
+
+export interface MigrationDeps {
+  /** Checked for record existence — the migration marker. */
+  store: WorkspaceStore;
+  /** The repository whose atomic `commit` validates + persists the candidate. */
+  repository: WorkspaceRepository;
+  legacy: LegacyWorkspaceInput;
+  genId: WorkspaceIdGen;
+}
+
+/** Run the one-shot migration when — and only when — no aggregate record
+ *  exists yet. Idempotent: once the aggregate persists, a later call finds the
+ *  record and returns `aggregate-exists` without rebuilding or rewriting. A
+ *  failed commit leaves the store (and every legacy key) untouched, so a retry
+ *  on the next load is safe. */
+export async function migrateLegacyWorkspaceIfNeeded(deps: MigrationDeps): Promise<MigrationResult> {
+  const { store, repository, legacy, genId } = deps;
+  const existing = await store.read();
+  if (existing !== null) return { migrated: false, reason: 'aggregate-exists' };
+  const candidate = buildLegacyMigrationCandidate(legacy, genId);
+  const result = await repository.commit(candidate);
+  if (!result.ok) return { migrated: false, reason: 'commit-failed', diagnostics: result.diagnostics };
+  return { migrated: true, result };
+}