@interocitor/core 0.0.0-beta.3 → 0.0.0-beta.4

package/dist/core/sync-engine.js

@@ -10,36 +10,29 @@
  * All data operations hit IndexedDB first; cloud sync is async.
  */
 import { hlcInit, hlcNow, hlcSerialize, hlcParse, hlcCompareStr } from "./hlc.js";
-import { applyOp } from "./crdt.js";
+import { Table, computeCacheKey } from "./table.js";
+import { readColumn } from "./crdt.js";
 import { LocalStore } from "../storage/local-store.js";
-import { Table } from "./table.js";
 // Extracted modules
-import { paths, log, generateId, getDeviceId, ROW_META_KEYS } from "./internals.js";
+import { paths, logAtLevel, normalizeLogLevel, generateId, getDeviceId } from "./internals.js";
 import { loadOrCreateManifest, upsertDeviceMetadata } from "./manifest.js";
 import { generateKey, keyToPassphrase, passphraseToKey } from "../crypto/encryption.js";
+import { MeshCredentialMismatchError } from "./errors.js";
 import { createCredentialStore } from "../storage/credential-store.js";
 import { flushToAdapter } from "./flush.js";
 import { pull as doPull } from "./pull.js";
 import { compact as doCompact, rehydrate as doRehydrate } from "./compaction.js";
