@spooky-sync/core 0.0.1-canary.206 → 0.0.1-canary.208

package/src/services/tabs/protocol.ts

@@ -215,7 +215,13 @@ export type FollowerToLeaderMessage =
    *  leader should drain it. Idempotent; a new leader's loadFromDatabase is
    *  the backstop for a notify lost in a failover window. */
   | { type: 'mutation-enqueued'; mutationId: string }
-  | { type: 'request-poll' };
+  | { type: 'request-poll' }
+  /** An optimistic write this follower committed to the SHARED store and
+   *  ingested into its own circuit. The leader ingests it (no DB write, the
+   *  row is already there) and fans it out to every OTHER follower as
+   *  `ingest-relay`, so a follower's write lands in every tab in one hop
+   *  instead of after the server round-trip. */
+  | { type: 'ingest'; tuples: IngestTuple[] };
 
 export type LeaderToFollowerMessage =
   | { type: 'db-ready'; leadershipId: number; bucketId: string; storageHealth: StorageHealth }
@@ -239,4 +245,14 @@ export type LeaderToFollowerMessage =
       recordId: string;
       eventType: 'create' | 'update' | 'delete';
       error: string;
+    }
+  /** The leader's drain pushed a mutation and deleted its outbox row from the
+   *  SHARED store. Every follower starts its settled-write grace so a row it
+   *  was rendering as a pending write does not blink out before its
+   *  `_00_list_ref` membership arrives. */
+  | {
+      type: 'mutation-settled';
+      mutationId: string;
+      recordId: string;
+      eventType: 'create' | 'update' | 'delete';
     };

package/src/sp00ky.ts

@@ -52,7 +52,7 @@ import { AppReleaseModule, AppReleaseHandle } from './modules/app-release/index'
 import type { AppReleaseOptions } from './modules/app-release/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
 import { ANON_USER_ID, bucketIdForUser } from './modules/ref-tables';
-import { parseParams, encodeRecordId, parseDuration } from './utils/index';
+import { parseQueryParams, encodeRecordId, parseDuration } from './utils/index';
 import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
 import { ResilientPersistenceClient } from './services/persistence/resilient';
 import { detectSharedTabsSupport } from './services/tabs/support';
