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

package/README.md

@@ -1,151 +1,483 @@
 <p align="center">
   <a href="https://github.com/TheUiTeam/interocitor">
-    <img src="https://raw.githubusercontent.com/TheUiTeam/interocitor/main/docs/assets/hero.svg" alt="interocitor" width="560"/>
+    <img src="../../docs/assets/hero.svg" alt="Interocitor" width="640" />
   </a>
 </p>
 
 <p align="center">
-  <strong>The JavaScript mailbox that can't read your mail.</strong>
+  <em>Encrypted local-first CRDT sync for browser apps.</em>
 </p>
 
-# interocitor
+# @interocitor/core
 
-Encrypted local-first CRDT sync for browser apps.
+End‑to‑end encrypted, local‑first sync over a remote folder you already
+own (Google Drive, WebDAV, Cloudflare R2, your own server). The cloud is
+a mailbox; merge happens on the device.
 
-## Why
+## What it is
+
+- A sync engine, not a database. Local reads/writes go through an embedded
+  store (IndexedDB in the browser). The engine ships diffs, not queries.
+- A CRDT over per‑column HLC values. Every device converges to the same
+  state without a central merge authority.
+- An end‑to‑end encryption layer. The remote sees ciphertext blobs and
+  enough metadata to route them; nothing else.
+- A pluggable transport. Any backend that can list/read/write/delete
+  files works. See `docs/adapter-contract.md`.
 
-Interocitor is your app's __personal keychain__.
-Your devices hold the key. The cloud is only a mailbox. It carries encrypted sync artifacts and cannot read your mail.
+## Why
 
-What this means:
-- encryption on by default
-- reads and writes are local-first
-- sync uses a remote mailbox, not a trusted database
-- restore is explicit app UI, not automatic magic
+- **Offline‑first by construction.** Every read and write hits a local
+  store. Network is needed only to share state with other devices.
+- **No server you have to operate.** The remote is dumb storage. You can
+  run the engine against a user's own Google Drive and ship zero
+  backend.
+- **End‑to‑end encryption by default.** The default config encrypts
+  every change file and snapshot before it leaves the device.
+- **Small, embeddable runtime.** No workers, no background services
+  required.
 
 ## Quick start
 
 ```ts
-import { SyncEngine, createRowId } from 'interocitor';
-import { WebDAVAdapter } from 'interocitor/adapters/webdav';
+import { Interocitor } from '@interocitor/core';
+import { GoogleDriveAdapter } from '@interocitor/core/adapters/google-drive';
 
-const adapter = new WebDAVAdapter({
-  baseUrl: 'https://your-webdav-server.example.com',
-  auth: { username: 'user', password: 'pass' },
-});
+const adapter = new GoogleDriveAdapter({ clientId: 'YOUR_GOOGLE_CLIENT_ID' });
 
-const engine = new SyncEngine(adapter, {
-  remotePath: '/MyApp',
-  dbName: 'my-app',
-  appName: 'My App',
-  // encrypted by default; set encrypted: false to opt out
+const db = new Interocitor(adapter, {
+  dbName: 'my-app',          // local DB name; keep stable across reloads
+  appName: 'My App',         // shown in biometric prompts / OS keychain
+  remotePath: '/MyApp',      // mesh-scoped folder on the remote
+  encrypted: true,           // E2E encryption (default)
 });
 
-await engine.init();
-await engine.connect();
+await db.init();
+await db.connect();
 
-const id = createRowId({ prefix: 'todo' });
-await engine.put('todos', id, {
-  text: 'Ship privacy-first sync',
-  done: false,
-});
+// Write — local-first, no network required
+await db.table('todos').add(
+  { text: 'Ship privacy-first sync', done: false },
+  { prefix: 'todo' },
+);
+
+// Share with another device — see "New device / restore" below
+console.log('Passphrase:', db.getPassphrase());
 ```
 
