@spooky-sync/core 0.0.1-canary.290 → 0.0.1-canary.291

package/dist/types.d.ts

@@ -483,6 +483,71 @@ type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
 //#endregion
 //#region src/services/logger/index.d.ts
 type Logger$1 = Logger;
+/** One line the logger wrote, as the DevTools Logs tab and the MCP read it. */
+interface CapturedLog {
+  /** Monotonic for the page's lifetime; a reader resumes after the last one it holds. */
+  seq: number;
+  time: number;
+  /** Pino's numeric level: 10 trace … 60 fatal. */
+  level: number;
+  msg: string;
+  /** The whole log object as JSON (what the console printed), capped at {@link LogTap.LINE_MAX}. */
+  line: string;
+}
+interface LogRead {
+  entries: CapturedLog[];
+  /** `seq` of the newest captured line; pass it back as `after` to resume. */
+  head: number;
+  /** Lines after `after` the ring overwrote before they were read (cleared ones excluded). */
+  dropped: number;
+  consoleLevel: Level;
+  captureLevel: Level;
+}
+/**
+ * JSON for a log object that can never throw into the call site: Errors keep
+ * their message and stack (plain `JSON.stringify` prints `{}`), bigints become
+ * strings, and a cycle prints `[Circular]` instead of throwing.
+ */
+
+/**
+ * The page-side log buffer behind the DevTools Logs tab. Always on and
+ * bounded: a line costs the JSON the console write produces anyway, and a
+ * panel opened after boot still sees the boot.
+ *
+ * It also owns the logger's level. The console prints at the configured level
+ * only; `setCaptureLevel` changes what is RECORDED (debug without flooding the
+ * console), live on every child logger, and keeps it for this tab's session so
+ * a reload captures its boot at that level too.
+ */
+declare class LogTap {
+  readonly consoleLevel: Level;
+  static readonly CAPACITY = 500;
+  static readonly LINE_MAX = 4000;
+  private readonly ring;
+  private seq;
+  /** `seq` at the last `clear()`: lines up to here are gone on purpose, not dropped. */
+  private clearedThrough;
+  private readonly listeners;
+  private readonly loggers;
+  private captureLevelValue;
+  constructor(consoleLevel: Level);
+  /** `seq` of the newest captured line. */
+  get head(): number;
+  get captureLevel(): Level;
+  /** What pino has to produce for both the console and the buffer. */
+  get effectiveLevel(): Level;
+  /** Whether the console prints a line at this numeric level. */
+  printsToConsole(level: number): boolean;
+  /** Remember a logger (the root and every child) so a level change reaches it. */
+  track(logger: Logger$1): void;
+  setCaptureLevel(level: Level): void;
+  record(o: Record<string, unknown>, line: string): void;
+  /** Lines after `after` (0 = everything still buffered), oldest first. */
+  read(after?: number, limit?: number): LogRead;
+  clear(): void;
+  /** Called synchronously inside the log call: keep it cheap, never log from it. */
+  subscribe(cb: () => void): () => void;
+}
 //#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
@@ -2018,4 +2083,4 @@ interface DebounceOptions {
   flushOnHide?: boolean;
 }
 //#endregion
