@spooky-sync/client-solid2 0.0.1-alpha.1

package/src/lib/create-preload.ts

@@ -0,0 +1,116 @@
+import type {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+} from '@spooky-sync/query-builder';
+import { createEffect } from 'solid-js';
+import { SyncedDb } from '..';
+import type {
+  Sp00kyQueryResultPromise,
+  PreloadOptions as CorePreloadOptions,
+} from '@spooky-sync/core';
+import { useDb } from './context';
+
+type PreloadArg<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+> =
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+  | (() =>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+      | null
+      | undefined);
+
+type PreloadOptions = CorePreloadOptions & {
+  /** Only preload while this returns true (defaults to always). */
+  enabled?: () => boolean;
+};
+
+// Overload: context-based (no explicit db)
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: PreloadOptions
+): void;
+
+// Overload: explicit db
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  db: SyncedDb<S>,
+  finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: PreloadOptions
+): void;
+
+/**
+ * Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
+ * function so it tracks reactive deps), dedupes on the query's stable identity
+ * hash, and registers it via `db.preload`: a live query nobody subscribes to,
+ * evicted a ttl after it was registered unless a view mounts it first. Nothing
+ * to clean up here.
+ *
+ * Typical use: inside a list row, preload the detail query the user is likely
+ * to open next, so navigation paints from cache instead of the network.
+ */
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  dbOrQuery: SyncedDb<S> | PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  queryOrOptions?: PreloadArg<S, TableName, T, RelatedFields, IsOne> | PreloadOptions,
+  maybeOptions?: PreloadOptions
+): void {
+  let db: SyncedDb<S>;
+  let finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>;
+  let options: PreloadOptions | undefined;
+
+  if (dbOrQuery instanceof SyncedDb) {
+    db = dbOrQuery;
+    finalQuery = queryOrOptions as PreloadArg<S, TableName, T, RelatedFields, IsOne>;
+    options = maybeOptions;
+  } else {
+    db = useDb<S>();
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as PreloadOptions | undefined;
+  }
+
+  let prevHash: number | undefined;
+
+  // Two-arg Solid 2 effect: compute resolves the query (tracking its reactive
+  // deps) and dedupes on the identity hash; the untracked apply fires the
+  // preload. Returning `undefined` from compute skips nothing — apply guards.
+  createEffect(
+    () => {
+      if (!(options?.enabled?.() ?? true)) return undefined;
+      const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+      if (!query) return undefined;
+      // Dedupe on the query's stable identity hash so a reactive re-run with
+      // an unchanged query doesn't refetch (the core also dedupes per session).
+      if (query.hash === prevHash) return undefined;
+      prevHash = query.hash;
+      return query;
+    },
+    (query) => {
+      if (!query) return;
+      void db
+        .getSp00ky()
+        .preload(query, { signal: options?.signal });
+    }
+  );
+}

package/src/lib/create-query.ts

