memorix 1.8.9 → 1.9.0

package/src/sync/adapters/postgres.ts

@@ -0,0 +1,269 @@
+import type { ChangeBatch, SyncCompactReport, SyncPullPage, SyncRemote } from '../types.js';
+import { decodePageCursor, encodePageCursor } from '../paging.js';
+import { isSafeSyncDeviceId } from '../namespace.js';
+
+export interface SqlClient {
+  query<T>(sql: string, params: unknown[]): Promise<T[]>;
+  exec(sql: string, params: unknown[]): Promise<void>;
+  close?(): Promise<void>;
+}
+
+interface BatchRow {
+  device_id: string;
+  sequence: number | string;
+  produced_at: string;
+  payload: ChangeBatch | string;
+}
+
+export class PostgresSyncRemote implements SyncRemote {
+  readonly kind = 'postgres';
+  readonly namespace: string;
+  private available = false;
+
+  constructor(private readonly sql: SqlClient, namespace: string) {
+    this.namespace = namespace;
+  }
+
+  async init(options: { create?: boolean } = {}): Promise<void> {
+    if (options.create === false) {
+      const [row] = await this.sql.query<{ name?: string | null }>(
+        `SELECT to_regclass('memorix_sync_batches') AS name`,
+        [],
+      );
+      this.available = typeof row?.name === 'string' && row.name.length > 0;
+      return;
+    }
+    await this.sql.exec(
+      `CREATE TABLE IF NOT EXISTS memorix_sync_batches (
+        namespace text NOT NULL,
+        device_id text NOT NULL,
+        sequence bigint NOT NULL,
+        produced_at text NOT NULL,
+        payload jsonb NOT NULL,
+        PRIMARY KEY (namespace, device_id, sequence)
+      )`,
+      [],
+    );
+    // Upgrade the pre-v3 #277 table without touching its payloads. Legacy rows
+    // stay quarantined under a non-project namespace; a fresh scoped sync never
+    // accidentally imports them.
+    await this.sql.exec(
+      `ALTER TABLE memorix_sync_batches
+       ADD COLUMN IF NOT EXISTS namespace text NOT NULL DEFAULT 'legacy'`,
+      [],
+    );
+    await this.sql.exec(
+      `CREATE UNIQUE INDEX IF NOT EXISTS memorix_sync_batches_scope_key
+       ON memorix_sync_batches(namespace, device_id, sequence)`,
+      [],
+    );
+    this.available = true;
+  }
+
+  async push(batch: ChangeBatch): Promise<void> {
+    assertBatchNamespace(batch, this.namespace);
+    if (!this.available) throw new Error('[memorix] Postgres sync remote is not initialized for writes');
+    await this.sql.exec(
+      `INSERT INTO memorix_sync_batches (namespace, device_id, sequence, produced_at, payload)
+       VALUES ($1, $2, $3, $4, $5::jsonb)
+       ON CONFLICT (namespace, device_id, sequence) DO NOTHING`,
+      [this.namespace, batch.deviceId, batch.sequence, batch.producedAt, JSON.stringify(batch)],
+    );
+    const [stored] = await this.sql.query<{ payload: ChangeBatch | string }>(
+      `SELECT payload FROM memorix_sync_batches
+       WHERE namespace = $1 AND device_id = $2 AND sequence = $3`,
+      [this.namespace, batch.deviceId, batch.sequence],
+    );
+    const payload = typeof stored?.payload === 'string'
+      ? JSON.parse(stored.payload) as ChangeBatch
+      : stored?.payload;
+    if (!payload || stableJson(payload) !== stableJson(batch)) {
+      throw new Error('[memorix] Postgres relay event path already contains a different payload');
+    }
+  }
+
+  async pull(since: Record<string, number>, limit: number, pageToken?: string): Promise<SyncPullPage> {
+    assertLimit(limit);
+    if (!this.available) return { batches: [], hasMore: false };
+    const after = decodePageCursor(pageToken);
+    const sinceEntries = Object.entries(since);
+    const params: unknown[] = [this.namespace];
+    const sinceClauses: string[] = [];
+    for (const [deviceId, sequence] of sinceEntries) {
+      params.push(deviceId, sequence);
+      const deviceParam = `$${params.length - 1}`;
+      const sequenceParam = `$${params.length}`;
+      sinceClauses.push(`(device_id = ${deviceParam} AND sequence > ${sequenceParam})`);
+    }
+    if (sinceEntries.length > 0) {
+      params.push(...sinceEntries.map(([deviceId]) => deviceId));
+      const placeholders = sinceEntries.map((_, index) => `$${params.length - sinceEntries.length + index + 1}`);
+      sinceClauses.push(`device_id NOT IN (${placeholders.join(', ')})`);
+    } else {
+      sinceClauses.push('TRUE');
+    }
+    const filters = [`(${sinceClauses.join(' OR ')})`];
+    if (after) {
+      params.push(after.deviceId, after.sequence);
+      const deviceParam = `$${params.length - 1}`;
+      const sequenceParam = `$${params.length}`;
+      filters.push(`(device_id > ${deviceParam} OR (device_id = ${deviceParam} AND sequence > ${sequenceParam}))`);
+    }
+    params.push(limit + 1);
+    const rows = await this.sql.query<BatchRow>(
+      `SELECT device_id, sequence, produced_at, payload
+       FROM memorix_sync_batches
+       WHERE namespace = $1 AND ${filters.join(' AND ')}
+       ORDER BY device_id, sequence
+       LIMIT $${params.length}`,
+      params,
+    );
+
+    const batches = rows
+      .map((row) => {
+        const payload = typeof row.payload === 'string'
+          ? JSON.parse(row.payload) as ChangeBatch
+          : row.payload;
+        return {
+          ...payload,
+          deviceId: row.device_id,
+          sequence: Number(row.sequence),
+          producedAt: row.produced_at,
+        };
+      })
+      .sort((left, right) => {
+        if (left.deviceId < right.deviceId) return -1;
+        if (left.deviceId > right.deviceId) return 1;
+        return left.sequence - right.sequence;
+      });
+    const hasMore = batches.length > limit;
+    const page = batches.slice(0, limit);
+    return {
+      batches: page,
+      hasMore,
+      nextPageToken: hasMore && page.length > 0
+        ? encodePageCursor(page[page.length - 1])
+        : undefined,
+    };
+  }
+
+  async compact(through: Record<string, number>, options: { dryRun?: boolean } = {}): Promise<SyncCompactReport> {
+    if (!this.available) return { candidates: 0, deleted: 0 };
+    const entries = Object.entries(through).filter(([, value]) => Number.isSafeInteger(value) && value >= 0);
+    if (entries.length === 0) return { candidates: 0, deleted: 0 };
+    const clauses: string[] = [];
+    const params: unknown[] = [this.namespace];
+    for (const [deviceId, sequence] of entries) {
+      params.push(deviceId, sequence);
+      clauses.push(`(device_id = $${params.length - 1} AND sequence <= $${params.length})`);
+    }
+    const where = `namespace = $1 AND (${clauses.join(' OR ')})`;
+    const [row] = await this.sql.query<{ count: number | string }>(`SELECT COUNT(*) AS count FROM memorix_sync_batches WHERE ${where}`, params);
+    const candidates = Number(row?.count ?? 0);
+    if (!options.dryRun && candidates > 0) await this.sql.exec(`DELETE FROM memorix_sync_batches WHERE ${where}`, params);
+    return { candidates, deleted: options.dryRun ? 0 : candidates };
+  }
+
+  async close(): Promise<void> {
+    await this.sql.close?.();
+  }
+}
+
+function assertBatchNamespace(batch: ChangeBatch, namespace: string): void {
+  if (batch.namespace !== namespace) {
+    throw new Error('[memorix] sync batch namespace does not match the Postgres relay');
+  }
+  if (!isSafeSyncDeviceId(batch.deviceId)) {
+    throw new Error('[memorix] sync batch has an invalid device id');
+  }
+}
+
+function assertLimit(limit: number): void {
+  if (!Number.isSafeInteger(limit) || limit < 1) {
+    throw new Error('[memorix] sync pull limit must be a positive integer');
+  }
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+interface PgPool {
+  query(sql: string, params: unknown[]): Promise<{ rows: unknown[] }>;
+  end?(): Promise<void>;
+}
+
+interface PgModule {
+  Pool?: new (config: Record<string, unknown>) => PgPool;
+  default?: {
+    Pool?: new (config: Record<string, unknown>) => PgPool;
+  };
+}
+
+export async function createPgSqlClient(env: NodeJS.ProcessEnv = process.env): Promise<SqlClient> {
+  const connectionString = env.MEMORIX_SYNC_PG_URL;
+  let config: Record<string, unknown>;
+
+  if (connectionString) {
+    config = { connectionString };
+  } else {
+    const required = [
+      'MEMORIX_SYNC_PG_HOST',
+      'MEMORIX_SYNC_PG_PORT',
+      'MEMORIX_SYNC_PG_DB',
+      'MEMORIX_SYNC_PG_USER',
+      'MEMORIX_SYNC_PG_PASSWORD',
+    ] as const;
+    const missing = required.filter((name) => !env[name]);
+    if (missing.length > 0) {
+      throw new Error(
+        `Postgres sync requires MEMORIX_SYNC_PG_URL or all discrete settings; missing ${missing.join(', ')}`,
+      );
+    }
+
+    const port = Number(env.MEMORIX_SYNC_PG_PORT);
+    if (!Number.isInteger(port) || port <= 0) {
+      throw new Error('MEMORIX_SYNC_PG_PORT must be a positive integer');
+    }
+    config = {
+      host: env.MEMORIX_SYNC_PG_HOST,
+      port,
+      database: env.MEMORIX_SYNC_PG_DB,
+      user: env.MEMORIX_SYNC_PG_USER,
+      password: env.MEMORIX_SYNC_PG_PASSWORD,
+    };
+  }
+
+  // pg is optional by design, so a static import would make every install require it.
+  const packageName = 'pg';
+  let pg: PgModule;
+  try {
+    pg = await import(packageName) as PgModule;
+  } catch (cause) {
+    throw new Error('Postgres sync requires the optional "pg" package; install it in your application', { cause });
+  }
+
+  const Pool = pg.Pool ?? pg.default?.Pool;
+  if (!Pool) {
+    throw new Error('The installed "pg" package does not export Pool');
+  }
+  const pool = new Pool(config);
+
+  return {
+    async query<T>(sql: string, params: unknown[]): Promise<T[]> {
+      const result = await pool.query(sql, params);
+      return result.rows as T[];
+    },
+    async exec(sql: string, params: unknown[]): Promise<void> {
+      await pool.query(sql, params);
+    },
+    async close(): Promise<void> {
+      await pool.end?.();
+    },
+  };
+}

package/src/sync/engine.ts

@@ -0,0 +1,353 @@
+/**
+ * Sync engine — orchestrates push and pull against any `SyncRemote`.
+ *
+ * Local-first and off the hot path: the engine reads the local store, ships a
+ * change journal, pulls remote batches, and applies them through the pure merge
+ * policy. All identity/versioning lives in `sync_row_state`; the engine only
+ * moves data between that state, the observation store, and the remote.
+ */
+import type { Observation } from '../types.js';
+import { computeChanges, contentHash, nowIso } from './journal.js';
+import { compareVersion, mergeOne } from './merge.js';
+import { eligibleObservations } from './policy.js';
+import { isSafeSyncDeviceId } from './namespace.js';
+import type {
+  ChangeBatch,
+  SyncConflict,
+  SyncDecision,
+  SyncCursor,
+  SyncPendingBatch,
+  SyncRemote,
+  SyncReport,
+  SyncRowState,
+} from './types.js';
+import { createHash } from 'node:crypto';
+
+/**
+ * Everything the engine needs from the local side. The SQLite binding lives in
+ * `store-port.ts`; tests supply an in-memory fake.
+ */
+export interface SyncStorePort {
+  projectId(): string;
+  namespace(): string;
+  /** Stable device id for this replica. */
+  deviceId(): string;
+  /** Refuse writes when this data directory was copied to another machine. */
+  assertCanPublish(): void;
+  /** Rotate a cloned installation onto a new device identity. */
+  rotateDevice(): string;
+  /** Current local cursor for this project/remote namespace. */
+  loadCursor(): Promise<SyncCursor>;
+  saveCursor(cursor: SyncCursor): Promise<void>;
+  /** Current project observations only. */
+  loadAll(): Promise<Observation[]>;
+  /** Recorded sync state, keyed by syncKey. */
+  loadState(): Promise<Map<string, SyncRowState>>;
+  /** Upsert sync-state rows. */
+  saveState(rows: SyncRowState[]): Promise<void>;
+  /** Reserve and return a fresh local observation id (for imports). */
+  allocateId(): Promise<number>;
+  /** Insert an imported observation and its sync state atomically. */
+  applyInsert(row: Observation, state: SyncRowState): Promise<void>;
+  /** Update an existing observation and its sync state atomically. */
+  applyUpdate(row: Observation, state: SyncRowState): Promise<void>;
+  /** Remove an observation and persist its tombstone state atomically. */
+  applyRemove(id: number, state: SyncRowState): Promise<void>;
+  getById(id: number): Promise<Observation | undefined>;
+  recordConflict(conflict: SyncConflict): Promise<void>;
+  loadPendingBatches(): Promise<SyncPendingBatch[]>;
+  enqueueBatch(pending: SyncPendingBatch): Promise<void>;
+  markBatchShipped(sequence: number): Promise<void>;
+  /** Next monotonic batch sequence for this device. */
+  nextSequence(): Promise<number>;
+}
+
+const PULL_PAGE_SIZE = 100;
+const MAX_BATCH_BYTES = 750_000;
+
+export interface RunOptions {
+  deviceId: string;
+  dryRun: boolean;
+  /** When false, only pull (no local changes shipped). */
+  push: boolean;
+  /** When false, only push (no remote changes applied). */
+  pull: boolean;
+}
+
+export async function runSync(
+  store: SyncStorePort,
+  remote: SyncRemote,
+  opts: RunOptions,
+): Promise<SyncReport> {
+  const report: SyncReport = {
+    remote: remote.kind,
+    namespace: remote.namespace,
+    projectId: store.projectId(),
+    deviceId: opts.deviceId,
+    pushed: 0,
+    pulledBatches: 0,
+    applied: 0,
+    skipped: 0,
+    tombstoned: 0,
+    eligible: 0,
+    excluded: 0,
+    conflicts: 0,
+    pending: 0,
+    dryRun: opts.dryRun,
+    decisions: [],
+  };
+
+  if (remote.namespace !== store.namespace()) {
+    throw new Error('[memorix] sync refused: store and remote namespaces do not match');
+  }
+  if (store.deviceId() !== opts.deviceId) {
+    throw new Error('[memorix] sync refused: requested device does not match the local replica identity');
+  }
+  try {
+    // Check the local replica before a remote init can create a branch, table,
+    // or bucket prefix. A copied data directory must not gain write access by
+    // merely starting a sync run.
+    if (opts.push && !opts.dryRun) store.assertCanPublish();
+    await remote.init({ create: opts.push && !opts.dryRun });
+
+    // ── Push ──────────────────────────────────────────────────────────
+    if (opts.push) {
+      const pending = await store.loadPendingBatches();
+      report.pending = pending.length;
+      if (!opts.dryRun) {
+        for (const pendingBatch of pending) {
+          validateBatches([pendingBatch.batch], store.projectId(), remote.namespace);
+          if (pendingBatch.batch.deviceId !== opts.deviceId) {
+            throw new Error('[memorix] sync outbox rejected: batch belongs to another device');
+          }
+          await remote.push(pendingBatch.batch);
+          await store.saveState(pendingBatch.states);
+          await store.markBatchShipped(pendingBatch.batch.sequence);
+          report.pushed += pendingBatch.batch.entries.length;
+        }
+        report.pending = 0;
+      }
+      const current = await store.loadAll();
+      const filtered = eligibleObservations(current, store.projectId());
+      report.eligible = filtered.eligible.length;
+      report.excluded = filtered.excluded;
+      const state = await store.loadState();
+      const changes = computeChanges({
+        current: filtered.eligible,
+        state,
+        deviceId: opts.deviceId,
+        projectId: store.projectId(),
+      });
+      if (changes.length > 0) {
+        const chunks = chunkChanges(changes);
+        for (const chunk of chunks) {
+          const sequence = opts.dryRun ? 0 : await store.nextSequence();
+          const batch: ChangeBatch = {
+            formatVersion: 3,
+            namespace: remote.namespace,
+            projectId: store.projectId(),
+            deviceId: opts.deviceId,
+            sequence,
+            producedAt: nowIso(),
+            entries: chunk.map((c) => c.entry),
+          };
+          if (!opts.dryRun) validateBatches([batch], store.projectId(), remote.namespace);
+          report.pushed += chunk.length;
+          if (!opts.dryRun) {
+            const states = chunk.map((c) => ({ ...c.nextState, shippedSeq: sequence }));
+            await store.enqueueBatch({ batch, states });
+            await remote.push(batch);
+            await store.saveState(states);
+            await store.markBatchShipped(sequence);
+          }
+        }
+      }
+    }
+
+    // ── Pull ──────────────────────────────────────────────────────────
+    if (opts.pull) {
+      const cursor = await store.loadCursor();
+      const state = await store.loadState();
+      const pullSince = { ...cursor.applied };
+      let pageToken: string | undefined;
+      let hasMore = true;
+      while (hasMore) {
+        // Keep the baseline fixed for every page. Adapters use pageToken to
+        // advance through one logical pull; passing the mutating cursor here
+        // can skip later rows after page one.
+        const page = await remote.pull(pullSince, PULL_PAGE_SIZE, pageToken);
+        report.pulledBatches += page.batches.length;
+        validateBatches(page.batches, store.projectId(), remote.namespace);
+
+        for (const batch of page.batches) {
+          if (batch.deviceId === opts.deviceId) {
+            cursor.applied[batch.deviceId] = Math.max(cursor.applied[batch.deviceId] ?? 0, batch.sequence);
+            continue;
+          }
+          for (const entry of batch.entries) {
+            const local = state.get(entry.syncKey);
+            const incomingHash = entry.row ? contentHash(entry.row) : '';
+            if (entry.contentHash !== incomingHash) {
+              throw new Error('[memorix] sync batch rejected: content hash mismatch');
+            }
+            if (
+              local
+              && compareVersion(entry.version, { revision: local.revision, writer: local.writer }) === 0
+              && local.contentHash !== incomingHash
+            ) {
+              throw new Error('[memorix] sync batch rejected: same version has different content');
+            }
+            const { decision, action } = mergeOne({ incoming: entry, local, incomingHash });
+            recordDecision(report, decision);
+            if (local && entry.version.revision === local.revision && entry.version.writer !== local.writer) {
+              const currentRow = local.obsId == null ? undefined : await store.getById(local.obsId);
+              if (opts.dryRun) report.conflicts++;
+              else await recordConcurrentConflict(store, report, local, entry, action.type === 'noop' ? entry.row : currentRow);
+            }
+            if (opts.dryRun || action.type === 'noop') {
+              if (!opts.dryRun && action.type === 'noop' && decision.outcome === 'apply') {
+                const next: SyncRowState = {
+                  projectId: store.projectId(),
+                  syncKey: entry.syncKey,
+                  obsId: null,
+                  revision: entry.version.revision,
+                  writer: entry.version.writer,
+                  kind: 'tombstone',
+                  contentHash: '',
+                  shippedSeq: local?.shippedSeq ?? 0,
+                };
+                state.set(entry.syncKey, next);
+                await store.saveState([next]);
+              }
+              continue;
+            }
+
+            let next: SyncRowState;
+            if (action.type === 'insert') {
+              const newId = await store.allocateId();
+              const row = { ...entry.row!, id: newId };
+              next = { projectId: store.projectId(), syncKey: entry.syncKey, obsId: newId, revision: action.version.revision, writer: action.version.writer, kind: 'upsert', contentHash: action.contentHash, shippedSeq: local?.shippedSeq ?? 0 };
+              await store.applyInsert(row, next);
+            } else if (action.type === 'update') {
+              const row = { ...entry.row!, id: action.obsId };
+              next = { projectId: store.projectId(), syncKey: entry.syncKey, obsId: action.obsId, revision: action.version.revision, writer: action.version.writer, kind: 'upsert', contentHash: action.contentHash, shippedSeq: local?.shippedSeq ?? 0 };
+              await store.applyUpdate(row, next);
+            } else {
+              next = { projectId: store.projectId(), syncKey: entry.syncKey, obsId: null, revision: action.version.revision, writer: action.version.writer, kind: 'tombstone', contentHash: '', shippedSeq: local?.shippedSeq ?? 0 };
+              await store.applyRemove(action.obsId, next);
+            }
+            state.set(entry.syncKey, next);
+            await store.saveState([next]);
+          }
+          cursor.applied[batch.deviceId] = Math.max(cursor.applied[batch.deviceId] ?? 0, batch.sequence);
+        }
+        hasMore = page.hasMore;
+        pageToken = page.nextPageToken;
+        if (!opts.dryRun && page.batches.length > 0) await store.saveCursor(cursor);
+        if (page.batches.length === 0 && !page.nextPageToken) hasMore = false;
+        if (hasMore && !page.nextPageToken) throw new Error('[memorix] sync remote returned an unpaged continuation');
+      }
+    }
+    return report;
+  } finally {
+    await remote.close();
+  }
+}
+
+function validateBatches(batches: ChangeBatch[], projectId: string, namespace: string): void {
+  for (const batch of batches) {
+    if (batch.formatVersion !== 3 || batch.projectId !== projectId || batch.namespace !== namespace) {
+      throw new Error('[memorix] sync batch rejected: wrong format, project, or remote namespace');
+    }
+    if (
+      !isSafeSyncDeviceId(batch.deviceId)
+      || !Number.isSafeInteger(batch.sequence)
+      || batch.sequence < 1
+      || !Array.isArray(batch.entries)
+      || Buffer.byteLength(JSON.stringify(batch), 'utf8') > MAX_BATCH_BYTES
+    ) {
+      throw new Error('[memorix] sync batch rejected: malformed envelope');
+    }
+    for (const entry of batch.entries) {
+      if (
+        !entry.syncKey
+        || (entry.kind !== 'upsert' && entry.kind !== 'tombstone')
+        || !entry.version
+        || !Number.isSafeInteger(entry.version.revision)
+        || entry.version.revision < 1
+        || !entry.version.writer
+        || typeof entry.contentHash !== 'string'
+        || (entry.kind === 'tombstone' && (entry.row !== undefined || entry.contentHash !== ''))
+        || (entry.kind === 'upsert' && (!/^[a-f0-9]{64}$/.test(entry.contentHash) || entry.row === undefined))
+      ) {
+        throw new Error('[memorix] sync batch rejected: malformed change entry');
+      }
+      if (
+        entry.kind === 'upsert'
+        && (!Number.isSafeInteger(entry.row!.id) || entry.row!.id < 1 || !eligibleObservations([entry.row!], projectId).eligible.length)
+      ) {
+        throw new Error('[memorix] sync batch rejected: ineligible observation payload');
+      }
+      const incomingHash = entry.row ? contentHash(entry.row) : '';
+      if (entry.contentHash !== incomingHash) {
+        throw new Error('[memorix] sync batch rejected: content hash mismatch');
+      }
+    }
+  }
+}
+
+function chunkChanges<T extends { entry: ChangeBatch['entries'][number] }>(changes: T[]): T[][] {
+  const chunks: T[][] = [];
+  let current: T[] = [];
+  let currentBytes = 2;
+  for (const change of changes) {
+    const bytes = Buffer.byteLength(JSON.stringify(change.entry), 'utf8') + 1;
+    if (bytes + 2 > MAX_BATCH_BYTES) throw new Error('[memorix] one sync event is too large for the relay');
+    if (current.length > 0 && currentBytes + bytes > MAX_BATCH_BYTES) {
+      chunks.push(current);
+      current = [];
+      currentBytes = 2;
+    }
+    current.push(change);
+    currentBytes += bytes;
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+
+async function recordConcurrentConflict(
+  store: SyncStorePort,
+  report: SyncReport,
+  local: SyncRowState,
+  incoming: ChangeBatch['entries'][number],
+  localRow: Observation | undefined,
+): Promise<void> {
+  const incomingWins = compareVersion(incoming.version, { revision: local.revision, writer: local.writer }) > 0;
+  const loser = incomingWins ? { revision: local.revision, writer: local.writer } : incoming.version;
+  const loserRow = incomingWins ? localRow : incoming.row;
+  const id = createHash('sha256')
+    .update(`${store.projectId()}|${incoming.syncKey}|${local.revision}|${local.writer}|${incoming.version.revision}|${incoming.version.writer}`)
+    .digest('hex');
+  await store.recordConflict({
+    id,
+    projectId: store.projectId(),
+    syncKey: incoming.syncKey,
+    winner: incomingWins ? incoming.version : { revision: local.revision, writer: local.writer },
+    loser,
+    loserKind: incomingWins ? local.kind : incoming.kind,
+    loserRow,
+    createdAt: nowIso(),
+    reason: 'concurrent versions shared the same logical revision',
+  });
+  report.conflicts++;
+}
+
+function recordDecision(report: SyncReport, decision: SyncDecision): void {
+  report.decisions.push(decision);
+  if (decision.outcome === 'apply') {
+    if (decision.kind === 'tombstone') report.tombstoned++;
+    else report.applied++;
+  } else {
+    report.skipped++;
+  }
+}