@spooky-sync/core 0.0.1-canary.153 → 0.0.1-canary.155

package/src/modules/data/mutation-id.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { mintMutationId, mutationOwnerTabId } from './mutation-id';
+
+// The old `_00_pending_mutations:${Date.now()}` collided within a millisecond
+// (guaranteed once multiple tabs share a store) and never actually ordered the
+// drain. These pin the new id's three properties: unique, sortable, routable.
+describe('mutation ids', () => {
+  it('never collides within a burst', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => mintMutationId('tabx')));
+    expect(ids.size).toBe(1000);
+  });
+
+  it('sorts lexicographically in mint order (ORDER BY id is chronological)', () => {
+    const ids = Array.from({ length: 200 }, () => mintMutationId('tabx'));
+    expect([...ids].sort()).toEqual(ids);
+  });
+
+  it('routes back to the owning tab', () => {
+    expect(mutationOwnerTabId(mintMutationId('tab-abc'))).toBe('tab-abc');
+  });
+
+  it('returns null for a legacy numeric id instead of misrouting', () => {
+    expect(mutationOwnerTabId('_00_pending_mutations:1753875000000')).toBeNull();
+  });
+});

package/src/modules/data/mutation-id.ts

@@ -0,0 +1,35 @@
+/**
+ * Outbox mutation ids. Previously `_00_pending_mutations:${Date.now()}`, which
+ * (a) collides when two mutations land in the same millisecond, a real case
+ * once multiple tabs share one store, and (b) never actually ordered the
+ * drain, because `loadFromDatabase` sorted by a `created_at` field that does
+ * not exist on the table. The new shape is sortable AND collision-free:
+ *
+ *   <13-digit zero-padded ms timestamp>_<4-digit base36 seq>_<tabId>
+ *
+ * Lexicographic order == chronological order (per tab; cross-tab within-ms
+ * ordering is arbitrary, which matches reality), so `ORDER BY id` in the
+ * drain is now meaningful. The tabId suffix also routes rollbacks back to the
+ * tab that owns the mutation in shared-tabs mode.
+ */
+
+let seq = 0;
+
+/** Tab identity for mutation ids in SOLO mode, minted once per session. In
+ *  shared-tabs mode the coordinator's tabId is passed in instead. */
+const FALLBACK_TAB_ID = Math.random().toString(36).slice(2, 8);
+
+export function mintMutationId(tabId?: string): string {
+  const ts = Date.now().toString().padStart(13, '0');
+  const n = (seq = (seq + 1) % 36 ** 4).toString(36).padStart(4, '0');
+  return `_00_pending_mutations:${ts}_${n}_${tabId ?? FALLBACK_TAB_ID}`;
+}
+
+/** The tab that created the mutation, or null for a legacy numeric id. */
+export function mutationOwnerTabId(mutationId: string): string | null {
+  const raw = mutationId.startsWith('_00_pending_mutations:')
+    ? mutationId.slice('_00_pending_mutations:'.length)
+    : mutationId;
+  const parts = raw.split('_');
+  return parts.length >= 3 ? parts[parts.length - 1] : null;
+}

package/src/modules/devtools/index.ts

@@ -22,6 +22,7 @@ import {
   parseBackendInfo,
   UNAVAILABLE,
 } from './versions';
+import { walkOpfs, type StorageInfo } from './storage-info';
 
 // Real bundled frontend versions, injected at build time by tsdown's
 // version-define plugin (see tsdown.config.ts). The `typeof` guard keeps these
@@ -50,6 +51,13 @@ export class DevToolsService implements StreamUpdateReceiver {
   // (the on-demand GET_STATE pull) still works before the push channel turns on.
   private enabled = false;
 
+  /** Shared-tabs snapshot for the panel, wired by Sp00kyClient when active. */
+  private tabsInfoProvider: (() => Record<string, unknown> | null) | null = null;
+
+  setTabsInfoProvider(provider: () => Record<string, unknown> | null): void {
+    this.tabsInfoProvider = provider;
+  }
+
   // Full local table list (incl. internal `_00_*`), enumerated from the local DB
   // via our own reliable `service.query` — the DevTools panel's page-eval query
   // bridge is unreliable under load, so the panel relies on this instead.
@@ -326,10 +334,78 @@ export class DevToolsService implements StreamUpdateReceiver {
         // Durability of the local store. `fallback: true` means persistence was
         // requested but the dataset is actually sitting in RAM.
         storage: this.databaseService.storageHealth ?? { status: 'unknown', fallback: false },
+        // Shared-tabs role state (null when the feature is off / fell back).
+        tabs: this.tabsInfoProvider?.() ?? null,
       },
     });
   }
 
