@quereus/sync 3.2.1 → 4.0.0

package/dist/src/sync/sync-manager-impl.js

@@ -4,18 +4,57 @@
  * Coordinates CRDT metadata tracking and sync operations.
  * Delegates to focused sub-modules for snapshot, streaming, and change application.
  */
-import { HLCManager, compareHLC } from '../clock/hlc.js';
+import { QuereusError, StatusCode, SYNC_EVICT_TAG } from '@quereus/quereus';
+import { HLCManager, compareHLC, createHLC, deterministicTxnId, MAX_OPSEQ } from '../clock/hlc.js';
 import { generateSiteId, SITE_ID_KEY, serializeSiteIdentity, deserializeSiteIdentity, siteIdEquals, } from '../clock/site.js';
 import { ColumnVersionStore, deserializeColumnVersion } from '../metadata/column-version.js';
 import { TombstoneStore, deserializeTombstone } from '../metadata/tombstones.js';
 import { PeerStateStore } from '../metadata/peer-state.js';
 import { SchemaMigrationStore, deserializeMigration } from '../metadata/schema-migration.js';
 import { ChangeLogStore } from '../metadata/change-log.js';
+import { QuarantineStore } from '../metadata/quarantine.js';
+import { BasisLifecycleStore, classifyBasisLifecycle, basisLifecycleRecordChanged, splitRelKey, parseEvictPolicyTag, isEvictable, quietSince, } from '../metadata/basis-lifecycle.js';
 import { SYNC_KEY_PREFIX, buildAllColumnVersionsScanBounds, buildAllTombstonesScanBounds, buildAllSchemaMigrationsScanBounds, parseColumnVersionKey, parseTombstoneKey, parseSchemaMigrationKey, } from '../metadata/keys.js';
-import { persistHLCState, persistHLCStateBatch, toError } from './sync-context.js';
-import { applyChanges as applyChangesImpl } from './change-applicator.js';
+import { persistHLCStateBatch, toError } from './sync-context.js';
+import { applyChanges as applyChangesImpl, drainHeldChanges as drainHeldChangesImpl, drainReappearedTables } from './change-applicator.js';
+import { buildTransactionChangeSets } from './change-grouping.js';
 import { getSnapshot as getSnapshotImpl, applySnapshot as applySnapshotImpl } from './snapshot.js';
 import { getSnapshotStream as getSnapshotStreamImpl, applySnapshotStream as applySnapshotStreamImpl, getSnapshotCheckpoint as getSnapshotCheckpointImpl, resumeSnapshotStream as resumeSnapshotStreamImpl, } from './snapshot-stream.js';
+/**
+ * Guard a transaction's running `opSeq` against the uint32 bound. `opSeq` is
+ * serialized as a big-endian uint32 in the HLC comparison key, so a fact count
+ * exceeding {@link MAX_OPSEQ} would silently wrap and corrupt ordering — throw
+ * instead. Practically unreachable (4 billion facts in one transaction); the
+ * write side telemeters the throw via an error sync-state event.
+ */
+export function assertOpSeqInRange(opSeq) {
+    if (opSeq > MAX_OPSEQ) {
+        throw new QuereusError(`Transaction exceeds ${MAX_OPSEQ + 1} facts; opSeq exhausted`, StatusCode.ERROR);
+    }
+}
+/**
+ * Map an engine schema-change event `(objectType, type)` to the sync
+ * {@link SchemaMigrationType} it records, or `undefined` when the combination is
+ * not tracked for replication (e.g. column-level or view/trigger objects, or an
+ * `alter` on an index). A `'table' alter` is recorded as `alter_column` — the
+ * coarse "table definition changed" migration the schema-sync layer replays.
+ */
+function mapSchemaMigrationType(objectType, type) {
+    if (objectType === 'table') {
+        switch (type) {
+            case 'create': return 'create_table';
+            case 'drop': return 'drop_table';
+            case 'alter': return 'alter_column';
+        }
+    }
+    else if (objectType === 'index') {
+        switch (type) {
+            case 'create': return 'add_index';
+            case 'drop': return 'drop_index';
+        }
+    }
+    return undefined;
+}
 /**
  * Implementation of SyncManager.
  *
@@ -31,36 +70,61 @@ export class SyncManagerImpl {
     peerStates;
     changeLog;
     schemaMigrations;
+    quarantine;
+    basisLifecycle;
     syncEvents;
     applyToStore;
     getTableSchema;
-    // Pending changes for the current transaction
-    pendingChanges = [];
-    currentTransactionId = null;
-    constructor(kv, config, hlcManager, syncEvents, applyToStore, getTableSchema) {
+    /** Reclaim-by-name callback for the eviction sweep; absent ⇒ sweep is a no-op. */
+    dropLocalTable;
+    // Last basis hash recorded per basis schema (in-memory, advisory). Drives the
+    // basis-drift warning in recordLensDeployment — a warning, not durable state.
+    lastBasisHash = new Map();
+    // Cumulative unknown-table disposition counters (in-memory, observe-only —
+    // mirrors the engine's materialized-view collision stats).
+    unknownTableIgnored = 0;
+    unknownTableQuarantined = 0;
+    unknownTableForwarded = 0;
+    // Cumulative forwardable changes re-offered through getChangesSince (the
+    // store-and-forward relay's outbound activity). Distinct from
+    // unknownTableForwarded, which counts apply-time holds: a held entry is held
+    // ONCE but relayed possibly MANY times until GC, so this counter grows with
+    // relay activity, not with distinct stragglers. Bumped in collectForwardableChanges.
+    unknownTableRelayed = 0;
+    unknownTableByTable = new Map();
+    constructor(kv, config, hlcManager, syncEvents, applyToStore, getTableSchema, dropLocalTable) {
         this.kv = kv;
         this.config = config;
         this.hlcManager = hlcManager;
         this.syncEvents = syncEvents;
         this.applyToStore = applyToStore;
         this.getTableSchema = getTableSchema;
+        this.dropLocalTable = dropLocalTable;
         this.columnVersions = new ColumnVersionStore(kv);
-        this.tombstones = new TombstoneStore(kv, config.tombstoneTTL);
+        this.tombstones = new TombstoneStore(kv, config.retentionHorizonMs);
         this.peerStates = new PeerStateStore(kv);
         this.changeLog = new ChangeLogStore(kv);
         this.schemaMigrations = new SchemaMigrationStore(kv);
+        this.quarantine = new QuarantineStore(kv);
+        this.basisLifecycle = new BasisLifecycleStore(kv);
     }
     /**
      * Create a new SyncManager, initializing or loading site identity.
      *
      * @param kv - KV store for sync metadata
-     * @param storeEvents - Store event emitter to subscribe to local changes
+     * @param transactionSource - Engine transaction-commit source for local change
+     *   capture (a `Database`, or any `onTransactionCommit` emitter). When provided,
+     *   sync subscribes to `onTransactionCommit` and records CRDT metadata for each
+     *   committed local transaction — one HLC per transaction. Pass `undefined` for a
+     *   relay-only deployment (e.g. a coordinator) that captures no local DML.
      * @param config - Sync configuration
      * @param syncEvents - Sync event emitter for UI integration
      * @param applyToStore - Optional callback for applying remote changes to the store
      * @param getTableSchema - Optional callback for getting table schema by name
+     * @param dropLocalTable - Optional reclaim-by-name callback for the basis-table
+     *   eviction sweep; when absent (e.g. a relay-only coordinator) the sweep is a no-op.
      */
