@businessmaps/metaontology-nuxt 0.63.0

package/composables/idbConnection.ts

@@ -0,0 +1,81 @@
+import { openDB } from 'idb'
+import type { IDBPDatabase } from 'idb'
+import type { BusinessMapsDB } from './idbSchema'
+import { DB_NAME, DB_VERSION } from './idbSchema'
+
+// ── Singleton IDB connection ────────────────────────────────────────────────
+//
+// The layer owns the IDB connection because IndexedDB only allows one upgrade
+// callback per database version. Splitting the upgrade between layer and app
+// would create a coordination problem (which side runs first on a fresh user?
+// who creates the legacy stores?). The clean answer is that the layer owns
+// the connection and the upgrade callback creates every store the database
+// needs to function - model-tier stores fully typed, legacy stores typed as
+// `unknown` value (see idbSchema.ts).
+//
+// Consuming apps access the same connection by re-exporting `getDb` and
+// `closeDb` from this module via a thin proxy in their own codebase.
+
+let _db: Promise<IDBPDatabase<BusinessMapsDB>> | null = null
+
+export function getDb(): Promise<IDBPDatabase<BusinessMapsDB>> {
+  if (!_db) {
+    _db = openDB<BusinessMapsDB>(DB_NAME, DB_VERSION, {
+      upgrade(db, oldVersion) {
+        // Legacy stores (created by older versions of the consuming app).
+        // Layer creates them with no value typing because the layer never
+        // reads or writes them - they exist so the app's helpers can.
+        if (!db.objectStoreNames.contains('documents')) {
+          db.createObjectStore('documents', { keyPath: 'id' })
+        }
+        if (!db.objectStoreNames.contains('branches')) {
+          db.createObjectStore('branches', { keyPath: 'mapId' })
+        }
+        if (!db.objectStoreNames.contains('history')) {
+          db.createObjectStore('history', { keyPath: 'mapId' })
+        }
+        if (!db.objectStoreNames.contains('config')) {
+          db.createObjectStore('config', { keyPath: 'key' })
+        }
+        if (!db.objectStoreNames.contains('tabs')) {
+          db.createObjectStore('tabs', { keyPath: 'workspaceId' })
+        }
+        if (!db.objectStoreNames.contains('conversations')) {
+          db.createObjectStore('conversations', { keyPath: 'id' })
+        }
+        if (!db.objectStoreNames.contains('blobs')) {
+          db.createObjectStore('blobs', { keyPath: 'id' })
+        }
+        if (!db.objectStoreNames.contains('sync_queue')) {
+          db.createObjectStore('sync_queue', {
+            keyPath: 'id',
+            autoIncrement: true,
+          })
+        }
+
+        // Model-tier stores (commit-sourced persistence, v2).
+        if (oldVersion < 2) {
+          const commits = db.createObjectStore('commits', { keyPath: 'id' })
+          commits.createIndex('by-map-branch-seq', ['mapId', 'branchId', 'sequence'])
+
+          const checkpoints = db.createObjectStore('checkpoints', { keyPath: 'id' })
+          checkpoints.createIndex('by-map-branch-seq', ['mapId', 'branchId', 'sequence'])
+
+          db.createObjectStore('heads', { keyPath: ['mapId', 'branchId'] })
+        }
+      },
+    }).catch(err => {
+      console.warn('[persistence] IndexedDB unavailable - data will not persist this session:', err.message)
+      throw err
+    })
+  }
+  return _db
+}
+
+/** Close connection and reset singleton (for tests and cleanup). */
+export function closeDb(): void {
+  if (_db) {
+    _db.then(db => db.close())
+    _db = null
+  }
+}

package/composables/idbHelpers.ts