-## How sync works
+> The constructor accepts either `(adapter, config)` or `(config)` alone.
+> Use the `(config)` form for local‑only mode (no remote). When you
+> attach a remote later, call `setRemoteStorage(adapter)` and then
+> `connect()`.
+
+## Mental model
 
 ```mermaid
 flowchart LR
   A[Browser app] --> B[Interocitor engine]
   B --> C[Local store]
-  B --> D[Encrypt changes locally]
+  B --> D[Encrypt locally]
   D --> E[Adapter]
-  E --> F[Remote mailbox\n(ciphertext only)]
+  E --> F[Remote mailbox<br/>ciphertext only]
   F --> E
-  E --> G[Download ciphertext]
-  G --> H[Decrypt locally]
-  H --> B
+  E --> G[Decrypt locally]
+  G --> B
 ```
 
-## Core API at a glance
+The remote is a mailbox. The engine puts encrypted change files into it
+and pulls down change files from peers. All merging happens on the
+device. There is no server‑side compute.
 
-```ts
-await engine.init();
-await engine.connect();
-await engine.put(table, id, data);
-await engine.get(table, id);
-await engine.query(table);
-await engine.sync();
-
-await engine.secureWithBiometrics();   // optional, explicit keychain enrollment
-await engine.restoreWithBiometrics();  // explicit recovery flow
-```
+Three artifacts live on the remote:
 
-## Row IDs
+- **change files** — one per write batch, named `<HLC>-chg_<id>.json`;
+- **snapshots** — periodic full state, written by compaction;
+- **a manifest** — pointer to the current generation, plus mesh metadata.
 
-Use stable string IDs for synced rows. Do not use auto-increment IDs.
+See `docs/adapter-contract.md` for the full layout.
 
-Good default:
+## Security model
 
-```ts
-import { createRowId } from 'interocitor';
+Encryption is on by default (`encrypted: true`). The engine uses
+**AES‑GCM 256** with a key derived from a base58 passphrase.
 
-const id = createRowId({ prefix: 'task' });
-```
+What it protects:
+
+- Row contents (field names, field values, table names) inside change
+  files and snapshots.
+- Integrity of each entry (AES‑GCM authentication tag).
+
+What it does **not** protect:
+
+- File names (they encode the HLC and a device id).
+- Manifest contents (mesh id, schema version, epoch, encrypted flag,
+  serverId).
+- Sizes, write timing, device count.
+- The local store on the device (IndexedDB / SQLite stores plaintext).
+
+What a malicious remote can still do:
 
-`createRowId()` uses platform crypto. No extra dependency needed.
+- Drop, withhold, replay, or roll back files.
+- Observe activity timing and device identities.
 
-## Offline guarantee
+For the threat model, the metadata table, and full mitigations see
+`docs/security-model.md`.
 
-Every read and write hits the local store. No network required.
-`sync()` is the only call that touches the remote mailbox.
+## Offline guarantees
 
 | Operation | Network? |
 | --- | --- |
+| `new Interocitor()` | No |
 | `init()` | No |
-| `put()` | No |
-| `delete()` | No |
-| `get()` / `query()` | No |
-| `sync()` | Yes, if adapter configured |
+| `table.add()` / `patch()` / `replace()` / `delete()` | No |
+| `table.row()` / `table.query()` / `table.where()` | No |
+| `connect()` | Yes (if adapter configured) |
+| `flush()` / `pull()` / `compact()` | Yes |
+
+Writes are persisted locally and queued in an outbox. They survive
+reload, crash, and offline periods. On reconnect the engine drains the
+outbox to the remote.
+
+## Sync guarantees
+
+- **Eventual convergence.** Two devices that have seen the same set of
+  change files (in any order) reach byte‑identical local state.
+- **Per‑column merge.** Conflicts are resolved field‑by‑field, not at
+  the row level. Default strategy is `'remote-wins'` — see
+  "Conflict resolution".
+- **Idempotent merge.** Replaying an already‑applied change is a no‑op.
+  Safe to re‑pull, safe to re‑process the same change file twice.
+- **Per‑device HLC monotonicity.** A single device's HLCs strictly
+  increase. Cross‑device order is total but only as wall‑clocks allow.
+- **Restore via snapshot.** A device that joins late (or rehydrates after
+  a long offline) loads the latest snapshot, then applies any change
+  files newer than the snapshot watermark.
+
+What we do **not** guarantee:
+
+- Cross‑device atomicity. A `db.batch()` is one atomic remote file, but
+  two unrelated batches from different devices are independent.
+- Real‑time delivery. The default poll interval is 30 s; some adapters
+  (Cloudflare) layer push notifications on top.
+- Recovery if the remote silently lies (drops writes, rolls back the
+  manifest). See `docs/security-model.md`.
+- Recovery if the passphrase is lost — see "New device / restore".
+
+## Setup lifecycle
 