+  /**
+   * Full storage diagnostics for the DevTools Storage tab. Every section is
+   * gathered independently and failures land in that section's `error` field,
+   * so one broken source (a mid-switch worker, a browser without OPFS) never
+   * blanks the whole panel.
+   */
+  public async getStorageInfo(opts?: { tableCounts?: boolean }): Promise<StorageInfo> {
+    const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+
+    const info: StorageInfo = {
+      at: Date.now(),
+      engine: {
+        kind: this.databaseService.engineKind ?? 'custom',
+        store: this.databaseService.getConfig()?.store ?? 'memory',
+        bucketId: this.databaseService.currentBucketId,
+      },
+      health: this.databaseService.storageHealth ?? { status: 'unknown', fallback: false },
+      browser: {},
+      opfs: { supported: false, entries: [], totalBytes: 0, truncated: false },
+    };
+
+    try {
+      if (nav?.storage?.estimate) {
+        const est = await nav.storage.estimate();
+        info.browser.usage = est.usage;
+        info.browser.quota = est.quota;
+        // Chrome-only per-storage-system breakdown; absent elsewhere.
+        const details = (est as any).usageDetails;
+        if (details && typeof details === 'object') info.browser.usageDetails = details;
+      }
+      if (nav?.storage?.persisted) {
+        info.browser.persisted = await nav.storage.persisted();
+      }
+    } catch (e) {
+      info.browser.error = e instanceof Error ? e.message : String(e);
+    }
+
+    info.opfs = await walkOpfs();
+
+    const stats = (globalThis as any).__sqliteStats;
+    if (stats && typeof stats === 'object') {
+      info.sqliteStats = { ...stats, byType: { ...(stats.byType ?? {}) } };
+    }
+
+    try {
+      info.engineDiagnostics = await this.databaseService.getStorageDiagnostics?.(opts);
+    } catch (e) {
+      this.logger.warn(
+        { err: e, Category: 'sp00ky-client::DevToolsService::getStorageInfo' },
+        'Engine storage diagnostics failed'
+      );
+    }
+
+    return this.serializeForDevTools(info);
+  }
+
+  /** Ask the browser to exempt this origin's storage from eviction. */
+  public async requestPersistentStorage(): Promise<{ granted: boolean }> {
+    try {
+      const granted = (await navigator.storage?.persist?.()) ?? false;
+      return { granted };
+    } catch {
+      return { granted: false };
+    }
+  }
+
   private notifyDevTools() {
     // No consumer attached → no getState() serialization, no postMessage broadcast.
     if (!this.enabled) return;
@@ -383,6 +459,10 @@ export class DevToolsService implements StreamUpdateReceiver {
       const result: Record<string, any> = {};
       for (const key in data) {
         if (Object.prototype.hasOwnProperty.call(data, key)) {
+          // Skip absent optional fields: recursing them would emit the STRING
+          // 'undefined' (the top-level mapping below), which panels then have
+          // to filter back out (see 3d84fe8a).
+          if (data[key] === undefined) continue;
           result[key] = this.serializeForDevTools(data[key], seen);
         }
       }
@@ -402,6 +482,8 @@ export class DevToolsService implements StreamUpdateReceiver {
           this.notifyDevTools();
         },
         refreshVersions: () => this.refreshBackendVersions(),
+        getStorageInfo: (opts?: { tableCounts?: boolean }) => this.getStorageInfo(opts),
+        requestPersistentStorage: () => this.requestPersistentStorage(),
         getTableData: async (tableName: string) => {
           try {
             // Returns the first statement result as T.

package/src/modules/devtools/storage-info.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { walkOpfs } from './storage-info';
+
+/** Minimal in-memory OPFS: directories are nested objects, files are numbers
+ *  (their size) or 'locked' (getFile() throws, like a live SAHPool handle). */
+type FakeTree = { [name: string]: FakeTree | number | 'locked' };
+
+function makeDirHandle(tree: FakeTree): any {
+  return {
+    kind: 'directory',
+    entries: async function* () {
+      for (const [name, node] of Object.entries(tree)) {
+        if (typeof node === 'object') {
+          yield [name, makeDirHandle(node)];
+        } else {
+          yield [
+            name,
+            {
+              kind: 'file',
+              getFile: async () => {
+                if (node === 'locked') throw new DOMException('locked', 'NoModificationAllowedError');
+                return { size: node };
+              },
+            },
+          ];
+        }
+      }
+    },
+  };
+}
+
+function stubOpfs(tree: FakeTree | null) {
+  vi.stubGlobal('navigator', tree === null ? {} : {
+    storage: { getDirectory: async () => makeDirHandle(tree) },
+  });
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('walkOpfs', () => {
+  it('reports unsupported without OPFS APIs', async () => {
+    stubOpfs(null);
+    expect(await walkOpfs()).toEqual({
+      supported: false,
+      entries: [],
+      totalBytes: 0,
+      truncated: false,
+    });
+  });
+
+  it('walks recursively, sums readable sizes, and omits size for locked files', async () => {
+    stubOpfs({
+      '.sp00ky-anon': { '0000000001': 4096, '0000000002': 'locked' },
+      'other.txt': 10,
+    });
+    const res = await walkOpfs();
+    expect(res.supported).toBe(true);
+    expect(res.truncated).toBe(false);
+    // Locked file present but without a size; total counts only readable bytes.
+    expect(res.totalBytes).toBe(4106);
+    expect(res.entries).toEqual([
+      { path: '.sp00ky-anon', kind: 'directory' },
+      { path: '.sp00ky-anon/0000000001', kind: 'file', size: 4096 },
+      { path: '.sp00ky-anon/0000000002', kind: 'file' },
+      { path: 'other.txt', kind: 'file', size: 10 },
+    ]);
+  });
+
+  it('caps the listing and flags truncation', async () => {
+    const big: FakeTree = {};
+    for (let i = 0; i < 10; i++) big[`f${i}`] = 1;
+    stubOpfs(big);
+    const res = await walkOpfs(5);
+    expect(res.truncated).toBe(true);
+    expect(res.entries.length).toBe(5);
+  });
+});

package/src/modules/devtools/storage-info.ts

@@ -0,0 +1,116 @@
+/**
+ * Storage diagnostics for the DevTools Storage tab: what engine backs the
+ * local cache, whether it actually persists, how much of the device's quota
+ * the origin uses, and what is physically sitting in OPFS. Assembled by
+ * `DevToolsService.getStorageInfo()`; everything here is JSON-safe.
+ */
+
+export interface OpfsEntry {
+  /** Path relative to the OPFS root, e.g. `.sp00ky-anon/0000000000000001`. */
+  path: string;
+  kind: 'file' | 'directory';
+  /** Absent when the file's size can't be read (e.g. an exclusive sync access
+   *  handle is held on it — exactly the case during SAHPool contention). */
+  size?: number;
+}
+
+/** Engine-side numbers only the engine can produce (worker round-trips). */
+export interface EngineStorageDiagnostics {
+  engine: 'sqlite';
+  bucketId: string;
+  useOpfs: boolean;
+  workerSelectConfigured: boolean;
+  /** `false` while configured `true` means the runtime downgraded to the
+   *  legacy multi-hop select (stale cached worker bundle). */
+  workerSelectEffective: boolean;
+  /** page_count * page_size. */
+  dbSizeBytes?: number;
+  /** freelist_count * page_size — reclaimable via VACUUM. */
+  freelistBytes?: number;
+  tableCounts?: { table: string; rows: number }[];
+  error?: string;
+}
+
+export interface StorageInfo {
+  at: number;
+  engine: { kind: 'surrealdb' | 'sqlite' | 'custom'; store: string; bucketId: string };
+  health: { status: 'unknown' | 'persistent' | 'memory'; fallback: boolean; error?: string };
+  browser: {
+    /** `navigator.storage.persisted()` — whether the origin's storage is
+     *  exempt from eviction (unrelated to the OPFS pool lock). */
+    persisted?: boolean;
+    usage?: number;
+    quota?: number;
+    /** Chrome-only per-system breakdown from `estimate()`. */
+    usageDetails?: Record<string, number>;
+    error?: string;
+  };
+  opfs: {
+    supported: boolean;
+    entries: OpfsEntry[];
+    totalBytes: number;
+    truncated: boolean;
+    error?: string;
+  };
+  /** Snapshot of `globalThis.__sqliteStats` (SQLite engine only). */
+  sqliteStats?: Record<string, unknown>;
+  engineDiagnostics?: EngineStorageDiagnostics;
+}
+
+/**
+ * Recursively list the origin's OPFS. Sizes come from `handle.getFile()`,
+ * which throws for a file another context holds an exclusive sync access
+ * handle on — SAHPool does exactly that for its whole pool, so a locked file
+ * (size omitted) is a live "who has the pool" signal, not a failure.
+ */
+export async function walkOpfs(maxEntries = 2000, maxDepth = 8): Promise<StorageInfo['opfs']> {
+  const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+  if (!nav?.storage?.getDirectory) {
+    return { supported: false, entries: [], totalBytes: 0, truncated: false };
+  }
+  const entries: OpfsEntry[] = [];
+  let totalBytes = 0;
+  let truncated = false;
+  try {
+    const root = await nav.storage.getDirectory();
+    const walk = async (dir: FileSystemDirectoryHandle, prefix: string, depth: number) => {
+      if (depth > maxDepth) return;
+      // entries() is standard; older lib.dom typings may lack it.
+      for await (const [name, handle] of (dir as any).entries() as AsyncIterable<
+        [string, FileSystemHandle]
+      >) {
+        if (entries.length >= maxEntries) {
+          truncated = true;
+          return;
+        }
+        const path = prefix ? `${prefix}/${name}` : name;
+        if (handle.kind === 'directory') {
+          entries.push({ path, kind: 'directory' });
+          await walk(handle as FileSystemDirectoryHandle, path, depth + 1);
+        } else {
+          let size: number | undefined;
+          try {
+            size = (await (handle as FileSystemFileHandle).getFile()).size;
+            totalBytes += size;
+          } catch {
+            // Locked by an exclusive access handle (e.g. a live SAHPool).
+          }
+          const entry: OpfsEntry = { path, kind: 'file' };
+          if (size !== undefined) entry.size = size;
+          entries.push(entry);
+        }
+      }
+    };
+    await walk(root, '', 0);
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { supported: true, entries, totalBytes, truncated };
+  } catch (e) {
+    return {
+      supported: true,
+      entries,
+      totalBytes,
+      truncated,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}

package/src/modules/sync/queue/queue-up.forwarded.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from 'vitest';
+import { UpQueue } from './queue-up';
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+const ROW = {
+  id: '_00_pending_mutations:0001753875000000_0001_tabB',
+  mutationType: 'create',
+  recordId: 'game:g1',
+  data: { title: 'x' },
+};
+
+// Shared-tabs: followers commit outbox rows into the shared store and notify
+// the leader by id. The notify may be REPLAYED (failover buffering), so the
+// enqueue must be idempotent, and only the leader ever drains.
+describe('UpQueue.enqueueFromDatabase', () => {
+  function makeQueue(rows: Record<string, unknown[]>) {
+    const query = vi.fn(async (_sql: string, vars?: Record<string, unknown>) => {
+      const id = String(vars?.mutation_id ?? '');
+      return [rows[id] ?? []];
+    });
+    const local: any = { query };
+    return { queue: new UpQueue(local, makeLogger()), query };
+  }
+
+  it('loads exactly the forwarded row and enqueues it once', async () => {
+    const { queue } = makeQueue({ [ROW.id]: [ROW] });
+    await queue.enqueueFromDatabase(ROW.id);
+    expect(queue.size).toBe(1);
+  });
+
+  it('is idempotent: a replayed notify does not double-enqueue', async () => {
+    const { queue, query } = makeQueue({ [ROW.id]: [ROW] });
+    await queue.enqueueFromDatabase(ROW.id);
+    await queue.enqueueFromDatabase(ROW.id);
+    expect(queue.size).toBe(1);
+    // The second call short-circuits before even touching the store.
+    expect(query).toHaveBeenCalledTimes(1);
+  });
+
+  it('a row that never committed is a silent no-op (the app promise already rejected)', async () => {
+    const { queue } = makeQueue({});
+    await queue.enqueueFromDatabase(ROW.id);
+    expect(queue.size).toBe(0);
+  });
+});

package/src/modules/sync/queue/queue-up.ts

@@ -6,7 +6,12 @@ import {
   createSyncQueueEventSystem,
   SyncQueueEventTypes,
 } from '../events/index';
-import { parseRecordIdString, extractTablePart, classifySyncError } from '../../../utils/index';
+import {
+  parseRecordIdString,
+  extractTablePart,
+  classifySyncError,
+  encodeRecordId,
+} from '../../../utils/index';
 import type { Logger } from '../../../services/logger/index';
 import type { PushEventOptions } from '../../../events/index';
 
@@ -184,49 +189,41 @@ export class UpQueue {
     return this.local.query(`DELETE $mutation_id`, { mutation_id });
   }
 
+  /**
+   * Shared-tabs: a follower committed an outbox row into the shared store and
+   * notified the leader; enqueue exactly that row. Idempotent: a replayed
+   * notify (failover) or a row already queued is a no-op, and a row that never
+   * committed simply is not found (the follower's own write promise already
+   * rejected in that case).
+   */
+  async enqueueFromDatabase(mutationId: string): Promise<void> {
+    if (this.queue.some((e) => encodeUpEventId(e) === mutationId)) return;
+    try {
+      const [records] = await this.local.query<any>(`SELECT * FROM $mutation_id`, {
+        mutation_id: parseRecordIdString(mutationId),
+      });
+      const event = Array.isArray(records) && records[0] ? rowToUpEvent(records[0], this.logger) : null;
+      if (event) this.addToQueue(event);
+    } catch (error) {
+      this.logger.error(
+        { error, mutationId, Category: 'sp00ky-client::UpQueue::enqueueFromDatabase' },
+        'Failed to load a forwarded mutation'
+      );
+    }
+  }
+
   async loadFromDatabase() {
     try {
+      // ORDER BY id: mutation ids are zero-padded-timestamp-prefixed (see
+      // modules/data/mutation-id.ts), so lexicographic id order IS chronological
+      // order. (The previous created_at was never a defined field on this
+      // table, so the old ordering was undefined.)
       const [records] = await this.local.query<any>(
-        `SELECT * FROM _00_pending_mutations ORDER BY created_at ASC`
+        `SELECT * FROM _00_pending_mutations ORDER BY id ASC`
       );
 
       this.queue = records
-        .map((r: any): UpEvent | null => {
-          switch (r.mutationType) {
-            case 'create':
-              return {
-                type: 'create',
-                mutation_id: parseRecordIdString(r.id),
-                record_id: parseRecordIdString(r.recordId),
-                data: r.data,
-                tableName: extractTablePart(r.recordId),
-              };
-            case 'update':
-              return {
-                type: 'update',
-                mutation_id: parseRecordIdString(r.id),
-                record_id: parseRecordIdString(r.recordId),
-                data: r.data,
-                beforeRecord: r.beforeRecord,
-              };
-            case 'delete':
-              return {
-                type: 'delete',
-                mutation_id: parseRecordIdString(r.id),
-                record_id: parseRecordIdString(r.recordId),
-              };
-            default:
-              this.logger.warn(
-                {
-                  mutationType: r.mutationType,
-                  record: r,
-                  Category: 'sp00ky-client::UpQueue::loadFromDatabase',
-                },
-                'Unknown mutation type'
-              );
-              return null;
-          }
-        })
+        .map((r: any): UpEvent | null => rowToUpEvent(r, this.logger))
         .filter((e: UpEvent | null): e is UpEvent => e !== null);
     } catch (error) {
       this.logger.error(
@@ -236,3 +233,42 @@ export class UpQueue {
     }
   }
 }
+
+/** The stable string id of an event's outbox row. */
+function encodeUpEventId(event: UpEvent): string {
+  return encodeRecordId(event.mutation_id);
+}
+
+/** Materialize one `_00_pending_mutations` row into an UpEvent. */
+function rowToUpEvent(r: any, logger: Logger): UpEvent | null {
+  switch (r.mutationType) {
+    case 'create':
+      return {
+        type: 'create',
+        mutation_id: parseRecordIdString(r.id),
+        record_id: parseRecordIdString(r.recordId),
+        data: r.data,
+        tableName: extractTablePart(r.recordId),
+      };
+    case 'update':
+      return {
+        type: 'update',
+        mutation_id: parseRecordIdString(r.id),
+        record_id: parseRecordIdString(r.recordId),
+        data: r.data,
+        beforeRecord: r.beforeRecord,
+      };
+    case 'delete':
+      return {
+        type: 'delete',
+        mutation_id: parseRecordIdString(r.id),
+        record_id: parseRecordIdString(r.recordId),
+      };
+    default:
+      logger.warn(
+        { mutationType: r.mutationType, record: r, Category: 'sp00ky-client::UpQueue::rowToUpEvent' },
+        'Unknown mutation type'
+      );
+      return null;
+  }
+}

package/src/modules/sync/scheduler.ts

@@ -26,8 +26,10 @@ export class SyncScheduler {
     private onSyncOutcome?: (ok: boolean, error?: unknown) => void
   ) {}
 
-  async init() {
-    await this.upQueue.loadFromDatabase();
+  async init(opts: { loadOutbox?: boolean } = {}) {
+    // Shared-tabs followers skip the outbox load: the shared store's
+    // `_00_pending_mutations` is drained by exactly one tab (the leader).
+    if (opts.loadOutbox !== false) await this.upQueue.loadFromDatabase();
     this.upQueue.events.subscribe(SyncQueueEventTypes.MutationEnqueued, this.syncUp.bind(this));
     this.downQueue.events.subscribe(
       SyncQueueEventTypes.QueryItemEnqueued,