@@ -0,0 +1,165 @@
+import type { IDBCommitRecord, IDBCheckpointRecord, IDBBranchHeadRecord } from './idbSchema'
+import { getDb } from './idbConnection'
+
+// ── Commit store helpers ──────────────────────────────────────────────
+
+export async function saveCommits(commits: IDBCommitRecord[]): Promise<void> {
+  if (commits.length === 0) return
+  const db = await getDb()
+  const tx = db.transaction('commits', 'readwrite')
+  for (const commit of commits) {
+    await tx.store.put(commit)
+  }
+  await tx.done
+}
+
+export async function loadCommitsSince(
+  mapId: string,
+  branchId: string,
+  sinceSequence: number,
+): Promise<IDBCommitRecord[]> {
+  const db = await getDb()
+  const index = db.transaction('commits', 'readonly').store.index('by-map-branch-seq')
+  const range = IDBKeyRange.bound(
+    [mapId, branchId, sinceSequence + 1],
+    [mapId, branchId, Number.MAX_SAFE_INTEGER],
+  )
+  return index.getAll(range)
+}
+
+// ── Checkpoint store helpers ─────────────────────────────────────────
+
+export async function saveCheckpoint(checkpoint: IDBCheckpointRecord): Promise<void> {
+  const db = await getDb()
+  await db.put('checkpoints', checkpoint)
+}
+
+export async function loadLatestCheckpoint(
+  mapId: string,
+  branchId: string,
+): Promise<IDBCheckpointRecord | null> {
+  const db = await getDb()
+  const index = db.transaction('checkpoints', 'readonly').store.index('by-map-branch-seq')
+  const range = IDBKeyRange.bound(
+    [mapId, branchId, 0],
+    [mapId, branchId, Number.MAX_SAFE_INTEGER],
+  )
+  // Get all and return the last one (highest sequence)
+  const all = await index.getAll(range)
+  return all.length > 0 ? all[all.length - 1]! : null
+}
+
+export async function pruneOldCheckpoints(
+  mapId: string,
+  branchId: string,
+  keepCount: number,
+): Promise<void> {
+  const db = await getDb()
+  const index = db.transaction('checkpoints', 'readwrite').store.index('by-map-branch-seq')
+  const range = IDBKeyRange.bound(
+    [mapId, branchId, 0],
+    [mapId, branchId, Number.MAX_SAFE_INTEGER],
+  )
+  const all = await index.getAll(range)
+  if (all.length <= keepCount) return
+
+  const tx = db.transaction('checkpoints', 'readwrite')
+  const toDelete = all.slice(0, all.length - keepCount)
+  for (const cp of toDelete) {
+    await tx.store.delete(cp.id)
+  }
+  await tx.done
+}
+
+// ── Branch head store helpers ────────────────────────────────────────
+
+export async function saveBranchHead(head: IDBBranchHeadRecord): Promise<void> {
+  const db = await getDb()
+  await db.put('heads', head)
+}
+
+// ── Sync cursor persistence ───────────────────────────────────────────
+//
+// The sync engine's `lastSyncedSequence` was originally ephemeral - held
+// only in the engine singleton and reset to 0 on every fresh page load.
+// That caused two user-visible failures:
+//
+//  1. After any refresh, the engine re-pushed every local commit starting
+//     from sequence 0, which 409'd against whatever the server already had.
+//  2. Navigating back then forward during an AI tool run could leave the
+//     engine thinking "0 commits synced" while the server had received
+//     200+ of them via `sync.schedulePush()` firing off `commits.value`
+//     before the debounced IDB flush caught up.
+//
+// We now persist the cursor alongside the branch head in the `config`
+// store under a keyed entry so it survives navigation, refresh, and tab
+// close. The value is a small JSON object keyed by `${mapId}:${branchId}`.
+//
+// `config` is typed as `unknown` at the layer (it's an app-owned legacy
+// store). We read/write via cast. If a future schema lifts it into the
+// typed layer surface, these helpers become the migration site.
+
+// The `config` store has `keyPath: 'key'` (see idbConnection.ts) so records
+// must carry the primary key inline as a `key` field. The value is a small
+// JSON object keyed by `sync-cursor:${mapId}:${branchId}`.
+interface SyncCursorRecord {
+  key: string
+  mapId: string
+  branchId: string
+  lastSyncedSequence: number
+  updatedAt: string
+}
+
+function syncCursorKey(mapId: string, branchId: string): string {
+  return `sync-cursor:${mapId}:${branchId}`
+}
+
+export async function saveSyncCursor(
+  mapId: string,
+  branchId: string,
+  lastSyncedSequence: number,
+): Promise<void> {
+  const db = await getDb()
+  const record: SyncCursorRecord = {
+    key: syncCursorKey(mapId, branchId),
+    mapId,
+    branchId,
+    lastSyncedSequence,
+    updatedAt: new Date().toISOString(),
+  }
+  // The `config` store is typed as `unknown` in the layer schema - the
+  // double-cast tells TypeScript we know what we're doing. The key is
+  // pulled from `record.key` via the store's keyPath.
+  await db.put('config', record as unknown as never)
+}
+
+export async function loadSyncCursor(
+  mapId: string,
+  branchId: string,
+): Promise<number> {
+  const db = await getDb()
+  const record = (await db.get('config', syncCursorKey(mapId, branchId))) as
+    | SyncCursorRecord
+    | undefined
+  return record?.lastSyncedSequence ?? 0
+}
+
+export async function clearSyncCursor(
+  mapId: string,
+  branchId: string,
+): Promise<void> {
+  const db = await getDb()
+  await db.delete('config', syncCursorKey(mapId, branchId))
+}
+
+// ── Storage quota helpers ─────────────────────────────────────────────
+
+export async function checkStorageQuota(): Promise<{
+  usage: number
+  quota: number
+  percentUsed: number
+} | null> {
+  if (!navigator.storage?.estimate) return null
+  const { usage = 0, quota = 0 } = await navigator.storage.estimate()
+  return { usage, quota, percentUsed: quota > 0 ? (usage / quota) * 100 : 0 }
+}