@@ -0,0 +1,388 @@
+import type {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+  QueryResult,
+} from '@spooky-sync/query-builder';
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  createStore,
+  onCleanup,
+  type Accessor,
+} from 'solid-js';
+import { SyncedDb } from '..';
+import type { Sp00kyQueryResultPromise } from '@spooky-sync/core';
+import { useDb } from './context';
+import { mergeRows } from './merge-rows';
+
+type QueryArg<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+> =
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+  | (() =>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+      | null
+      | undefined);
+
+export type QueryOptions = {
+  enabled?: () => boolean;
+  /**
+   * Tear down the query (remote `_00_query` view + local WASM view) when this
+   * hook is disposed and no other subscriber remains, instead of keeping it
+   * resident for cheap re-subscription. Use for viewport-windowed lists that
+   * mount/unmount a query per scroll window and want off-screen windows
+   * cancelled. Trade-off: scrolling back to a torn-down window re-registers it.
+   */
+  deregisterOnCleanup?: boolean;
+};
+
+export type CreateQueryResult<TData> = {
+  /**
+   * Reactive result. Never suspends and never throws: born as an empty
+   * committed value (`[]` / `null`) and reconciled in place (keyed by `id`) on
+   * every live emission — unchanged rows keep identity, and coarse readers
+   * (`<For>`) are notified on add/remove/reorder.
+   */
+  data: Accessor<TData>;
+  /**
+   * Suspending read of the same result for `<Loading>` users: throws Solid's
+   * not-ready protocol until the query has delivered its first real result
+   * (or errored, in which case it returns the empty value and `error()` is
+   * set). Read this inside a `<Loading>` boundary.
+   */
+  ready: Accessor<TData>;
+  error: Accessor<Error | undefined>;
+  /**
+   * True only on a COLD first load: nothing has painted for this identity,
+   * the server has not answered yet, and registration has not failed. A query
+   * that painted from the local cache is not loading, however long the server
+   * takes; a query the server answered with zero rows is not loading either
+   * (see `isEmpty`). Resets when the query identity changes.
+   */
+  isLoading: Accessor<boolean>;
+  /** True while a fetch cycle is in flight (registration, a sync round). */
+  isFetching: Accessor<boolean>;
+  /**
+   * True once server membership is known for this identity: a registration or
+   * poll landed, or the durable membership of a previous session was read on
+   * boot. From then on `data()` is the server's answer, not a cache guess.
+   * Latched until the identity changes (or a bucket switch resets it).
+   */
+  isAuthoritative: Accessor<boolean>;
+  /** Whether `data()` currently holds anything: rows for a list, a row for `one()`. */
+  hasData: Accessor<boolean>;
+  /**
+   * The server answered and the answer is "no rows". The signal to render an
+   * empty state on; a bare `!hasData()` cannot tell empty from not-yet-loaded.
+   */
+  isEmpty: Accessor<boolean>;
+  /**
+   * True once server membership is known AND no fetch cycle is in flight.
+   * While settled, results are authoritative: a windowed query returning fewer
+   * rows than its LIMIT really is the end of the list. Not monotonic: a later
+   * sync round re-enters `isFetching`; latch it if a verdict must stick.
+   */
+  isSettled: Accessor<boolean>;
+};
+
+// Overload: context-based (no explicit db)
+export function createQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: QueryOptions
+): CreateQueryResult<TData>;
+
+// Overload: explicit db
+export function createQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  db: SyncedDb<S>,
+  finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: QueryOptions
+): CreateQueryResult<TData>;
+
+// Implementation
+export function createQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends {
+    columns: Record<string, ColumnSchema>;
+  },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  dbOrQuery: SyncedDb<S> | QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  queryOrOptions?: QueryArg<S, TableName, T, RelatedFields, IsOne> | QueryOptions,
+  maybeOptions?: QueryOptions
+): CreateQueryResult<TData> {
+  let db: SyncedDb<S>;
+  let finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>;
+  let options: QueryOptions | undefined;
+
+  if (dbOrQuery instanceof SyncedDb) {
+    db = dbOrQuery;
+    finalQuery = queryOrOptions as QueryArg<S, TableName, T, RelatedFields, IsOne>;
+    options = maybeOptions;
+  } else {
+    db = useDb<S>();
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as QueryOptions | undefined;
+  }
+
+  const sp00ky = db.getSp00ky();
+
+  // Status channel. Written from subscription callbacks and generator
+  // continuations, which run outside any tracking scope — `ownedWrite` opts
+  // these signals out of Solid 2's owned-scope write guard.
+  const [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true });
+  // Server membership known for the current identity (core `membershipKnown`).
+  const [isAuthoritative, setIsAuthoritative] = createSignal(false, { ownedWrite: true });
+  // An emission WITH data has been applied for the current identity. Together
+  // with `isAuthoritative` this is what ends the cold-load state: a cached
+  // paint ends it without the server, a server answer ends it without rows.
+  const [hasPainted, setHasPainted] = createSignal(false, { ownedWrite: true });
+  const [isFetching, setIsFetching] = createSignal(false, { ownedWrite: true });
+
+  // The hash of the currently-installed subscription, for opt-in deregister on
+  // dispose (see `deregisterOnCleanup`).
+  let activeHash: string | undefined;
+
+  // Results live in a plain store, written from the engine's subscription
+  // callback and reconciled in place keyed by `id`, so unchanged rows keep
+  // identity and coarse readers (`<For>`) are notified on add/remove/reorder.
+  //
+  // NOT an async-generator projection. A live query's generator never returns:
+  // it awaits the next emission forever, which leaves its node permanently
+  // PENDING. Solid 2 holds a navigation transition until every pending node in
+  // the new tree settles, so with a generator here the first client-side
+  // navigation into a screen that opens a query never commits: the URL and
+  // effects update while the old DOM stays on screen, with no error and no
+  // <Loading> fallback that can rescue it. Subscription writes settle
+  // immediately, which is what the Solid 1 binding did too.
+  //
+  // Wrapped in an object so `one()` queries (row object or null) and list
+  // queries share one store shape; `mergeRows` keys `value`'s contents by id.
+  const [store, setStore] = createStore<{ value: TData }>({ value: null as TData });
+
+  // Identity of the installed subscription, so a superseded run cannot write
+  // results for a query the caller has already moved off.
+  let runId = 0;
+
+  // Woken by the first result or error, for the suspending `ready()` read.
+  let readyWaiters: (() => void)[] = [];
+  const wakeReady = () => {
+    const waiters = readyWaiters;
+    readyWaiters = [];
+    for (const w of waiters) w();
+  };
+
+  // Tracked: the query identity and the `enabled` gate. Untracked apply: the
+  // registration + subscription, whose teardown is the returned cleanup.
+  createEffect(
+    () => {
+      const enabled = options?.enabled?.() ?? true;
+      const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+      return { enabled, query };
+    },
+    ({ enabled, query }) => {
+      const myRun = ++runId;
+      // A new identity starts clean: a previous identity's failure must not
+      // keep this one out of its loading state.
+      setIsAuthoritative(false);
+      setHasPainted(false);
+      setError(undefined);
+      if (!enabled || !query) return;
+
+      const cleanups: (() => void)[] = [];
+      let disposed = false;
+      // `sp00ky.subscribe` resolves its unsubscribe asynchronously; the status
+      // subscription returns one directly. Accept both, and if teardown already
+      // happened while the promise was in flight, unsubscribe immediately.
+      const addCleanup = (c: (() => void) | Promise<(() => void) | undefined> | undefined) => {
+        if (!c) return;
+        if (typeof c === 'function') {
+          if (disposed) c();
+          else cleanups.push(c);
+          return;
+        }
+        void Promise.resolve(c).then((fn) => {
+          if (typeof fn !== 'function') return;
+          if (disposed) fn();
+          else cleanups.push(fn);
+        });
+      };
+
+      /**
+       * Registration can fail — the canonical case is the SSP answering 503
+       * NOT_READY while it bootstraps. Surface it as `error()` instead of
+       * throwing into the graph: the sync scheduler retries the registration
+       * underneath, so a transient failure still recovers, and a spinner
+       * driven by `isLoading()` resolves via `error()`.
+       */
+      query
+        .run()
+        .then(({ hash }: { hash: string }) => {
+          if (disposed || myRun !== runId) return;
+          activeHash = hash;
+
+          // Mirror the query's fetch status so the UI can show a "loading
+          // more" state while the sync engine pulls records in the background.
+          addCleanup(
+            sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === 'fetching'), {
+              immediate: true,
+            })
+          );
+
+          // Mirror whether the server's membership is known. This is the
+          // channel that ends a cold load for a query whose honest answer is
+          // zero rows: the core emits no second `[]` for it, but it does flip
+          // authority once the registration (or a poll) has landed. A flip
+          // back to false is a bucket switch (a different principal), whose
+          // rebind also empties the rows, so the paint latch goes with it.
+          addCleanup(
+            sp00ky.subscribeQueryAuthority(
+              hash,
+              (known) => {
+                if (disposed || myRun !== runId) return;
+                setIsAuthoritative(known);
+                if (known) wakeReady();
+                else setHasPainted(false);
+              },
+              { immediate: true }
+            )
+          );
+
+          addCleanup(
+            sp00ky.subscribe(
+              hash,
+              (rows: Record<string, any>[]) => {
+                if (disposed || myRun !== runId) return;
+                const queryData = (query.isOne ? (rows[0] ?? null) : rows) as TData;
+                // Every emission is applied as-is: the core only emits what
+                // it has decided the query holds (cached rows on mount, the
+                // server's set once membership is known), and it never emits
+                // a wrongful `[]` for a lost or still-publishing view. An
+                // emission WITH data ends the cold-load state on its own.
+                const hasRows = query.isOne
+                  ? queryData !== null && queryData !== undefined
+                  : rows.length > 0;
+                if (hasRows) {
+                  setHasPainted(true);
+                  wakeReady();
+                }
+
+                const t0 = performance.now();
+                setStore((s) => {
+                  if (query.isOne || queryData === null || !Array.isArray(s.value)) {
+                    s.value = queryData;
+                  } else {
+                    mergeRows(s.value as any[], queryData as any[]);
+                  }
+                });
+                sp00ky.reportFrontendTiming(hash, performance.now() - t0);
+              },
+              { immediate: true }
+            )
+          );
+        })
+        .catch((err: unknown) => {
+          if (disposed || myRun !== runId) return;
+          setError(err instanceof Error ? err : new Error(String(err)));
+          wakeReady();
+        });
+
+      return () => {
+        disposed = true;
+        for (const c of cleanups) c();
+      };
+    }
+  );
+
+  // Fallback empty value served before the first emission of a list query.
+  const emptyList = [] as unknown as TData;
+
+  const data: Accessor<TData> = () => {
+    const v = store.value;
+    if (v === null || v === undefined) {
+      const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+      if (query && !query.isOne) return emptyList;
+    }
+    return v as TData;
+  };
+
+  // Suspending read: pends until the first real result (or error). Reading it
+  // inside <Loading> integrates with Solid 2's boundary protocol; `data` stays
+  // non-throwing.
+  //
+  // `lazy` matters, and so does the promise actually resolving: an unresolved
+  // async node stays PENDING, every queue flush carries pending nodes forward,
+  // and a navigation transition waits on them. Lazy means only a query whose
+  // `ready()` is read creates the node at all, and the deferred below is
+  // settled by the same emission (or authority flip) that ends `isLoading`.
+  const readyGate = createMemo(
+    async (): Promise<true> => {
+      if (isAuthoritative() || hasPainted() || error()) return true;
+      await new Promise<void>((resolve) => readyWaiters.push(resolve));
+      return true;
+    },
+    { lazy: true }
+  );
+  const ready: Accessor<TData> = () => {
+    readyGate();
+    return data();
+  };
+
+  // Tear down the live subscription when the hook's owner is disposed. The
+  // projection's own onCleanup (inside the compute) already unsubscribes; this
+  // hook-scope cleanup only handles the opt-in query deregistration.
+  onCleanup(() => {
+    // Opt-in: cancel the query once this hook (its last subscriber) is gone.
+    // The compute's cleanup removed this hook's callback, so deregisterQuery's
+    // refcount guard sees the true remaining-subscriber count.
+    if (options?.deregisterOnCleanup && activeHash) {
+      sp00ky.deregisterQuery(activeHash);
+    }
+  });
+
+  const hasData = () => {
+    const v = store.value as unknown;
+    return Array.isArray(v) ? v.length > 0 : v !== null && v !== undefined;
+  };
+  const isLoading = () => !isAuthoritative() && !hasPainted() && error() === undefined;
+  const isEmpty = () => isAuthoritative() && !hasData();
+  const isSettled = () => isAuthoritative() && !isFetching();
+
+  return {
+    data,
+    ready,
+    error,
+    isLoading,
+    isFetching,
+    isAuthoritative,
+    hasData,
+    isEmpty,
+    isSettled,
+  };
+}
+
+/** @deprecated Renamed `createQuery` in the Solid 2 binding. */
+export const useQuery = createQuery;