-## Adapters
+```
+new Interocitor(adapter?, config)
+        │
+        ▼
+  configureMesh({...})       ← optional; pin meshId / passphrase upfront
+        │
+        ▼
+       init()                ← opens local store, restores credentials
+        │
+        ▼
+  setRemoteStorage(adapter)  ← only if no adapter passed to ctor
+        │
+        ▼
+     connect()               ← loads/creates manifest, pulls, flushes, polls
+```
 
-### Google Drive
-For zero new backend infrastructure where Google Drive is acceptable as the encrypted mailbox.
+`connect()` will auto‑`init()` if needed. App code should still treat
+init as explicit so credential restore happens before any writes.
 
-### WebDAV
-For self-hosted sync, local demos, and inspectable remote artifacts.
+The `encrypted` flag is **pinned at mesh bootstrap** and cannot change
+between sessions for the same `dbName`. Reconnecting with a different
+mode throws a typed `MeshEncryptionMismatchError`.
 
-### Cloudflare (experimental)
-For Interocitor-native transport flows with invalidation fanout and maintenance endpoints while keeping decryption client-side.
+```ts
+import { MeshEncryptionMismatchError } from '@interocitor/core';
+
+try {
+  await db.connect();
+} catch (err) {
+  if (err instanceof MeshEncryptionMismatchError) {
+    // err.expectedMode is the mode the remote was bootstrapped with
+  }
+  throw err;
+}
+```
 
-### Memory
-For tests and adapter-contract validation.
+## New device / restore
 
-## Local store
+Joining a new device to an existing mesh requires three things:
 
-Interocitor is a sync engine, not a database. The local store is a pluggable abstraction (`LocalStoreAdapter`). The browser default uses IndexedDB. The Swift package uses SQLite. You don't need to care which — reads, writes, and queries go through the engine API.
+1. The **`meshId`** of the existing mesh.
+2. The **passphrase** that decrypts the mesh.
+3. Access to the same **remote mailbox** (the same `remotePath` on a
+   storage backend the new device can reach).
 
-## CRDT strategy
+The pairing flow ships these three over an ECDH relay handshake (see
+`generateShareQR` / `handleScannedQR` in the handshake module). After
+the handshake the new device:
 
-Interocitor uses per-column CRDTs with hybrid logical clocks (HLC). All merge happens on the client. Remote storage is just a byte pipe.
+```ts
+const db = new Interocitor(adapter, {
+  dbName: 'my-app',
+  appName: 'My App',
+  remotePath: '/MyApp',
+  passphrase: 'base58-from-handshake',
+  encrypted: true,
+});
 
-Conflict default: `'remote-wins'`.
-Override at database, table, or field level.
+await db.init();
+await db.connect();   // pulls the manifest, rehydrates from snapshot, then catches up
+```
 