package/composables/idbSchema.ts

@@ -0,0 +1,93 @@
+import type { DBSchema } from 'idb'
+import type { RootContext } from '@businessmaps/metaontology/types/context'
+import type { DispatchableCommand } from '@businessmaps/metaontology/types/commands'
+import type { M0State } from '@businessmaps/metaontology/types/m0'
+
+// ── Model-tier records (layer-owned persistence) ────────────────────────────
+//
+// These three records are the model-tier persistence layer. They live in the
+// ontology layer because the engine owns commit-sourced state derivation.
+// The consuming app's view-state records (documents, branches, history, tabs,
+// conversations, blobs, sync_queue) are typed in the app's own schema file.
+// The layer's BusinessMapsDB schema below names those
+// stores so the upgrade callback can create them, but types their values as
+// `unknown` - the layer never reads or writes them directly.
+
+export interface IDBCommitRecord {
+  id: string
+  mapId: string
+  branchId: string
+  sequence: number
+  command: DispatchableCommand
+  inverse: DispatchableCommand
+  timestamp: string
+  deviceId: string
+  parentId: string | null
+}
+
+export interface IDBCheckpointRecord {
+  id: string
+  mapId: string
+  branchId: string
+  commitId: string
+  sequence: number
+  model: RootContext
+  m0?: M0State
+  timestamp: string
+}
+
+export interface IDBBranchHeadRecord {
+  mapId: string
+  branchId: string
+  name: string
+  headCommitId: string
+  forkPointCommitId: string
+  parentBranchId: string
+  createdAt: string
+}
+
+// ── BusinessMapsDB ──────────────────────────────────────────────────────────
+//
+// The full IDB schema for the `businessmaps` database. The layer owns the
+// connection (because IDB only allows one upgrade callback per DB version),
+// so the layer's schema must name every store. Legacy stores have their value
+// types narrowed to `unknown` - the layer doesn't import app types. The
+// consuming app re-exports a typed view of the same database in its own
+// schema file for its own helpers.
+
+export interface BusinessMapsDB extends DBSchema {
+  // ── Model-tier (layer-owned, fully typed) ──
+  commits: {
+    key: string
+    value: IDBCommitRecord
+    indexes: { 'by-map-branch-seq': [string, string, number] }
+  }
+  checkpoints: {
+    key: string
+    value: IDBCheckpointRecord
+    indexes: { 'by-map-branch-seq': [string, string, number] }
+  }
+  heads: {
+    key: [string, string]  // [mapId, branchId]
+    value: IDBBranchHeadRecord
+  }
+
+  // ── Legacy / canvas-tier (app-owned, narrowed to unknown at the layer) ──
+  documents: { key: string; value: unknown }
+  branches: { key: string; value: unknown }
+  history: { key: string; value: unknown }
+  config: { key: string; value: unknown }
+  tabs: { key: string; value: unknown }
+  conversations: { key: string; value: unknown }
+  blobs: { key: string; value: unknown }
+  sync_queue: {
+    key: number
+    value: unknown
+    autoIncrement: true
+  }
+}
+
+export const DB_NAME = 'businessmaps'
+export const DB_VERSION = 3
+
+export const MODEL_STORE_NAMES = ['commits', 'checkpoints', 'heads'] as const

package/composables/syncTypes.ts