-    static async create(kv, storeEvents, config, syncEvents, applyToStore, getTableSchema) {
+    static async create(kv, transactionSource, config, syncEvents, applyToStore, getTableSchema, dropLocalTable) {
         // Load or create site identity
         const siteIdKey = new TextEncoder().encode(SITE_ID_KEY);
         let siteId;
@@ -89,10 +153,15 @@ export class SyncManagerImpl {
             };
         }
         const hlcManager = new HLCManager(siteId, hlcState);
-        const manager = new SyncManagerImpl(kv, config, hlcManager, syncEvents, applyToStore, getTableSchema);
-        // Subscribe to store events
-        storeEvents.onDataChange((event) => manager.handleDataChange(event));
-        storeEvents.onSchemaChange((event) => manager.handleSchemaChange(event));
+        const manager = new SyncManagerImpl(kv, config, hlcManager, syncEvents, applyToStore, getTableSchema, dropLocalTable);
+        // Capture local changes at the engine transaction boundary: one grouped
+        // `onTransactionCommit` batch ⇒ one transaction ⇒ one HLC. The store's
+        // per-table emitter is below the transaction boundary and cannot group a
+        // multi-table transaction (docs/sync.md § Transaction-Based Change Grouping),
+        // so we subscribe here, not there. Omitted for relay-only deployments.
+        transactionSource?.onTransactionCommit((batch) => {
+            void manager.handleTransactionCommit(batch);
+        });
         return manager;
     }
     // ============================================================================