package/src/lib/create-submission.ts

@@ -0,0 +1,57 @@
+import { createSignal, type Accessor } from 'solid-js';
+
+export interface Submission<Args extends unknown[], R> {
+  /** Run the wrapped async fn. Concurrent submits share the pending flag. */
+  submit: (...args: Args) => Promise<R | undefined>;
+  /** True while at least one submit is in flight. */
+  pending: Accessor<boolean>;
+  /** Error from the most recent settled submit, cleared on the next submit. */
+  error: Accessor<Error | undefined>;
+  /** Result of the most recent successful submit. */
+  result: Accessor<R | undefined>;
+  clearError: () => void;
+}
+
+/**
+ * Thin submission-state wrapper for mutations — button spinner/disable state
+ * around `db.create/update/delete/run` calls.
+ *
+ * Deliberately NOT built on Solid 2's `action()`/`createOptimisticStore`: the
+ * spooky engine is already optimistic local-first (writes commit to the local
+ * DB and re-render through live queries before sync; `run()` is an outbox
+ * CREATE), so a transaction/revert layer on top buys nothing and `action()`'s
+ * await-vs-yield transaction escape is a real footgun. Errors here mean the
+ * LOCAL commit failed — sync/push failures surface through `useSyncStatus`
+ * and `usePendingMutations` instead.
+ */
+export function createSubmission<Args extends unknown[], R>(
+  fn: (...args: Args) => Promise<R>
+): Submission<Args, R> {
+  // Written from promise continuations — outside any tracking scope.
+  const [inFlight, setInFlight] = createSignal(0, { ownedWrite: true });
+  const [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true });
+  const [result, setResult] = createSignal<R | undefined>(undefined, { ownedWrite: true });
+
+  const submit = async (...args: Args): Promise<R | undefined> => {
+    setError(undefined);
+    setInFlight((n) => n + 1);
+    try {
+      const r = await fn(...args);
+      setResult(() => r);
+      return r;
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return undefined;
+    } finally {
+      setInFlight((n) => n - 1);
+    }
+  };
+
+  return {
+    submit,
+    pending: () => inFlight() > 0,
+    error,
+    result,
+    clearError: () => setError(undefined),
+  };
+}