@@ -0,0 +1,145 @@
+import type { Commit } from '@businessmaps/metaontology/types/commits'
+
+// ── Sync target descriptor ──────────────────────────────────────────────────
+// A named destination where commits are pushed. Maps without auth have no
+// target (local only). The target is the declared identity of sync, not an
+// implementation detail.
+
+export type SyncTargetKind = 'cloud' | 'filesystem'
+
+export interface SyncTargetDescriptor {
+  kind: SyncTargetKind
+  label: string          // "Business Maps Cloud", "~/projects/mymap"
+  icon: 'cloud' | 'folder'
+}
+
+// ── Sync status ─────────────────────────────────────────────────────────────
+
+export type SyncStatus = 'idle' | 'pushing' | 'pulling' | 'conflict' | 'error'
+
+// ── Error categories ────────────────────────────────────────────────────────
+// Classification of sync failures so the UI can show a friendly message and
+// the engine can adjust its retry/log behavior. The raw error string is still
+// available via `lastError` for advanced views; `errorCategory` drives default
+// UX. Add new categories here as new failure modes appear in the wild.
+
+export type SyncErrorCategory =
+  | 'network'    // generic network failure (DNS, fetch failed, ECONNREFUSED, offline)
+  | 'cors'       // CORS preflight rejection - usually a misconfigured bucket
+  | 'auth'       // 401/403 - token expired, no permission
+  | 'conflict'   // 409 - remote has newer changes (covered by status='conflict' too)
+  | 'server'     // 5xx - remote service is broken
+  | 'crypto'     // missing/invalid encryption key
+  | 'unknown'    // doesn't match any of the above
+
+/**
+ * Classify a thrown error or error message into a SyncErrorCategory.
+ *
+ * Used by both `useSyncEngine` (to drive log throttling and category-aware
+ * retry decisions) and the UI (to render friendly status text). Pure: takes
+ * any value, returns one category. Defensive against unknown error shapes.
+ */
+export function classifySyncError(e: unknown): SyncErrorCategory {
+  if (!e) return 'unknown'
+
+  // Status-code-based classification - most reliable signal when present.
+  const status = (e as { statusCode?: number; status?: number }).statusCode
+    ?? (e as { statusCode?: number; status?: number }).status
+  if (status === 401 || status === 403) return 'auth'
+  if (status === 409) return 'conflict'
+  if (status && status >= 500 && status < 600) return 'server'
+
+  const message = e instanceof Error ? e.message : String(e)
+  const lower = message.toLowerCase()
+
+  // CORS-specific patterns. Browsers report CORS failures as "fetch failed"
+  // or "Failed to fetch" with no status code (preflight blocked). The most
+  // reliable signal is `ERR_FAILED` in the message or a fetch failure with
+  // no status against a known cross-origin endpoint.
+  if (lower.includes('cors')) return 'cors'
+  if (lower.includes('err_failed') && lower.includes('fetch')) return 'cors'
+
+  // Network-down / unreachable patterns. The two distinct patterns here
+  // come from different runtimes:
+  //  - Browser fetch: "Failed to fetch", "NetworkError", and the bare
+  //    "net::ERR_FAILED" Chrome surfaces when the OS-level connection
+  //    cannot complete (also surfaces for opaque CORS preflight failures
+  //    where the browser refuses to expose the response to JS).
+  //  - Node fetch: ECONNREFUSED, ENOTFOUND, ETIMEDOUT.
+  if (lower.includes('failed to fetch')) return 'network'
+  if (lower.includes('networkerror')) return 'network'
+  if (lower.includes('err_failed')) return 'network'
+  if (lower.includes('econnrefused')) return 'network'
+  if (lower.includes('enotfound')) return 'network'
+  if (lower.includes('etimedout')) return 'network'
+  if (lower.includes('offline')) return 'network'
+
+  // Crypto/auth-key cases (the adapter returns these as Error('No encryption key')).
+  if (lower.includes('encryption key')) return 'crypto'
+
+  return 'unknown'
+}
+
+/**
+ * Map a SyncErrorCategory to a short, user-facing status string. Used in the
+ * branch manager dropdown and the sync indicator. Keep these terse - the
+ * dropdown is narrow, and the user wants to know "is sync working?" first,
+ * "why not?" second.
+ */
+export function friendlySyncErrorMessage(category: SyncErrorCategory): string {
+  switch (category) {
+    case 'network':  return 'Cloud unreachable - working locally'
+    case 'cors':     return 'Cloud sync misconfigured (CORS)'
+    case 'auth':     return 'Sign-in expired'
+    case 'conflict': return 'Remote has newer changes - pull required'
+    case 'server':   return 'Cloud sync temporarily unavailable'
+    case 'crypto':   return 'Encryption key missing'
+    case 'unknown':  return 'Sync error'
+  }
+}
+
+// ── Adapter result types ────────────────────────────────────────────────────
+
+export interface PushResult {
+  success: boolean
+  newHeadSequence: number
+  error?: string
+  conflict?: boolean      // 409 - remote has newer changes
+}
+
+export interface PullResult {
+  success: boolean
+  commits: Commit[]
+  remoteHead: number
+  error?: string
+}
+
+// ── Sync adapter interface ──────────────────────────────────────────────────
+// Transport-agnostic contract for pushing/pulling commits to a sync target.
+// Encryption, HTTP, presigned URLs, filesystem writes - all internal to the
+// adapter. The sync engine doesn't care how commits move, only that they do.
+
+export interface SyncAdapter {
+  readonly descriptor: SyncTargetDescriptor
+
+  /** Push local commits to the remote target. */
+  push(
+    mapId: string,
+    branchId: string,
+    commits: Commit[],
+    baseSequence: number,
+  ): Promise<PushResult>
+
+  /** Pull remote commits since a given sequence. */
+  pull(
+    mapId: string,
+    branchId: string,
+    sinceSequence: number,
+  ): Promise<PullResult>
+
+  /** Get the current remote head sequence for optimistic locking. */
+  getRemoteHead(
+    mapId: string,
+    branchId: string,
+  ): Promise<number>
+}