@@ -104,126 +173,451 @@ export class SyncManagerImpl {
     getCurrentHLC() {
         return this.hlcManager.now();
     }
+    /**
+     * Basis-membership oracle for unknown-table detection. `getTableSchema(s,t)
+     * === undefined` ⇒ the table is outside the local basis. When no oracle was
+     * provided (e.g. a relay-only coordinator), detection is inert: every table
+     * reports in-basis and the store adapter's defensive throw governs.
+     */
+    isTableInBasis(schema, table) {
+        return this.getTableSchema ? this.getTableSchema(schema, table) !== undefined : true;
+    }
+    /**
+     * Current column names for an in-basis table via the `getTableSchema` oracle, or
+     * `undefined` when the table is outside the basis (oracle returns nothing) OR no
+     * oracle was wired. Backs the drain path's basis gate + schema-drift filter (see
+     * {@link SyncContext.getTableColumnNames}). The no-oracle `undefined` makes drain
+     * a clean no-op on a relay-only coordinator, exactly as detection is inert there.
+     */
+    getTableColumnNames(schema, table) {
+        return this.getTableSchema?.(schema, table)?.columns?.map(c => c.name);
+    }
+    /**
+     * Accumulate unknown-table disposition stats (called by the apply path after a
+     * diverted group is successfully admitted).
+     */
+    recordUnknownTable(disposition, schema, table, changeCount) {
+        if (disposition === 'quarantine') {
+            this.unknownTableQuarantined += changeCount;
+        }
+        else if (disposition === 'store-and-forward') {
+            this.unknownTableForwarded += changeCount;
+        }
+        else {
+            this.unknownTableIgnored += changeCount;
+        }
+        // byTable is the union across all dispositions (the per-disposition counters
+        // partition it) — accumulated unconditionally, never against `forwarded` alone.
+        const key = `${schema}.${table}`;
+        this.unknownTableByTable.set(key, (this.unknownTableByTable.get(key) ?? 0) + changeCount);
+    }
+    getUnknownTableStats() {
+        return {
+            ignored: this.unknownTableIgnored,
+            quarantined: this.unknownTableQuarantined,
+            forwarded: this.unknownTableForwarded,
+            relayed: this.unknownTableRelayed,
+            byTable: new Map(this.unknownTableByTable),
+        };
+    }
     // ============================================================================
-    // Event Handlers (local store changes)
+    // Basis-table lifecycle (legacy-table retirement bookkeeping)
     // ============================================================================
     /**
-     * Handle a data change event from the store.
-     * Records CRDT metadata for the change.
+     * Record one logical schema's lens deployment over its basis, recomputing the
+     * durable per-basis-table lifecycle classification (`docs/migration.md`
+     * § 2 Converge). See {@link SyncManager.recordLensDeployment}.
+     *
+     * The snapshot is scoped to ONE logical schema, so this schema's directly-mapped
+     * contribution is stored per-schema (`mappedBy`) and the aggregate state ORs all
+     * schemas — a basis table stays `directly-mapped` until the last mapper drops it.
+     * The classification is a pure function of `(snapshot, basis schema)`, both
+     * reachable from `db`: the directly-mapped set is the union of every table
+     * snapshot's `relationBacking` keys (plus deferred surrogate-split members), and
+     * the basis membership / derivation sources come from enumerating the basis
+     * schema's tables.
      */
-    async handleDataChange(event) {
-        try {
-            if (event.remote)
-                return;
-            const hlc = this.hlcManager.tick();
-            const { schemaName, tableName, type, oldRow, newRow } = event;
-            const pk = event.key ?? event.pk;
-            if (!pk) {
-                console.warn(`[Sync] Missing primary key for ${schemaName}.${tableName} ${type} event — change not tracked`);
-                return;
+    async recordLensDeployment(db, logicalSchemaName, snapshot) {
+        const logical = logicalSchemaName.toLowerCase();
+        // This schema's directly-mapped contribution: the union of every table
+        // snapshot's basis relations. surrogateMemberKeys mark deferred surrogate-split
+        // members that back the table INDIRECTLY — fold them in as referenced so a
+        // deferred member is never misclassified as an eviction candidate.
+        const directlyMapped = new Set();
+        for (const tableSnapshot of snapshot.tables.values()) {
+            for (const key of tableSnapshot.relationBacking.keys())
+                directlyMapped.add(key);
+            if (tableSnapshot.surrogateMemberKeys) {
+                for (const key of tableSnapshot.surrogateMemberKeys)
+                    directlyMapped.add(key);
             }
-            const batch = this.kv.batch();
-            if (type === 'delete') {
-                this.tombstones.setTombstoneBatch(batch, schemaName, tableName, pk, hlc);
-                this.changeLog.recordDeletionBatch(batch, hlc, schemaName, tableName, pk);
-                await this.columnVersions.deleteRowVersions(schemaName, tableName, pk);
-                const change = {
-                    type: 'delete',
-                    schema: schemaName,
-                    table: tableName,
-                    pk,
-                    hlc,
-                };
-                this.pendingChanges.push(change);
-            }
-            else {
-                if (newRow) {
-                    await this.recordColumnVersions(batch, schemaName, tableName, pk, oldRow, newRow, hlc);
+        }
+        // Enumerate the basis schema (the common case is `main`, but the basis may be
+        // an attached schema — resolve by name). basisMembership = all table keys;
+        // derivationSources = union of every maintained table's sourceTables.
+        const basisSchema = db.schemaManager.getSchema(snapshot.basisSchemaName);
+        const basisMembership = new Set();
+        const derivationSources = new Set();
+        const displayName = new Map();
+        // Snapshot the eviction-policy tag + secondary-index names of each in-basis
+        // table NOW: both are gone once the table detaches (its schema + tag vanish),
+        // and the eviction sweep needs the index list to reclaim index stores by name.
+        const evictPolicyByKey = new Map();
+        const indexNamesByKey = new Map();
+        if (basisSchema) {
+            for (const table of basisSchema.getAllTables()) {
+                const key = `${table.schemaName}.${table.name}`.toLowerCase();
+                basisMembership.add(key);
+                displayName.set(key, { schema: table.schemaName, table: table.name });
+                for (const src of table.derivation?.sourceTables ?? []) {
+                    derivationSources.add(src.toLowerCase());
                 }
+                const policy = parseEvictPolicyTag(table.tags?.[SYNC_EVICT_TAG] ?? null);
+                if (policy !== undefined)
+                    evictPolicyByKey.set(key, policy);
+                const indexNames = (table.indexes ?? []).map(i => i.name);
+                if (indexNames.length > 0)
+                    indexNamesByKey.set(key, indexNames);
+            }
+        }
+        else if (snapshot.basisSchemaName) {
+            console.warn(`[Sync] recordLensDeployment: basis schema '${snapshot.basisSchemaName}' not found; basis membership treated as empty`);
+        }
+        // Basis-drift detection: warn (don't silently reclassify) when the basis hash
+        // changed out-of-band vs. the last deploy we recorded for this basis.
+        const priorHash = this.lastBasisHash.get(snapshot.basisSchemaName);
+        if (priorHash !== undefined && priorHash !== snapshot.basisHash) {
+            console.warn(`[Sync] recordLensDeployment: basis '${snapshot.basisSchemaName}' hash drifted out-of-band `
+                + `(recorded ${priorHash || '∅'}, current ${snapshot.basisHash || '∅'})`);
+        }
+        this.lastBasisHash.set(snapshot.basisSchemaName, snapshot.basisHash);
+        const stored = await this.basisLifecycle.getAll();
+        // The universe of basis-relation keys to (re)classify: the current basis +
+        // its derivation sources + this schema's directly-mapped set + every stored
+        // record. directlyMapped is folded in (beyond the ticket's literal
+        // membership/derivation/stored universe) so every relation the lens maps is
+        // tracked even in the defensive case where the basis schema can't be resolved
+        // — a no-op normally, since a mapped relation is a real basis table. Stored
+        // keys keep an empty/detach deploy revisiting tables it no longer maps.
+        const keys = new Set([...basisMembership, ...derivationSources, ...directlyMapped, ...stored.keys()]);
+        const now = Date.now();
+        const batch = this.kv.batch();
+        let wroteAny = false;
+        const pendingEvents = [];
+        // Tables transitioning detached → present this deploy: a retired table the lens
+        // re-maps back into the basis. Its held out-of-basis changes should replay NOW
+        // (after the lifecycle records are durable) rather than waiting on the periodic
+        // sweep — the lens-redeploy sibling of the inbound-create_table reappearance path.
+        const reappeared = [];
+        for (const key of keys) {
+            const prior = stored.get(key);
+            // OR this schema's contribution into the per-schema mapper set: add when it
+            // maps the table now, remove when it no longer does (so the LAST mapper
+            // dropping it is what flips the aggregate off directly-mapped).
+            const mapped = new Set((prior?.mappedBy ?? []).map(s => s.toLowerCase()));
+            if (directlyMapped.has(key))
+                mapped.add(logical);
+            else
+                mapped.delete(logical);
+            const mappedBy = [...mapped].sort();
+            const derivationSource = derivationSources.has(key);
+            const inBasis = basisMembership.has(key);
+            const state = classifyBasisLifecycle(mappedBy, derivationSource, inBasis);
+            // Stamp mapped-since on entry into directly-mapped (clearing any prior
+            // unmapped-since); unmapped-since on exit from it (the retirement hint).
+            const wasMapped = prior?.state === 'directly-mapped';
+            const isMapped = state === 'directly-mapped';
+            let mappedSince = prior?.mappedSince;
+            let unmappedSince = prior?.unmappedSince;
+            if (isMapped && !wasMapped) {
+                mappedSince = now;
+                unmappedSince = undefined;
+            }
+            else if (!isMapped && wasMapped) {
+                unmappedSince = now;
+            }
+            // Stamp detached-at on entry into detached (the eviction quiet-clock
+            // fallback when the table was never directly mapped); clear it on re-attach.
+            const wasDetached = prior?.state === 'detached';
+            const isDetached = state === 'detached';
+            let detachedAt = prior?.detachedAt;
+            if (isDetached && !wasDetached)
+                detachedAt = now;
+            else if (!isDetached)
+                detachedAt = undefined;
+            // Eviction override + index list: while in-basis the tag/index list are
+            // authoritative (re-captured each deploy, so a removed tag clears the
+            // override); once out of basis they are gone, so carry the prior record's.
+            const evictPolicy = inBasis ? evictPolicyByKey.get(key) : prior?.evictPolicy;
+            const indexNames = inBasis ? indexNamesByKey.get(key) : prior?.indexNames;
+            const display = displayName.get(key)
+                ?? (prior ? { schema: prior.schema, table: prior.table } : splitRelKey(key));
+            const record = {
+                schema: display.schema,
+                table: display.table,
+                state,
+                mappedBy,
+                derivationSource,
+                inBasis,
+                ...(mappedSince !== undefined ? { mappedSince } : {}),
+                ...(unmappedSince !== undefined ? { unmappedSince } : {}),
+                ...(detachedAt !== undefined ? { detachedAt } : {}),
+                // The dynamic signal is owned by the change applicator — carry through here.
+                ...(prior?.lastDirectlyMappedWriteAt !== undefined ? { lastDirectlyMappedWriteAt: prior.lastDirectlyMappedWriteAt } : {}),
+                ...(evictPolicy !== undefined ? { evictPolicy } : {}),
+                ...(indexNames && indexNames.length > 0 ? { indexNames } : {}),
+            };
+            if (!prior || basisLifecycleRecordChanged(prior, record)) {
+                this.basisLifecycle.put(batch, record);
+                wroteAny = true;
+            }
+            // Emit only on an ACTUAL state change of an already-tracked table — a
+            // brand-new table's first classification and an idempotent re-apply emit
+            // nothing (a spurious event would mislead the retirement hint).
+            if (prior && prior.state !== state) {
+                pendingEvents.push({
+                    schema: record.schema,
+                    table: record.table,
+                    previousState: prior.state,
+                    newState: state,
+                    at: now,
+                });
+            }
+            // Detached → present (any in-basis state): a previously-retired table this
+            // deploy re-mapped back into the basis — its held out-of-basis changes should
+            // replay now. Use the precise `detached → present` transition rather than the
+            // broader "inBasis newly true": held entries only ever exist for previously
+            // out-of-basis tables, so the precise check skips spurious scoped scans for
+            // brand-new tables (excluded anyway by the `prior` guard). A cheapness
+            // optimization, not a correctness gate — drainHeldChanges' oracle gate makes
+            // any over-trigger a harmless no-op.
+            if (wasDetached && !isDetached) {
+                reappeared.push({ schema: record.schema, table: record.table });
             }
-            // Persist HLC state in batch (DRY: uses shared helper)
-            persistHLCStateBatch(this, batch);
+        }
+        if (wroteAny)
             await batch.write();
-            const changesToEmit = [...this.pendingChanges];
-            this.pendingChanges = [];
-            this.syncEvents.emitLocalChange({
-                transactionId: this.currentTransactionId || crypto.randomUUID(),
-                changes: changesToEmit,
-                pendingSync: true,
-            });
+        // Emit AFTER the records are durable, so a listener that reads back
+        // getBasisTableLifecycle() sees the committed transition.
+        for (const event of pendingEvents) {
+            this.syncEvents.emitBasisTableLifecycle(event);
         }
-        catch (error) {
-            console.error('[Sync] Error handling data change:', error);
-            this.syncEvents.emitSyncStateChange({
-                status: 'error',
-                error: toError(error),
+        // Reactive low-latency drain (sync-drain-reappear-lens-redeploy): a table this
+        // deploy re-mapped detached → present may hold out-of-basis changes waiting on it.
+        // Replay them as a SEPARATE post-commit apply unit, after the lifecycle batch above
+        // is durable and its events have fired, so the oracle (getTableColumnNames) sees the
+        // re-attached table and the held changes LWW-resolve against the present basis —
+        // instead of waiting up to one periodic-sweep interval. Symmetric with the
+        // inbound-create_table path in applyChanges. Advisory: drainReappearedTables logs +
+        // swallows any per-table failure, so a drain throw never aborts the deploy (which is
+        // itself advisory bookkeeping — the store-module forwarder wraps it in try/catch).
+        //
+        // RE-ENTRANCY: in production this runs inside the firing `apply schema` statement,
+        // which holds the engine exec mutex (the module `notifyLensDeployment` hook is awaited
+        // mid-statement). The drain re-enters the engine via `applyToStore` →
+        // `db.ingestExternalRowChanges`, which acquires that same mutex — awaiting it inline
+        // would deadlock (the statement can't release the mutex until this returns). So when
+        // the engine reports it is mid-statement, defer the drain to fire-and-forget: it queues
+        // on the mutex and runs the instant `apply schema` commits and releases it (callers
+        // observe the drained rows after the capture settle, exactly like the local-change
+        // capture). Outside a live statement (e.g. unit tests over a stub store that never
+        // touches the engine mutex), await inline so the drain completes before returning.
+        if (reappeared.length > 0) {
+            if (db._isExecuting?.()) {
+                void drainReappearedTables(this, reappeared);
+            }
+            else {
+                await drainReappearedTables(this, reappeared);
+            }
+        }
+    }
+    async getBasisTableLifecycle() {
+        return this.basisLifecycle.list();
+    }
+    /**
+     * Reclaim the local storage of every detached basis table that has been quiet
+     * past its effective retention horizon (`docs/migration.md` § 4 Contract).
+     * Host-driven (like {@link pruneTombstones} / {@link pruneQuarantine}) — the
+     * host schedules it; the library adds no timer. Returns the number of tables
+     * evicted.
+     *
+     * No-op when no `dropLocalTable` reclaim callback is wired (e.g. a relay-only
+     * coordinator with no store). For each evictable record it re-reads the record
+     * and re-checks eligibility immediately before dropping — guarding against a
+     * concurrent re-deploy that re-mapped the table between the scan and the drop —
+     * then drops the storage, emits `onBasisTableEvicted`, and clears the record. A
+     * `dropLocalTable` throw leaves the record in place to retry next sweep (the
+     * drop is idempotent).
+     */
+    async evictExpiredBasisTables(now = Date.now()) {
+        if (!this.dropLocalTable)
+            return 0;
+        const records = await this.basisLifecycle.list();
+        let evicted = 0;
+        for (const candidate of records) {
+            if (!isEvictable(candidate, now, this.config))
+                continue;
+            // Re-read + re-check immediately before the drop: a concurrent re-deploy
+            // may have re-mapped (and so re-attached) the table since the scan.
+            const fresh = await this.basisLifecycle.get(candidate.schema, candidate.table);
+            if (!fresh || fresh.state !== 'detached' || !isEvictable(fresh, now, this.config))
+                continue;
+            try {
+                await this.dropLocalTable(fresh.schema, fresh.table, fresh.indexNames ?? []);
+            }
+            catch (error) {
+                // Leave the record; retry next sweep. The drop is idempotent, so a
+                // partial reclaim is re-attempted rather than stranded.
+                console.warn(`[Sync] evictExpiredBasisTables: dropLocalTable failed for '${fresh.schema}.${fresh.table}'; `
+                    + `record retained for retry: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            // Storage reclaimed — clear the record (a later re-create starts fresh) and
+            // emit AFTER the drop succeeded.
+            await this.basisLifecycle.delete(fresh.schema, fresh.table);
+            this.syncEvents.emitBasisTableEvicted({
+                schema: fresh.schema,
+                table: fresh.table,
+                at: now,
+                quietForMs: now - quietSince(fresh),
             });
+            evicted++;
         }
+        return evicted;
     }
+    // ============================================================================
+    // Local change capture (engine transaction boundary)
+    // ============================================================================
     /**
-     * Handle a schema change event from the store.
-     * Records schema migrations for sync.
+     * Record CRDT metadata for one committed local transaction.
+     *
+     * Driven by the engine's `onTransactionCommit` group — the authoritative
+     * "one transaction = one HLC" boundary. The clock is ticked exactly **once**;
+     * every fact of the transaction shares that base `(wallTime, counter, siteId)`
+     * and differs only in `opSeq` (a contiguous, 0-based sub-order). DDL is recorded
+     * before DML so migrations sort below the same transaction's data facts
+     * (docs/sync.md § DDL Application Order). All metadata for the transaction —
+     * schema migrations, column versions, tombstones, change-log entries, and the
+     * HLC clock state — lands in a single KV batch.
      */
-    async handleSchemaChange(event) {
+    async handleTransactionCommit(batch) {
         try {
-            if (event.remote)
+            // Capture only LOCAL facts. An all-remote group is a pure sync-apply echo:
+            // its metadata was already recorded by the apply path. A mixed group
+            // (local + remote in one transaction — unusual) records only its local
+            // facts; opSeq is assigned only to recorded facts so they stay contiguous.
+            const localSchema = batch.schemaEvents.filter(e => !e.remote);
+            const localData = batch.dataEvents.filter(e => !e.remote);
+            if (localSchema.length === 0 && localData.length === 0)
                 return;
-            const hlc = this.hlcManager.tick();
-            const { type, objectType, schemaName, objectName, ddl } = event;
-            let migrationType;
-            if (objectType === 'table') {
-                switch (type) {
-                    case 'create':
-                        migrationType = 'create_table';
-                        break;
-                    case 'drop':
-                        migrationType = 'drop_table';
-                        break;
-                    case 'alter':
-                        migrationType = 'alter_column';
-                        break;
-                    default: return;
-                }
-            }
-            else if (objectType === 'index') {
-                switch (type) {
-                    case 'create':
-                        migrationType = 'add_index';
-                        break;
-                    case 'drop':
-                        migrationType = 'drop_index';
-                        break;
-                    default: return;
-                }
+            // ONE tick per committed transaction. tick() returns opSeq 0; the closure
+            // below stamps each successive fact with the next opSeq off the same base.
+            const base = this.hlcManager.tick();
+            const transactionId = deterministicTxnId(base);
+            let opSeq = 0;
+            const nextHlc = () => {
+                // Throw (telemetered via the catch below) rather than wrap the uint32.
+                assertOpSeqInRange(opSeq);
+                return createHLC(base.wallTime, base.counter, base.siteId, opSeq++);
+            };
+            const kvBatch = this.kv.batch();
+            const changes = [];
+            // DDL before DML: migrations take the lowest opSeqs.
+            const versionCounters = new Map();
+            for (const event of localSchema) {
+                await this.recordSchemaMigration(kvBatch, event, nextHlc, versionCounters);
             }
-            else {
-                return;
+            for (const event of localData) {
+                await this.recordDataEvent(kvBatch, event, nextHlc, changes);
             }
-            const currentVersion = await this.schemaMigrations.getCurrentVersion(schemaName, objectName);
-            const newVersion = currentVersion + 1;
-            await this.schemaMigrations.recordMigration(schemaName, objectName, {
-                type: migrationType,
-                ddl: ddl || '',
-                hlc,
-                schemaVersion: newVersion,
-            });
-            // Persist HLC state (DRY: uses shared helper)
-            await persistHLCState(this);
+            // Persist HLC clock state (wallTime/counter only — opSeq is never persisted).
+            persistHLCStateBatch(this, kvBatch);
+            await kvBatch.write();
             this.syncEvents.emitLocalChange({
-                transactionId: crypto.randomUUID(),
-                changes: [],
+                transactionId,
+                changes,
                 pendingSync: true,
             });
         }
         catch (error) {
-            console.error('[Sync] Error handling schema change:', error);
+            console.error('[Sync] Error handling transaction commit:', error);
             this.syncEvents.emitSyncStateChange({
                 status: 'error',
                 error: toError(error),
             });
         }
     }
-    async recordColumnVersions(batch, schemaName, tableName, pk, oldRow, newRow, hlc) {
+    /**
+     * Record one local schema-change event as a migration. Allocates an `opSeq`
+     * (via `nextHlc`) only when the event maps to a tracked migration, so
+     * unsupported object types consume no sub-order. `versionCounters` carries the
+     * running per-table schema version across this transaction's migrations.
+     */
+    async recordSchemaMigration(batch, event, nextHlc, versionCounters) {
+        const migrationType = mapSchemaMigrationType(event.objectType, event.type);
+        if (!migrationType)
+            return;
+        const { schemaName, objectName, ddl } = event;
+        const counterKey = `${schemaName}.${objectName}`;
+        let version = versionCounters.get(counterKey);
+        if (version === undefined) {
+            version = await this.schemaMigrations.getCurrentVersion(schemaName, objectName);
+        }
+        version += 1;
+        versionCounters.set(counterKey, version);
+        this.schemaMigrations.recordMigrationBatch(batch, schemaName, objectName, {
+            type: migrationType,
+            ddl: ddl || '',
+            hlc: nextHlc(),
+            schemaVersion: version,
+        });
+    }
+    /**
+     * Record one local data-change event: a tombstone (delete) or the changed
+     * column versions (insert/update). Each recorded fact consumes one `opSeq`.
+     */
+    async recordDataEvent(batch, event, nextHlc, changes) {
+        const { schemaName, tableName, type, oldRow, newRow } = event;
+        const pk = event.key;
+        if (!pk) {
+            console.warn(`[Sync] Missing primary key for ${schemaName}.${tableName} ${type} event — change not tracked`);
+            return;
+        }
+        if (type === 'delete') {
+            // Dedupe the change-log delete entry the same way columns are deduped: if a
+            // prior tombstone exists for this pk (a delete→reinsert→delete key reuse),
+            // its stale delete entry must go, so at most one delete entry survives per pk
+            // with HLC equal to the current tombstone. This keeps collectChangesSince's
+            // boundary detection (keyed on the log HLC) in lockstep with grouping (keyed
+            // on the resolved tombstone HLC) — see its LOAD-BEARING INVARIANT.
+            const existing = await this.tombstones.getTombstone(schemaName, tableName, pk);
+            if (existing) {
+                this.changeLog.deleteEntryBatch(batch, existing.hlc, 'delete', schemaName, tableName, pk);
+            }
+            const hlc = nextHlc();
+            // Carry the row's last-known image (the engine `oldRow`) as a best-effort
+            // before-image on both the persisted tombstone and the inline change. Copy
+            // it so neither aliases the engine's row buffer; absent when the event
+            // carried no `oldRow` (relayed/synthesized deletes).
+            const priorRow = oldRow ? [...oldRow] : undefined;
+            this.tombstones.setTombstoneBatch(batch, schemaName, tableName, pk, hlc, priorRow);
+            this.changeLog.recordDeletionBatch(batch, hlc, schemaName, tableName, pk);
+            await this.columnVersions.deleteRowVersions(schemaName, tableName, pk);
+            const change = {
+                type: 'delete',
+                schema: schemaName,
+                table: tableName,
+                pk,
+                hlc,
+                ...(priorRow !== undefined ? { priorRow } : {}),
+            };
+            changes.push(change);
+        }
+        else if (newRow) {
+            await this.recordColumnVersions(batch, schemaName, tableName, pk, oldRow, newRow, nextHlc, changes);
+        }
+    }
+    async recordColumnVersions(batch, schemaName, tableName, pk, oldRow, newRow, nextHlc, changes) {
         const tableSchema = this.getTableSchema?.(schemaName, tableName);
         const columnNames = tableSchema?.columns?.map(c => c.name);
         if (!tableSchema && this.getTableSchema) {
@@ -238,7 +632,14 @@ export class SyncManagerImpl {
                 if (oldVersion) {
                     this.changeLog.deleteEntryBatch(batch, oldVersion.hlc, 'column', schemaName, tableName, pk, column);
                 }
-                const version = { hlc, value: newValue };
+                const hlc = nextHlc();
+                // Carry the overwritten cell version as a best-effort before-image on
+                // both the persisted version and the inline change. Spread only when a
+                // prior exists — first writes carry neither field (absent, not undefined).
+                const prior = oldVersion
+                    ? { priorHlc: oldVersion.hlc, priorValue: oldVersion.value }
+                    : undefined;
+                const version = { hlc, value: newValue, ...prior };
                 this.columnVersions.setColumnVersionBatch(batch, schemaName, tableName, pk, column, version);
                 this.changeLog.recordColumnChangeBatch(batch, hlc, schemaName, tableName, pk, column);
                 const change = {
@@ -249,103 +650,186 @@ export class SyncManagerImpl {
                     column,
                     value: newValue,
                     hlc,
+                    ...prior,
                 };
-                this.pendingChanges.push(change);
+                changes.push(change);
             }
         }
     }
     // ============================================================================
     // Delta Sync API
     // ============================================================================
+    /**
+     * Extract changes for a peer as **one {@link ChangeSet} per source
+     * transaction** (grouped by HLC identity `(wallTime, counter, siteId)`),
+     * bounded at transaction granularity by `config.batchSize`. A transaction is
+     * never split across ChangeSets and two transactions are never merged, so a
+     * consumer that advances `lastSyncHLC = ChangeSet.hlc` always lands on a real
+     * commit boundary (docs/sync.md § Transaction-Based Change Grouping → Read side).
+     */
     async getChangesSince(peerSiteId, sinceHLC) {
+        const dataChanges = sinceHLC
+            ? await this.collectChangesSince(peerSiteId, sinceHLC, this.config.batchSize)
+            : await this.collectAllChanges(peerSiteId);
+        // Fold forwardable held changes (the `store-and-forward` relay's outbound
+        // half) into the SAME ChangeSet[] return — no new transport surface. Each
+        // keeps its ORIGINAL hlc + siteId, so buildTransactionChangeSets re-forms the
+        // straggler's transaction by deterministicTxnId: a forwarded change rejoins any
+        // applied part of the same straggler txn (e.g. a txn that wrote both a live and
+        // a now-retired-here table), correct by construction.
+        //
+        // BOUND + ORDERING (verify, no extra code): collectChangesSince early-exits its
+        // change-log scan at a transaction cut C; collectForwardableChanges is FULLY
+        // scanned (all `> sinceHLC`). buildTransactionChangeSets re-bounds the UNION at
+        // batchSize at a transaction boundary M ≤ C. Everything ≤ M from BOTH sources is
+        // present (change-log up to C ⊇ ≤ M; forwardable fully scanned ⊇ ≤ M), so the
+        // returned prefix is contiguous, advancing the consumer's watermark to M loses
+        // nothing, and forwardable entries with HLC in (M, …] are re-collected next round
+        // (still `> sinceHLC`). Groups are HLC-ordered, so a forwarded change interleaves
+        // with change-log changes in global HLC order — never out of order.
+        const forwardable = await this.collectForwardableChanges(peerSiteId, sinceHLC);
+        const changes = forwardable.length > 0 ? [...dataChanges, ...forwardable] : dataChanges;
+        const schemaMigrations = await this.collectSchemaMigrations(peerSiteId, sinceHLC);
+        return buildTransactionChangeSets(changes, schemaMigrations, this.config.batchSize, (transactionId, changeCount) => {
+            // Oversized transactions are returned whole (never split); telemeter
+            // rather than silently chunk so the bound breach is observable.
+            console.warn(`[Sync] Oversized transaction ${transactionId}: ${changeCount} changes exceed batchSize ${this.config.batchSize}; returned as one ChangeSet`);
+        });
+    }
+    /**
+     * Delta extraction: facts after `sinceHLC`, in change-log (HLC) order, bounded
+     * at **scan time** to whole transactions whose cumulative data-change count
+     * reaches `batchSize`.
+     *
+     * The change-log scan is keyed by `(wallTime, counter, siteId, opSeq)`, so a
+     * transaction's facts arrive contiguously and transactions arrive in commit
+     * order. That lets us stop scanning as soon as enough WHOLE transactions have
+     * accumulated, instead of draining the entire iterator into memory and letting
+     * {@link buildTransactionChangeSets} truncate afterward (the pre-
+     * `sync-getchangessince-bounded-extraction` behavior, where `batchSize` capped
+     * the response but not the scan). The bound here mirrors that grouping step
+     * exactly — whole transactions accumulate until the cumulative data-change count
+     * reaches `batchSize`, never splitting a transaction — so the grouped response
+     * is byte-identical; only the scan footprint shrinks.
+     *
+     * LOAD-BEARING INVARIANT: boundary detection keys off `logEntry.hlc`, but the
+     * grouper keys off the *resolved* version's HLC ({@link resolveLogEntry} returns
+     * `cv.hlc` / `tombstone.hlc`). These agree only when each non-null-resolving log
+     * entry's HLC equals its resolved version's HLC, which holds for BOTH entry types
+     * because each is deduped on overwrite — at most one entry survives per key, and
+     * its HLC equals the current version's:
+     *   - COLUMN: an overwrite deletes the prior `(pk, column)` entry (see
+     *     {@link recordColumnVersions} and `commitChangeMetadata`), so the survivor's
+     *     HLC is the current `cv.hlc`.
+     *   - DELETE: a newer tombstone deletes the prior `pk` delete entry (see
+     *     {@link recordDataEvent} and `commitChangeMetadata`), so a
+     *     delete→reinsert→delete key reuse no longer leaves a stale entry that
+     *     re-attributes to a later tombstone HLC; the survivor's HLC is the current
+     *     `tombstone.hlc`.
+     *
+     * The overwrite dedup above covers entries written across SEPARATE writes/applies
+     * (each later one sees the prior committed version). The apply path additionally
+     * collapses in-batch repeats: two versions of one key inside a single
+     * `applyChanges` call resolve against the SAME pre-batch prior version, so neither
+     * sees the other — `commitChangeMetadata` keeps only the max-HLC winner per key and
+     * writes a single entry, preserving the invariant regardless of how many versions
+     * of a key were batched.
+     *
+     * (Schema migrations are still fully scanned by {@link collectSchemaMigrations};
+     * the `sm:` range is not HLC-ordered, but migrations are few and the grouping
+     * step drops any that sort past the bounded fact watermark.)
+     */
+    async collectChangesSince(peerSiteId, sinceHLC, batchSize) {
         const changes = [];
-        if (sinceHLC) {
-            for await (const logEntry of this.changeLog.getChangesSince(sinceHLC)) {
-                if (siteIdEquals(logEntry.hlc.siteId, peerSiteId))
-                    continue;
-                if (logEntry.entryType === 'column') {
-                    const cv = await this.columnVersions.getColumnVersion(logEntry.schema, logEntry.table, logEntry.pk, logEntry.column);
-                    if (!cv)
-                        continue;
-                    const columnChange = {
-                        type: 'column',
-                        schema: logEntry.schema,
-                        table: logEntry.table,
-                        pk: logEntry.pk,
-                        column: logEntry.column,
-                        value: cv.value,
-                        hlc: cv.hlc,
-                    };
-                    changes.push(columnChange);
-                }
-                else {
-                    const tombstone = await this.tombstones.getTombstone(logEntry.schema, logEntry.table, logEntry.pk);
-                    if (!tombstone)
-                        continue;
-                    const deletion = {
-                        type: 'delete',
-                        schema: logEntry.schema,
-                        table: logEntry.table,
-                        pk: logEntry.pk,
-                        hlc: tombstone.hlc,
-                    };
-                    changes.push(deletion);
-                }
-            }
-        }
-        else {
-            await this.collectAllChanges(peerSiteId, changes);
-        }
-        // Collect schema migrations
-        const schemaMigrations = [];
-        const smBounds = buildAllSchemaMigrationsScanBounds();
-        for await (const entry of this.kv.iterate(smBounds)) {
-            const parsed = parseSchemaMigrationKey(entry.key);
-            if (!parsed)
-                continue;
-            const migration = deserializeMigration(entry.value);
-            if (sinceHLC && compareHLC(migration.hlc, sinceHLC) <= 0)
+        // Data-change count over fully-scanned (whole) transactions. The in-flight
+        // transaction's own count is held separately until its boundary is crossed,
+        // so it is only folded in once the transaction is known to be complete.
+        let completedChangeCount = 0;
+        let currentTxnId = null;
+        let currentTxnChangeCount = 0;
+        for await (const logEntry of this.changeLog.getChangesSince(sinceHLC)) {
+            // A transaction is wholly one site's, so skipping the peer's own facts
+            // filters whole transactions cleanly (no half-empty ChangeSet).
+            if (siteIdEquals(logEntry.hlc.siteId, peerSiteId))
                 continue;
-            if (siteIdEquals(migration.hlc.siteId, peerSiteId))
+            // deterministicTxnId excludes opSeq, so it is exactly the transaction
+            // identity. Facts of one transaction are contiguous in the HLC-ordered
+            // scan, so a change of id means the prior transaction is complete and can
+            // be folded into the bound.
+            const txnId = deterministicTxnId(logEntry.hlc);
+            if (currentTxnId !== null && txnId !== currentTxnId) {
+                completedChangeCount += currentTxnChangeCount;
+                // Enough whole transactions accumulated — stop before touching the next
+                // one. buildTransactionChangeSets re-applies the same bound, so feeding
+                // it this prefix yields the same ChangeSets the full scan would have.
+                if (completedChangeCount >= batchSize)
+                    break;
+                currentTxnChangeCount = 0;
+            }
+            currentTxnId = txnId;
+            const change = await this.resolveLogEntry(logEntry);
+            if (!change)
                 continue;
-            schemaMigrations.push({
-                type: migration.type,
-                schema: parsed.schema,
-                table: parsed.table,
-                ddl: migration.ddl,
-                hlc: migration.hlc,
-                schemaVersion: migration.schemaVersion,
-            });
-        }
-        if (changes.length === 0 && schemaMigrations.length === 0) {
-            return [];
-        }
-        schemaMigrations.sort((a, b) => compareHLC(a.hlc, b.hlc));
-        const result = [];
-        for (let i = 0; i < changes.length; i += this.config.batchSize) {
-            const batch = changes.slice(i, i + this.config.batchSize);
-            const maxHLC = batch.reduce((max, c) => compareHLC(c.hlc, max) > 0 ? c.hlc : max, batch[0].hlc);
-            result.push({
-                siteId: this.getSiteId(),
-                transactionId: crypto.randomUUID(),
-                hlc: maxHLC,
-                changes: batch,
-                schemaMigrations: i === 0 ? schemaMigrations : [],
-            });
+            changes.push(change);
+            currentTxnChangeCount++;
         }
-        if (result.length === 0 && schemaMigrations.length > 0) {
-            const maxHLC = schemaMigrations.reduce((max, m) => compareHLC(m.hlc, max) > 0 ? m.hlc : max, schemaMigrations[0].hlc);
-            result.push({
-                siteId: this.getSiteId(),
-                transactionId: crypto.randomUUID(),
-                hlc: maxHLC,
-                changes: [],
-                schemaMigrations,
-            });
+        return changes;
+    }
+    /**
+     * Resolve a change-log entry to the live {@link Change} it references, or
+     * `null` when the underlying column version / tombstone is gone — a stale log
+     * entry (e.g. a column overwritten, or a row deleted after the entry was
+     * written). The authoritative HLC and value come from the current version, not
+     * the log key.
+     */
+    async resolveLogEntry(logEntry) {
+        if (logEntry.entryType === 'column') {
+            const cv = await this.columnVersions.getColumnVersion(logEntry.schema, logEntry.table, logEntry.pk, logEntry.column);
+            if (!cv)
+                return null;
+            const columnChange = {
+                type: 'column',
+                schema: logEntry.schema,
+                table: logEntry.table,
+                pk: logEntry.pk,
+                column: logEntry.column,
+                value: cv.value,
+                hlc: cv.hlc,
+                // Re-emit the stored before-image (spread only when present), so a
+                // receiver/relay forwards the origin's prior chain unchanged.
+                ...(cv.priorHlc !== undefined ? { priorHlc: cv.priorHlc, priorValue: cv.priorValue } : {}),
+            };
+            return columnChange;
         }
-        return result;
+        const tombstone = await this.tombstones.getTombstone(logEntry.schema, logEntry.table, logEntry.pk);
+        if (!tombstone)
+            return null;
+        const deletion = {
+            type: 'delete',
+            schema: logEntry.schema,
+            table: logEntry.table,
+            pk: logEntry.pk,
+            hlc: tombstone.hlc,
+            // Re-emit the stored before-image (spread only when present) so a
+            // receiver/relay forwards the origin's last-known row image unchanged.
+            ...(tombstone.priorRow !== undefined ? { priorRow: tombstone.priorRow } : {}),
+        };
+        return deletion;
     }
-    async collectAllChanges(peerSiteId, changes) {
+    /**
+     * Full extraction (initial sync / delta-from-zero): every column version and
+     * tombstone not originating from the peer. Ordering is owned by
+     * {@link buildTransactionChangeSets}, so no pre-sort is needed here.
+     *
+     * Unlike {@link collectChangesSince}, this path cannot early-exit at scan time:
+     * the `cv:`/`tb:` scans are keyed by table/pk, NOT by HLC, so transactions are
+     * interleaved arbitrarily and no transaction boundary is reachable without a
+     * full scan + sort. It is left unbounded because it is the from-zero path: a
+     * large initial range is expected to be served by a snapshot rather than this
+     * delta path (docs/sync.md).
+     */
+    async collectAllChanges(peerSiteId) {
+        const changes = [];
         const cvBounds = buildAllColumnVersionsScanBounds();
         for await (const entry of this.kv.iterate(cvBounds)) {
             const parsed = parseColumnVersionKey(entry.key);
@@ -362,6 +846,7 @@ export class SyncManagerImpl {
                 column: parsed.column,
                 value: cv.value,
                 hlc: cv.hlc,
+                ...(cv.priorHlc !== undefined ? { priorHlc: cv.priorHlc, priorValue: cv.priorValue } : {}),
             };
             changes.push(columnChange);
         }
@@ -379,10 +864,107 @@ export class SyncManagerImpl {
                 table: parsed.table,
                 pk: parsed.pk,
                 hlc: tombstone.hlc,
+                ...(tombstone.priorRow !== undefined ? { priorRow: tombstone.priorRow } : {}),
             };
             changes.push(deletion);
         }
-        changes.sort((a, b) => compareHLC(a.hlc, b.hlc));
+        return changes;
+    }
+    /**
+     * Collect forwardable held changes to re-offer to a peer — the outbound half of
+     * the `store-and-forward` unknown-table disposition. Source is
+     * {@link QuarantineStore.listForwardable}: straggler changes this peer held
+     * because it has retired the table, marked forwardable. Each is re-offered with
+     * its ORIGINAL `hlc` + `siteId` (the straggler's fact, not a new local one) — the
+     * identity that makes the relay loop-free and convergent across hops with NO
+     * per-table peer-membership oracle (none exists): a peer that already holds the
+     * change re-holds it idempotently (HLC-keyed) and the per-peer watermark stops
+     * re-send after one exchange.
+     *
+     * Two filters, mirroring {@link collectChangesSince} / {@link collectAllChanges}:
+     *  - **Echo exclusion** — drop a change whose origin (`change.hlc.siteId`) is the
+     *    peer itself, so a straggler's fact is never echoed back to its own author.
+     *  - **Watermark filter** — when `sinceHLC` is defined (delta path), keep only
+     *    `compareHLC(change.hlc, sinceHLC) > 0`. REQUIRED: the consumer advances its
+     *    per-peer `lastSyncHLC` to `max(returned ChangeSet.hlc)`, so a round that
+     *    returned a forwarded change with HLC ≤ the watermark would REGRESS it and
+     *    trigger a re-scan/re-deliver flood. Filtering `> sinceHLC` keeps the merged
+     *    response a safe contiguous prefix — exactly the change-log contract. When
+     *    `sinceHLC` is undefined (from-zero / {@link collectAllChanges} path) there is
+     *    no lower bound, so all (origin ≠ peer) are kept.
+     *
+     * Accepted limitation (documented intent, not a defect): a straggler whose change
+     * is causally older than the holder's sync recency with a peer (`HLC ≤ sinceHLC`)
+     * is NOT relayed via this delta path — the same scalar-watermark limitation the
+     * base delta layer already has. store-and-forward targets the transitional
+     * uneven-retirement window, where the straggler's writes are recent enough to
+     * exceed holder watermarks; quarantine already prevents write loss outside it.
+     *
+     * Snapshot carve-out: forwardable entries are DELTA-ONLY. The snapshot collectors
+     * scan only `cv:`/`tb:`/`sm:` (never `qt:`), since a snapshot transfers the
+     * offering peer's OWN basis and a forwarded change is for a table that peer does
+     * not have.
+     *
+     * Full horizon-bounded scan (no early-exit), paralleling {@link collectAllChanges}:
+     * the forwardable set is bounded by the retention horizon and is EMPTY — so this
+     * is zero-cost — in the no-straggler case.
+     */
+    async collectForwardableChanges(peerSiteId, sinceHLC) {
+        const held = await this.quarantine.listForwardable();
+        const changes = [];
+        for (const entry of held) {
+            const change = entry.change;
+            // Echo exclusion: the change's HLC siteId is the straggler origin.
+            if (siteIdEquals(change.hlc.siteId, peerSiteId))
+                continue;
+            // Watermark filter on the delta path (see contract above).
+            if (sinceHLC && compareHLC(change.hlc, sinceHLC) <= 0)
+                continue;
+            changes.push(change);
+        }
+        // Relay-activity telemetry: a held entry is counted on EVERY getChangesSince
+        // that re-offers it (repeatedly until GC), and the batch bound may defer some to
+        // a later round (re-counted then) — so this measures relay ACTIVITY, not distinct
+        // deliveries (distinct from the apply-time `forwarded` hold count).
+        this.unknownTableRelayed += changes.length;
+        return changes;
+    }
+    /**
+     * Collect schema migrations after `sinceHLC` not originating from the peer.
+     * Each migration shares its transaction's base HLC, so the grouping step
+     * rejoins it with that transaction's data facts (or forms a DDL-only ChangeSet).
+     *
+     * The `sm:` range is keyed by `{schema}.{table}:{version}`, not by HLC, so this
+     * scan cannot early-exit the way {@link collectChangesSince} does — it is drained
+     * in full even when the fact side stops early. That is acceptable because
+     * migrations are few, and {@link buildTransactionChangeSets} drops any migration
+     * that sorts past the bounded fact watermark (its DDL-only group falls beyond the
+     * `batchSize` cut), so over-scanning here costs work but never correctness. A
+     * peer with a pathological volume of un-synced DDL is the one case this leaves
+     * unbounded; see the bounded-extraction ticket's handoff.
+     */
+    async collectSchemaMigrations(peerSiteId, sinceHLC) {
+        const schemaMigrations = [];
+        const smBounds = buildAllSchemaMigrationsScanBounds();
+        for await (const entry of this.kv.iterate(smBounds)) {
+            const parsed = parseSchemaMigrationKey(entry.key);
+            if (!parsed)
+                continue;
+            const migration = deserializeMigration(entry.value);
+            if (sinceHLC && compareHLC(migration.hlc, sinceHLC) <= 0)
+                continue;
+            if (siteIdEquals(migration.hlc.siteId, peerSiteId))
+                continue;
+            schemaMigrations.push({
+                type: migration.type,
+                schema: parsed.schema,
+                table: parsed.table,
+                ddl: migration.ddl,
+                hlc: migration.hlc,
+                schemaVersion: migration.schemaVersion,
+            });
+        }
+        return schemaMigrations;
     }
     // ============================================================================
     // Delegated: Change Application
@@ -390,15 +972,18 @@ export class SyncManagerImpl {
     async applyChanges(changes) {
         return applyChangesImpl(this, changes);
     }
+    async drainHeldChanges(schema, table) {
+        return drainHeldChangesImpl(this, schema, table);
+    }
     async canDeltaSync(peerSiteId, sinceHLC) {
         const peerState = await this.peerStates.getPeerState(peerSiteId);
         if (!peerState) {
             return false;
         }
-        // Check if tombstone TTL covers the requested time range
+        // Check if retention horizon covers the requested time range
         const now = Date.now();
         const sinceTime = Number(sinceHLC.wallTime);
-        if (now - sinceTime > this.config.tombstoneTTL) {
+        if (now - sinceTime > this.config.retentionHorizonMs) {
             return false;
         }
         return true;
@@ -429,7 +1014,7 @@ export class SyncManagerImpl {
         const tbBounds = buildAllTombstonesScanBounds();
         for await (const entry of this.kv.iterate(tbBounds)) {
             const tombstone = deserializeTombstone(entry.value);
-            if (now - tombstone.createdAt > this.config.tombstoneTTL) {
+            if (now - tombstone.createdAt > this.config.retentionHorizonMs) {
                 batch.delete(entry.key);
                 count++;
             }
@@ -437,6 +1022,16 @@ export class SyncManagerImpl {
         await batch.write();
         return count;
     }
+    /**
+     * GC quarantined out-of-basis straggler changes past the retention horizon —
+     * the quarantine sibling of {@link pruneTombstones}, keyed off the same
+     * `retentionHorizonMs`. A held change older than the horizon was already
+     * outside the delivery guarantee.
+     */
+    async pruneQuarantine() {
+        const cutoff = Date.now() - this.config.retentionHorizonMs;
+        return this.quarantine.pruneOlderThan(cutoff);
+    }
     getEventEmitter() {
         return this.syncEvents;
     }