package/src/lib/from-subscription.ts

@@ -0,0 +1,32 @@
+import { createMemo, onCleanup, type Accessor } from 'solid-js';
+import { conflate } from './conflate';
+
+/**
+ * Reactive view over a spooky subscribe-callback API.
+ *
+ * The memo's async generator pulls from a conflated (latest-wins) iterator;
+ * `initial` is committed as the memo's `loadingValue`, so the accessor is
+ * readable synchronously from birth and never suspends. Spooky's subscribe
+ * APIs fire immediately with the current value, so the real value lands within
+ * a tick of the first read.
+ *
+ * Teardown is manual by contract (see conflate.ts): onCleanup terminates the
+ * iterator, which unsubscribes.
+ */
+export function fromSubscription<T>(
+  subscribe: (cb: (v: T) => void) => (() => void) | Promise<() => void>,
+  initial: T
+): Accessor<T> {
+  return createMemo(
+    async function* (): AsyncGenerator<T> {
+      const it = conflate(subscribe)[Symbol.asyncIterator]();
+      onCleanup(() => void it.return?.());
+      while (true) {
+        const r = await it.next();
+        if (r.done) break;
+        yield r.value;
+      }
+    },
+    { loadingValue: initial }
+  );
+}

package/src/lib/merge-rows.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import { mergeRows, sameValue } from './merge-rows';
+
+// A stand-in for the SDK's RecordId: a class with a value-carrying toString,
+// where two instances of the same record are never `===`.
+class Rid {
+  constructor(private tb: string, private id: string) {}
+  toString() {
+    return `${this.tb}:${this.id}`;
+  }
+}
+
+// Counts field writes on a row, the way a store proxy would notify.
+function tracked(row: Record<string, unknown>) {
+  const writes: string[] = [];
+  const proxy = new Proxy(row, {
+    set(target, prop, value) {
+      writes.push(String(prop));
+      (target as any)[prop] = value;
+      return true;
+    },
+    deleteProperty(target, prop) {
+      writes.push(`delete:${String(prop)}`);
+      delete (target as any)[prop];
+      return true;
+    },
+  });
+  return { proxy, writes };
+}
+
+describe('sameValue', () => {
+  it('treats two RecordId-like wrappers of the same record as equal', () => {
+    expect(sameValue(new Rid('user', 'a'), new Rid('user', 'a'))).toBe(true);
+    expect(sameValue(new Rid('user', 'a'), new Rid('user', 'b'))).toBe(false);
+  });
+  it('compares dates by time', () => {
+    expect(sameValue(new Date(5), new Date(5))).toBe(true);
+    expect(sameValue(new Date(5), new Date(6))).toBe(false);
+  });
+  it('keeps identity semantics for plain objects and arrays', () => {
+    expect(sameValue({ a: 1 }, { a: 1 })).toBe(false);
+    expect(sameValue([1], [1])).toBe(false);
+    const o = { a: 1 };
+    expect(sameValue(o, o)).toBe(true);
+  });
+  it('never equates a value with null', () => {
+    expect(sameValue(null, new Rid('x', 'y'))).toBe(false);
+    expect(sameValue(undefined, null)).toBe(false);
+  });
+});
+
+describe('mergeRows', () => {
+  it('writes nothing when a re-emitted row only differs by wrapper identity', () => {
+    const { proxy, writes } = tracked({
+      id: new Rid('conversation', 'c1'),
+      user_a: new Rid('user', 'a'),
+      last_message_ms: 10,
+      created_at: new Date(1000),
+    });
+    const draft = [proxy];
+    mergeRows(draft, [
+      {
+        id: new Rid('conversation', 'c1'),
+        user_a: new Rid('user', 'a'),
+        last_message_ms: 10,
+        created_at: new Date(1000),
+      },
+    ]);
+    expect(writes).toEqual([]);
+  });
+
+  it('writes only the field that actually changed', () => {
+    const { proxy, writes } = tracked({
+      id: new Rid('conversation', 'c1'),
+      last_message_ms: 10,
+    });
+    const draft = [proxy];
+    mergeRows(draft, [{ id: new Rid('conversation', 'c1'), last_message_ms: 11 }]);
+    expect(writes).toEqual(['last_message_ms']);
+    expect((proxy as any).last_message_ms).toBe(11);
+  });
+
+  it('still inserts, drops and reorders rows by key', () => {
+    const a = { id: 'a', v: 1 };
+    const b = { id: 'b', v: 1 };
+    const draft: any[] = [a, b];
+    mergeRows(draft, [{ id: 'b', v: 2 }, { id: 'c', v: 1 }]);
+    expect(draft.map((r) => r.id)).toEqual(['b', 'c']);
+    expect(draft[0]).toBe(b);
+    expect(b.v).toBe(2);
+  });
+});