@@ -673,20 +673,18 @@ export class Sp00kyClient<S extends SchemaStructure> {
       resumeSyncLeaderDuties: () => this.sync.resumeLeaderDuties(),
       becomeSyncFollower: (forwarder) => {
         this.streamProcessor.setPersistenceEnabled(false);
-        this.cache.setIngestRelay(null);
+        // A follower's own mutations go to the leader, which ingests them and
+        // fans them out to the other followers: one hop, no server round-trip.
+        // Only the mutation path relays; this tab's sync fetches are the
+        // leader's data coming back and must not be re-broadcast.
+        this.cache.setIngestRelay((tuples) => forwarder.ingest(tuples), {
+          localWritesOnly: true,
+        });
         this.sync.setTabContext('follower', tabId);
         this.dataModule.setTabId(tabId);
+        // Installs the whole syncPort handler: ingest-relay, list_ref relay,
+        // settled writes, rollbacks.
         this.sync.demoteToFollower(forwarder);
-        // demoteToFollower installed the sync-level handler (list_ref relay,
-        // rollbacks); layer the cache-level ingest relay in front of it.
-        const inner = forwarder.onLeaderMessage;
-        forwarder.onLeaderMessage = (msg) => {
-          if (msg.type === 'ingest-relay') {
-            this.cache.applyRelayedIngest(msg.tuples);
-            return;
-          }
-          inner?.(msg);
-        };
       },
       becomeSyncSolo: () => {
         this.streamProcessor.setPersistenceEnabled(true);
@@ -1360,7 +1358,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
       throw new Error(`Table ${table} not found`);
     }
 
-    const params = parseParams(tableSchema.columns, q.selectQuery.vars ?? {});
+    const params = parseQueryParams(tableSchema.columns, q.selectQuery.vars ?? {});
     const hash = await this.dataModule.query(
       table,
       q.selectQuery.query,
@@ -1472,7 +1470,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
     if (!tableSchema) {
       throw new Error(`Table ${tableName} not found`);
     }
-    const params = parseParams(tableSchema.columns, q.selectQuery.vars ?? {});
+    const params = parseQueryParams(tableSchema.columns, q.selectQuery.vars ?? {});
     const hashKey = String(q.hash);
 
     const marker = await this.dataModule.getPreloadMarker(hashKey);

package/src/utils/parser.test.ts

@@ -1,125 +1,54 @@
-import { describe, it, expect } from 'vitest';
-import { RecordId } from 'surrealdb';
-import { parseParams, cleanRecord } from './parser';
-
-describe('parseParams', () => {
-  it('passes through plain values unchanged', () => {
-    const schema = {
-      name: { type: 'string' as const, optional: false },
-      age: { type: 'number' as const, optional: false },
-    };
-    const result = parseParams(schema, { name: 'Alice', age: 30 });
-    expect(result).toEqual({ name: 'Alice', age: 30 });
-  });
-
-  it('converts string to RecordId for recordId columns', () => {
-    const schema = {
-      owner: { type: 'string' as const, optional: false, recordId: true },
-    };
-    const result = parseParams(schema, { owner: 'user:123' });
-    expect(result.owner).toBeInstanceOf(RecordId);
-    expect(result.owner.table.toString()).toBe('user');
-    expect(result.owner.id).toBe('123');
-  });
-
-  it('passes through existing RecordId for recordId columns', () => {
-    const schema = {
-      owner: { type: 'string' as const, optional: false, recordId: true },
-    };
-    const rid = new RecordId('user', '456');
-    const result = parseParams(schema, { owner: rid });
-    expect(result.owner).toBe(rid);
-  });
-
-  it('converts string to Date for dateTime columns', () => {
-    const schema = {
-      createdAt: { type: 'string' as const, optional: false, dateTime: true },
-    };
-    const result = parseParams(schema, { createdAt: '2024-01-01T00:00:00Z' });
-    expect(result.createdAt).toBeInstanceOf(Date);
-    expect(result.createdAt.toISOString()).toBe('2024-01-01T00:00:00.000Z');
-  });
-
-  it('converts number (timestamp) to Date for dateTime columns', () => {
-    const schema = {
-      createdAt: { type: 'string' as const, optional: false, dateTime: true },
-    };
-    const ts = 1704067200000; // 2024-01-01T00:00:00.000Z
-    const result = parseParams(schema, { createdAt: ts });
-    expect(result.createdAt).toBeInstanceOf(Date);
-    expect(result.createdAt.getTime()).toBe(ts);
-  });
-
-  it('passes through existing Date for dateTime columns', () => {
-    const schema = {
-      createdAt: { type: 'string' as const, optional: false, dateTime: true },
-    };
-    const date = new Date('2024-01-01');
-    const result = parseParams(schema, { createdAt: date });
-    expect(result.createdAt).toBe(date);
-  });
-
-  it('skips undefined values', () => {
-    const schema = {
-      name: { type: 'string' as const, optional: false },
-      age: { type: 'number' as const, optional: true },
-    };
-    const result = parseParams(schema, { name: 'Alice', age: undefined });
-    expect(result).toEqual({ name: 'Alice' });
-    expect('age' in result).toBe(false);
-  });
-
-  it('throws on invalid recordId value', () => {
-    const schema = {
-      owner: { type: 'string' as const, optional: false, recordId: true },
-    };
-    expect(() => parseParams(schema, { owner: 12345 })).toThrow('Invalid value for owner');
-  });
-
-  it('throws on invalid dateTime value', () => {
-    const schema = {
-      createdAt: { type: 'string' as const, optional: false, dateTime: true },
-    };
-    expect(() => parseParams(schema, { createdAt: true })).toThrow(
-      'Invalid value for createdAt'
-    );
+import { describe, expect, it } from 'vitest';
+import { RecordId } from '@spooky-sync/query-builder';
+import { parseParams, parseQueryParams } from './parser';
+
+const columns = {
+  white: { recordId: true },
+  black: { recordId: true },
+  owner: { recordId: true },
+  created_at: { dateTime: true },
+  result: {},
+} as any;
+
+describe('parseQueryParams', () => {
+  // The regression this exists for: an `_or` group binds under synthetic names,
+  // and dropping them left `(white = $white__or0 OR black = $black__or1)` with
+  // nothing bound, so every OR query registered and matched no rows at all.
+  it('keeps an _or branch param and types it through its field', () => {
+    const parsed = parseQueryParams(columns, {
+      owner: 'user:abc',
+      white__or0: 'player_name:PN_1',
+      black__or1: 'player_name:PN_1',
+    });
+
+    expect(Object.keys(parsed).sort()).toEqual(['black__or1', 'owner', 'white__or0']);
+    expect(parsed.white__or0).toBeInstanceOf(RecordId);
+    expect(String(parsed.white__or0)).toBe('player_name:PN_1');
+    expect(parsed.black__or1).toBeInstanceOf(RecordId);
+  });
+
+  it('passes a param it cannot resolve through untouched instead of dropping it', () => {
+    const parsed = parseQueryParams(columns, { in: 'anything', limit: 30 });
+    expect(parsed).toEqual({ in: 'anything', limit: 30 });
+  });
+
+  it('still types and keeps plain column params, and skips undefined', () => {
+    const parsed = parseQueryParams(columns, {
+      owner: 'user:abc',
+      created_at: '2026-01-01T00:00:00.000Z',
+      result: undefined,
+    });
+    expect(parsed.owner).toBeInstanceOf(RecordId);
+    expect(parsed.created_at).toBeInstanceOf(Date);
+    expect('result' in parsed).toBe(false);
   });
 });
 
-describe('cleanRecord', () => {
-  const tableSchema = {
-    name: { type: 'string' as const, optional: false },
-    age: { type: 'number' as const, optional: false },
-  };
-
-  it('keeps schema fields and strips non-schema fields', () => {
-    const record = { id: 'user:1', name: 'Alice', age: 30, _internal: true, computed_score: 99 };
-    const result = cleanRecord(tableSchema, record);
-    expect(result).toEqual({ id: 'user:1', name: 'Alice', age: 30 });
-  });
-
-  it('always preserves id even though it is not in schema', () => {
-    const record = { id: 'user:2', extra: 'gone' };
-    const result = cleanRecord(tableSchema, record);
-    expect(result).toEqual({ id: 'user:2' });
-  });
-
-  it('does not coerce or transform values', () => {
-    const date = new Date('2024-01-01');
-    const schema = { created: { type: 'string' as const, optional: false, dateTime: true } };
-    const record = { id: 'x:1', created: date };
-    const result = cleanRecord(schema, record);
-    expect(result.created).toBe(date);
-  });
-
-  it('returns only id when record has no schema fields', () => {
-    const record = { id: 'user:3', unknown1: 'a', unknown2: 'b' };
-    const result = cleanRecord(tableSchema, record);
-    expect(result).toEqual({ id: 'user:3' });
-  });
-
-  it('handles empty record', () => {
-    const result = cleanRecord(tableSchema, {});
-    expect(result).toEqual({});
+describe('parseParams', () => {
+  // Records keep the old behaviour: a field the schema does not know is dropped
+  // rather than written.
+  it('drops a field that is not a column', () => {
+    const parsed = parseParams(columns, { result: '1-0', nonsense: 'x', white__or0: 'y' });
+    expect(parsed).toEqual({ result: '1-0' });
   });
 });

package/src/utils/parser.ts

@@ -1,5 +1,5 @@
 import type { ColumnSchema} from '@spooky-sync/query-builder';
-import { RecordId } from '@spooky-sync/query-builder';
+import { RecordId, baseFieldOfParam } from '@spooky-sync/query-builder';
 import { parseRecordIdString } from './index';
 import { DateTime } from 'surrealdb';
 
@@ -16,6 +16,10 @@ export function cleanRecord(
   return cleaned;
 }
 
+/**
+ * Parse a RECORD's fields against the table schema. Anything the schema does not
+ * know is dropped, which is what keeps a stray field out of a write.
+ */
 export function parseParams(
   tableSchema: Record<string, ColumnSchema>,
   params: Record<string, any>
@@ -31,6 +35,31 @@ export function parseParams(
   return parsedParams;
 }
 
+/**
+ * Parse a QUERY's params. Unlike a record's fields, a param name is not always a
+ * column: an `_or` branch binds under a synthetic `white__or0` (see
+ * `orParamName` in @spooky-sync/query-builder), and the surql that references it
+ * is already written. So resolve the column through the synthetic name, and keep
+ * a param we cannot type rather than dropping it.
+ *
+ * Dropping was the bug: `parseParams` kept only column-named params, so every
+ * `_or` query registered with `$or0`/`$or1` unbound and matched no rows at all,
+ * silently (rowCount 0, errorCount 0).
+ */
+export function parseQueryParams(
+  tableSchema: Record<string, ColumnSchema>,
+  params: Record<string, any>
+) {
+  const parsedParams: Record<string, any> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    const column = tableSchema[key] ?? tableSchema[baseFieldOfParam(key)];
+    parsedParams[key] = column ? parseValue(key, column, value) : value;
+  }
+
+  return parsedParams;
+}
+
 function parseValue(name: string, column: ColumnSchema, value: any) {
   if (column.recordId) {
     if (value instanceof RecordId) return value;