-export { WebPushSubscribeOptions as $, RunOptions as A, LocalStore as At, SyncHealthStatus as B, TokenClaims as Bt, QueryTimeToLive as C, SignOutHook as Ct, RecordVersionArray as D, createAuthEventSystem as Dt, ReconnectConfig as E, AuthEventTypes as Et, StorageHealth as F, ImpersonationInfo as Ft, WebPushConfig as G, UpdateOptions as H, impersonationFromToken as Ht, StorageHealthStatus as I, ImpersonationTimerHost as It, WebPushErrorCode as J, WebPushDevice as K, StoreType as L, ImpersonationTimers as Lt, Sp00kyConfig as M, EventDefinition as Mt, Sp00kyQueryResult as N, EventSystem as Nt, RecordVersionDiff as O, RemoteDatabaseService as Ot, Sp00kyQueryResultPromise as P, IMPERSONATION_ACCESS as Pt, WebPushModule as Q, SyncHealth as R, ORIGIN_TOKEN_KEY as Rt, QueryStatusCallback as S, SignOutContext as St, QueryUpdateCallback as T, AuthEventTypeMap as Tt, PUSH_ENDPOINT_KEY as U, renewDelayMs as Ut, TimingPhase as V, decodeTokenClaims as Vt, PushDeviceKind as W, sameImpersonation as Wt, WebPushMessage as X, WebPushInfo as Y, WebPushMessageInput as Z, QueryConfig as _, isPushPayload as _t, Level$1 as a, WebPushUpdateOptions as at, QueryState as b, ImpersonationCandidate as bt, MutationCallback as c, BridgeTokenMessage as ct, PersistenceClient as d, PushNotificationAction as dt, WebPushSupport as et, PhaseStat as f, PushOp as ft, QueryAuthorityCallback as g, WebPushClientMessage as gt, PreloadRefresh as h, PushUrgency as ht, InlineRow as i, WebPushUnsupportedReason as it, ServerViewMeta as j, SealedQuery as jt, RegistrationTimings as k, Logger$1 as kt, MutationEvent as l, PUSH_PAYLOAD_VERSION as lt, PreloadOptions as m, PushPayloadKind as mt, DebounceOptions as n, WebPushSyncStatus as nt, MATERIALIZATION_SAMPLE_WINDOW as o, detectWebPushSupport as ot, PinoTransmit as p, PushPayload as pt, WebPushError as q, EventSubscriptionOptions as r, WebPushUnsubscribeOptions as rt, MembershipOutcome as s, BridgeSignOutMessage as st, ConnectionState as t, WebPushSyncOptions as tt, MutationEventType as u, PushNotification as ut, QueryConfigRecord as v, ActiveImpersonation as vt, QueryTimings as w, AuthEventSystem as wt, QueryStatus as x, SIGN_OUT_HOOK_TIMEOUT_MS as xt, QueryHash as y, AuthService as yt, SyncHealthConfig as z, SESSION_POLL_MS as zt };
+export { WebPushSubscribeOptions as $, RunOptions as A, Logger$1 as At, SyncHealthStatus as B, SESSION_POLL_MS as Bt, QueryTimeToLive as C, SignOutHook as Ct, RecordVersionArray as D, createAuthEventSystem as Dt, ReconnectConfig as E, AuthEventTypes as Et, StorageHealth as F, IMPERSONATION_ACCESS as Ft, WebPushConfig as G, sameImpersonation as Gt, UpdateOptions as H, decodeTokenClaims as Ht, StorageHealthStatus as I, ImpersonationInfo as It, WebPushErrorCode as J, WebPushDevice as K, StoreType as L, ImpersonationTimerHost as Lt, Sp00kyConfig as M, SealedQuery as Mt, Sp00kyQueryResult as N, EventDefinition as Nt, RecordVersionDiff as O, RemoteDatabaseService as Ot, Sp00kyQueryResultPromise as P, EventSystem as Pt, WebPushModule as Q, SyncHealth as R, ImpersonationTimers as Rt, QueryStatusCallback as S, SignOutContext as St, QueryUpdateCallback as T, AuthEventTypeMap as Tt, PUSH_ENDPOINT_KEY as U, impersonationFromToken as Ut, TimingPhase as V, TokenClaims as Vt, PushDeviceKind as W, renewDelayMs as Wt, WebPushMessage as X, WebPushInfo as Y, WebPushMessageInput as Z, QueryConfig as _, isPushPayload as _t, Level$1 as a, WebPushUpdateOptions as at, QueryState as b, ImpersonationCandidate as bt, MutationCallback as c, BridgeTokenMessage as ct, PersistenceClient as d, PushNotificationAction as dt, WebPushSupport as et, PhaseStat as f, PushOp as ft, QueryAuthorityCallback as g, WebPushClientMessage as gt, PreloadRefresh as h, PushUrgency as ht, InlineRow as i, WebPushUnsupportedReason as it, ServerViewMeta as j, LocalStore as jt, RegistrationTimings as k, LogTap as kt, MutationEvent as l, PUSH_PAYLOAD_VERSION as lt, PreloadOptions as m, PushPayloadKind as mt, DebounceOptions as n, WebPushSyncStatus as nt, MATERIALIZATION_SAMPLE_WINDOW as o, detectWebPushSupport as ot, PinoTransmit as p, PushPayload as pt, WebPushError as q, EventSubscriptionOptions as r, WebPushUnsubscribeOptions as rt, MembershipOutcome as s, BridgeSignOutMessage as st, ConnectionState as t, WebPushSyncOptions as tt, MutationEventType as u, PushNotification as ut, QueryConfigRecord as v, ActiveImpersonation as vt, QueryTimings as w, AuthEventSystem as wt, QueryStatus as x, SIGN_OUT_HOOK_TIMEOUT_MS as xt, QueryHash as y, AuthService as yt, SyncHealthConfig as z, ORIGIN_TOKEN_KEY as zt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.290",
+  "version": "0.0.1-canary.291",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.290",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.290",
+    "@spooky-sync/query-builder": "0.0.1-canary.291",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.291",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/client/services.ts

@@ -2,7 +2,7 @@ import type { Uuid } from 'surrealdb';
 import type { SchemaStructure } from '@spooky-sync/query-builder';
 import type { Sp00kyConfig, PersistenceClient } from '../types';
 import type { Logger } from '../services/logger/index';
-import { createLogger } from '../services/logger/index';
+import { LogTap, createLogger } from '../services/logger/index';
 import { ConnectionSupervisor, LocalMigrator, RemoteDatabaseService, createLocalEngine } from '../services/database/index';
 import type { LocalStore } from '../services/database/index';
 import { StreamProcessorService } from '../services/stream-processor/index';
@@ -63,6 +63,8 @@ export function mintSalt(): string {
 /** Everything the facade talks to besides the runtime. */
 export interface Services<S extends SchemaStructure> {
   logger: Logger;
+  /** What the logger wrote, for the DevTools Logs tab. Absent in test fakes. */
+  logTap?: LogTap;
   local: LocalStore;
   remote: RemoteDatabaseService;
   connectionSupervisor: ConnectionSupervisor;
@@ -89,7 +91,8 @@ export interface ServiceHost {
 }
 
 export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S>): Services<S> {
-  const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit);
+  const logTap = new LogTap(config.logLevel ?? 'info');
+  const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit, logTap);
   if (config.crdt) void preloadLoro();
   const tabsSupport = detectSharedTabsSupport(config);
   const local = createLocalEngine(config.localEngine, config.database, logger, { shared: tabsSupport.supported });
@@ -119,6 +122,7 @@ export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S
   const tabId = typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `tab_${Math.random().toString(36).slice(2)}`;
   return {
     logger,
+    logTap,
     local,
     remote,
     connectionSupervisor,

package/src/client/sp00ky-client.test.ts

@@ -34,6 +34,36 @@ function makeClient(over: Parameters<typeof fakeAdapters>[0] = {}) {
 }
 
 describe('Sp00kyClient facade', () => {
+  it('hands DevTools the outbox and the failed tray', async () => {
+    const { client } = makeClient();
+    await client.init();
+    const source = (client as any).devTools.mutationSource;
+    expect(source.state()).toBe(client.state);
+    expect(await source.listFailed()).toEqual([]);
+    expect(await source.retryFailed('_00_pending_mutations:gone')).toBe(false);
+    expect(await source.discardFailed('_00_pending_mutations:gone')).toBe(false);
+  });
+
+  it('logs each finished statement at debug, and nothing below it', () => {
+    const { services } = makeClient();
+    const lines: unknown[] = [];
+    const log = services.logger as any;
+    log.debug = (fields: unknown, msg: string) => lines.push([fields, msg]);
+    log.isLevelEnabled = () => true;
+    const long = `SELECT * FROM thing WHERE ${'a = 1 AND '.repeat(30)}b = 2`;
+    services.emitStoreEvent('DATABASE_LOCAL_QUERY', { query: 'SELECT\n  1', vars: {}, duration: 1.234, success: true });
+    services.emitStoreEvent('DATABASE_REMOTE_QUERY', { query: long, duration: 3, success: false, error: 'boom' });
+    services.emitStoreEvent('DATABASE_LOCAL_QUERY', undefined);
+    log.isLevelEnabled = () => false;
+    services.emitStoreEvent('DATABASE_LOCAL_QUERY', { query: 'SELECT 3' });
+    expect(lines).toEqual([
+      [expect.objectContaining({ store: 'local', ms: 1.2, ok: true }), 'SELECT 1'],
+      [expect.objectContaining({ store: 'remote', query: long, ok: false, error: 'boom' }), `${long.slice(0, 160)}…`],
+      [expect.objectContaining({ store: 'local', ms: 0, ok: true }), ''],
+    ]);
+    expect((lines[0] as any[])[0].query).toBeUndefined();
+  });
+
   it('init resolves from the local store while the remote connect never does', async () => {
     const { client, a } = makeClient();
     expect(client.isLocalReady()).toBe(false);
@@ -178,7 +208,9 @@ describe('Sp00kyClient facade', () => {
     runtime.emit({ type: 'query:authority', hash: 'h', known: true });
     runtime.emit({ type: 'query:view-lost', hash: 'h' });
     runtime.emit({ type: 'mutation:event', event: { type: 'create', record_id: new RecordId('thing', '1'), data: {} } });
-    runtime.emit({ type: 'devtools', name: 'X', data: 1 });
+    runtime.emit({ type: 'mutation:settled', mutationId: 'm', recordId: 'thing:1', eventType: 'create' });
+    runtime.emit({ type: 'mutation:rolled-back', mutationId: 'm2', recordId: 'thing:1', eventType: 'update', error: 'denied' });
+    runtime.emit({ type: 'tray:changed', count: 1 });
     expect(await client.authenticate('tok')).toBe('tok');
     await client.deauthenticate();
     expect(await client.useRemote(async () => 'r')).toBe('r');

package/src/client/sp00ky-client.ts

@@ -59,6 +59,8 @@ import { ImpersonationBanner } from '../modules/auth/impersonation-banner';
 import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
 
 const UNKNOWN_STORAGE_HEALTH: StorageHealth = Object.freeze({ status: 'unknown', fallback: false });
+/** Longest SurrealQL a statement log line shows as its message. */
+const STATEMENT_MSG_MAX = 160;
 
 export interface Sp00kyClientDeps<S extends SchemaStructure> {
   services?: Services<S>;
@@ -168,6 +170,13 @@ export class Sp00kyClient<S extends SchemaStructure> {
     this.devTools.setFeatureFlagOverrides(this.featureFlags);
     s.streamProcessor.addReceiver(this.devTools);
     this.devTools.setBlobInfoProvider(() => s.blobs.stats());
+    this.devTools.setMutationSource({
+      state: () => this.runtime.state,
+      listFailed: () => this.listFailedMutations(),
+      retryFailed: (id) => this.retryFailedMutation(id),
+      discardFailed: (id) => this.discardFailedMutation(id),
+    });
+    if (s.logTap) this.devTools.setLogTap(s.logTap);
     if (config.sharedTabs) {
       this.devTools.setTabsInfoProvider(() => {
         const c = s.tabs;
@@ -219,26 +228,62 @@ export class Sp00kyClient<S extends SchemaStructure> {
       if (e.type === 'tabs:sendTo' && this.hub) this.hub.sendTo(e.tabId, e.message as never);
     });
     this.runtime.on('*', (e) => this.forwardToDevTools(e));
-    s.local.getEvents().subscribe('DATABASE_LOCAL_QUERY', (event: any) => this.devTools.logEvent('LOCAL_QUERY', event.payload));
-    s.remote.getEvents().subscribe('DATABASE_REMOTE_QUERY', (event: any) => this.devTools.logEvent('REMOTE_QUERY', event.payload));
+    // One debug line per finished statement, for both stores and every engine
+    // (the SQLite engine logs none of its own). Guarded: this is the hottest
+    // path there is, and at the default `info` the line is never written.
+    // The message is the SurrealQL itself, so the Logs tab reads like a query
+    // trail; a long statement is cut there and kept whole in `query`.
+    const logStatement = (store: 'local' | 'remote') => (event: any) => {
+      if (!s.logger.isLevelEnabled('debug')) return;
+      const q = event.payload ?? {};
+      const sql = String(q.query ?? '').replace(/\s+/g, ' ').trim();
+      const cut = sql.length > STATEMENT_MSG_MAX;
+      s.logger.debug(
+        {
+          store,
+          ...(cut ? { query: q.query } : {}),
+          vars: q.vars,
+          ms: Math.round((q.duration ?? 0) * 10) / 10,
+          ok: q.success !== false,
+          error: q.error,
+          Category: `sp00ky-client::${store}`,
+        },
+        cut ? `${sql.slice(0, STATEMENT_MSG_MAX)}…` : sql
+      );
+    };
+    s.local.getEvents().subscribe('DATABASE_LOCAL_QUERY', logStatement('local'));
+    s.remote.getEvents().subscribe('DATABASE_REMOTE_QUERY', logStatement('remote'));
   }
 
+  /** Runtime events the DevTools panel follows; query transitions also go to the log. */
   private forwardToDevTools(e: OutEvent): void {
+    const log = this.services.logger;
     switch (e.type) {
       case 'query:status':
-        this.devTools.logEvent('QUERY_STATUS_CHANGED', { queryHash: e.hash, status: e.status });
+        log.debug({ hash: e.hash, status: e.status, Category: 'sp00ky-client::query' }, 'Query status');
+        this.devTools.onStateChanged();
         break;
       case 'query:authority':
-        this.devTools.logEvent('QUERY_AUTHORITY_CHANGED', { queryHash: e.hash, known: e.known });
+        log.debug({ hash: e.hash, known: e.known, Category: 'sp00ky-client::query' }, e.known ? 'Query membership known' : 'Query membership unknown');
+        this.devTools.onStateChanged();
         break;
       case 'query:view-lost':
-        this.devTools.logEvent('QUERY_VIEW_LOST', { queryHash: e.hash });
+        log.info({ hash: e.hash, Category: 'sp00ky-client::query' }, 'Query view lost on the server; re-registering');
+        this.devTools.onStateChanged();
         break;
       case 'mutation:event':
         this.devTools.onMutation([e.event]);
         break;
-      case 'devtools':
-        this.devTools.logEvent(e.name, e.data);
+      case 'mutation:settled':
+        this.devTools.onMutationOutcome({ mutationId: e.mutationId, recordId: e.recordId, eventType: e.eventType, status: 'synced' });
+        break;
+      case 'mutation:rolled-back':
+        this.devTools.onMutationOutcome({ mutationId: e.mutationId, recordId: e.recordId, eventType: e.eventType, status: 'rolled-back', error: e.error });
+        break;
+      case 'tray:changed':
+      case 'health:changed':
+      case 'activity:changed':
+        this.devTools.onStateChanged();
         break;
       default:
         break;

package/src/kernel/events.ts

@@ -54,5 +54,4 @@ export type OutEvent =
   | { type: 'activity:changed'; fetching: number; pending: number }
   | { type: 'tabs:broadcast'; message: unknown }
   | { type: 'tabs:sendTo'; tabId: string; message: unknown }
-  | { type: 'devtools'; name: string; data?: unknown }
   | { type: 'log'; level: 'debug' | 'info' | 'warn' | 'error'; message: string; data?: unknown };