@jcbuisson/express-x-plugins 5.0.6 → 5.0.8

package/test/electric-offline-model.test.mjs

@@ -22,14 +22,14 @@ test('edits survive a committed create whose response was lost', async () => {
    let model
    try {
       await server.exec('CREATE TABLE todos (id UUID PRIMARY KEY, title TEXT NOT NULL)')
-      await prepareElectricSyncSchema(server, [{ name: 'todos', tombstoneData: { title: '' } }])
+      await prepareElectricSyncSchema(server, [{ name: 'todos', primaryKey: 'id', tombstoneData: { title: '' } }])
       let service
       const pool = {
          query: server.query.bind(server),
          async connect() { return { query: server.query.bind(server), release() {} } },
       }
       electricServerPlugin({ createService(_name, methods) { service = methods }, get() {} }, pool,
-         [{ name: 'todos', tombstoneData: { title: '' } }], { sync: true })
+         [{ name: 'todos', primaryKey: 'id', tombstoneData: { title: '' } }], { sync: true })
       let loseResponse = true
       const requests = []
       const proxy = {
@@ -42,7 +42,7 @@ test('edits survive a committed create whose response was lost', async () => {
       }
       const app = { service: () => proxy }
       electricClientPlugin(app, { ShapeStream: Stream, Shape })
-      model = app.createElectricModel('todos', { localDb: db, retryMs: 60_000 })
+      model = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, retryMs: 60_000 })
       await model.prepare()
       const row = await model.create({ title: 'original' })
       await model.flushQueue()
@@ -95,7 +95,7 @@ test('offline writes stay local until the acknowledged Electric version arrives'
    }
    const app = { service: () => service }
    electricClientPlugin(app, { ShapeStream: Stream, Shape })
-   const model = app.createElectricModel('todos', { localDb: db, network: { onLine: false }, retryMs: 60_000 })
+   const model = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, network: { onLine: false }, retryMs: 60_000 })
    try {
       await model.prepare()
       const local = await model.create({ title: 'offline' })
@@ -105,7 +105,7 @@ test('offline writes stay local until the acknowledged Electric version arrives'
       assert.equal(calls.length, 0)
 
       // Simulate reconnect, then an old Shape snapshot followed by confirmation.
-      const onlineModel = app.createElectricModel('todos', { localDb: db, network: { onLine: true }, retryMs: 60_000 })
+      const onlineModel = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, network: { onLine: true }, retryMs: 60_000 })
       await onlineModel.flushQueue()
       assert.equal(calls.length, 1)
       assert.equal(calls[0].metadata.revision, '1')

package/test/electric-relations-postgres.test.mjs