-// ─── Sync Engine ─────────────────────────────────────────────────────
-/**
- * Typed sync engine. `S` is your database shape — inferred automatically
- * from `InferSchemaType<typeof schema>`. No default: either typed or `any`.
- *
- * @example
- * const schema = { version: 1, tables: { tasks: { fields: { title: types.string } } } }
- *   satisfies DatabaseSchemaDefinition;
- *
- * type DB = InferSchemaType<typeof schema>;
- * const engine = new SyncEngine<DB>(adapter, { schema, remotePath: '/App', appName: 'App' });
- *
- * // Or declare a typed getter:
- * const getDb = async (): Promise<SyncEngine<DB>> => { ... }
- *
- * engine.table('tasks'); // Table<{ title: string }>
- * engine.table('other'); // TS error — 'other' is not keyof DB
- */
-export class SyncEngine {
+const DEFAULT_COMPACT_WARNING_THRESHOLD = 50;
+const DEFAULT_COMPACT_AUTO_THRESHOLD = 50;
+const DEFAULT_COMPACT_AUTO_SAMPLE_NUMERATOR = 10;
+const DEFAULT_COMPACT_AUTO_DEVICE_COUNT = 1;
+const DEFAULT_FIRST_COMPACT_DELAY_MS = 10 * 60000;
+const DEFAULT_FIRST_COMPACT_DELAY_JITTER_MS = 5 * 60000;
+const DEFAULT_SECOND_COMPACT_DELAY_MS = 15 * 60000;
+const DEFAULT_SECOND_COMPACT_DELAY_JITTER_MS = 5 * 60000;
+const DEFAULT_COMPACT_REMOTE_CHANGE_THRESHOLD = 2;
+const DEFAULT_BATCH_WINDOW_MS = 1000;
+export class Interocitor {
     constructor(adapterOrConfig, maybeConfig) {
         this.encryptionKey = null;
         this.encrypted = false;
@@ -53,13 +46,41 @@ export class SyncEngine {
         // Flush management
         this.flushTimer = null;
         this.pendingCount = 0;
-        // Poll management
+        this.compactWarningEmitted = false;
+        this.compactInFlight = null;
+        this.compactScheduleVersion = 0;
+        this.compactCheckTimer = null;
+        this.compactRunTimer = null;
+        this.batchTimer = null;
+        this.pendingBatch = null;
+        // Poll / push invalidation management
         this.pollTimer = null;
+        this.unsubscribeRemoteInvalidations = null;
         // Lifecycle state
         this.initialized = false;
         this.connected = false;
+        this.initPromise = null;
+        // In-flight connect dedupe. Concurrent callers (React StrictMode double-
+        // mount, dual auto-reconnect resolves) share the same execution instead of
+        // both running the full connect() pipeline (manifest create, pull, flush,
+        // startPolling) twice in parallel — which doubles every flushed change file
+        // and stacks polling timers.
+        this.connectPromise = null;
         // Event listeners
         this.listeners = new Set();
+        // Async query cache. cacheKey -> entry. See QueryCacheEntry doc above.
+        this.queryCache = new Map();
+        // table name -> set of cache keys whose descriptors target that table.
+        this.queryCacheByTable = new Map();
+        // Single-row cache. Mirrors queryCache 1:1 in shape and lifecycle.
+        // key = `r=table|id=rowId`. Same emit() chokepoint invalidates.
+        this.rowCache = new Map();
+        this.rowCacheByTable = new Map();
+        // ── Batched writes ─────────────────────────────────────────────────
+        // All writes performed inside `fn` are merged into ONE ChangeEntry.
+        // Implicit batching also happens automatically: writes within the
+        // configured batchWindowMs window are flushed into a single ChangeEntry.
+        this.batchDepth = 0;
         const config = (maybeConfig ?? adapterOrConfig);
         const adapter = (maybeConfig ? adapterOrConfig : null);
         this.schema = config.schema;
@@ -74,12 +95,27 @@ export class SyncEngine {
             pollInterval: config.pollInterval ?? 30000,
             flushDebounce: config.flushDebounce ?? 2000,
             flushThreshold: config.flushThreshold ?? 50,
+            compactWarnThreshold: config.compactWarnThreshold ?? DEFAULT_COMPACT_WARNING_THRESHOLD,
+            compactAutoThreshold: config.compactAutoThreshold ?? DEFAULT_COMPACT_AUTO_THRESHOLD,
+            compactAutoSampleNumerator: config.compactAutoSampleNumerator ?? DEFAULT_COMPACT_AUTO_SAMPLE_NUMERATOR,
+            compactAutoDeviceCount: Math.max(1, Math.floor(config.compactAutoDeviceCount ?? DEFAULT_COMPACT_AUTO_DEVICE_COUNT)),
+            autoCompact: config.autoCompact ?? true,
+            firstCompactDelayMs: config.firstCompactDelayMs ?? DEFAULT_FIRST_COMPACT_DELAY_MS,
+            firstCompactDelayJitterMs: config.firstCompactDelayJitterMs ?? DEFAULT_FIRST_COMPACT_DELAY_JITTER_MS,
+            secondCompactDelayMs: config.secondCompactDelayMs ?? DEFAULT_SECOND_COMPACT_DELAY_MS,
+            secondCompactDelayJitterMs: config.secondCompactDelayJitterMs ?? DEFAULT_SECOND_COMPACT_DELAY_JITTER_MS,
+            compactRemoteChangeThreshold: config.compactRemoteChangeThreshold ?? DEFAULT_COMPACT_REMOTE_CHANGE_THRESHOLD,
+            batchWindowMs: config.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS,
             dbName: config.dbName ?? 'interocitor',
             localStoreFactory: config.localStoreFactory ?? (() => new LocalStore(config.dbName, undefined, config.schema)),
             schema: config.schema,
             replicas: config.replicas ?? [],
+            onInit: config.onInit,
+            resolveInitialState: config.resolveInitialState,
         };
         this.serverId = this.config.serverId;
+        this.dbName = this.config.dbName;
+        this.logLevel = normalizeLogLevel(config.logLevel);
         this.local = this.config.localStoreFactory();
         this.deviceId = getDeviceId(config.deviceId);
         this.hlc = hlcInit(this.deviceId);
@@ -93,8 +129,333 @@ export class SyncEngine {
         }
         else {
             this.encrypted = true;
-            // Will generate key in init() if no persisted key found
+            // Will generate key in doInit() if no persisted key found
+        }
+    }
+    log(level, ...args) {
+        logAtLevel(this.logLevel, level, ...args);
+    }
+    supportsRemoteInvalidations(adapter) {
+        return typeof adapter.subscribeToInvalidations === 'function';
+    }
+    /** Await this before any storage operation. Returns the shared init promise. */
+    ensureReady() {
+        if (this.initialized)
+            return Promise.resolve();
+        if (!this.initPromise)
+            this.initPromise = this.doInit();
+        return this.initPromise;
+    }
+    async putNow(table, rowId, columns, _userId) {
+        const tableName = table;
+        const current = await this.local.getRow(tableName, rowId);
+        // Clone row with namespaced shape. New rows start with empty payload.
+        const row = current
+            ? { _meta: { ...current._meta }, payload: { ...current.payload } }
+            : {
+                _meta: { table: tableName, rowId, deleted: false, schemaVersion: this.schema?.version ?? 0 },
+                payload: {},
+            };
+        const nextHlc = hlcNow(this.hlc);
+        this.hlc = nextHlc;
+        const stamp = hlcSerialize(nextHlc);
+        // User payload is fully isolated. Any key — including names like
+        // `_table`, `_rowId`, `_meta`, `payload` — is safe; meta is a separate
+        // namespace and cannot be reached by user input.
+        for (const [key, value] of Object.entries(columns)) {
+            row.payload[key] = { value: value === undefined ? null : value, hlc: stamp };
         }
+        row._meta.deleted = false;
+        row._meta.deletedHlc = undefined;
+        row._meta.owner = this.deviceId;
+        await this.local.putRow(row);
+        const op = this.rowToSyncOp(row);
+        const hlc = this.getRowHlc(row);
+        if (op && hlc)
+            await this.queueOpForBatchedFlush(op, hlc);
+        this.knownTables.add(tableName);
+        this.emit({ type: 'change', table: tableName, rowId, row });
+        return row;
+    }
+    async deleteNow(table, rowId, _userId) {
+        const tableName = table;
+        const current = await this.local.getRow(tableName, rowId);
+        if (!current || current._meta.deleted)
+            return;
+        const nextHlc = hlcNow(this.hlc);
+        this.hlc = nextHlc;
+        current._meta.deleted = true;
+        current._meta.deletedHlc = hlcSerialize(nextHlc);
+        current._meta.owner = this.deviceId;
+        await this.local.putRow(current);
+        const op = this.rowToSyncOp(current);
+        const hlc = this.getRowHlc(current);
+        if (op && hlc)
+            await this.queueOpForBatchedFlush(op, hlc);
+        this.emit({ type: 'delete', table: tableName, rowId });
+    }
+    /**
+     * Append the op to the in-flight batch. If we are inside a `batch()` block,
+     * the op stays buffered until the block ends. Otherwise it joins an
+     * implicit window of `batchWindowMs`. Either way the result is one
+     * ChangeEntry per batch instead of one per write.
+     */
+    async queueOpForBatchedFlush(op, hlc) {
+        this.appendOpToPendingBatch(op, hlc);
+        if (this.isBatching())
+            return;
+        if (this.config.batchWindowMs <= 0) {
+            await this.flushPendingBatch();
+            return;
+        }
+        this.armImplicitBatchTimer();
+    }
+    async queryNow(table) {
+        return this.local.getTable(table);
+    }
+    async queryWhereNow(table, clause) {
+        return this.local.queryWhere(table, clause);
+    }
+    // ── Query cache (async-only, descriptor-keyed) ─────────────────────
+    /** Public readiness signal. Used by render-time consumers to decide
+     *  between sync cache reads and awaiting a load. */
+    isReady() {
+        return this.initialized;
+    }
+    /** Stable cache key for a descriptor. Owned by core. */
+    getQueryCacheKey(descriptor) {
+        return computeCacheKey(descriptor);
+    }
+    /** Sync cache snapshot. Never starts a load. Empty/pending/ready/error. */
+    readQueryCache(descriptor) {
+        const key = this.getQueryCacheKey(descriptor);
+        const entry = this.queryCache.get(key);
+        if (!entry)
+            return { status: 'empty', promise: null };
+        return {
+            status: entry.status,
+            promise: entry.promise ?? null,
+            rows: entry.rows,
+            error: entry.error,
+        };
+    }
+    /**
+     * Load rows through the cache.
+     *
+     * - If a snapshot exists and `bypassCache` is not set, dedupes to the
+     *   in-flight promise (when pending) or starts a refresh that keeps the
+     *   stale rows visible until it resolves.
+     * - When the engine is not yet ready, falls through `ensureReady()`; if
+     *   `bypassCache` is set, never returns the cached rows.
+     */
+    loadQueryRows(descriptor, options) {
+        const key = this.getQueryCacheKey(descriptor);
+        const existing = this.queryCache.get(key);
+        if (!options?.bypassCache && existing?.status === 'pending' && existing.promise) {
+            return existing.promise;
+        }
+        if (!options?.bypassCache && existing?.status === 'ready' && existing.rows) {
+            // Fast-path: hand back resolved rows without re-fetch.
+            // Callers that want freshness pass `bypassCache: true`.
+            return Promise.resolve(existing.rows);
+        }
+        return this.runQuery(descriptor, key);
+    }
+    runQuery(descriptor, key) {
+        const promise = (async () => {
+            await this.ensureReady();
+            const rows = descriptor.clause
+                ? await this.local.queryWhere(descriptor.table, descriptor.clause)
+                : await this.local.getTable(descriptor.table);
+            // Apply deterministic orderBy from descriptor, so cache stores already-
+            // ordered rows. Sync-only `.sort(compareFn)` derivations stay outside
+            // and run after the cache hand-off.
+            if (!descriptor.orderBy)
+                return rows;
+            const { field, dir } = descriptor.orderBy;
+            const sorted = [...rows].sort((a, b) => {
+                const av = readColumn(a, field);
+                const bv = readColumn(b, field);
+                if (av === bv)
+                    return 0;
+                const lt = av < bv ? -1 : 1;
+                return dir === 'asc' ? lt : -lt;
+            });
+            return sorted;
+        })();
+        const previous = this.queryCache.get(key);
+        const entry = {
+            descriptor,
+            status: 'pending',
+            rows: previous?.rows, // keep stale rows visible while refreshing
+            promise,
+        };
+        this.queryCache.set(key, entry);
+        this.indexCacheByTable(descriptor.table, key);
+        promise.then(rows => {
+            const current = this.queryCache.get(key);
+            if (current?.promise !== promise)
+                return; // superseded
+            this.queryCache.set(key, { descriptor, status: 'ready', rows });
+        }).catch(err => {
+            const current = this.queryCache.get(key);
+            if (current?.promise !== promise)
+                return;
+            this.queryCache.set(key, {
+                descriptor,
+                status: 'error',
+                error: err instanceof Error ? err : new Error(String(err)),
+                rows: current.rows,
+            });
+        });
+        return promise;
+    }
+    indexCacheByTable(table, key) {
+        let set = this.queryCacheByTable.get(table);
+        if (!set) {
+            set = new Set();
+            this.queryCacheByTable.set(table, set);
+        }
+        set.add(key);
+    }
+    /**
+     * Mark all cached queries against `table` as stale and refresh them in the
+     * background. Stale rows stay visible. Called from local mutations.
+     */
+    invalidateQueryCacheForTable(table) {
+        const keys = this.queryCacheByTable.get(table);
+        if (!keys || keys.size === 0)
+            return;
+        for (const key of keys) {
+            const entry = this.queryCache.get(key);
+            if (!entry)
+                continue;
+            this.runQuery(entry.descriptor, key);
+        }
+    }
+    // ── Row cache (async-only, descriptor-keyed) ───────────────────────
+    // Same shape and semantics as the query cache. Kept as a separate map so
+    // single-row reads don't compete with table scans.
+    /** Stable cache key for a row descriptor. Owned by core. */
+    getRowCacheKey(descriptor) {
+        return `r=${descriptor.table}|id=${descriptor.rowId}`;
+    }
+    /** Sync row cache snapshot. Never starts a load. */
+    readRowCache(descriptor) {
+        const key = this.getRowCacheKey(descriptor);
+        const entry = this.rowCache.get(key);
+        if (!entry)
+            return { status: 'empty', promise: null };
+        return {
+            status: entry.status,
+            promise: entry.promise ?? null,
+            row: entry.row,
+            error: entry.error,
+        };
+    }
+    /**
+     * Load a row through the cache. Same dedupe + stale-while-revalidate
+     * semantics as `loadQueryRows`.
+     */
+    loadRow(descriptor, options) {
+        const key = this.getRowCacheKey(descriptor);
+        const existing = this.rowCache.get(key);
+        if (!options?.bypassCache && existing?.status === 'pending' && existing.promise) {
+            return existing.promise;
+        }
+        if (!options?.bypassCache && existing?.status === 'ready') {
+            return Promise.resolve(existing.row ?? undefined);
+        }
+        return this.runRow(descriptor, key);
+    }
+    runRow(descriptor, key) {
+        const promise = (async () => {
+            await this.ensureReady();
+            const row = await this.local.getRow(descriptor.table, descriptor.rowId);
+            if (!row || row._meta.deleted)
+                return undefined;
+            return row;
+        })();
+        const previous = this.rowCache.get(key);
+        const entry = {
+            descriptor,
+            status: 'pending',
+            row: previous?.row, // keep stale row visible while refreshing
+            promise,
+        };
+        this.rowCache.set(key, entry);
+        this.indexRowCacheByTable(descriptor.table, key);
+        promise.then(row => {
+            const current = this.rowCache.get(key);
+            if (current?.promise !== promise)
+                return;
+            this.rowCache.set(key, { descriptor, status: 'ready', row: row ?? null });
+        }).catch(err => {
+            const current = this.rowCache.get(key);
+            if (current?.promise !== promise)
+                return;
+            this.rowCache.set(key, {
+                descriptor,
+                status: 'error',
+                error: err instanceof Error ? err : new Error(String(err)),
+                row: current.row,
+            });
+        });
+        return promise;
+    }
+    indexRowCacheByTable(table, key) {
+        let set = this.rowCacheByTable.get(table);
+        if (!set) {
+            set = new Set();
+            this.rowCacheByTable.set(table, set);
+        }
+        set.add(key);
+    }
+    /**
+     * Refresh all cached rows for a table. Called from emit() alongside the
+     * query cache invalidation. Keeps prior row visible while in-flight.
+     *
+     * Table-wide invalidation is intentional: Interocitor targets rare-update
+     * workloads, not realtime state streams. The over-fetch on a write is a
+     * fixed-cost reload of cached rows for that one table — cheap, simple,
+     * and matches the query cache strategy. Finer-grained per-rowId
+     * invalidation can be added later without changing this contract.
+     */
+    invalidateRowCacheForTable(table) {
+        const keys = this.rowCacheByTable.get(table);
+        if (!keys || keys.size === 0)
+            return;
+        for (const key of keys) {
+            const entry = this.rowCache.get(key);
+            if (!entry)
+                continue;
+            this.runRow(entry.descriptor, key);
+        }
+    }
+    get initContext() {
+        return {
+            put: this.putNow.bind(this),
+            delete: this.deleteNow.bind(this),
+            // Cache APIs (ReadinessAwareQueryExecutor). Init-time tables need them
+            // because Table constructors and Table.row()/Table.query() resolve
+            // through engine.getQueryCacheKey / readQueryCache / loadQueryRows
+            // (and row equivalents). Without these, onInit handlers calling
+            // ctx.table(x).row(id) crash at construction time.
+            isReady: this.isReady.bind(this),
+            getQueryCacheKey: this.getQueryCacheKey.bind(this),
+            readQueryCache: this.readQueryCache.bind(this),
+            loadQueryRows: this.loadQueryRows.bind(this),
+            getRowCacheKey: this.getRowCacheKey.bind(this),
+            readRowCache: this.readRowCache.bind(this),
+            loadRow: this.loadRow.bind(this),
+            query: this.queryNow.bind(this),
+            queryWhere: this.queryWhereNow.bind(this),
+            table: (name) => new Table(this.initContext, name),
+            on: this.on.bind(this),
+            getDeviceId: this.getDeviceId.bind(this),
+            getMeshId: this.getMeshId.bind(this),
+            isEncrypted: this.isEncrypted.bind(this),
+        };
     }
     // ── Internal accessors ─────────────────────────────────────────────
     requireAdapter(operation) {
@@ -105,6 +466,11 @@ export class SyncEngine {
         }
         return this.adapter;
     }
+    requireRemotePath(operation) {
+        if (!this.config.remotePath)
+            throw new Error(`${operation} requires remotePath; configure mesh before connecting`);
+        return this.config.remotePath;
+    }
     get codecState() {
         return {
             encryptionKey: this.encryptionKey,
@@ -115,7 +481,7 @@ export class SyncEngine {
     get manifestContext() {
         return {
             adapter: this.requireAdapter('manifest'),
-            remotePath: this.config.remotePath,
+            remotePath: this.requireRemotePath('manifest'),
             serverId: this.serverId,
             serverManaged: this.config.serverManaged,
             deviceId: this.deviceId,
@@ -131,6 +497,22 @@ export class SyncEngine {
             this.flushTimer = null;
         }
     }
+    clearCompactTimers() {
+        if (this.compactCheckTimer)
+            clearTimeout(this.compactCheckTimer);
+        if (this.compactRunTimer)
+            clearTimeout(this.compactRunTimer);
+        this.compactCheckTimer = null;
+        this.compactRunTimer = null;
+        this.compactScheduleVersion += 1;
+    }
+    jitterDelay(baseMs, jitterMs) {
+        if (jitterMs <= 0)
+            return Math.max(0, baseMs);
+        const min = Math.max(0, baseMs - jitterMs);
+        const max = baseMs + jitterMs;
+        return Math.floor(min + Math.random() * (max - min + 1));
+    }
     stopPolling() {
         if (this.pollTimer) {
             clearInterval(this.pollTimer);
@@ -143,70 +525,77 @@ export class SyncEngine {
             this.pull().catch(() => { });
         }, this.config.pollInterval);
     }
-    // ── State helpers ──────────────────────────────────────────────────
-    async resetRemoteSyncState() {
-        this.manifest = null;
-        this.remotePoisonError = null;
-        this.connected = false;
-        await this.local.setMeta('cursor', '');
-        await this.local.setMeta('epoch', 0);
-        await this.local.setMeta('meshId', '');
+    stopRemoteInvalidations() {
+        if (!this.unsubscribeRemoteInvalidations)
+            return;
+        try {
+            this.unsubscribeRemoteInvalidations();
+        }
+        catch { }
+        this.unsubscribeRemoteInvalidations = null;
+    }
+    startRemoteInvalidations(adapter) {
+        this.stopRemoteInvalidations();
+        if (!this.supportsRemoteInvalidations(adapter)) {
+            this.log('debug', '[interocitor:relay] adapter has no invalidation subscription', { adapter: adapter.name });
+            this.emit({ type: 'relay:unavailable', adapter: adapter.name, reason: 'adapter-unsupported' });
+            return;
+        }
+        this.log('info', '[interocitor:relay] subscribing', { adapter: adapter.name, remotePath: this.config.remotePath, deviceId: this.deviceId });
+        this.emit({ type: 'relay:subscribe', adapter: adapter.name, remotePath: this.config.remotePath, deviceId: this.deviceId });
+        this.unsubscribeRemoteInvalidations = adapter.subscribeToInvalidations((payload) => {
+            this.log('info', '[interocitor:relay] invalidation received', payload);
+            this.emit({ type: 'relay:message', adapter: adapter.name, payload });
+            if (!this.connected)
+                return;
+            this.pull().catch((error) => {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.log('warn', '[interocitor:relay] pull after invalidation failed', err);
+                this.emit({ type: 'relay:error', adapter: adapter.name, error: err });
+            });
+        }, {
+            onReady: () => {
+                this.log('info', '[interocitor:relay] ready', { adapter: adapter.name });
+                this.emit({ type: 'relay:ready', adapter: adapter.name });
+            },
+            onError: (error) => {
+                const err = error instanceof Error ? error : new Error(error ? String(error) : 'Remote invalidation subscription error');
+                this.log('warn', '[interocitor:relay] subscription error', err);
+                this.emit({ type: 'relay:error', adapter: adapter.name, error: err });
+            },
+            onClose: () => {
+                this.log('warn', '[interocitor:relay] closed', { adapter: adapter.name });
+                this.emit({ type: 'relay:closed', adapter: adapter.name });
+            },
+        });
     }
+    // ── State helpers ──────────────────────────────────────────────────
     getRowHlc(row) {
-        let latest = row._deletedHlc ?? '';
-        for (const [key, value] of Object.entries(row)) {
-            if (ROW_META_KEYS.has(key))
-                continue;
-            if (!value || typeof value !== 'object' || !('hlc' in value) || !('value' in value))
+        let latest = row._meta.deletedHlc ?? '';
+        for (const entry of Object.values(row.payload)) {
+            if (!entry?.hlc)
                 continue;
-            const entryHlc = value.hlc;
-            if (!latest || hlcCompareStr(entryHlc, latest) > 0)
-                latest = entryHlc;
+            if (!latest || hlcCompareStr(entry.hlc, latest) > 0)
+                latest = entry.hlc;
         }
         return latest;
     }
     rowToSyncOp(row) {
-        if (row._deleted) {
-            const hlc = row._deletedHlc ?? this.getRowHlc(row);
+        if (row._meta.deleted) {
+            const hlc = row._meta.deletedHlc ?? this.getRowHlc(row);
             if (!hlc)
                 return null;
-            return { type: 'delete', table: row._table, rowId: row._rowId, hlc };
+            return { type: 'delete', table: row._meta.table, rowId: row._meta.rowId, hlc };
         }
         const columns = {};
-        for (const [key, value] of Object.entries(row)) {
-            if (ROW_META_KEYS.has(key))
-                continue;
-            if (!value || typeof value !== 'object' || !('hlc' in value) || !('value' in value))
+        for (const [key, entry] of Object.entries(row.payload)) {
+            if (!entry?.hlc)
                 continue;
-            columns[key] = value;
+            columns[key] = entry;
         }
         if (Object.keys(columns).length === 0)
             return null;
-        return { type: 'upsert', table: row._table, rowId: row._rowId, columns };
-    }
-    buildChangeEntry(op, hlc) {
-        return {
-            id: generateId('chg'),
-            ts: Date.now(),
-            device: this.deviceId,
-            hlc,
-            ops: [op],
-        };
-    }
-    async rebuildOutboxFromLocalState() {
-        await this.local.drainOutbox();
-        const rows = await this.local.getAllRows();
-        let queued = 0;
-        for (const row of rows) {
-            const op = this.rowToSyncOp(row);
-            const hlc = this.getRowHlc(row);
-            if (!op || !hlc)
-                continue;
-            await this.local.pushOutbox(this.buildChangeEntry(op, hlc));
-            queued++;
-        }
-        this.pendingCount = queued;
-        return queued;
+        return { type: 'upsert', table: row._meta.table, rowId: row._meta.rowId, columns };
     }
     async loadLocalState() {
         this.tables = {};
@@ -239,8 +628,32 @@ export class SyncEngine {
             this.stopPolling();
             this.clearScheduledFlush();
             this.connected = false;
+            this.connectPromise = null;
+            // Drop the adapter's "ensured folders" cache. After poison we don't
+            // know whether the structure on disk is intact (corrupt manifest may
+            // have been minted while folders were partially created), so the
+            // next connect must re-validate every folder.
+            this.adapter?.resetFolderCache?.();
+            this.log('error', 'remote:poisoned — sync halted', {
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                path,
+                message: poisoned.message,
+            });
         }
-        this.emit({ type: 'remote:poisoned', error: poisoned, path });
+        this.emit({
+            type: 'remote:poisoned',
+            error: poisoned,
+            path,
+            context: {
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                meshId: this.manifest?.meshId,
+                encrypted: this.encrypted,
+            },
+        });
         return poisoned;
     }
     // ── Events ─────────────────────────────────────────────────────────
@@ -249,6 +662,14 @@ export class SyncEngine {
         return () => this.listeners.delete(listener);
     }
     emit(event) {
+        // Single chokepoint for cache invalidation. Local mutations and remote
+        // pull both flow through emit(); both invalidate query cache for the
+        // affected table the same way. Local mutations also pre-invalidate so
+        // synchronous reads after `put`/`delete` see fresh data.
+        if (event.type === 'change' || event.type === 'delete') {
+            this.invalidateQueryCacheForTable(event.table);
+            this.invalidateRowCacheForTable(event.table);
+        }
         for (const listener of this.listeners) {
             try {
                 listener(event);
@@ -260,7 +681,77 @@ export class SyncEngine {
     async persistCredentials() {
         if (!this.credentialStore || !this.passphrase)
             return;
-        await this.credentialStore.save({ passphrase: this.passphrase, deviceId: this.deviceId });
+        try {
+            // Bind the persisted record to the active meshId when known.
+            // The store keeps ONE record per dbName; meshId lets the engine
+            // detect "wrong mesh" on the next load instead of silently reusing
+            // the previous mesh's key.
+            //
+            // Crucial: do NOT clobber an existing stored meshId when the
+            // engine's manifest has not been loaded yet (e.g. persist runs
+            // during init before connect()). Read-modify-write preserves the
+            // marker so `assertCredentialMeshParity` can still detect a stale
+            // record on the upcoming connect.
+            let meshId = this.manifest?.meshId;
+            if (!meshId) {
+                try {
+                    const existing = await this.credentialStore.load();
+                    if (existing?.meshId)
+                        meshId = existing.meshId;
+                }
+                catch { /* best-effort merge */ }
+            }
+            await this.credentialStore.save({
+                passphrase: this.passphrase,
+                deviceId: this.deviceId,
+                ...(meshId ? { meshId } : {}),
+            });
+            this.log('debug', 'persistCredentials() — saved', { dbName: this.dbName, deviceId: this.deviceId, meshId });
+            this.emit({
+                type: 'credentials:persisted',
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                encrypted: this.encrypted,
+            });
+        }
+        catch (err) {
+            this.log('error', 'persistCredentials() — failed', err);
+            // Persistence failure must not break local writes; surface via log only.
+        }
+    }
+    /**
+     * Compare the persisted credential record against the live meshId.
+     *
+     * Throws `MeshCredentialMismatchError` (and emits `credentials:meshMismatch`)
+     * when the credential store has a record under this `dbName` whose meshId
+     * disagrees with `manifest.meshId`. The remote is NOT poisoned — the local
+     * credential store has stale data from a previous mesh that shared the
+     * same dbName.
+     */
+    async assertCredentialMeshParity() {
+        const activeMeshId = this.manifest?.meshId;
+        if (!activeMeshId || !this.credentialStore)
+            return;
+        let stored = null;
+        try {
+            stored = await this.credentialStore.load();
+        }
+        catch {
+            return; // load failures already surface elsewhere; do not block connect
+        }
+        if (!stored?.meshId)
+            return; // legacy/no-meshId record: nothing to assert
+        if (stored.meshId === activeMeshId)
+            return;
+        this.emit({
+            type: 'credentials:meshMismatch',
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            storedMeshId: stored.meshId,
+            activeMeshId,
+        });
+        throw new MeshCredentialMismatchError(this.dbName, stored.meshId, activeMeshId);
     }
     async loadPersistedCredentials() {
         if (!this.credentialStore)
@@ -273,17 +764,38 @@ export class SyncEngine {
         await this.credentialStore.clear();
     }
     async resolveEncryption() {
-        if (!this.encrypted)
+        console.log('[interocitor:cred] resolveEncryption() — entry', {
+            dbName: this.dbName,
+            encrypted: this.encrypted,
+            hasPassphrase: !!this.passphrase,
+            hasKey: !!this.encryptionKey,
+            passphraseFingerprint: this.passphrase ? `len=${this.passphrase.length} head=${this.passphrase.slice(0, 8)} tail=${this.passphrase.slice(-4)}` : null,
+        });
+        if (!this.encrypted) {
+            this.log('debug', 'resolveEncryption() — encryption disabled');
             return;
+        }
         // 1. Have passphrase (from config, setPassphrase(), or restoreCredentials())
         if (this.passphrase && !this.encryptionKey) {
             this.encryptionKey = await passphraseToKey(this.passphrase);
+            try {
+                const raw = await crypto.subtle.exportKey('raw', this.encryptionKey);
+                const hash = await crypto.subtle.digest('SHA-256', raw);
+                const bytes = new Uint8Array(hash);
+                const hex = Array.from(bytes.slice(0, 6)).map(b => b.toString(16).padStart(2, '0')).join('');
+                console.log('[interocitor:cred] resolveEncryption() — derived key', { dbName: this.dbName, keyFingerprint: `sha256-${hex}` });
+            }
+            catch { /* ignore */ }
             await this.persistCredentials();
+            this.log('info', 'resolveEncryption() — derived key from passphrase', { dbName: this.dbName });
+            this.emit({ type: 'encryption:resolved', strategy: 'passphrase', dbName: this.dbName, remotePath: this.config.remotePath, encrypted: true });
             return;
         }
         // 2. Already have a key (set via setPassphrase before init)
         if (this.encryptionKey) {
             await this.persistCredentials();
+            this.log('info', 'resolveEncryption() — using preset key', { dbName: this.dbName });
+            this.emit({ type: 'encryption:resolved', strategy: 'existing-key', dbName: this.dbName, remotePath: this.config.remotePath, encrypted: true });
             return;
         }
         // 3. Generate fresh key (first-time open)
@@ -291,15 +803,54 @@ export class SyncEngine {
         this.encryptionKey = key;
         this.passphrase = await keyToPassphrase(key);
         await this.persistCredentials();
+        this.log('warn', 'resolveEncryption() — generated fresh key (first-time open). Lose credentials => lose data.', { dbName: this.dbName });
+        this.emit({ type: 'encryption:resolved', strategy: 'generated', dbName: this.dbName, remotePath: this.config.remotePath, encrypted: true });
+    }
+    applyInitialState(state) {
+        if (!state)
+            return;
+        if (state.deviceId) {
+            this.deviceId = state.deviceId;
+            this.hlc.nodeId = state.deviceId;
+        }
+        if (state.remotePath !== undefined) {
+            this.config.remotePath = state.remotePath;
+        }
+        if (state.encrypted !== undefined) {
+            this.encrypted = state.encrypted;
+            if (!state.encrypted) {
+                this.passphrase = null;
+                this.encryptionKey = null;
+            }
+        }
+        if (state.passphrase !== undefined) {
+            this.passphrase = state.passphrase;
+            this.encryptionKey = null;
+            if (state.passphrase !== null)
+                this.encrypted = true;
+        }
+    }
+    configureMesh(state) {
+        if (this.connected)
+            throw new Error('Cannot configure mesh while connected');
+        if (this.initialized)
+            throw new Error('Cannot configure mesh after init(); create a new engine or configure before connect');
+        this.applyInitialState(state);
+        this.emit({
+            type: 'mesh:configured',
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            encrypted: this.encrypted,
+            hadPassphrase: this.passphrase !== null,
+        });
     }
     /**
      * Set the mesh encryption passphrase.
      * Call before init() or between disconnect() and init().
      */
     setPassphrase(passphrase) {
-        this.passphrase = passphrase;
-        this.encrypted = true;
-        this.encryptionKey = null; // re-derived in init()
+        this.configureMesh({ passphrase, encrypted: true });
     }
     /**
      * Get the current mesh passphrase.
@@ -330,15 +881,30 @@ export class SyncEngine {
      * Returns true if restore succeeded.
      */
     async restoreWithBiometrics() {
-        const restored = await (this.credentialStore?.restoreWithBiometrics?.() ?? Promise.resolve(null));
+        let restored = null;
+        try {
+            restored = await (this.credentialStore?.restoreWithBiometrics?.() ?? Promise.resolve(null));
+        }
+        catch (err) {
+            this.log('warn', 'restoreWithBiometrics() — failed', err);
+            return false;
+        }
         if (!restored)
             return false;
+        const deviceIdChanged = restored.deviceId !== this.deviceId;
         this.deviceId = restored.deviceId;
         this.hlc.nodeId = restored.deviceId;
         this.passphrase = restored.passphrase;
         if (this.encrypted) {
             this.encryptionKey = await passphraseToKey(restored.passphrase);
         }
+        this.log('info', 'restoreWithBiometrics() — restored', { dbName: this.dbName, deviceIdChanged });
+        this.emit({
+            type: 'credentials:restored',
+            source: 'biometric',
+            deviceIdChanged,
+            hadPassphrase: true,
+        });
         return true;
     }
     /**
@@ -360,140 +926,523 @@ export class SyncEngine {
     }
     // ── Lifecycle ──────────────────────────────────────────────────────
     async init() {
-        log('debug', 'init() — opening local store', { dbName: this.config.dbName, encrypted: this.encrypted });
+        await this.ensureReady();
+    }
+    async doInit() {
+        this.log('debug', 'init() — opening local store', { dbName: this.config.dbName, encrypted: this.encrypted, remotePath: this.config.remotePath });
         try {
             await this.local.open();
-        }
-        catch (err) {
-            log('error', 'init() — local store open failed', err);
-            throw err;
-        }
-        if (this.schema) {
-            await this.local.setMeta('schema:version', this.schema.version);
-        }
-        // Recover credentials from the silent primary store only.
-        // No biometric prompt during normal init.
-        await this.restoreCredentials();
-        // Resolve encryption: derive key from passphrase, load persisted, or generate.
-        await this.resolveEncryption();
-        log('debug', 'init() — loading local state (table names, HLC)');
-        try {
+            if (this.schema) {
+                await this.local.setMeta('schema:version', this.schema.version);
+            }
+            const initialState = await this.config.resolveInitialState?.();
+            this.applyInitialState(initialState ?? null);
+            // Recover credentials from the silent primary store only.
+            // No biometric prompt during normal init.
+            await this.restoreCredentials();
+            // Resolve encryption: derive key from passphrase, load persisted, or generate.
+            await this.resolveEncryption();
+            this.log('debug', 'init() — loading local state (table names, HLC)');
             await this.loadLocalState();
+            this.log('debug', 'init() — complete', { knownTables: Array.from(this.knownTables) });
+            this.initialized = true;
+            if (this.config.onInit) {
+                await this.config.onInit(this.initContext);
+            }
         }
         catch (err) {
-            log('error', 'init() — loadLocalState failed', err);
+            this.log('error', 'init() — failed', err);
+            this.initPromise = null;
             throw err;
         }
-        log('debug', 'init() — complete', { knownTables: Array.from(this.knownTables) });
-        this.initialized = true;
     }
     /**
      * Silent credential restore from the primary store only.
      * Used during normal init(). No biometric prompt.
      */
     async restoreCredentials() {
-        const stored = await this.loadPersistedCredentials();
-        if (!stored)
+        console.log('[interocitor:cred] restoreCredentials() — entry', {
+            dbName: this.dbName,
+            activeDeviceId: this.deviceId,
+            activePassphraseFingerprint: this.passphrase ? `len=${this.passphrase.length} head=${this.passphrase.slice(0, 8)} tail=${this.passphrase.slice(-4)}` : null,
+            hasKey: !!this.encryptionKey,
+            encrypted: this.encrypted,
+        });
+        let stored = null;
+        try {
+            stored = await this.loadPersistedCredentials();
+        }
+        catch (err) {
+            console.log('[interocitor:cred] restoreCredentials() — store load failed', { dbName: this.dbName, err: err instanceof Error ? err.message : String(err) });
+            this.log('warn', 'restoreCredentials() — silent load failed', err);
+            return;
+        }
+        console.log('[interocitor:cred] restoreCredentials() — store loaded', {
+            dbName: this.dbName,
+            hasStored: !!stored,
+            storedDeviceId: stored?.deviceId,
+            storedMeshId: stored?.meshId,
+            storedPassphraseFingerprint: stored?.passphrase ? `len=${stored.passphrase.length} head=${stored.passphrase.slice(0, 8)} tail=${stored.passphrase.slice(-4)}` : null,
+        });
+        if (!stored) {
+            this.log('debug', 'restoreCredentials() — no persisted credentials', { dbName: this.dbName });
             return;
+        }
+        // Mesh-id parity check.
+        //
+        // The credential store keeps ONE record per dbName. If the stored
+        // record names a meshId and the local store already knows a different
+        // meshId for this dbName (typical: user clicked "create new mesh"
+        // under the same dbName, then reloaded), the persisted passphrase is
+        // for the OLD mesh and silently adopting it would either fail
+        // decryption or poison the new remote.
+        //
+        // The connect-time post-manifest check below covers the case where
+        // the local-store meshId is empty (fresh install + stale cred record).
+        if (stored.meshId) {
+            const localMeshIdRaw = await this.local.getMeta('meshId');
+            const localMeshId = typeof localMeshIdRaw === 'string' ? localMeshIdRaw : '';
+            if (localMeshId && localMeshId !== stored.meshId) {
+                this.log('error', 'restoreCredentials() — meshId mismatch, refusing to adopt stored credentials', {
+                    dbName: this.dbName,
+                    storedMeshId: stored.meshId,
+                    activeMeshId: localMeshId,
+                });
+                this.emit({
+                    type: 'credentials:meshMismatch',
+                    dbName: this.dbName,
+                    remotePath: this.config.remotePath,
+                    storedMeshId: stored.meshId,
+                    activeMeshId: localMeshId,
+                });
+                throw new MeshCredentialMismatchError(this.dbName, stored.meshId, localMeshId);
+            }
+        }
+        let deviceIdChanged = false;
         if (stored.deviceId && stored.deviceId !== this.deviceId) {
+            // The local device-id global is shared across meshes on this origin.
+            // If the persisted dbName-scoped store has a different device-id than
+            // the global, the user is straddling two meshes and we are about to
+            // self-poison their HLC. Surface it so the UI can intervene before
+            // any writes happen.
+            this.log('warn', 'restoreCredentials() — device-id mismatch, restoring stored id', {
+                dbName: this.dbName,
+                storedDeviceId: stored.deviceId,
+                activeDeviceId: this.deviceId,
+            });
+            this.emit({
+                type: 'credentials:conflict',
+                storedDeviceId: stored.deviceId,
+                activeDeviceId: this.deviceId,
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+            });
             this.deviceId = stored.deviceId;
             this.hlc.nodeId = stored.deviceId;
             try {
-                localStorage.setItem('interocitor-device-id', stored.deviceId);
+                if (typeof localStorage !== 'undefined')
+                    localStorage.setItem('interocitor-device-id', stored.deviceId);
             }
             catch { /* ok */ }
+            deviceIdChanged = true;
         }
-        if (this.encrypted && !this.passphrase && stored.passphrase) {
-            this.passphrase = stored.passphrase;
+        let hadPassphrase = false;
+        if (this.encrypted && stored.passphrase) {
+            if (!this.passphrase) {
+                this.passphrase = stored.passphrase;
+                hadPassphrase = true;
+            }
+            else if (this.passphrase !== stored.passphrase) {
+                // Caller passed a different passphrase than the one persisted under
+                // dbName. This is the classic "self-sabotage": same dbName, two keys.
+                // Local rows were written with one key; new flushes will use another;
+                // every reload after this will start poisoning remote files.
+                this.log('error', 'restoreCredentials() — passphrase conflict! Caller-provided passphrase differs from persisted. Refusing to silently swap.', {
+                    dbName: this.dbName,
+                    remotePath: this.config.remotePath,
+                });
+                // Keep caller-provided passphrase; the conflict event lets UI prompt
+                // the user to either clearCredentials() or correct the passphrase.
+                this.emit({
+                    type: 'credentials:conflict',
+                    storedDeviceId: stored.deviceId,
+                    activeDeviceId: this.deviceId,
+                    dbName: this.dbName,
+                    remotePath: this.config.remotePath,
+                });
+                // Reset the local cursor so the upcoming pull cannot use the
+                // skip-listing fast-path. Without this, doFlush()'s post-write
+                // cursor advance under the OLD key hides remote change files
+                // from the new (mismatched) key — the engine would never decode
+                // them and never surface the decode failure that proves the
+                // passphrase is wrong. Conflict surfaces via decode:error +
+                // remote:poisoned on the next pull, instead of silently going.
+                try {
+                    await this.local.setMeta('cursor', '');
+                }
+                catch { /* best-effort */ }
+            }
         }
+        this.emit({
+            type: 'credentials:restored',
+            source: 'silent-store',
+            deviceIdChanged,
+            hadPassphrase,
+        });
     }
     async connect() {
-        if (!this.initialized) {
-            throw new Error('Engine must be initialized via init() before connect()');
+        console.log('[interocitor:connect] connect() — entry', {
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            adapter: this.adapter?.name ?? null,
+            encrypted: this.encrypted,
+            hasPassphrase: !!this.passphrase,
+            hasKey: !!this.encryptionKey,
+            meshId: this.manifest?.meshId,
+            connected: this.connected,
+            hasInFlight: !!this.connectPromise,
+        });
+        await this.ensureReady();
+        if (!this.config.remotePath)
+            throw new Error('connect() requires remotePath; configure mesh before connecting');
+        // Idempotent. If we are already connected to a live mesh on this
+        // adapter+remotePath, don't restart the session — restart was the root
+        // cause of the "observer" reload bug, where polling/flush timers and
+        // adapter sessions stacked across UI reloads and started corrupting
+        // the local cursor + remote files.
+        if (this.connected && !this.remotePoisonError) {
+            this.log('debug', 'connect() — already connected, no-op', {
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+            });
+            this.emit({
+                type: 'connect:noop',
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: 'already-connected',
+            });
+            return;
+        }
+        // Concurrent-callers dedupe. The `connected` flag flips true only after
+        // the full pipeline (manifest, pull, doFlush, startPolling) resolves;
+        // a second caller arriving before that would re-enter and double every
+        // flushed change file. Share the in-flight promise instead.
+        if (this.connectPromise) {
+            this.log('debug', 'connect() — join in-flight connect', {
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+            });
+            this.emit({
+                type: 'connect:noop',
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: 'already-connected',
+            });
+            return this.connectPromise;
+        }
+        this.connectPromise = this.doConnect().finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    async tryConnectFastPath(adapter) {
+        const cursorRaw = await this.local.getMeta('cursor');
+        const cursor = typeof cursorRaw === 'string' ? cursorRaw : '';
+        if (!cursor)
+            return false;
+        if (await this.local.outboxSize() > 0)
+            return false;
+        const remotePath = this.requireRemotePath('connect() fast-path');
+        const p = paths(remotePath);
+        try {
+            const headRaw = await adapter.readFile(p.changesHead);
+            const head = JSON.parse(new TextDecoder().decode(headRaw));
+            this.emit({
+                type: 'trace:head',
+                op: 'read',
+                reason: 'connect-fast-path',
+                path: p.changesHead,
+                priorHlc: head.latestHlc ?? null,
+            });
+            if (head.latestHlc && hlcCompareStr(head.latestHlc, cursor) <= 0) {
+                this.emit({
+                    type: 'trace:head',
+                    op: 'skip-no-change',
+                    reason: 'connect-fast-path',
+                    path: p.changesHead,
+                    priorHlc: head.latestHlc,
+                    nextHlc: cursor,
+                });
+                this.emit({
+                    type: 'connect:state',
+                    dbName: this.dbName,
+                    remotePath: this.config.remotePath,
+                    deviceId: this.deviceId,
+                    meshId: this.manifest?.meshId,
+                    encrypted: this.encrypted,
+                });
+                this.emit({ type: 'sync:complete', entriesMerged: 0 });
+                this.startPolling();
+                this.startRemoteInvalidations(adapter);
+                this.connected = true;
+                return true;
+            }
+        }
+        catch {
+            // Missing or malformed head means this is not a safe fast path.
+            // Fall back to the full connect pipeline, which validates manifest,
+            // folders, credentials, epoch, and then pulls.
         }
+        return false;
+    }
+    async doConnect() {
         const adapter = this.requireAdapter('connect()');
-        log('debug', 'connect() — authenticating with adapter', { adapter: adapter.name });
+        console.log('[interocitor:connect] doConnect() — start', {
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            adapter: adapter.name,
+            meshIdBefore: this.manifest?.meshId,
+        });
+        const stage = (s, err) => {
+            const e = err instanceof Error ? err : new Error(String(err));
+            console.log('[interocitor:connect] doConnect() — STAGE FAIL', { stage: s, dbName: this.dbName, deviceId: this.deviceId, err: e.message });
+            this.emit({
+                type: 'connect:error',
+                error: e,
+                stage: s,
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+            });
+            return e;
+        };
+        const stageOk = (s, extra) => {
+            console.log('[interocitor:connect] doConnect() — stage ok', { stage: s, dbName: this.dbName, deviceId: this.deviceId, ...(extra ?? {}) });
+        };
+        this.log('debug', 'connect() — authenticating with adapter', { adapter: adapter.name });
         if (!adapter.isAuthenticated()) {
             this.emit({ type: 'auth:required' });
             try {
                 await adapter.authenticate();
             }
             catch (err) {
-                log('error', 'connect() — authentication failed', err);
-                throw err;
+                this.log('error', 'connect() — authentication failed', err);
+                throw stage('authenticate', err);
             }
             this.emit({ type: 'auth:complete' });
         }
-        const p = paths(this.config.remotePath);
-        log('debug', 'connect() — ensuring remote folders', { remotePath: this.config.remotePath, deviceId: this.deviceId });
-        for (const folder of [this.config.remotePath, p.devicesFolder, p.mainlineFolder, p.changesFolder]) {
+        // Reload steady-state fast path: local IDB has a cursor, there is no
+        // pending outbox, and remote head has not advanced. In that case the
+        // client has nothing to publish or merge. After the minimal auth check,
+        // probe head and stop — no folder creation, manifest reads, device
+        // metadata writes, listFiles, or change-file reads. This covers clients
+        // that recreate the adapter on reload before calling setRemoteStorage().
+        if (await this.tryConnectFastPath(adapter))
+            return;
+        const remotePath = this.requireRemotePath('connect()');
+        const p = paths(remotePath);
+        this.log('debug', 'connect() — ensuring remote folders', { remotePath, deviceId: this.deviceId });
+        for (const folder of [remotePath, p.devicesFolder, p.mainlineFolder, p.changesFolder]) {
             try {
                 await adapter.ensureFolder(folder);
-                log('debug', 'connect() — ensureFolder ok', folder);
+                this.log('debug', 'connect() — ensureFolder ok', folder);
             }
             catch (err) {
-                log('error', 'connect() — ensureFolder failed', folder, err);
-                throw err;
+                this.log('error', 'connect() — ensureFolder failed', folder, err);
+                throw stage('ensureFolder', err);
             }
         }
-        log('debug', 'connect() — loading/creating manifest');
+        this.log('debug', 'connect() — loading/creating manifest');
+        let bootstrapped = false;
         try {
-            await this.doLoadOrCreateManifest();
+            // Force on connect: any cached manifest predates the new transport
+            // session and may be stale (compaction by another writer, mesh swap).
+            ({ bootstrapped } = await this.doLoadOrCreateManifest('connect', true));
+            stageOk('loadOrCreateManifest', { bootstrapped, meshId: this.manifest?.meshId, generation: this.manifest?.generation });
         }
         catch (err) {
-            log('error', 'connect() — loadOrCreateManifest failed', err);
-            throw err;
+            this.log('error', 'connect() — loadOrCreateManifest failed', err);
+            throw stage('loadOrCreateManifest', err);
+        }
+        // Post-manifest credential check.
+        //
+        // We now know the live meshId. Compare it to the meshId attached to
+        // the persisted credential record. If they disagree, the persisted
+        // record is for a different mesh that happened to share the same
+        // dbName (e.g. user clicked "create new mesh" twice). Refuse to
+        // proceed — silently using the wrong key would poison the remote.
+        //
+        // The restoreCredentials() check covers reloads where the local
+        // store already remembers the active meshId; this branch covers the
+        // first connect after a fresh install.
+        try {
+            await this.assertCredentialMeshParity();
+            stageOk('credentialMeshParity', { meshId: this.manifest?.meshId });
+        }
+        catch (err) {
+            this.log('error', 'connect() — credential mesh parity failed', err);
+            throw stage('credentialMeshParity', err);
         }
-        await upsertDeviceMetadata(adapter, this.config.remotePath, this.deviceId);
+        // Anchor credentials to the live meshId now that parity is known
+        // good. First-connect of a fresh mesh has no meshId in the
+        // credential record yet; on reconnect this is a no-op write that
+        // keeps the record fresh.
+        await this.persistCredentials();
+        stageOk('persistCredentialsPostManifest');
+        await upsertDeviceMetadata(adapter, remotePath, this.deviceId, {
+            displayName: this.config.deviceName,
+            deviceType: this.config.deviceType,
+            // Skip the read-merge GET when we just minted the manifest in this
+            // same connect cycle — no prior device record can possibly exist.
+            bootstrap: bootstrapped,
+        });
         const localEpochRaw = await this.local.getMeta('epoch');
         const localEpoch = typeof localEpochRaw === 'number' ? localEpochRaw : 0;
         const remoteEpoch = this.manifest?.epoch ?? 0;
-        log('debug', 'connect() — epoch check', { localEpoch, remoteEpoch });
+        this.log('debug', 'connect() — epoch check', { localEpoch, remoteEpoch });
+        this.emit({
+            type: 'connect:state',
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            localEpoch,
+            remoteEpoch,
+            meshId: this.manifest?.meshId,
+            encrypted: this.encrypted,
+        });
         if (localEpoch < remoteEpoch) {
-            log('debug', 'connect() — epoch advanced, rehydrating from snapshot');
+            this.log('debug', 'connect() — epoch advanced, rehydrating from snapshot');
             await this.rehydrate();
         }
         else {
-            log('debug', 'connect() — running initial pull');
+            this.log('debug', 'connect() — running initial pull');
             await this.pull();
         }
-        await this.flush();
+        await this.doFlush();
         this.startPolling();
+        this.startRemoteInvalidations(adapter);
         this.connected = true;
-        log('info', 'connect() — connected', { remotePath: this.config.remotePath, deviceId: this.deviceId, pollInterval: this.config.pollInterval });
+        this.log('info', 'connect() — connected', { remotePath: this.config.remotePath, deviceId: this.deviceId, pollInterval: this.config.pollInterval });
         if (typeof window !== 'undefined') {
             window.addEventListener('visibilitychange', () => {
                 if (document.visibilityState === 'hidden') {
-                    this.flush().catch(() => { });
+                    this.doFlush().catch(() => { });
                 }
             });
         }
     }
     async disconnect() {
+        await this.ensureReady();
+        // Hard tear-down. Order matters: stop timers first so no in-flight
+        // poll/push/flush touches the adapter while we are killing the session.
         this.stopPolling();
+        this.stopRemoteInvalidations();
         this.clearScheduledFlush();
-        if (!this.remotePoisonError)
-            await this.flush();
+        this.clearCompactTimers();
+        this.clearBatchTimer();
+        await this.flushPendingBatch();
+        if (!this.remotePoisonError) {
+            try {
+                await this.doFlush();
+            }
+            catch (err) {
+                this.log('warn', 'disconnect() — flush before close failed (continuing)', err);
+            }
+        }
+        this.emit({
+            type: 'transport:teardown',
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            reason: 'disconnect',
+        });
         this.local.close();
         this.connected = false;
         this.initialized = false;
+        this.initPromise = null;
+        this.connectPromise = null;
         this.remotePoisonError = null;
     }
     async setRemoteStorage(adapter) {
+        console.log('[interocitor:share] setRemoteStorage() — entry', {
+            dbName: this.dbName,
+            newAdapter: adapter?.name ?? null,
+            currentAdapter: this.adapter?.name ?? null,
+            sameByRef: adapter === this.adapter,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            connected: this.connected,
+            meshId: this.manifest?.meshId,
+        });
+        await this.ensureReady();
+        this.log('debug', 'setRemoteStorage()', { adapter: adapter?.name ?? null, remotePath: this.config.remotePath });
         const wasConnected = this.connected;
         const hadAdapter = this.adapter !== null;
-        if (wasConnected && hadAdapter && !this.remotePoisonError)
-            await this.pull();
+        const switching = adapter !== this.adapter;
+        console.log('[interocitor:share] setRemoteStorage() — decision', { wasConnected, hadAdapter, switching });
+        // Same-adapter no-op. Callers (auto-reconnect, React StrictMode, etc.)
+        // commonly re-attach the same adapter on every reload. Without this
+        // guard we would tear down the live transport, reset cursor/epoch/meshId,
+        // re-queue every IDB row into the outbox via rebuildOutboxFromLocalState,
+        // then reconnect — which re-flushes the entire dataset as a fresh batch
+        // of change files on every reload.
+        if (!switching) {
+            this.log('debug', 'setRemoteStorage() — same adapter, no-op');
+            return;
+        }
+        if (wasConnected && hadAdapter && !this.remotePoisonError) {
+            try {
+                await this.pull();
+            }
+            catch (err) {
+                this.log('warn', 'setRemoteStorage() — final pull before swap failed (continuing)', err);
+            }
+        }
+        // Hard tear-down of the previous transport before swapping.
+        // Without this, polling timers + outbox flush can race against the
+        // newly-attached adapter and re-write the *new* mesh with files signed
+        // for the old mesh — i.e. self-poison the remote on adapter switch.
         this.stopPolling();
+        this.stopRemoteInvalidations();
         this.clearScheduledFlush();
+        this.connected = false;
+        if (switching && hadAdapter) {
+            // Drop the OLD adapter's folder cache before we let go of it.
+            // Belt-and-braces: if the old adapter is reattached later, we cannot
+            // trust prior "this folder exists" observations against a potentially
+            // different mesh layout.
+            this.adapter?.resetFolderCache?.();
+            this.emit({
+                type: 'transport:teardown',
+                dbName: this.dbName,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: adapter ? 'switch-adapter' : 'detach',
+            });
+        }
         if (this.initialized) {
-            await this.resetRemoteSyncState();
-            if (adapter)
-                await this.rebuildOutboxFromLocalState();
+            // Transport swaps are not semantic local-state resets. Preserve cursor,
+            // epoch, meshId, rows, and any genuine unsent outbox entries. The next
+            // connect will re-read/validate the manifest for the newly attached
+            // adapter and pull only if its head is ahead of the preserved cursor.
+            //
+            // The previous code called resetRemoteSyncState() and then
+            // rebuildOutboxFromLocalState(), which converted every canonical local
+            // row back into a pending outbound write. That made reload/adapter attach
+            // self-feed: already-synced rows became fresh change files for no reason.
+            this.manifest = null;
+            this.remotePoisonError = null;
+            this.connected = false;
+            this.pendingCount = await this.local.outboxSize();
         }
         else {
             this.manifest = null;
-            this.connected = false;
         }
         this.adapter = adapter;
         this.remotePoisonError = null;
@@ -501,9 +1450,10 @@ export class SyncEngine {
             await this.connect();
     }
     async setLocalStorage(local) {
+        await this.ensureReady();
         const wasConnected = this.connected;
         if (wasConnected)
-            await this.flush();
+            await this.doFlush();
         this.clearScheduledFlush();
         this.pendingCount = 0;
         this.local.close();
@@ -514,139 +1464,481 @@ export class SyncEngine {
         if (!wasConnected)
             return;
         await this.pull();
-        await this.flush();
+        await this.doFlush();
     }
     // ── Manifest (delegated) ───────────────────────────────────────────
-    async doLoadOrCreateManifest() {
-        const manifest = await loadOrCreateManifest(this.manifestContext, this.codecState, this.local, (err, path) => this.poisonRemote(err, path));
+    /**
+     * Load the mesh manifest, optionally short-circuiting via the in-memory
+     * cache.
+     *
+     * `reason` is a free-form caller tag used by `trace:manifest` events so
+     * developers can answer "why is my manifest being re-read every flush?".
+     *
+     * `force=true` bypasses the cache. Required after poison, after compaction
+     * advances generation, or whenever the caller explicitly needs disk state.
+     * Cached path emits `trace:manifest { op: 'cache-hit' }` so test/devtools
+     * can assert that the steady-state pipeline does ZERO GETs on flush/pull.
+     */
+    /**
+     * Returns whether the manifest was bootstrapped (freshly minted) on this
+     * call. Callers (connect()) use this to skip the device-metadata GET when
+     * we know no prior device record can exist.
+     */
+    async doLoadOrCreateManifest(reason = 'unknown', force = false) {
+        if (!force && this.manifest && !this.remotePoisonError) {
+            this.emit({
+                type: 'trace:manifest',
+                op: 'cache-hit',
+                reason,
+                generation: this.manifest.generation,
+                cached: true,
+            });
+            return { bootstrapped: false };
+        }
+        const { manifest, bootstrapped } = await loadOrCreateManifest(this.manifestContext, this.codecState, this.local, (err, path) => this.poisonRemote(err, path), reason);
         this.manifest = manifest;
         this.encrypted = manifest.encrypted || this.encrypted;
+        return { bootstrapped };
     }
     // ── Local writes ───────────────────────────────────────────────────
     async put(table, rowId, columns, userId) {
-        this.hlc = hlcNow(this.hlc);
-        const hlcStr = hlcSerialize(this.hlc);
-        const columnEntries = {};
-        for (const [key, value] of Object.entries(columns)) {
-            columnEntries[key] = { value: value, hlc: hlcStr };
-        }
-        const op = { type: 'upsert', table, rowId, columns: columnEntries };
-        await this.ensureRowsCached([op]);
-        const row = applyOp(this.tables, op, this.manifest?.schema ?? 1, this.schema);
-        this.knownTables.add(table);
-        await this.local.putRow(row);
-        await this.local.setMeta('hlc', hlcSerialize(this.hlc));
-        const entry = {
-            id: generateId('chg'),
-            ts: Date.now(),
-            device: this.deviceId,
-            user: userId,
-            hlc: hlcStr,
-            ops: [op],
-        };
-        await this.local.pushOutbox(entry);
-        this.emit({ type: 'change', table, rowId, row });
-        this.scheduleFlush();
-        return row;
+        await this.ensureReady();
+        return this.putNow(table, rowId, columns, userId);
     }
     async delete(table, rowId, userId) {
-        this.hlc = hlcNow(this.hlc);
-        const hlcStr = hlcSerialize(this.hlc);
-        const op = { type: 'delete', table, rowId, hlc: hlcStr };
-        await this.ensureRowsCached([op]);
-        applyOp(this.tables, op, this.manifest?.schema ?? 1, this.schema);
-        const row = this.tables[table]?.[rowId];
-        if (row)
-            await this.local.putRow(row);
-        await this.local.setMeta('hlc', hlcSerialize(this.hlc));
-        const entry = {
-            id: generateId('chg'),
-            ts: Date.now(),
-            device: this.deviceId,
-            user: userId,
-            hlc: hlcStr,
-            ops: [op],
-        };
-        await this.local.pushOutbox(entry);
-        this.emit({ type: 'delete', table, rowId });
-        this.scheduleFlush();
-    }
-    // ── Read ───────────────────────────────────────────────────────────
-    async get(table, rowId) {
-        const row = await this.local.getRow(table, rowId);
-        if (!row || row._deleted)
-            return undefined;
-        return row;
+        await this.ensureReady();
+        return this.deleteNow(table, rowId, userId);
     }
     async query(table) {
-        return this.local.getTable(table);
+        await this.ensureReady();
+        return this.queryNow(table);
     }
     async queryWhere(table, clause) {
-        return this.local.queryWhere(table, clause);
+        await this.ensureReady();
+        return this.queryWhereNow(table, clause);
     }
     async tableNames() {
+        await this.ensureReady();
         return Array.from(this.knownTables);
     }
     table(name) {
         return new Table(this, name);
     }
+    /**
+     * Group a sequence of writes into a single ChangeEntry. The entry
+     * carries every op as one atomic unit, producing one remote file
+     * instead of one per write.
+     *
+     * Nested batch() calls join the outer batch.
+     */
+    async batch(fn) {
+        await this.ensureReady();
+        this.batchDepth += 1;
+        try {
+            const result = await fn();
+            return result;
+        }
+        finally {
+            this.batchDepth -= 1;
+            if (this.batchDepth === 0)
+                await this.flushPendingBatch();
+        }
+    }
+    isBatching() {
+        return this.batchDepth > 0;
+    }
+    clearBatchTimer() {
+        if (!this.batchTimer)
+            return;
+        clearTimeout(this.batchTimer);
+        this.batchTimer = null;
+    }
+    appendOpToPendingBatch(op, hlc) {
+        if (!this.pendingBatch) {
+            this.pendingBatch = {
+                id: generateId('chg'),
+                ts: Date.now(),
+                device: this.deviceId,
+                hlc,
+                ops: [op],
+            };
+        }
+        else {
+            this.pendingBatch.ops.push(op);
+            // Carry the highest HLC seen in this batch
+            if (hlcCompareStr(hlc, this.pendingBatch.hlc) > 0)
+                this.pendingBatch.hlc = hlc;
+        }
+    }
+    armImplicitBatchTimer() {
+        if (this.isBatching())
+            return;
+        if (this.batchTimer)
+            return;
+        this.batchTimer = setTimeout(() => {
+            this.batchTimer = null;
+            void this.flushPendingBatch();
+        }, this.config.batchWindowMs);
+    }
+    async flushPendingBatch() {
+        const pending = this.pendingBatch;
+        this.pendingBatch = null;
+        this.clearBatchTimer();
+        if (!pending)
+            return;
+        await this.local.pushOutbox(pending);
+        this.scheduleFlush();
+    }
     // ── Flush (local → cloud) ──────────────────────────────────────────
     scheduleFlush() {
         this.pendingCount++;
+        this.maybeEmitCompactWarning();
+        this.armDelayedCompactAfterChange();
         if (this.pendingCount >= this.config.flushThreshold) {
-            this.flush().catch(err => this.emit({ type: 'flush:error', error: err }));
+            this.doFlush().catch(err => this.emit({ type: 'flush:error', error: err }));
             return;
         }
         if (this.flushTimer)
             clearTimeout(this.flushTimer);
         this.flushTimer = setTimeout(() => {
-            this.flush().catch(err => this.emit({ type: 'flush:error', error: err }));
+            this.doFlush().catch(err => this.emit({ type: 'flush:error', error: err }));
         }, this.config.flushDebounce);
     }
+    maybeEmitCompactWarning() {
+        if (this.compactWarningEmitted)
+            return;
+        if (this.pendingCount < this.config.compactWarnThreshold)
+            return;
+        this.compactWarningEmitted = true;
+        this.emit({
+            type: 'compact:warning',
+            queuedChangeCount: this.pendingCount,
+            threshold: this.config.compactWarnThreshold,
+            autoCompactThreshold: this.config.compactAutoThreshold,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+        });
+    }
+    resetCompactWarning() {
+        if (this.pendingCount !== 0)
+            return;
+        this.compactWarningEmitted = false;
+    }
+    async maybeAutoCompact(triggerQueuedChangeCount) {
+        if (triggerQueuedChangeCount < this.config.compactAutoThreshold)
+            return;
+        const sampleWindow = Math.max(1, Math.floor(this.config.compactAutoDeviceCount / Math.max(1, this.config.compactAutoSampleNumerator)));
+        const sampleRoll = Math.floor(Math.random() * sampleWindow);
+        const baseEvent = {
+            queuedChangeCount: triggerQueuedChangeCount,
+            threshold: this.config.compactAutoThreshold,
+            sampleRoll,
+            sampleWindow,
+            trigger: 'immediate',
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+        };
+        if (!this.config.autoCompact) {
+            this.emit({ type: 'compact:auto:skip', ...baseEvent, reason: 'disabled' });
+            return;
+        }
+        if (!this.adapter || !this.config.remotePath) {
+            this.emit({ type: 'compact:auto:skip', ...baseEvent, reason: 'missing-remote' });
+            return;
+        }
+        if (!this.connected) {
+            this.emit({ type: 'compact:auto:skip', ...baseEvent, reason: 'not-connected' });
+            return;
+        }
+        if (this.remotePoisonError) {
+            this.emit({ type: 'compact:auto:skip', ...baseEvent, reason: 'poisoned' });
+            return;
+        }
+        if (this.compactInFlight) {
+            this.emit({ type: 'compact:auto:skip', ...baseEvent, reason: 'already-running' });
+            return;
+        }
+        if (sampleRoll !== 0) {
+            this.emit({ type: 'compact:auto:skip', ...baseEvent, reason: 'sampling' });
+            return;
+        }
+        this.emit({ type: 'compact:auto:start', ...baseEvent });
+        const run = this.compact().then(() => {
+            this.emit({
+                type: 'compact:auto:complete',
+                queuedChangeCount: triggerQueuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'immediate',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+            });
+        }).catch((error) => {
+            this.emit({
+                type: 'compact:auto:error',
+                queuedChangeCount: triggerQueuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'immediate',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                error,
+            });
+        }).finally(() => {
+            if (this.compactInFlight === run)
+                this.compactInFlight = null;
+        });
+        this.compactInFlight = run;
+        await run;
+    }
+    // ── Delayed compact support (secondary path) ────────────────────────
+    // Independent from the immediate sampled auto-compact above. Both paths
+    // can co-exist: any single compact() call is deduped via compactInFlight.
+    // Helps lazy clients eventually compact even when sampling never fires.
+    armDelayedCompactAfterChange() {
+        if (!this.config.autoCompact)
+            return;
+        if (!this.config.remotePath)
+            return;
+        const delayMs = this.jitterDelay(this.config.firstCompactDelayMs, this.config.firstCompactDelayJitterMs);
+        this.compactScheduleVersion += 1;
+        const version = this.compactScheduleVersion;
+        if (this.compactCheckTimer)
+            clearTimeout(this.compactCheckTimer);
+        this.emit({
+            type: 'compact:delayed:scheduled',
+            queuedChangeCount: this.pendingCount,
+            delayMs,
+            phase: 'check',
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+        });
+        this.compactCheckTimer = setTimeout(() => {
+            this.compactCheckTimer = null;
+            this.runDelayedCompactCheck(version).catch(() => { });
+        }, delayMs);
+    }
+    async runDelayedCompactCheck(version) {
+        if (version !== this.compactScheduleVersion)
+            return;
+        if (!this.config.autoCompact || !this.connected || !this.adapter || !this.config.remotePath)
+            return;
+        if (this.remotePoisonError)
+            return;
+        let remoteChangeFileCount = 0;
+        try {
+            const adapter = this.adapter;
+            const remoteRoot = this.config.remotePath;
+            const list = await adapter.listFiles(`${remoteRoot}/changes`).catch(() => []);
+            remoteChangeFileCount = list.filter(f => /\/changes\/[^/]+-chg_[^/]+\.json$/.test(f.path)).length;
+        }
+        catch { /* best-effort */ }
+        this.emit({
+            type: 'compact:delayed:check',
+            queuedChangeCount: this.pendingCount,
+            remoteChangeFileCount,
+            threshold: this.config.compactRemoteChangeThreshold,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+        });
+        if (remoteChangeFileCount <= this.config.compactRemoteChangeThreshold) {
+            this.emit({
+                type: 'compact:auto:skip',
+                queuedChangeCount: this.pendingCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: 'below-remote-threshold',
+            });
+            return;
+        }
+        const delayMs = this.jitterDelay(this.config.secondCompactDelayMs, this.config.secondCompactDelayJitterMs);
+        if (this.compactRunTimer)
+            clearTimeout(this.compactRunTimer);
+        this.emit({
+            type: 'compact:delayed:scheduled',
+            queuedChangeCount: this.pendingCount,
+            delayMs,
+            phase: 'compact',
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+        });
+        const triggerQueuedChangeCount = this.pendingCount;
+        this.compactRunTimer = setTimeout(() => {
+            this.compactRunTimer = null;
+            this.runDelayedCompact(version, triggerQueuedChangeCount, remoteChangeFileCount).catch(() => { });
+        }, delayMs);
+    }
+    async runDelayedCompact(version, queuedChangeCount, remoteChangeFileCount) {
+        if (version !== this.compactScheduleVersion) {
+            this.emit({
+                type: 'compact:auto:skip',
+                queuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: 'superseded',
+            });
+            return;
+        }
+        if (!this.config.autoCompact || !this.connected || !this.adapter || !this.config.remotePath) {
+            this.emit({
+                type: 'compact:auto:skip',
+                queuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: !this.connected ? 'not-connected' : !this.config.autoCompact ? 'disabled' : 'missing-remote',
+            });
+            return;
+        }
+        if (this.remotePoisonError) {
+            this.emit({
+                type: 'compact:auto:skip',
+                queuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: 'poisoned',
+            });
+            return;
+        }
+        if (this.compactInFlight) {
+            this.emit({
+                type: 'compact:auto:skip',
+                queuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                reason: 'already-running',
+            });
+            return;
+        }
+        this.emit({
+            type: 'compact:auto:start',
+            queuedChangeCount,
+            threshold: this.config.compactAutoThreshold,
+            trigger: 'delayed',
+            remoteChangeFileCount,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+        });
+        const run = this.compact().then(() => {
+            this.emit({
+                type: 'compact:auto:complete',
+                queuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remoteChangeFileCount,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+            });
+        }).catch((error) => {
+            this.emit({
+                type: 'compact:auto:error',
+                queuedChangeCount,
+                threshold: this.config.compactAutoThreshold,
+                trigger: 'delayed',
+                remoteChangeFileCount,
+                remotePath: this.config.remotePath,
+                deviceId: this.deviceId,
+                error,
+            });
+        });
+        await run;
+    }
+    /** Public flush — waits for init. Safe to call from user code. */
     async flush() {
+        await this.ensureReady();
+        // Drain any pending implicit batch first so its ops reach the outbox
+        // before we read it. Without this, flush() called from user code right
+        // after a write inside the batch window would skip those writes.
+        await this.flushPendingBatch();
+        return this.doFlush();
+    }
+    /** Internal flush — no ensureReady guard (called from connect, pull, doInit). */
+    async doFlush() {
         if (!this.adapter) {
             this.clearScheduledFlush();
             return;
         }
+        const triggerQueuedChangeCount = this.pendingCount;
         const entries = await this.local.drainOutbox();
-        if (entries.length === 0)
+        if (entries.length === 0) {
+            this.pendingCount = 0;
+            this.resetCompactWarning();
             return;
-        log('debug', 'flush() — start', { entryCount: entries.length });
+        }
+        this.log('debug', 'flush() — start', { entryCount: entries.length });
         this.emit({ type: 'flush:start', entryCount: entries.length });
         this.pendingCount = 0;
+        this.resetCompactWarning();
         this.clearScheduledFlush();
         try {
-            await this.doLoadOrCreateManifest();
-            await flushToAdapter(this.adapter, this.config.remotePath, entries, true, this.codecState, this.deviceId);
+            // Cached path: in steady state this is a 0-GET no-op that emits
+            // `trace:manifest { op: 'cache-hit', reason: 'flush' }`. The cache
+            // is dropped on poison and re-loaded on the next connect/compact.
+            await this.doLoadOrCreateManifest('flush');
+            await flushToAdapter(this.adapter, this.requireRemotePath('flush()'), entries, true, this.codecState, this.deviceId, (e) => this.emit(e));
             for (const replica of this.config.replicas) {
                 try {
-                    const replicaRoot = replica.remotePath ?? this.config.remotePath;
+                    const replicaRoot = replica.remotePath ?? this.requireRemotePath('flush() replica');
                     if (!replica.adapter.isAuthenticated())
                         await replica.adapter.authenticate();
                     await flushToAdapter(replica.adapter, replicaRoot, entries, false, this.codecState, this.deviceId);
                 }
                 catch (err) {
-                    log('warn', 'flush() — replica write failed', { adapter: replica.adapter.name }, err);
+                    this.log('warn', 'flush() — replica write failed', { adapter: replica.adapter.name }, err);
                     this.emit({ type: 'replica:error', adapter: replica.adapter.name, error: err });
                 }
             }
-            log('debug', 'flush() — complete', { entryCount: entries.length });
+            // Advance the local cursor past our own just-flushed entries.
+            // The cursor is the "we have already merged everything <= X"
+            // marker that pull()'s fast-path uses to short-circuit listing
+            // and reading change files. Without this, a page reload after a
+            // local-only write storm re-lists the changes folder and re-GETs
+            // every file we authored ourselves — re-decoding our own writes
+            // through the CRDT path despite local IDB already being canonical.
+            // Monotonic-forward only: never let cursor go backwards on disk.
+            let highestFlushedHlc = '';
+            for (const entry of entries) {
+                if (!entry.hlc)
+                    continue;
+                if (!highestFlushedHlc || hlcCompareStr(entry.hlc, highestFlushedHlc) > 0) {
+                    highestFlushedHlc = entry.hlc;
+                }
+            }
+            if (highestFlushedHlc) {
+                const cursorRaw = await this.local.getMeta('cursor');
+                const cursor = typeof cursorRaw === 'string' ? cursorRaw : '';
+                if (!cursor || hlcCompareStr(highestFlushedHlc, cursor) > 0) {
+                    await this.local.setMeta('cursor', highestFlushedHlc);
+                }
+            }
+            this.log('debug', 'flush() — complete', { entryCount: entries.length });
             this.emit({ type: 'flush:complete' });
+            await this.maybeAutoCompact(triggerQueuedChangeCount);
         }
         catch (err) {
-            log('error', 'flush() — failed, re-queuing entries', err);
+            this.log('error', 'flush() — failed, re-queuing entries', err);
             for (const entry of entries)
                 await this.local.pushOutbox(entry);
+            this.pendingCount = entries.length;
+            this.maybeEmitCompactWarning();
             throw err;
         }
     }
     // ── Pull (cloud → local) ──────────────────────────────────────────
     async pull() {
+        await this.ensureReady();
         const adapter = this.requireAdapter('pull()');
         this.hlc = await doPull({
             adapter,
             local: this.local,
-            remotePath: this.config.remotePath,
+            remotePath: this.requireRemotePath('pull()'),
             codecState: this.codecState,
             hlc: this.hlc,
             deviceId: this.deviceId,
@@ -656,11 +1948,12 @@ export class SyncEngine {
             emit: (e) => this.emit(e),
             ensureRowsCached: (ops) => this.ensureRowsCached(ops),
             poisonRemote: (err, path) => this.poisonRemote(err, path),
-            loadOrCreateManifest: () => this.doLoadOrCreateManifest(),
+            loadOrCreateManifest: async () => { await this.doLoadOrCreateManifest('pull'); },
         });
     }
     // ── Rehydrate / Compact ────────────────────────────────────────────
     async rehydrate() {
+        await this.ensureReady();
         const adapter = this.requireAdapter('rehydrate()');
         this.hlc = await doRehydrate({
             adapter,
@@ -677,21 +1970,31 @@ export class SyncEngine {
         });
     }
     async compact() {
-        const adapter = this.requireAdapter('compact()');
-        if (!this.manifest)
-            throw new Error('Engine is not connected');
-        this.manifest = await doCompact({
-            adapter,
-            local: this.local,
-            remotePath: this.config.remotePath,
-            manifest: this.manifest,
-            codecState: this.codecState,
-            hlc: this.hlc,
-            deviceId: this.deviceId,
-            serverId: this.serverId,
-            emit: (e) => this.emit(e),
-            pull: () => this.pull(),
+        await this.ensureReady();
+        if (this.compactInFlight)
+            return this.compactInFlight;
+        const run = (async () => {
+            const adapter = this.requireAdapter('compact()');
+            if (!this.manifest)
+                throw new Error('Engine is not connected');
+            this.manifest = await doCompact({
+                adapter,
+                local: this.local,
+                remotePath: this.requireRemotePath('compact()'),
+                manifest: this.manifest,
+                codecState: this.codecState,
+                hlc: this.hlc,
+                deviceId: this.deviceId,
+                serverId: this.serverId,
+                emit: (e) => this.emit(e),
+                pull: () => this.pull(),
+            });
+        })().finally(() => {
+            if (this.compactInFlight === run)
+                this.compactInFlight = null;
         });
+        this.compactInFlight = run;
+        return run;
     }
     // ── Mesh management ────────────────────────────────────────────────
     getManifest() {
@@ -715,4 +2018,3 @@ export class SyncEngine {
         this.encrypted = true;
     }
 }
-//# sourceMappingURL=sync-engine.js.map