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

package/dist/adapters/cloudflare.js

@@ -14,6 +14,12 @@ export class CloudflareAdapter {
     constructor(config) {
         this.name = 'cloudflare';
         this.authenticated = false;
+        // Per-session cache of folders we have already ensured. Cloudflare's
+        // /ensure-folder is idempotent but a POST per folder per connect is
+        // pure round-trip overhead — Interocitor.connect re-runs the same
+        // 4-folder loop on every reload. Cache wipes via `resetFolderCache()`
+        // (mesh swap / poison) or process exit.
+        this.ensuredFolders = new Set();
         this.config = { ...config, baseUrl: config.baseUrl.replace(/\/$/, '') };
     }
     headers(extra) {
@@ -23,23 +29,33 @@ export class CloudflareAdapter {
         }
         return { ...base, ...extra };
     }
-    get ioBaseUrl() {
-        const u = new URL(this.config.baseUrl);
+    parseBaseUrl() {
+        const base = /^https?:\/\//i.test(this.config.baseUrl)
+            ? this.config.baseUrl
+            : new URL(this.config.baseUrl, 'http://interocitor').toString();
+        const u = new URL(base);
         if (!u.pathname.includes('/io/')) {
             throw new Error('CloudflareAdapter baseUrl must include /io/<prefix>');
         }
+        return u;
+    }
+    get ioBaseUrl() {
+        const u = this.parseBaseUrl();
+        if (!/^https?:\/\//i.test(this.config.baseUrl)) {
+            return `${u.pathname}${u.search}${u.hash}`.replace(/\/$/, '');
+        }
         return u.toString().replace(/\/$/, '');
     }
     get notifyUrl() {
-        const u = new URL(this.config.baseUrl);
-        if (!u.pathname.includes('/io/')) {
-            throw new Error('CloudflareAdapter baseUrl must include /io/<prefix>');
-        }
+        const u = this.parseBaseUrl();
         u.pathname = u.pathname.replace('/io/', '/notify/');
         u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
         if (this.config.token) {
             u.searchParams.set('access_token', this.config.token);
         }
+        if (!/^https?:\/\//i.test(this.config.baseUrl)) {
+            return `${u.pathname}${u.search}${u.hash}`.replace(/\/$/, '');
+        }
         return u.toString().replace(/\/$/, '');
     }
     ioUrl(pathname) {
@@ -87,8 +103,8 @@ export class CloudflareAdapter {
             try {
                 ws = new WebSocket(this.notifyUrl);
             }
-            catch {
-                hooks?.onError?.();
+            catch (error) {
+                hooks?.onError?.(error);
                 scheduleReconnect();
                 return;
             }
@@ -107,12 +123,14 @@ export class CloudflareAdapter {
                     onInvalidate({ type: 'unknown', path: '/', ts: Date.now() });
                 }
             };
-            ws.onerror = () => {
-                hooks?.onError?.();
+            ws.onerror = (event) => {
+                hooks?.onError?.(event);
             };
             ws.onclose = () => {
-                if (!cancelled)
+                if (!cancelled) {
+                    hooks?.onClose?.();
                     scheduleReconnect();
+                }
             };
         };
         const scheduleReconnect = () => {
@@ -132,6 +150,8 @@ export class CloudflareAdapter {
         };
     }
     async ensureFolder(path) {
+        if (this.ensuredFolders.has(path))
+            return;
         const res = await fetch(this.ioUrl('/ensure-folder'), {
             method: 'POST',
             headers: this.headers({ 'Content-Type': 'application/json; charset=utf-8' }),
@@ -140,6 +160,13 @@ export class CloudflareAdapter {
         if (!res.ok && res.status !== 405) {
             throw new Error(`Failed to ensure folder ${path}: HTTP ${res.status}`);
         }
+        this.ensuredFolders.add(path);
+    }
+    /** Drop the per-session ensureFolder cache. Call after mesh swap, poison,
+     *  or any state where a previous "this folder exists" observation must
+     *  not be trusted. */
+    resetFolderCache() {
+        this.ensuredFolders.clear();
     }
     async listFiles(path) {
         const res = await fetch(this.ioUrl('/list-files'), {
@@ -224,4 +251,3 @@ export class CloudflareAdapter {
         };
     }
 }
-//# sourceMappingURL=cloudflare.js.map

package/dist/adapters/google-drive.d.ts

@@ -22,7 +22,7 @@ interface GoogleDriveConfig {
  * @example
  * ```ts
  * const adapter = new GoogleDriveAdapter({ clientId: 'YOUR_GOOGLE_CLIENT_ID' });
- * const engine = new SyncEngine(adapter, { remotePath: '/MyApp' });
+ * const engine = new Interocitor(adapter, { remotePath: '/MyApp' });
  * ```
  */
 export declare class GoogleDriveAdapter implements StorageAdapter {

package/dist/adapters/google-drive.js

@@ -19,7 +19,7 @@ const UPLOAD_API = 'https://www.googleapis.com/upload/drive/v3';
  * @example
  * ```ts
  * const adapter = new GoogleDriveAdapter({ clientId: 'YOUR_GOOGLE_CLIENT_ID' });
- * const engine = new SyncEngine(adapter, { remotePath: '/MyApp' });
+ * const engine = new Interocitor(adapter, { remotePath: '/MyApp' });
  * ```
  */
 export class GoogleDriveAdapter {
@@ -337,4 +337,3 @@ export class GoogleDriveAdapter {
         this.folderIdCache.clear();
     }
 }
-//# sourceMappingURL=google-drive.js.map

package/dist/adapters/memory.d.ts

@@ -14,7 +14,7 @@ import type { StorageAdapter, FileEntry } from '../core/types.ts';
  * @example
  * ```ts
  * const adapter = new MemoryAdapter();
- * const engine = new SyncEngine(adapter, { remotePath: '/Demo' });
+ * const engine = new Interocitor(adapter, { remotePath: '/Demo' });
  * ```
  */
 export declare class MemoryAdapter implements StorageAdapter {
@@ -22,6 +22,7 @@ export declare class MemoryAdapter implements StorageAdapter {
     private files;
     private folders;
     private authenticated;
+    private ensuredFolders;
     authenticate(): Promise<void>;
     /**
      * Memory adapter has no real backend — returns an empty config.
@@ -30,6 +31,8 @@ export declare class MemoryAdapter implements StorageAdapter {
     getHandshakeConfig(): string;
     isAuthenticated(): boolean;
     ensureFolder(path: string): Promise<void>;
+    /** Drop the per-session ensureFolder cache. Tests / mesh-swap callers. */
+    resetFolderCache(): void;
     listFiles(folderPath: string): Promise<FileEntry[]>;
     /** List immediate subfolder names under a path. */
     listFolders(folderPath: string): Promise<string[]>;

package/dist/adapters/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,KAAK,CAAsE;IACnF,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,aAAa,CAAS;IAExB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAI5B,eAAe,IAAI,OAAO;IAIpB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAsBzD,mDAAmD;IAC7C,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBlD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAM3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAY9D,kDAAkD;IAClD,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAS9B,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,KAAK,CAAsE;IACnF,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,aAAa,CAAS;IAK9B,OAAO,CAAC,cAAc,CAA0B;IAE1C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAI5B,eAAe,IAAI,OAAO;IAIpB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C,0EAA0E;IAC1E,gBAAgB,IAAI,IAAI;IAIlB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAsBzD,mDAAmD;IAC7C,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBlD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAM3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAY9D,kDAAkD;IAClD,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAS9B,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAId"}

package/dist/adapters/memory.js

@@ -13,7 +13,7 @@
  * @example
  * ```ts
  * const adapter = new MemoryAdapter();
- * const engine = new SyncEngine(adapter, { remotePath: '/Demo' });
+ * const engine = new Interocitor(adapter, { remotePath: '/Demo' });
  * ```
  */
 export class MemoryAdapter {
@@ -22,6 +22,11 @@ export class MemoryAdapter {
         this.files = new Map();
         this.folders = new Set();
         this.authenticated = false;
+        // Mirrors the cloud-adapter convention: cache "ensured" paths so a
+        // re-`ensureFolder` is a no-op. Memory adapter is cheap, but keeping
+        // the same shape lets tests assert call-count parity with the real
+        // adapters (cloudflare, webdav).
+        this.ensuredFolders = new Set();
     }
     async authenticate() {
         this.authenticated = true;
@@ -37,7 +42,14 @@ export class MemoryAdapter {
         return this.authenticated;
     }
     async ensureFolder(path) {
+        if (this.ensuredFolders.has(path))
+            return;
         this.folders.add(path);
+        this.ensuredFolders.add(path);
+    }
+    /** Drop the per-session ensureFolder cache. Tests / mesh-swap callers. */
+    resetFolderCache() {
+        this.ensuredFolders.clear();
     }
     async listFiles(folderPath) {
         const prefix = folderPath.endsWith('/') ? folderPath : folderPath + '/';
@@ -126,4 +138,3 @@ export class MemoryAdapter {
         this.folders.clear();
     }
 }
-//# sourceMappingURL=memory.js.map

package/dist/adapters/webdav.d.ts

@@ -34,6 +34,7 @@ export declare class WebDAVAdapter implements StorageAdapter {
     readonly name = "webdav";
     private config;
     private authenticated;
+    private ensuredFolders;
     constructor(config: WebDAVConfig);
     private url;
     private authHeader;
@@ -47,6 +48,10 @@ export declare class WebDAVAdapter implements StorageAdapter {
     getHandshakeConfig(): string;
     isAuthenticated(): boolean;
     ensureFolder(path: string): Promise<void>;
+    /** Drop the per-session ensureFolder cache. Call after mesh swap, poison,
+     *  or any state where we cannot trust a previous "this folder exists"
+     *  observation. */
+    resetFolderCache(): void;
     listFiles(folderPath: string): Promise<FileEntry[]>;
     private parsePropfindResponse;
     listFolders(folderPath: string): Promise<string[]>;

package/dist/adapters/webdav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webdav.d.ts","sourceRoot":"","sources":["../../src/adapters/webdav.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElE,UAAU,YAAY;IACpB,sGAAsG;IACtG,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,EAAE,YAAY;IAIhC,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,OAAO;IAOT,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBnC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;IAI5B,eAAe,IAAI,OAAO;IAIpB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBzC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IA0BzD,OAAO,CAAC,qBAAqB;IAoCvB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmClD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAY3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAyC/D"}
+{"version":3,"file":"webdav.d.ts","sourceRoot":"","sources":["../../src/adapters/webdav.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElE,UAAU,YAAY;IACpB,sGAAsG;IACtG,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAS;IAM9B,OAAO,CAAC,cAAc,CAA0B;gBAEpC,MAAM,EAAE,YAAY;IAIhC,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,OAAO;IAOT,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBnC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;IAI5B,eAAe,IAAI,OAAO;IAIpB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB/C;;uBAEmB;IACnB,gBAAgB,IAAI,IAAI;IAIlB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IA0BzD,OAAO,CAAC,qBAAqB;IAoCvB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmClD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAY3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAyC/D"}

package/dist/adapters/webdav.js

@@ -22,6 +22,12 @@ export class WebDAVAdapter {
     constructor(config) {
         this.name = 'webdav';
         this.authenticated = false;
+        // Per-session cache of folders we have already MKCOL'd. WebDAV folders
+        // are stable for the life of the mesh; a caller (Interocitor.connect)
+        // re-runs the same 4-folder ensureFolder loop on every reload, which
+        // costs 4 sequential MKCOL round-trips for no benefit. Cache wipes on
+        // explicit `resetFolderCache()` (mesh swap / poison) or process exit.
+        this.ensuredFolders = new Set();
         this.config = config;
     }
     url(path) {
@@ -70,10 +76,14 @@ export class WebDAVAdapter {
         return this.authenticated;
     }
     async ensureFolder(path) {
+        if (this.ensuredFolders.has(path))
+            return;
         const parts = path.split('/').filter(Boolean);
         let current = '';
         for (const part of parts) {
             current += '/' + part;
+            if (this.ensuredFolders.has(current))
+                continue; // ancestor cached
             const res = await fetch(this.url(current), {
                 method: 'MKCOL',
                 headers: this.headers(),
@@ -82,7 +92,15 @@ export class WebDAVAdapter {
             if (!res.ok && res.status !== 405) {
                 throw new Error(`Failed to create folder ${current}: ${res.status}`);
             }
+            this.ensuredFolders.add(current);
         }
+        this.ensuredFolders.add(path);
+    }
+    /** Drop the per-session ensureFolder cache. Call after mesh swap, poison,
+     *  or any state where we cannot trust a previous "this folder exists"
+     *  observation. */
+    resetFolderCache() {
+        this.ensuredFolders.clear();
     }
     async listFiles(folderPath) {
         const res = await fetch(this.url(folderPath), {
@@ -244,4 +262,3 @@ export class WebDAVAdapter {
         };
     }
 }
-//# sourceMappingURL=webdav.js.map

package/dist/core/codec.d.ts

@@ -1,7 +1,7 @@
 /**
  * Codec — encryption/decryption of change and snapshot payloads.
  *
- * Extracted from SyncEngine to keep the orchestrator lean.
+ * Extracted from Interocitor to keep the orchestrator lean.
  * Not part of the public API.
  */
 import type { ChangeEntry, Manifest, Snapshot, LocalStoreAdapter } from './types.ts';

package/dist/core/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/core/codec.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,EAGR,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,SAAS,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1F;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtF;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAQhG;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,CAAC,CAUtB;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlG;AAED,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC,CAUnB"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/core/codec.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,EAGR,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,SAAS,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1F;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BtF;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAQhG;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,CAAC,CAgBtB;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlG;AAED,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC,CAgBnB"}

package/dist/core/codec.js

@@ -1,7 +1,7 @@
 /**
  * Codec — encryption/decryption of change and snapshot payloads.
  *
- * Extracted from SyncEngine to keep the orchestrator lean.
+ * Extracted from Interocitor to keep the orchestrator lean.
  * Not part of the public API.
  */
 import { encryptEntry, decryptEntry } from "../crypto/encryption.js";
@@ -13,7 +13,36 @@ export async function encodeForCloud(state, plaintext) {
 export async function decodeFromCloud(state, data) {
     if (!state.encrypted || !state.encryptionKey)
         return data;
-    return decryptEntry(state.encryptionKey, data);
+    try {
+        return await decryptEntry(state.encryptionKey, data);
+    }
+    catch (err) {
+        // Re-throw with explicit context. Decode errors at this layer mean the
+        // active key cannot decrypt this payload — either the wrong key was
+        // loaded, or the payload was written under a different key (mesh swap,
+        // passphrase rotated, two devices bound to same dbName but different
+        // passphrases). Caller wraps this in poisonRemote with the file path.
+        const reason = err instanceof Error ? err.message : String(err);
+        let keyFingerprint = '<unknown>';
+        try {
+            const raw = await crypto.subtle.exportKey('raw', state.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('');
+            keyFingerprint = `sha256-${hex}`;
+        }
+        catch { /* ignore */ }
+        console.log('[interocitor:decode] decodeFromCloud() — DECRYPT FAIL', {
+            keyFingerprint,
+            meshId: state.manifest?.meshId,
+            payloadFirst32: data.slice(0, 32),
+            payloadLen: data.length,
+            reason,
+        });
+        const e = new Error(`Decryption failed: payload not decryptable with the active mesh key (${reason}). The remote was likely written under a different key/mesh.`);
+        e.cause = err;
+        throw e;
+    }
 }
 export async function assertExpectedMeshId(local, manifest, meshId) {
     if (!meshId) {
@@ -40,6 +69,10 @@ export async function encodeChangePayload(state, entry) {
 export async function decodeChangePayload(state, local, data, path) {
     const decoded = await decodeFromCloud(state, data);
     const payload = JSON.parse(decoded);
+    const payloadRecord = payload;
+    if ('mesh' in payloadRecord && !('meshId' in payloadRecord)) {
+        throw new Error(`Remote change payload has invalid shape: ${path}`);
+    }
     if (payload.kind !== 'change' || !payload.entry) {
         throw new Error(`Remote change payload has invalid shape: ${path}`);
     }
@@ -57,10 +90,13 @@ export async function encodeSnapshotPayload(state, snapshot) {
 export async function decodeSnapshotPayload(state, local, data, path) {
     const decoded = await decodeFromCloud(state, data);
     const payload = JSON.parse(decoded);
+    const payloadRecord = payload;
+    if ('mesh' in payloadRecord && !('meshId' in payloadRecord)) {
+        throw new Error(`Remote snapshot payload has invalid shape: ${path}`);
+    }
     if (payload.kind !== 'snapshot' || !payload.snapshot) {
         throw new Error(`Remote snapshot payload has invalid shape: ${path}`);
     }
     await assertExpectedMeshId(local, state.manifest, String(payload.meshId || ''));
     return payload.snapshot;
 }
-//# sourceMappingURL=codec.js.map

package/dist/core/compaction.d.ts

@@ -1,7 +1,14 @@
 /**
  * Compaction — snapshot + manifest rotation + change file pruning.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Concurrency note:
+ * - No built-in lock or CAS on manifest pointer.
+ * - Concurrent compaction can race and overwrite the pointer.
+ * - Recommended: acquire a remote lease (e.g. mainline/compact-lock.json)
+ *   and abort if another compactor is active, or if manifest generation
+ *   changes after the lease is acquired.
+ *
+ * Extracted from Interocitor. Not part of the public API.
  */
 import type { StorageAdapter, LocalStoreAdapter, Manifest, Row, SyncEvent } from './types.ts';
 import type { HLC } from './types.ts';
@@ -17,6 +24,7 @@ export interface CompactContext {
     serverId: string;
     emit: (event: SyncEvent) => void;
     pull: () => Promise<void>;
+    offlineGraceMs?: number;
 }
 export declare function compact(ctx: CompactContext): Promise<Manifest>;
 export interface RehydrateContext {

package/dist/core/compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/core/compaction.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,QAAQ,EAGR,GAAG,EACH,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuFpE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjC,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,iDAAiD;AACjD,wBAAsB,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,CAgDnE"}
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/core/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,QAAQ,EAGR,GAAG,EACH,SAAS,EAEV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAkCD,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsGpE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjC,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,iDAAiD;AACjD,wBAAsB,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,CAiDnE"}

package/dist/core/compaction.js

@@ -1,13 +1,56 @@
 /**
  * Compaction — snapshot + manifest rotation + change file pruning.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Concurrency note:
+ * - No built-in lock or CAS on manifest pointer.
+ * - Concurrent compaction can race and overwrite the pointer.
+ * - Recommended: acquire a remote lease (e.g. mainline/compact-lock.json)
+ *   and abort if another compactor is active, or if manifest generation
+ *   changes after the lease is acquired.
+ *
+ * Extracted from Interocitor. Not part of the public API.
  */
 import { hlcSerialize, hlcCompareStr } from "./hlc.js";
 import { paths, textEncoder, textDecoder, generateId, computeContentHash, log } from "./internals.js";
 import { encodeSnapshotPayload, decodeSnapshotPayload } from "./codec.js";
-import { writeJson } from "./manifest.js";
+import { readJsonIfExists, writeJson } from "./manifest.js";
 import { hlcParse } from "./hlc.js";
+async function computeGcFloor(ctx, nowMs) {
+    const p = paths(ctx.remotePath);
+    const graceMs = ctx.offlineGraceMs ?? 7 * 24 * 60 * 60000;
+    const cutoffMs = nowMs - graceMs;
+    const floors = [];
+    try {
+        const files = await ctx.adapter.listFiles(p.devicesFolder);
+        for (const file of files) {
+            if (!file.name.endsWith('.json'))
+                continue;
+            const deviceId = file.name.slice(0, -'.json'.length);
+            const meta = await readJsonIfExists(ctx.adapter, p.deviceFile(deviceId));
+            if (!meta || meta.retired)
+                continue;
+            const lastSeen = Date.parse(meta.lastSeenAt || '');
+            if (Number.isFinite(lastSeen) && lastSeen < cutoffMs)
+                continue;
+            // Active devices that have not yet acknowledged a watermark block
+            // advancement. They are still inside the offline grace window.
+            if (!meta.observedWatermarkHlc)
+                return ctx.manifest.gcFloorHlc ?? '';
+            floors.push(meta.observedWatermarkHlc);
+        }
+    }
+    catch {
+        return ctx.manifest.gcFloorHlc ?? '';
+    }
+    if (floors.length === 0)
+        return ctx.manifest.gcFloorHlc ?? '';
+    floors.sort(hlcCompareStr);
+    const candidate = floors[0];
+    const existing = ctx.manifest.gcFloorHlc ?? '';
+    if (existing && hlcCompareStr(existing, candidate) > 0)
+        return existing;
+    return candidate;
+}
 export async function compact(ctx) {
     const { adapter, local, remotePath, manifest, codecState, deviceId, serverId } = ctx;
     if (manifest.server.managed && deviceId !== serverId) {
@@ -16,7 +59,9 @@ export async function compact(ctx) {
     // Ensure the compactor has merged latest remote changes before snapshotting.
     await ctx.pull();
     const p = paths(remotePath);
-    const now = new Date().toISOString();
+    const nowDate = new Date();
+    const now = nowDate.toISOString();
+    const gcFloorHlc = await computeGcFloor(ctx, nowDate.getTime());
     const nextEpoch = manifest.epoch + 1;
     const nextGeneration = manifest.generation + 1;
     const snapshotPath = `${p.mainlineFolder}/snapshot-${nextEpoch}-${serverId}.json`;
@@ -24,9 +69,16 @@ export async function compact(ctx) {
     const allRows = await local.getAllRows();
     const snapshotTables = {};
     for (const row of allRows) {
-        if (!snapshotTables[row._table])
-            snapshotTables[row._table] = {};
-        snapshotTables[row._table][row._rowId] = row;
+        if (gcFloorHlc
+            && row._meta.deleted
+            && row._meta.deletedHlc
+            && hlcCompareStr(row._meta.deletedHlc, gcFloorHlc) <= 0) {
+            continue;
+        }
+        const t = row._meta.table;
+        if (!snapshotTables[t])
+            snapshotTables[t] = {};
+        snapshotTables[t][row._meta.rowId] = row;
     }
     const snapshot = {
         snapshotId: generateId('snap'),
@@ -53,6 +105,10 @@ export async function compact(ctx) {
         watermarkHlc: hlcSerialize(ctx.hlc),
         snapshotPath,
         deltaPath: null,
+        gcFloorHlc,
+        gcEpoch: gcFloorHlc ? nextEpoch : manifest.gcEpoch,
+        gcCreatedAt: gcFloorHlc ? now : manifest.gcCreatedAt,
+        offlineGraceMs: ctx.offlineGraceMs,
     };
     const nextManifest = {
         ...manifestPayload,
@@ -123,6 +179,7 @@ export async function rehydrate(ctx) {
         ctx.emit({ type: 'rehydrate:complete', rowCount });
     }
     catch (err) {
+        ctx.emit({ type: 'decode:error', error: err instanceof Error ? err : new Error(String(err)), path: snapshotPath, context: { stage: 'rehydrate' } });
         const poisoned = await ctx.poisonRemote(err, snapshotPath);
         ctx.emit({ type: 'sync:error', error: poisoned });
         throw poisoned;
@@ -131,4 +188,3 @@ export async function rehydrate(ctx) {
     await ctx.pull();
     return hlc;
 }
-//# sourceMappingURL=compaction.js.map

package/dist/core/crdt.d.ts

@@ -10,6 +10,10 @@
  *  - custom function  — `(local, remote, ctx) => ColumnEntry`
  *
  * Deletes are soft (tombstone with HLC) and always use LWW.
+ *
+ * Row shape (`{_meta, payload}`) keeps user payload fully isolated from
+ * engine metadata. The merge loop only touches `row.payload`; `row._meta`
+ * is never indexed by user-controlled keys.
  */
 import type { Row, Op, ChangeEntry, DatabaseSchemaDefinition } from './types.ts';
 /**
@@ -22,12 +26,11 @@ export declare function applyOp(tables: Record<string, Record<string, Row>>, op:
  * Returns list of affected rows.
  */
 export declare function applyChangeEntry(tables: Record<string, Record<string, Row>>, entry: ChangeEntry, schemaVersion: number, schema?: DatabaseSchemaDefinition): Row[];
-/**
- * Read a column value from a row, unwrapping the ColumnEntry.
- */
+/** Read a column value from a row, unwrapping the ColumnEntry. */
 export declare function readColumn(row: Row, column: string): unknown;
 /**
  * Build a plain object from a row (strip HLC metadata).
+ * Returns user-facing fields with `_meta` projection (table, rowId, deleted).
  */
 export declare function rowToPlain(row: Row): Record<string, unknown>;
 //# sourceMappingURL=crdt.d.ts.map

package/dist/core/crdt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/core/crdt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,EAAE,EAEF,WAAW,EACX,wBAAwB,EAGzB,MAAM,YAAY,CAAC;AA0EpB;;;GAGG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,EAAE,EAAE,EAAE,EACN,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,wBAAwB,GAChC,GAAG,GAAG,IAAI,CA4EZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,wBAAwB,GAChC,GAAG,EAAE,CAOP;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAM5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa5D"}
+{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/core/crdt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,EAAE,EAEF,WAAW,EACX,wBAAwB,EAGzB,MAAM,YAAY,CAAC;AAoEpB;;;GAGG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,EAAE,EAAE,EAAE,EACN,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,wBAAwB,GAChC,GAAG,GAAG,IAAI,CAuEZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,wBAAwB,GAChC,GAAG,EAAE,CAOP;AAED,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAU5D"}