@@ -0,0 +1,113 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { setTimeout as delay } from 'node:timers/promises'
+import { electricServerPlugin, prepareElectricSyncSchema } from '../src/electric-server-plugin.mjs'
+
+const connectionString = process.env.ELECTRIC_TEST_DATABASE_URL
+
+function register(db, models) {
+   const services = new Map()
+   electricServerPlugin({ createService(name, methods) { services.set(name, methods) }, get() {} }, db, models, { sync: true })
+   return services
+}
+
+function commitGate(pool) {
+   let reached
+   let release
+   const waiting = new Promise(resolve => { reached = resolve })
+   const released = new Promise(resolve => { release = resolve })
+   return {
+      waiting, release,
+      db: {
+         query: (...args) => pool.query(...args),
+         async connect() {
+            const client = await pool.connect()
+            return {
+               async query(sql, values) {
+                  if (sql === 'COMMIT') { reached(); await released }
+                  return client.query(sql, values)
+               },
+               release: () => client.release(),
+            }
+         },
+      },
+   }
+}
+
+test('PostgreSQL serializes concurrent membership writes and soft deletes across plugin instances', {
+   skip: !connectionString,
+   timeout: 30_000,
+}, async t => {
+   const { Pool } = await import('pg')
+   const schema = `electric_sync_test_${crypto.randomUUID().replaceAll('-', '')}`
+   const admin = new Pool({ connectionString })
+   let pool
+   t.after(async () => {
+      try {
+         await pool?.end()
+         await admin.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`)
+      } finally { await admin.end() }
+   })
+   await admin.query(`CREATE SCHEMA "${schema}"`)
+   pool = new Pool({ connectionString, options: `-c search_path=${schema}`, statement_timeout: 10_000 })
+   await pool.query(`
+      CREATE TABLE people (uid UUID PRIMARY KEY);
+      CREATE TABLE groups (uid UUID PRIMARY KEY);
+      CREATE TABLE membership (
+         uid UUID PRIMARY KEY,
+         user_uid UUID REFERENCES people(uid) ON DELETE CASCADE,
+         group_uid UUID REFERENCES groups(uid) ON DELETE CASCADE
+      );
+   `)
+   const models = [
+      { name: 'user', table: 'people' },
+      { name: 'group', table: 'groups' },
+      { name: 'membership', tombstoneData: { user_uid: null, group_uid: null } },
+   ]
+   await prepareElectricSyncSchema(pool, models)
+   const services = register(pool, models)
+   const metadata = () => ({ clientId: crypto.randomUUID(), revision: '1' })
+
+   for (const first of ['delete', 'create']) {
+      await t.test(`${first} reaches the server first`, async () => {
+         const user = crypto.randomUUID()
+         const group = crypto.randomUUID()
+         const membership = crypto.randomUUID()
+         await services.get('user').create(user, {}, metadata())
+         await services.get('group').create(group, {}, metadata())
+         const gate = commitGate(pool)
+         const gated = register(gate.db, models)
+         const create = service => service.get('membership').create(membership, { user_uid: user, group_uid: group }, metadata())
+         const remove = service => service.get('group').delete(group, metadata())
+         const firstWrite = first === 'delete' ? remove(gated) : create(gated)
+         let secondWrite
+         try {
+            // Keep the first transaction open after its mutation. The second
+            // must wait for the same advisory lock on another connection.
+            await Promise.race([gate.waiting, firstWrite.then(() => { throw new Error('commit gate was not reached') })])
+            secondWrite = first === 'delete' ? create(services) : remove(services)
+            let blocked = false
+            for (let attempt = 0; attempt < 100; attempt++) {
+               const { rows } = await pool.query(`SELECT EXISTS (
+                  SELECT 1 FROM pg_locks WHERE locktype = 'advisory' AND NOT granted
+                     AND classid = 178693771 AND objid = 1
+                     AND database = (SELECT oid FROM pg_database WHERE datname = current_database())
+               ) AS blocked`)
+               if (rows[0].blocked) { blocked = true; break }
+               await delay(10)
+            }
+            assert.equal(blocked, true, 'the second mutation must block until the first commits')
+         } finally {
+            gate.release()
+            await Promise.allSettled([firstWrite, secondWrite])
+         }
+         const results = await Promise.all([firstWrite, secondWrite])
+         if (first === 'delete') assert.equal(results[1].syncRejection.code, 'sync-parent-deleted')
+         const row = (await pool.query('SELECT * FROM membership WHERE uid = $1', [membership])).rows[0]
+         assert.equal(row.deleted, true)
+         assert.equal(row.user_uid, null)
+         assert.equal(row.group_uid, null)
+         assert.equal((await pool.query('SELECT deleted FROM groups WHERE uid = $1', [group])).rows[0].deleted, true)
+      })
+   }
+})

package/test/electric-relations.test.mjs

@@ -0,0 +1,220 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { PGlite } from '@electric-sql/pglite'
+import { electricServerPlugin, prepareElectricSyncSchema } from '../src/electric-server-plugin.mjs'
+import { electricClientPlugin } from '../src/electric-client-plugin.mjs'
+
+const models = [
+   { name: 'user', table: 'people', tombstoneData: { email: null } },
+   { name: 'group', table: 'groups', tombstoneData: { name: null } },
+   { name: 'membership', tombstoneData: { user_uid: null, group_uid: null } },
+   { name: 'note', primaryKey: 'id', tombstoneData: { membership_uid: null } },
+]
+
+// Pool semantics on a single PGlite connection: queue complete transactions,
+// never interleave BEGIN/COMMIT from concurrently flushing model queues.
+function poolFor(db) {
+   let tail = Promise.resolve()
+   return {
+      query: (...args) => db.query(...args),
+      async connect() {
+         let release
+         const next = new Promise(resolve => { release = resolve })
+         const previous = tail
+         tail = next
+         await previous
+         return { query: (...args) => db.query(...args), release }
+      },
+   }
+}
+
+async function fixture(t) {
+   const db = new PGlite()
+   t.after(() => db.close())
+   await db.exec(`
+      CREATE TABLE people (uid UUID PRIMARY KEY, email TEXT UNIQUE);
+      CREATE TABLE groups (uid UUID PRIMARY KEY, name TEXT UNIQUE);
+      CREATE TABLE membership (
+         uid UUID PRIMARY KEY,
+         user_uid UUID REFERENCES people(uid) ON DELETE CASCADE,
+         group_uid UUID REFERENCES groups(uid) ON DELETE CASCADE,
+         label TEXT,
+         UNIQUE (user_uid, group_uid)
+      );
+      CREATE TABLE note (id UUID PRIMARY KEY, membership_uid UUID REFERENCES membership(uid) ON DELETE CASCADE);
+   `)
+   await prepareElectricSyncSchema(db, models)
+   const services = new Map()
+   const app = { createService(name, methods) { services.set(name, methods) }, get() {} }
+   electricServerPlugin(app, poolFor(db), models, { sync: true })
+   const metadata = () => ({ clientId: crypto.randomUUID(), revision: '1' })
+   const user = crypto.randomUUID()
+   const group = crypto.randomUUID()
+   await services.get('user').create(user, { email: 'member@example.com' }, metadata())
+   await services.get('group').create(group, { name: 'Team' }, metadata())
+   return { db, services, metadata, user, group }
+}
+
+test('membership committed before an offline group delete is cascaded, including descendants', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   const membership = crypto.randomUUID()
+   const note = crypto.randomUUID()
+   const created = await services.get('membership').create(membership, { user_uid: user, group_uid: group }, metadata())
+   await services.get('note').create(note, { membership_uid: membership }, metadata())
+   const deleted = await services.get('group').delete(group, metadata())
+   assert.equal(deleted.deleted, true)
+   const row = (await db.query('SELECT * FROM membership')).rows[0]
+   assert.equal(row.deleted, true)
+   assert.equal(row.user_uid, null)
+   assert.equal(row.group_uid, null)
+   assert.ok(BigInt(row.version) > BigInt(created.version))
+   assert.equal((await db.query('SELECT * FROM note')).rows[0].deleted, true)
+   assert.equal((await db.query('SELECT * FROM people')).rows[0].deleted, false)
+})
+
+test('membership sent after parent deletion becomes a replayable rejection tombstone', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   await services.get('group').delete(group, metadata())
+   const id = crypto.randomUUID()
+   const request = [id, { user_uid: user, group_uid: group }, metadata()]
+   const rejected = await services.get('membership').create(...request)
+   assert.equal(rejected.deleted, true)
+   assert.equal(rejected.syncRejection.code, 'sync-parent-deleted')
+   assert.deepEqual(await services.get('membership').create(...request), rejected)
+   assert.equal((await db.query('SELECT count(*)::int AS count FROM membership WHERE NOT deleted')).rows[0].count, 0)
+   assert.equal((await db.query('SELECT * FROM membership')).rows[0].group_uid, null)
+})
+
+test('user deletion also cascades; delayed updates cannot resurrect the membership', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   const id = crypto.randomUUID()
+   await services.get('membership').create(id, { user_uid: user, group_uid: group }, metadata())
+   await services.get('user').delete(user, metadata())
+   const delayed = await services.get('membership').update(id, { label: 'late edit' }, metadata())
+   assert.equal(delayed.deleted, true)
+   assert.equal((await db.query('SELECT * FROM membership')).rows[0].deleted, true)
+   assert.equal((await db.query('SELECT * FROM groups')).rows[0].deleted, false)
+})
+
+test('membership reassignment checks deleted parents and colliding creates cannot delete valid rows', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   const id = crypto.randomUUID()
+   const other = crypto.randomUUID()
+   await services.get('group').create(other, { name: 'Other' }, metadata())
+   await services.get('group').delete(other, metadata())
+   const original = await services.get('membership').create(id, { user_uid: user, group_uid: group }, metadata())
+   const collision = await services.get('membership').create(id, { user_uid: user, group_uid: other }, metadata())
+   assert.deepEqual(collision, original)
+   const reassigned = await services.get('membership').update(id, { group_uid: other }, metadata())
+   assert.equal(reassigned.deleted, true)
+   assert.equal(reassigned.syncRejection.code, 'sync-parent-deleted')
+   assert.equal((await db.query('SELECT * FROM membership')).rows[0].deleted, true)
+})
+
+test('a missing parent is retriable so parent and child can be created offline together', async t => {
+   const { services, metadata, user } = await fixture(t)
+   const group = crypto.randomUUID()
+   const request = [crypto.randomUUID(), { user_uid: user, group_uid: group }, metadata()]
+   await assert.rejects(services.get('membership').create(...request), { code: 'sync-parent-missing' })
+   await services.get('group').create(group, { name: 'Queued parent' }, metadata())
+   assert.equal((await services.get('membership').create(...request)).deleted, false)
+})
+
+test('partial updates validate retained foreign keys, including fields passed as undefined', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   const id = crypto.randomUUID()
+   await services.get('membership').create(id, { user_uid: user, group_uid: group }, metadata())
+   // Simulate a legacy orphan left by an older server instance.
+   await db.query('UPDATE groups SET deleted = true WHERE uid = $1', [group])
+   const result = await services.get('membership').update(id, { group_uid: undefined, label: 'edit' }, metadata())
+   assert.equal(result.deleted, true)
+   assert.equal(result.syncRejection.code, 'sync-parent-deleted')
+})
+
+test('schema preparation repairs existing soft-delete orphans and is idempotent', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   const id = crypto.randomUUID()
+   await services.get('membership').create(id, { user_uid: user, group_uid: group }, metadata())
+   await services.get('note').create(crypto.randomUUID(), { membership_uid: id }, metadata())
+   await db.query('UPDATE groups SET deleted = true WHERE uid = $1', [group])
+   await prepareElectricSyncSchema(db, models)
+   const repaired = (await db.query('SELECT * FROM membership')).rows[0]
+   assert.equal(repaired.deleted, true)
+   assert.equal((await db.query('SELECT * FROM note')).rows[0].deleted, true)
+   await prepareElectricSyncSchema(db, models)
+   assert.deepEqual((await db.query('SELECT * FROM membership')).rows[0], repaired)
+})
+
+test('cascade failure rolls back the parent, children, and mutation cursor together', async t => {
+   const { db, services, metadata, user, group } = await fixture(t)
+   await services.get('membership').create(crypto.randomUUID(), { user_uid: user, group_uid: group }, metadata())
+   const broken = models.map(model => model.name === 'membership' ? { ...model, tombstoneData: () => { throw new Error('factory failed') } } : model)
+   const brokenServices = new Map()
+   electricServerPlugin({ createService(name, methods) { brokenServices.set(name, methods) }, get() {} }, poolFor(db), broken, { sync: true })
+   const mutation = metadata()
+   await assert.rejects(brokenServices.get('group').delete(group, mutation), /factory failed/)
+   assert.equal((await db.query('SELECT * FROM groups')).rows[0].deleted, false)
+   assert.equal((await db.query('SELECT * FROM membership')).rows[0].deleted, false)
+   assert.equal((await db.query('SELECT count(*)::int AS count FROM electric_mutation_cursor WHERE client_id = $1', [mutation.clientId])).rows[0].count, 0)
+})
+
+test('cyclic CASCADE relationships terminate and tombstone every descendant', async t => {
+   const db = new PGlite()
+   t.after(() => db.close())
+   await db.exec('CREATE TABLE nodes (uid UUID PRIMARY KEY, parent_uid UUID REFERENCES nodes(uid) ON DELETE CASCADE)')
+   const models = [{ name: 'nodes', tombstoneData: { parent_uid: null } }]
+   await prepareElectricSyncSchema(db, models)
+   let service
+   electricServerPlugin({ createService(_name, methods) { service = methods }, get() {} }, poolFor(db), models, { sync: true })
+   const first = crypto.randomUUID()
+   const second = crypto.randomUUID()
+   await service.create(first, { parent_uid: first }, { clientId: crypto.randomUUID(), revision: '1' })
+   await service.create(second, { parent_uid: first }, { clientId: crypto.randomUUID(), revision: '1' })
+   await service.update(first, { parent_uid: second }, { clientId: crypto.randomUUID(), revision: '1' })
+   await service.delete(first, { clientId: crypto.randomUUID(), revision: '1' })
+   assert.ok((await db.query('SELECT * FROM nodes')).rows.every(row => row.deleted))
+})
+
+class Stream {
+   subscribe() {}
+   isConnected() { return true }
+   unsubscribeAll() {}
+}
+class Shape {
+   static current
+   constructor() { Shape.current = this }
+   subscribe(callback) { this.emit = callback }
+}
+
+test('offline rejected memberships disappear immediately, report a conflict, and stop retrying', async t => {
+   const { db: server, services, metadata, user, group } = await fixture(t)
+   const db = new PGlite()
+   t.after(() => db.close())
+   const errors = []
+   let requests = 0
+   const app = { service: () => ({ async create(...args) { requests++; return services.get('membership').create(...args) } }) }
+   electricClientPlugin(app, { ShapeStream: Stream, Shape })
+   const network = { onLine: false }
+   const model = app.createElectricModel('membership', { localDb: db, network, retryMs: 60_000, onError: error => errors.push(error) })
+   await model.prepare()
+   const local = await model.create({ user_uid: user, group_uid: group })
+   assert.equal((await model.findMany()).length, 1)
+   await services.get('group').delete(group, metadata())
+   network.onLine = true
+   await model.flushQueue()
+   assert.equal((await model.findMany()).length, 0)
+   assert.equal(errors[0].code, 'sync-parent-deleted')
+   assert.equal(errors[0].rowId, local.uid)
+   await model.flushQueue()
+   assert.equal(requests, 1)
+   model.start()
+   t.after(async () => { model.stop(); await model.waitForIdle() })
+   // An older snapshot cannot restore the rejected optimistic row.
+   Shape.current.emit({ rows: [{ ...local, version: '0', deleted: false }] })
+   await model.waitForIdle()
+   assert.equal((await model.findMany()).length, 0)
+   Shape.current.emit({ rows: (await server.query('SELECT * FROM membership')).rows })
+   await model.waitForIdle()
+   assert.equal((await model.getStatus()).pending, 0)
+   assert.equal((await model.findMany()).length, 0)
+})

package/test/electric-server-plugin.test.mjs

@@ -17,7 +17,7 @@ function fixture({ authorize = async () => true, fetch } = {}) {
       createService(name, methods) { services.set(name, methods) },
       get(path, handler) { routes.set(path, handler) },
    }
-   const registration = electricServerPlugin(app, db, ['todos'], { authorize, fetch: fetch ?? globalThis.fetch })
+   const registration = electricServerPlugin(app, db, [{ name: 'todos', primaryKey: 'id' }], { authorize, fetch: fetch ?? globalThis.fetch })
    return { app, db, services, routes, queries, registration }
 }
 
@@ -192,10 +192,11 @@ test('sync mode commits a versioned write and rejects replayed or stale revision
 
 test('sync schema prepares version and tombstone columns', async () => {
    const queries = []
-   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql) } }, ['todos'])
-   assert.equal(queries.length, 4)
+   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql); return { rows: [] } } }, [{ name: 'todos', primaryKey: 'id' }])
+   assert.equal(queries.length, 5)
    assert.match(queries[2], /ADD COLUMN IF NOT EXISTS version BIGINT/)
    assert.match(queries[3], /ADD COLUMN IF NOT EXISTS deleted BOOLEAN/)
+   assert.match(queries[4], /FROM pg_constraint/)
 })
 
 test('sync delete writes a versioned tombstone and clears configured fields', async () => {
@@ -301,3 +302,10 @@ test('invalid tombstone factory results roll back before writing a tombstone', a
       assert.ok(!queries.some(sql => sql.includes('INSERT INTO "users"')))
    }
 })
+
+
+test('server models default to the uid primary key', () => {
+   const app = { createService() {}, get() {} }
+   const result = electricServerPlugin(app, { query() {} }, ['users'], { authorize: async () => true })
+   assert.equal(result.models[0].primaryKey, 'uid')
+})

package/test/sync-algorithm.test.mjs

@@ -0,0 +1,229 @@
+import { test, describe, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { computeSyncResult } from '../src/sync-algorithm.mjs'
+
+const T0 = new Date('2026-01-01T00:00:00Z')
+const T1 = new Date('2026-01-02T00:00:00Z')
+const T2 = new Date('2026-01-03T00:00:00Z')
+
+// ─── Dialog helpers ────────────────────────────────────────────────────────────
+// Lightweight simulations of server (drizzle-plugins.mjs) and client (client.js)
+// that run the sync protocol using plain objects instead of Dexie / PostgreSQL.
+
+function matchesWhere(value, where) {
+   return Object.entries(where).every(([k, v]) => value[k] === v)
+}
+
+describe('computeSyncResult', () => {
+
+   test('both empty → all arrays empty', () => {
+      const result = computeSyncResult({}, {}, {})
+      assert.deepEqual(result.addClient, [])
+      assert.deepEqual(result.updateClient, [])
+      assert.deepEqual(result.deleteClient, [])
+      assert.deepEqual(result.addDatabase, [])
+      assert.deepEqual(result.updateDatabase, [])
+      assert.deepEqual(result.deleteDatabase, [])
+   })
+
+   test('record only in DB → sent to client (addClient)', () => {
+      const value = { uid: 'a', label: 'Vacances' }
+      const meta  = { uid: 'a', created_at: T0 }
+      const result = computeSyncResult({ a: value }, {}, { a: meta })
+      assert.equal(result.addClient.length, 1)
+      assert.deepEqual(result.addClient[0], [value, meta])
+      assert.deepEqual(result.addDatabase, [])
+   })
+
+   test('record only on client, not deleted → sent to database (addDatabase)', () => {
+      const clientMeta = { uid: 'b', created_at: T0 }
+      const result = computeSyncResult({}, { b: clientMeta }, {})
+      assert.deepEqual(result.addDatabase, [clientMeta])
+      assert.deepEqual(result.addClient, [])
+      assert.deepEqual(result.deleteClient, [])
+   })
+
+   test('record only on client, deleted → ignored on both sides (deleteClient)', () => {
+      const clientMeta = { uid: 'c', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({}, { c: clientMeta }, {})
+      assert.deepEqual(result.deleteClient, [['c', T1]])
+      assert.deepEqual(result.addDatabase, [])
+   })
+
+   test('server tombstone newer than client copy → delete client, do not recreate DB', () => {
+      const clientMeta = { uid: 'x', created_at: T0 }
+      const dbTombstone = { uid: 'x', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({}, { x: clientMeta }, { x: dbTombstone })
+      assert.deepEqual(result.deleteClient, [['x', T1]])
+      assert.deepEqual(result.addDatabase, [])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('client tombstone newer than server tombstone → upgrade server tombstone', () => {
+      const clientMeta = { uid: 'x2', created_at: T0, deleted_at: T2 }
+      const dbTombstone = { uid: 'x2', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({}, { x2: clientMeta }, { x2: dbTombstone })
+      assert.deepEqual(result.deleteDatabase, ['x2'])
+      assert.deepEqual(result.deleteClient, [['x2', T2]])
+      assert.deepEqual(result.addDatabase, [])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('record only in DB with tombstone metadata → delete stale DB row, do not add client', () => {
+      const value = { uid: 'd', label: 'stale-server-row' }
+      const dbTombstone = { uid: 'd', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({ d: value }, {}, { d: dbTombstone })
+      assert.deepEqual(result.deleteDatabase, ['d'])
+      assert.deepEqual(result.addClient, [])
+      assert.deepEqual(result.updateClient, [])
+   })
+
+   test('client update newer than server tombstone → recreate database', () => {
+      const clientMeta = { uid: 'y', created_at: T0, updated_at: T2 }
+      const dbTombstone = { uid: 'y', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({}, { y: clientMeta }, { y: dbTombstone })
+      assert.deepEqual(result.addDatabase, [clientMeta])
+      assert.deepEqual(result.deleteClient, [])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('server live metadata newer than client but row missing → tombstone server metadata and delete client', () => {
+      const clientMeta = { uid: 'm', created_at: T0, updated_at: T1 }
+      const dbMeta = { uid: 'm', created_at: T0, updated_at: T2 }
+      const result = computeSyncResult({}, { m: clientMeta }, { m: dbMeta })
+      assert.deepEqual(result.deleteDatabase, ['m'])
+      assert.equal(result.deleteClient.length, 1)
+      assert.equal(result.deleteClient[0][0], 'm')
+      assert.equal(new Date(result.deleteClient[0][1]).getTime(), T2.getTime())
+      assert.deepEqual(result.addDatabase, [])
+   })
+
+   test('client tombstone newer than server live metadata but row missing → tombstone server metadata too', () => {
+      const clientMeta = { uid: 'n', created_at: T0, deleted_at: T2 }
+      const dbMeta = { uid: 'n', created_at: T0, updated_at: T1 }
+      const result = computeSyncResult({}, { n: clientMeta }, { n: dbMeta })
+      assert.deepEqual(result.deleteDatabase, ['n'])
+      assert.deepEqual(result.deleteClient, [['n', T2]])
+      assert.deepEqual(result.addDatabase, [])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('record in both, server tombstone newer than client copy → delete stale DB row and client', () => {
+      const value = { uid: 'z', label: 'stale-server-row' }
+      const clientMeta = { uid: 'z', created_at: T0 }
+      const dbTombstone = { uid: 'z', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({ z: value }, { z: clientMeta }, { z: dbTombstone })
+      assert.deepEqual(result.deleteDatabase, ['z'])
+      assert.deepEqual(result.deleteClient, [['z', T1]])
+      assert.deepEqual(result.updateClient, [])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('record in both, client newer → update database (updateDatabase)', () => {
+      const value      = { uid: 'd', label: 'old' }
+      const dbMeta     = { uid: 'd', created_at: T0, updated_at: T1 }
+      const clientMeta = { uid: 'd', created_at: T0, updated_at: T2 }
+      const result = computeSyncResult({ d: value }, { d: clientMeta }, { d: dbMeta })
+      assert.deepEqual(result.updateDatabase, [clientMeta])
+      assert.deepEqual(result.updateClient, [])
+   })
+
+   test('record in both, DB newer → update client (updateClient)', () => {
+      const value      = { uid: 'e', label: 'new' }
+      const dbMeta     = { uid: 'e', created_at: T0, updated_at: T2 }
+      const clientMeta = { uid: 'e', created_at: T0, updated_at: T1 }
+      const result = computeSyncResult({ e: value }, { e: clientMeta }, { e: dbMeta })
+      assert.deepEqual(result.updateClient, [[value, dbMeta]])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('sub-day timestamp matches its day-truncated DB counterpart → no action', () => {
+      // The DB stores TIMESTAMP. Before this fix it stored DATE (day precision), which
+      // caused new Date('2026-01-02T06:00:00Z') - new Date('2026-01-02') > 0, triggering
+      // a spurious updateDatabase on every sync after the initial addDatabase push.
+      const value      = { uid: 'p', label: 'precision' }
+      const dbMeta     = { uid: 'p', created_at: '2026-01-02T06:00:00.000Z' }            // TIMESTAMP from server
+      const clientMeta = { uid: 'p', created_at: new Date('2026-01-02T06:00:00.000Z') }  // full timestamp on client
+      const result = computeSyncResult({ p: value }, { p: clientMeta }, { p: dbMeta })
+      assert.deepEqual(result.updateDatabase, [], 'identical timestamps must not trigger spurious updateDatabase')
+      assert.deepEqual(result.updateClient,   [])
+   })
+
+   test('record in both, same timestamp → no action', () => {
+      const value      = { uid: 'f', label: 'same' }
+      const dbMeta     = { uid: 'f', created_at: T0, updated_at: T1 }
+      const clientMeta = { uid: 'f', created_at: T0, updated_at: T1 }
+      const result = computeSyncResult({ f: value }, { f: clientMeta }, { f: dbMeta })
+      assert.deepEqual(result.updateClient, [])
+      assert.deepEqual(result.updateDatabase, [])
+   })
+
+   test('record in both, client deleted → delete on DB and notify client', () => {
+      const value      = { uid: 'g', label: 'bye' }
+      const dbMeta     = { uid: 'g', created_at: T0 }
+      const clientMeta = { uid: 'g', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({ g: value }, { g: clientMeta }, { g: dbMeta })
+      assert.deepEqual(result.deleteDatabase, ['g'])
+      assert.deepEqual(result.deleteClient, [['g', T1]])
+   })
+
+   test('record in both, client delete newer than DB update → delete on DB and notify client', () => {
+      const value      = { uid: 'h', label: 'server-old' }
+      const dbMeta     = { uid: 'h', created_at: T0, updated_at: T1 }
+      const clientMeta = { uid: 'h', created_at: T0, deleted_at: T2 }
+      const result = computeSyncResult({ h: value }, { h: clientMeta }, { h: dbMeta })
+      assert.deepEqual(result.deleteDatabase, ['h'])
+      assert.deepEqual(result.deleteClient, [['h', T2]])
+      assert.deepEqual(result.updateClient, [])
+   })
+
+   test('record in both, DB update newer than client delete → restore client from DB', () => {
+      const value      = { uid: 'i', label: 'server-new' }
+      const dbMeta     = { uid: 'i', created_at: T0, updated_at: T2 }
+      const clientMeta = { uid: 'i', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({ i: value }, { i: clientMeta }, { i: dbMeta })
+      assert.deepEqual(result.updateClient, [[value, dbMeta]])
+      assert.deepEqual(result.deleteDatabase, [])
+      assert.deepEqual(result.deleteClient, [])
+   })
+
+   test('mixed scenario: one of each case', () => {
+      const dbOnly      = { uid: 'db', label: 'db-only' }
+      const dbOnlyMeta  = { uid: 'db', created_at: T0 }
+
+      const clientNewMeta = { uid: 'cn', created_at: T1 }
+
+      const sharedValue       = { uid: 'sh', label: 'shared' }
+      const sharedDbMeta      = { uid: 'sh', created_at: T0, updated_at: T1 }
+      const sharedClientMeta  = { uid: 'sh', created_at: T0, updated_at: T2 }
+
+      const result = computeSyncResult(
+         { db: dbOnly, sh: sharedValue },
+         { cn: clientNewMeta, sh: sharedClientMeta },
+         { db: dbOnlyMeta, sh: sharedDbMeta },
+      )
+
+      assert.equal(result.addClient.length, 1)
+      assert.deepEqual(result.addClient[0], [dbOnly, dbOnlyMeta])
+      assert.deepEqual(result.addDatabase, [clientNewMeta])
+      assert.deepEqual(result.updateDatabase, [sharedClientMeta])
+      assert.deepEqual(result.updateClient, [])
+      assert.deepEqual(result.deleteClient, [])
+      assert.deepEqual(result.deleteDatabase, [])
+   })
+
+   test('special uid keys do not corrupt synchronization dictionaries', () => {
+      const databaseValues = Object.create(null)
+      const databaseMetadata = Object.create(null)
+      const clientMetadata = Object.create(null)
+      databaseValues.__proto__ = { uid: '__proto__', label: 'safe' }
+      databaseMetadata.__proto__ = { uid: '__proto__', created_at: T0 }
+
+      const result = computeSyncResult(databaseValues, clientMetadata, databaseMetadata)
+
+      assert.equal(result.addClient.length, 1)
+      assert.equal(result.addClient[0][0].uid, '__proto__')
+   })
+
+})