memorix 1.8.8 → 1.9.0

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++;
+  }
+}

package/src/sync/journal.ts

@@ -0,0 +1,162 @@
+/**
+ * Change journal — derives the set of local changes to ship without diffing
+ * the whole database, and defines the stable cross-device row identity.
+ *
+ * `sync_row_state` maps `syncKey -> SyncRowState` (version + content hash +
+ * local id). A row is "dirty" when its current content hash differs from the
+ * recorded one; a key present in state but absent from `observations` is a
+ * tombstone. These tables are additive — they never touch the `observations`
+ * schema — so enabling sync needs no migration of existing data.
+ */
+import { createHash } from 'node:crypto';
+
+import type { Observation } from '../types.js';
+import { nextVersion } from './merge.js';
+import type { ChangeEntry, SyncRowState } from './types.js';
+
+export const CREATE_SYNC_TABLES = [
+  `CREATE TABLE IF NOT EXISTS sync_row_state (
+     projectId   TEXT NOT NULL,
+     syncKey     TEXT NOT NULL,
+     obsId       INTEGER,
+     revision    INTEGER NOT NULL,
+     writer      TEXT NOT NULL,
+     kind        TEXT NOT NULL,
+     contentHash TEXT NOT NULL,
+     shippedSeq  INTEGER NOT NULL,
+     PRIMARY KEY (projectId, syncKey)
+   );`,
+  `CREATE TABLE IF NOT EXISTS sync_meta (
+     key   TEXT PRIMARY KEY,
+     value TEXT NOT NULL
+  );`,
+  `CREATE TABLE IF NOT EXISTS sync_conflicts (
+     id          TEXT PRIMARY KEY,
+     projectId   TEXT NOT NULL,
+     syncKey     TEXT NOT NULL,
+     winnerJson  TEXT NOT NULL,
+     loserJson   TEXT NOT NULL,
+     createdAt   TEXT NOT NULL,
+     reason      TEXT NOT NULL
+   );`,
+  `CREATE TABLE IF NOT EXISTS sync_outbox (
+     projectId   TEXT NOT NULL,
+     namespace   TEXT NOT NULL,
+     deviceId    TEXT NOT NULL,
+     sequence    INTEGER NOT NULL,
+     batchJson   TEXT NOT NULL,
+     statesJson  TEXT NOT NULL,
+     createdAt   TEXT NOT NULL,
+     PRIMARY KEY (projectId, namespace, deviceId, sequence)
+   );`,
+].join('\n');
+
+/** ISO timestamp helper (single source of "now" for the engine). */
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Stable cross-device identity for a row.
+ *   - Topic-keyed observations share `t:<projectId>:<topicKey>` on every
+ *     machine, so an upsert to the same topic converges instead of forking.
+ *   - Unkeyed observations get `u:<originDevice>:<originId>`, minted once at
+ *     first ship and thereafter carried in `sync_row_state`. Two devices
+ *     inserting unrelated rows can never collide, because the origin device id
+ *     is part of the key.
+ */
+export function deriveSyncKey(obs: Observation, originDevice: string): string {
+  const project = encodeURIComponent(obs.projectId);
+  if (obs.topicKey) return `p:${project}:t:${encodeURIComponent(obs.topicKey)}`;
+  return `p:${project}:u:${encodeURIComponent(originDevice)}:${obs.id}`;
+}
+
+/**
+ * Content fingerprint of the row body. Excludes replica-local fields (`id`,
+ * `writeGeneration`) so the same logical content hashes identically on every
+ * machine and does not spuriously mark a row dirty after import.
+ */
+export function contentHash(obs: Observation): string {
+  const { id: _id, writeGeneration: _wg, ...rest } = obs as Observation & { writeGeneration?: number };
+  const stable = stableJson(rest);
+  return createHash('sha256').update(stable).digest('hex');
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value as Record<string, unknown>).sort().map((key) =>
+      `${JSON.stringify(key)}:${stableJson((value as Record<string, unknown>)[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+export interface ComputeInput {
+  /** All live observations currently in the local store. */
+  current: Observation[];
+  /** Recorded sync state, keyed by syncKey. */
+  state: Map<string, SyncRowState>;
+  /** This device's stable id (becomes the `writer` of new local versions). */
+  deviceId: string;
+  projectId: string;
+}
+
+/** A change plus the row-state it should persist once the batch is shipped. */
+export interface ComputedChange {
+  entry: ChangeEntry;
+  nextState: SyncRowState;
+}
+
+/**
+ * Compute the local changes to ship: new/modified rows as upserts, and rows
+ * that vanished from `observations` (but are still live in state) as
+ * tombstones. Version numbers advance per-row from the recorded revision.
+ */
+export function computeChanges(input: ComputeInput): ComputedChange[] {
+  const { current, state, deviceId, projectId } = input;
+  const at = nowIso();
+  const changes: ComputedChange[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const obs of current) {
+    // Reuse the recorded key for this row if one exists (its origin device may
+    // differ from us); otherwise derive a fresh one.
+    const priorEntry = findStateByObsId(state, obs.id);
+    const syncKey = priorEntry?.syncKey ?? deriveSyncKey(obs, deviceId);
+    seenKeys.add(syncKey);
+
+    const hash = contentHash(obs);
+    const prior = state.get(syncKey);
+    if (prior && prior.kind === 'upsert' && prior.obsId === obs.id && prior.contentHash === hash) {
+      continue; // unchanged since last ship
+    }
+    const version = nextVersion(prior, deviceId, at);
+    changes.push({
+      entry: { syncKey, kind: 'upsert', version, contentHash: hash, row: obs },
+      nextState: { projectId, syncKey, obsId: obs.id, revision: version.revision, writer: deviceId, kind: 'upsert', contentHash: hash, shippedSeq: 0 },
+    });
+  }
+
+  // Tombstones also retract a row that was previously eligible but is now
+  // private, targeted, candidate, or ephemeral. Without this branch a user
+  // could make a memory private locally while it remained visible on another
+  // device forever. A row that was never recorded in state produces no event.
+  for (const prior of state.values()) {
+    if (prior.kind === 'tombstone') continue;
+    if (seenKeys.has(prior.syncKey)) continue;
+    const version = nextVersion(prior, deviceId, at);
+    changes.push({
+      entry: { syncKey: prior.syncKey, kind: 'tombstone', version, contentHash: '' },
+      nextState: { projectId, syncKey: prior.syncKey, obsId: null, revision: version.revision, writer: deviceId, kind: 'tombstone', contentHash: '', shippedSeq: 0 },
+    });
+  }
+
+  return changes;
+}
+
+function findStateByObsId(state: Map<string, SyncRowState>, obsId: number): SyncRowState | undefined {
+  for (const s of state.values()) {
+    if (s.kind === 'upsert' && s.obsId === obsId) return s;
+  }
+  return undefined;
+}

package/src/sync/merge.ts

@@ -0,0 +1,116 @@
+/**
+ * Merge policy — pure, convergent last-writer-wins.
+ *
+ * Every row is versioned by a per-row logical clock `(revision, writer)` and
+ * merged against the locally recorded `SyncRowState` for its `syncKey`. Because
+ * the comparison is a single strict total order, applying a set of changes in
+ * any order yields the same final state (CRDT-style convergence). Tombstones
+ * are ordinary versioned states, so a stale upsert can never resurrect a row a
+ * newer delete removed.
+ *
+ * Everything here is pure: no I/O, no store access. That keeps the policy
+ * unit-testable and identical across every remote backend.
+ */
+import type { ChangeEntry, RowVersion, SyncDecision, SyncRowState } from './types.js';
+
+/**
+ * Compare two row versions. Returns >0 if `a` wins, <0 if `b` wins, 0 if they
+ * are the same logical version. Lexicographic over `(revision, writer)`.
+ */
+export function compareVersion(a: RowVersion, b: RowVersion): number {
+  if (a.revision !== b.revision) return a.revision - b.revision;
+  if (a.writer === b.writer) return 0;
+  return a.writer < b.writer ? -1 : 1;
+}
+
+/** The next logical version for a locally originated write. */
+export function nextVersion(prior: SyncRowState | undefined, writer: string, at: string): RowVersion {
+  const revision = (prior?.revision ?? 0) + 1;
+  return { revision, writer, at };
+}
+
+export type MergeOutcome = SyncDecision['outcome'];
+
+/** What the engine must do to the local store to realize the merge result. */
+export type MergeAction =
+  | { type: 'noop' }
+  | { type: 'insert'; version: RowVersion; contentHash: string }
+  | { type: 'update'; obsId: number; version: RowVersion; contentHash: string }
+  | { type: 'remove'; obsId: number; version: RowVersion };
+
+export interface MergeInput {
+  incoming: ChangeEntry;
+  /** Locally recorded state for this syncKey, or undefined if unknown here. */
+  local: SyncRowState | undefined;
+  /** Content fingerprint of `incoming.row` (upserts only). */
+  incomingHash: string;
+}
+
+export interface MergeResult {
+  decision: SyncDecision;
+  action: MergeAction;
+}
+
+/**
+ * Decide the fate of one incoming change against local state. Pure LWW: the
+ * strictly-newer version wins; ties (same version) are treated as already
+ * applied. No lifecycle special-casing — generation/revision ordering alone
+ * guarantees a stale write never overrides a newer one.
+ */
+export function mergeOne(input: MergeInput): MergeResult {
+  const { incoming, local, incomingHash } = input;
+  const { syncKey, kind, version } = incoming;
+
+  // Nothing known locally: an upsert becomes an insert; a tombstone is still
+  // recorded (durably) so a later stale upsert cannot resurrect the row.
+  if (!local) {
+    if (kind === 'tombstone') {
+      return {
+        decision: { syncKey, kind, outcome: 'apply', reason: 'record remote tombstone' },
+        action: { type: 'noop' },
+      };
+    }
+    return {
+      decision: { syncKey, kind, outcome: 'apply', reason: 'new row from remote' },
+      action: { type: 'insert', version, contentHash: incomingHash },
+    };
+  }
+
+  const cmp = compareVersion(version, { revision: local.revision, writer: local.writer });
+  if (cmp < 0) {
+    return {
+      decision: { syncKey, kind, outcome: 'skip-older', reason: 'local version is newer' },
+      action: { type: 'noop' },
+    };
+  }
+  if (cmp === 0) {
+    return {
+      decision: { syncKey, kind, outcome: 'skip-equal', reason: 'identical version' },
+      action: { type: 'noop' },
+    };
+  }
+
+  // Incoming wins.
+  if (kind === 'tombstone') {
+    // Delete a row we still hold; if already tombstoned locally, just advance.
+    const action: MergeAction =
+      local.obsId != null ? { type: 'remove', obsId: local.obsId, version } : { type: 'noop' };
+    return {
+      decision: { syncKey, kind, outcome: 'apply', reason: 'newer tombstone' },
+      action,
+    };
+  }
+
+  // Upsert wins. Update in place if we still have a live row, else re-insert
+  // (covers reviving from a local tombstone with a genuinely newer version).
+  if (local.obsId != null) {
+    return {
+      decision: { syncKey, kind, outcome: 'apply', reason: 'newer upsert' },
+      action: { type: 'update', obsId: local.obsId, version, contentHash: incomingHash },
+    };
+  }
+  return {
+    decision: { syncKey, kind, outcome: 'apply', reason: 'newer upsert after local tombstone' },
+    action: { type: 'insert', version, contentHash: incomingHash },
+  };
+}

package/src/sync/namespace.ts

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+
+/** Stable, path-safe namespace for one canonical Git project. */
+export function syncNamespace(projectId: string): string {
+  return `project-${createHash('sha256').update(projectId).digest('hex').slice(0, 32)}`;
+}
+
+export function projectSyncPrefix(projectId: string): string {
+  return `p:${encodeURIComponent(projectId)}:`;
+}
+
+/** Device IDs are path segments in the filesystem relay and keys elsewhere. */
+export function isSafeSyncDeviceId(value: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
+}

package/src/sync/paging.ts

@@ -0,0 +1,45 @@
+/**
+ * Stable keyset cursors for append-only relay logs.
+ *
+ * An integer offset is not safe while another device appends a batch between
+ * two pages: a new key can move the offset and make an event disappear. The
+ * adapters use the last `(deviceId, sequence)` they returned instead.
+ */
+
+export interface SyncPageCursor {
+  deviceId: string;
+  sequence: number;
+}
+
+export function encodePageCursor(cursor: SyncPageCursor): string {
+  return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+}
+
+export function decodePageCursor(token: string | undefined): SyncPageCursor | undefined {
+  if (token === undefined) return undefined;
+  try {
+    const value = JSON.parse(Buffer.from(token, 'base64url').toString('utf8')) as Partial<SyncPageCursor>;
+    const sequence = value.sequence;
+    if (
+      typeof value.deviceId !== 'string'
+      || value.deviceId.length === 0
+      || typeof sequence !== 'number'
+      || !Number.isSafeInteger(sequence)
+      || sequence < 1
+    ) {
+      throw new Error('invalid cursor fields');
+    }
+    return { deviceId: value.deviceId, sequence };
+  } catch {
+    throw new Error('[memorix] sync page token is invalid');
+  }
+}
+
+export function comparePageKey(
+  left: Pick<SyncPageCursor, 'deviceId' | 'sequence'>,
+  right: Pick<SyncPageCursor, 'deviceId' | 'sequence'>,
+): number {
+  if (left.deviceId < right.deviceId) return -1;
+  if (left.deviceId > right.deviceId) return 1;
+  return left.sequence - right.sequence;
+}