-## Events
+On `connect()` the engine:
+
+1. Reads `manifest.json` from the remote.
+2. Compares stored `meshId` (from the credential store) against the live
+   one. Mismatch → `MeshCredentialMismatchError`.
+3. If local epoch < remote epoch, calls `rehydrate()` to load the
+   latest snapshot.
+4. Pulls any change files newer than the snapshot watermark.
+5. Starts polling.
+
+> **If the passphrase is lost and no other device holds it, the mesh is
+> unreadable.** The engine has no recovery path — the data is end‑to‑end
+> encrypted and the key is the passphrase. Treat the passphrase as the
+> only thing that matters; back it up out of band (1Password, paper,
+> another device's `WebAuthnCredentialStore`).
+
+For the credential store details (records, anchors, biometric paths)
+see `docs/credential-store.md`.
+
+## Core API
 
 ```ts
-engine.on('change', (event) => {
-  console.log(event.type, event.table, event.id);
+const db = new Interocitor(adapter, {
+  dbName: 'my-app',
+  appName: 'My App',
+  remotePath: '/MyApp',
+  schema,
+});
+await db.init();
+
+await db.table('tasks').add({ title: 'Ship it', done: false }, { prefix: 'task' });
+await db.table('tasks').patch(taskId, { done: true });
+await db.table('tasks').replace(taskId, fullTask);
+await db.table('tasks').delete(taskId);
+
+await db.table('tasks').row(taskId);                          // single row
+await db.table('tasks').query();                              // all rows
+await db.table('tasks').where('done').equals(false).orderBy('title');
+
+await db.connect();                                           // attach + sync
+await db.flush();                                             // force outbox drain
+await db.pull();                                              // force pull
+await db.compact();                                           // see docs/compaction.md
+await db.disconnect();                                        // tear down
+
+// Credentials
+db.getPassphrase();
+db.setPassphrase(passphrase);
+await db.secureWithBiometrics();
+await db.restoreWithBiometrics();
+await db.clearCredentials();
+
+// Batched writes — one ChangeEntry per batch
+await db.batch(async () => {
+  await db.table('todos').add({ title: 'a' });
+  await db.table('todos').patch(otherId, { done: true });
 });
 ```
 
-## Local TODO demo (WebDAV)
+### Schema typing
 
-From the monorepo root:
+```ts
+import { types } from '@interocitor/core';
+import type { DatabaseSchemaDefinition } from '@interocitor/core';
+
+const schema = {
+  version: 1,
+  tables: {
+    todos: {
+      fields: {
+        text: types.string,
+        done: types.boolean,
+        createdAt: types.index(types.date),
+        note: types.string.optional,
+        items: types.typed<TodoItem[]>('json'),
+      },
+    },
+  },
+} satisfies DatabaseSchemaDefinition;
+
+// Inferred row type:
+// { text: string; done: boolean; createdAt: Date; note?: string; items: TodoItem[] }
+```
 
-```bash
-yarn demo:todo
+`.optional` makes the field optional in the inferred type. Indexed and
+unique fields cannot be optional. `types.index(...)` marks a field for
+efficient `where`/`orderBy`.
+
+### Conflict resolution
+
+Per‑column CRDT with HLC. Default merge strategy: **`'remote-wins'`**.
+
+> "Remote‑wins" is per‑column, not per‑row. When two devices write the
+> same column on the same row, the merge keeps the value with the higher
+> HLC. Because HLCs are timestamp‑first, this is "later wall‑clock
+> wins, ties broken by device id". Calling it "remote‑wins" is a
+> historical accident of where the merge runs (during pull); both sides
+> apply the same rule and reach the same answer. Override per database,
+> table, or field if you need `'lww'`, `'local-wins'`, or a custom
+> `MergeFunction`.
+
+Available strategies:
+
+- `'lww'` — last‑write‑wins by HLC. Functionally identical to
+  `'remote-wins'` for this CRDT but keeps semantics explicit.
+- `'remote-wins'` (default).
+- `'local-wins'` — keep local on tie; remote still wins on a strictly
+  greater HLC.
+- `MergeFunction` — `(local, remote, ctx) => result` for custom logic.
+
+### Deletion semantics
+
+`delete()` writes a **tombstone**, not an immediate unlink. Tombstones:
+
+- carry `deletedHlc` like any other write;
+- hide the row from public reads and queries;
+- keep an empty payload, so deleted user data does not linger inside the
+  tombstone;
+- are needed so that slower devices cannot replay an older `add()` and
+  resurrect the row.
+
+Re-inserting the same row id after a delete starts a fresh row
+incarnation. Columns from the old incarnation are not carried forward;
+a partial insert only contains the new columns.
+
+Compaction can later hard-delete tombstones from snapshots. The engine
+tracks per-device acknowledgements in `devices/<deviceId>.json`; once
+all active devices have observed a manifest watermark, compaction
+publishes `manifest.gcFloorHlc` as a point of no return. Tombstones with
+`deletedHlc <= gcFloorHlc` are omitted from the next snapshot.
+
+Devices not seen within `offlineGraceMs` (default seven days) are
+excluded from GC consensus. If one wakes up with local outbox entries at
+or before `gcFloorHlc`, the engine refuses to flush those entries and
+rehydrates from the canonical snapshot instead.
+
+### Local store
+
+The local store is a pluggable `LocalStoreAdapter`. Browser default is
+IndexedDB. The Swift package ships SQLite. Tests use an in‑memory
+implementation. Reads, writes, queries, and the outbox all go through
+this interface.
+
+## Adapters
+
+| Adapter | Use when | Notes |
+| --- | --- | --- |
+| `GoogleDriveAdapter` | You want zero infrastructure | OAuth in the browser; the user owns the data |
+| `WebDAVAdapter` | Self‑hosted (Nextcloud, OwnCloud, custom WebDAV) | Easy to inspect remotely |
+| `CloudflareAdapter` | You operate a worker; want push invalidations | Experimental |
+| `MemoryAdapter` | Tests and demos | No persistence |
+
+Implementing your own adapter: see `docs/adapter-contract.md` for
+required semantics, consistency assumptions, and the contract test
+suite.
+
+## Remote mailbox layout
+
+For `remotePath: '/MyApp'`:
+
+```
+/MyApp/
+├── manifest.json                           # pointer { currentGeneration, file }
+├── manifest-1.json                         # generation 1
+├── manifest-2.json                         # ...
+├── changes/
+│   ├── head.json                           # { latestHlc } — pull fast path
+│   └── <HLC>-chg_<id>.json                 # encrypted change entries
+├── devices/
+│   └── <deviceId>.json                     # device metadata
+└── mainline/
+    └── snapshot-<epoch>-<serverId>.json    # encrypted snapshot
+```
+
+`remotePath` is **mesh‑scoped**. One folder = one mesh = one logical
+database. Two meshes sharing the same folder will fight over the
+manifest and poison the remote.
+
+## Maintenance / compaction
+
+Compaction collapses the change log into a snapshot, bumps the manifest,
+prunes old change files, and advances the tombstone GC floor when active
+devices have acknowledged the prior watermark. Sync works without it;
+the remote folder just grows until *some* device compacts.
+
+Two paths run automatically:
+
+- **Immediate sampled** — after a flush of ≥ `compactAutoThreshold`
+  (default 50) ops, with probability ≈
+  `compactAutoSampleNumerator / compactAutoDeviceCount`.
+- **Delayed two‑phase** — per‑write timer (10 ± 5 min) → check that
+  remote change files exceed `compactRemoteChangeThreshold` (default 2)
+  → second timer (15 ± 5 min) → run.
+
+Both paths are deduped by a single in‑flight guard. You can also call
+`db.compact()` manually.
+
+> **The auto defaults and the recommended manual policy are different
+> things.** The manual policy ("idle > 1 min, churn > 20") is what to
+> gate a "Sync now" button on. The auto defaults are what runs without
+> any button. See `docs/compaction.md`.
+
+> **Compaction is not race‑safe across devices.** The adapter contract
+> has no CAS/ETag write, so two simultaneous compactors can both
+> overwrite the manifest pointer. Mitigations: rely on probabilistic
+> avoidance for small meshes, or run with `serverManaged: true` and a
+> single authorized writer.
+
+Full protocol, events, lock story, device acknowledgement / GC-floor
+rules, prune invariants, and tuning checklist: **`docs/compaction.md`**.
+
+## Schema migration
+
+Schema versions are integers in `manifest.schema`. The engine tracks the
+current version on every write. There is **no in‑place rewrite of the
+remote history** — change files written under v1 stay v1 ciphertext.
+
+Recommended migration pattern:
+
+1. Bump `schema.version` in your code.
+2. Implement a one‑shot `onInit` migration that reads v1 rows from the
+   local store and writes v2 rows back. Use `db.batch(...)` to keep it
+   atomic per row group.
+3. Trigger compaction after the migration so the snapshot is written
+   under v2 and old v1 change files are pruned.
+4. Devices that have not yet migrated will read v2 change files; your
+   schema definitions need to handle the transition (e.g. accept both
+   shapes during the rollout window).
+
+For breaking changes that cannot be rolled out gradually, the
+heavier path is to bootstrap a fresh mesh, replicate data over, and
+retire the old mesh. The engine does not automate this.
+
+## Events
+
+```ts
+db.on(event => {
+  switch (event.type) {
+    case 'sync:start':                /* pull began */ break;
+    case 'sync:complete':             /* event.entriesMerged */ break;
+    case 'change':                    /* event.table, event.rowId, event.row */ break;
+    case 'delete':                    /* event.table, event.rowId */ break;
+    case 'flush:start':               /* event.entryCount */ break;
+    case 'flush:complete':            break;
+    case 'flush:error':               /* event.error */ break;
+    case 'remote:poisoned':           /* unrecoverable; see security-model.md */ break;
+    case 'credentials:meshMismatch':  /* stored meshId != live; offer clearCredentials() */ break;
+    case 'compact:warning':           /* outbox is large */ break;
+    // compact:auto:start / complete / skip / error / delayed:* — see docs/compaction.md
+  }
+});
 ```
 
 ## What this is not
@@ -156,22 +488,45 @@ yarn demo:todo
 - not Replicache
 - not a hosted backend
 - not a query engine over the cloud
-- not a server-trusted merge layer
+- not a server‑trusted merge layer
+
+## What can go wrong
+
+A short field guide. Detailed mitigations in the linked docs.
+
+| Symptom | Likely cause | Where to look |
+| --- | --- | --- |
+| `MeshCredentialMismatchError` on connect | Same `dbName`, new mesh; stale credential record | `engine.clearCredentials()` then reconnect; `docs/credential-store.md` |
+| `MeshEncryptionMismatchError` on connect | App flipped `encrypted` between sessions | Pin `encrypted` per `dbName`, never change |
+| `remote:poisoned` event | Decode failure on a manifest, change file, or snapshot | `docs/security-model.md` — usually wrong key, schema drift, or remote tampering |
+| Writes never appear on peer | Peer never compacted, or peer's poll interval is long, or remote dropped writes | Check `flush:complete` events; check remote folder by hand |
+| Local store has rows that are "old" after re‑pair | Engine kept local data when you re‑paired with a fresh mesh | Either delete local DB on re‑pair, or accept the merge |
+| Lost passphrase | No recovery | Passphrase is the key. Back it up out of band |
+| Long‑offline device "lost" recent edits | Rehydrate replaced local state with the snapshot | Local writes already in the outbox survive; in‑flight uncommitted UI state does not |
+| Compaction never runs | `autoCompact: false`, or no remote, or `compactAutoThreshold` never reached | `docs/compaction.md` — subscribe to `compact:auto:skip` |
+| Two compactors race | No CAS in the adapter; small probability in small meshes | Use `serverManaged: true` for large meshes |
 
 ## Tests
 
-From the monorepo root:
+```bash
+yarn workspace @interocitor/core test
+```
+
+Adapter contract tests (run for every adapter):
 
 ```bash
-yarn workspace interocitor test
+yarn workspace @interocitor/core test webdav.adapter.contract
 ```
 
 ## Package context
 
-This package is the main JavaScript/TypeScript runtime in the monorepo. See also:
+Part of the Interocitor monorepo. See:
+
 - root `README.md` — monorepo overview
-- `packages/interocitor-swift` — Swift client
-- `examples/todo-webdav` — local demo app
+- `docs/security-model.md` — threat model
+- `docs/adapter-contract.md` — adapter requirements
+- `docs/compaction.md` — compaction protocol & tuning
+- `docs/credential-store.md` — credential persistence
 
 ## License
 

package/dist/adapters/cloudflare.d.ts

@@ -10,7 +10,7 @@
  * The adapter derives:
  *   wss://<worker>/notify/<prefix>  (WebSocket invalidations via InterocitorRelay DO)
  */
-import type { StorageAdapter, FileEntry } from '../core/types.ts';
+import type { StorageAdapter, FileEntry, RemoteInvalidationPayload, RemoteInvalidationHooks } from '../core/types.ts';
 export interface CloudflareAdapterConfig {
     /** Worker IO base URL that includes prefix, e.g. https://worker/io/team-a */
     baseUrl: string;
@@ -40,8 +40,10 @@ export declare class CloudflareAdapter implements StorageAdapter {
     readonly name = "cloudflare";
     private readonly config;
     private authenticated;
+    private ensuredFolders;
     constructor(config: CloudflareAdapterConfig);
     private headers;
+    private parseBaseUrl;
     private get ioBaseUrl();
     private get notifyUrl();
     private ioUrl;
@@ -53,15 +55,12 @@ export declare class CloudflareAdapter implements StorageAdapter {
      */
     getHandshakeConfig(): string;
     isAuthenticated(): boolean;
-    subscribeToInvalidations(onInvalidate: (payload: {
-        type: string;
-        path: string;
-        ts: number;
-    }) => void, hooks?: {
-        onReady?: () => void;
-        onError?: () => void;
-    }): () => void;
+    subscribeToInvalidations(onInvalidate: (payload: RemoteInvalidationPayload) => void, hooks?: RemoteInvalidationHooks): () => void;
     ensureFolder(path: string): Promise<void>;
+    /** 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(): void;
     listFiles(path: string): Promise<FileEntry[]>;
     listFolders(path: string): Promise<string[]>;
     readFile(path: string): Promise<Uint8Array>;

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

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;;;;;;GAaG;AACH,wFAAwF;AACxF,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,EAAE,uBAAuB;IAI3C,OAAO,CAAC,OAAO;IAQf,OAAO,KAAK,SAAS,GAMpB;IAED,OAAO,KAAK,SAAS,GAWpB;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,OAAO;IAMT,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBnC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAK5B,eAAe,IAAI,OAAO;IAI1B,wBAAwB,CACtB,YAAY,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,EAC3E,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,GACrD,MAAM,IAAI;IAwDP,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAqB7C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAe5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAa3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAsB/D"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEtH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;;;;;;GAaG;AACH,wFAAwF;AACxF,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,aAAa,CAAS;IAM9B,OAAO,CAAC,cAAc,CAA0B;gBAEpC,MAAM,EAAE,uBAAuB;IAI3C,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,YAAY;IAWpB,OAAO,KAAK,SAAS,GAMpB;IAED,OAAO,KAAK,SAAS,GAWpB;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,OAAO;IAMT,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBnC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAK5B,eAAe,IAAI,OAAO;IAI1B,wBAAwB,CACtB,YAAY,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,EAC1D,KAAK,CAAC,EAAE,uBAAuB,GAC9B,MAAM,IAAI;IA2DP,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/C;;0BAEsB;IACtB,gBAAgB,IAAI,IAAI;IAIlB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAqB7C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAe5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAa3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAsB/D"}