taladb 0.9.0 → 0.9.2

package/dist/index.browser.mjs

@@ -48,7 +48,7 @@ async function writeCursor(cursorCol, target, cursor) {
     await cursorCol.insert({ target, ...cursor });
   }
 }
-async function runSync(handle, adapter, options) {
+async function runSync(handle, adapter, options, syncSchemas = {}) {
   const direction = options.direction ?? "both";
   const target = options.target ?? "default";
   const doPush = direction === "push" || direction === "both";
@@ -63,11 +63,25 @@ async function runSync(handle, adapter, options) {
   const cursorCol = handle.collection(CURSOR_COLLECTION);
   const cursor = await readCursor(cursorCol, target);
   const local = doPush ? await handle.exportChanges(collections, 0) : "[]";
+  const scopedSchemas = {};
+  for (const c of collections) {
+    if (syncSchemas[c]) scopedSchemas[c] = syncSchemas[c];
+  }
+  const useValidated = handle.importChangesValidated && Object.keys(scopedSchemas).length > 0;
   let pulled = 0;
+  let skipped = 0;
+  let quarantined = 0;
   if (doPull) {
     const remote = await adapter.pull(0);
     if (remote && remote !== "[]") {
-      pulled = await handle.importChanges(remote);
+      if (useValidated) {
+        const report = await handle.importChangesValidated(remote, JSON.stringify(scopedSchemas));
+        pulled = report.applied;
+        skipped = report.skipped;
+        quarantined = report.quarantined;
+      } else {
+        pulled = await handle.importChanges(remote);
+      }
     }
   }
   let pushed = 0;
@@ -79,7 +93,7 @@ async function runSync(handle, adapter, options) {
     pushMs: cursor.pushMs,
     pullMs: cursor.pullMs
   });
-  return { pushed, pulled, cursor: 0 };
+  return { pushed, pulled, skipped, quarantined, cursor: 0 };
 }
 
 // src/http-adapter.ts
@@ -128,9 +142,34 @@ var TalaDbValidationError = class extends Error {
     this.name = "TalaDbValidationError";
   }
 };
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+  const ao = a;
+  const bo = b;
+  const keys = Object.keys(ao);
+  if (keys.length !== Object.keys(bo).length) return false;
+  return keys.every(
+    (k) => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k])
+  );
+}
 function applySchema(col, options) {
-  const { schema, validateOnRead = false } = options;
-  if (!schema) return col;
+  const { schema, validateOnRead = false, migrateDocument, syncSchema, persistMigrations = false } = options;
+  const targetVersion = syncSchema?.version ?? 0;
+  if (migrateDocument && targetVersion < 1) {
+    throw new Error("CollectionOptions.migrateDocument requires syncSchema.version (the migration target)");
+  }
+  if (syncSchema && targetVersion < 1 && (syncSchema.renames || syncSchema.defaults)) {
+    throw new Error(
+      "CollectionOptions.syncSchema.renames/defaults require syncSchema.version >= 1 \u2014 without a version the import migration step never runs and documents missing the renamed/defaulted fields are quarantined instead of upgraded"
+    );
+  }
+  const stampVersion = targetVersion > 0;
+  if (!schema && !migrateDocument && !stampVersion) return col;
   function parseWrite(doc, label) {
     try {
       return schema.parse(doc);
@@ -138,31 +177,96 @@ function applySchema(col, options) {
       throw new TalaDbValidationError(err, label);
     }
   }
-  function parseRead(doc) {
+  function stamp(doc) {
+    if (!stampVersion || doc._v !== void 0) return doc;
+    return { ...doc, _v: targetVersion };
+  }
+  function diffUpdate(original, migrated) {
+    const $set = {};
+    const $unset = {};
+    for (const k of Object.keys(migrated)) {
+      if (k === "_id") continue;
+      if (!deepEqual(migrated[k], original[k])) $set[k] = migrated[k];
+    }
+    for (const k of Object.keys(original)) {
+      if (k !== "_id" && !(k in migrated)) $unset[k] = true;
+    }
+    const update = {};
+    if (Object.keys($set).length) update.$set = $set;
+    if (Object.keys($unset).length) update.$unset = $unset;
+    return Object.keys(update).length ? update : null;
+  }
+  function migrateRead(doc) {
+    if (!migrateDocument) return doc;
+    const fromVersion = typeof doc._v === "number" ? doc._v : 0;
+    if (fromVersion >= targetVersion) return doc;
+    return { ...migrateDocument(doc, fromVersion), _v: targetVersion };
+  }
+  function validateRead(doc) {
+    if (!validateOnRead || !schema) return doc;
     try {
       return schema.parse(doc);
     } catch (err) {
       throw new TalaDbValidationError(err, "read");
     }
   }
+  async function persistAll(originals, migrated) {
+    if (!persistMigrations) return;
+    for (let i = 0; i < originals.length; i++) {
+      const original = originals[i];
+      if (migrated[i] === original || typeof original._id !== "string") continue;
+      const update = diffUpdate(original, migrated[i]);
+      if (!update) continue;
+      try {
+        await col.updateOne({ _id: original._id }, update);
+      } catch {
+      }
+    }
+  }
+  const wrapReads = Boolean(migrateDocument) || validateOnRead && Boolean(schema);
+  const wrapWrites = Boolean(schema) || stampVersion;
   return {
     ...col,
-    insert: async (doc) => {
-      parseWrite(doc, "insert");
-      return col.insert(doc);
-    },
-    insertMany: async (docs) => {
-      docs.forEach((doc, i) => parseWrite(doc, `insertMany[${i}]`));
-      return col.insertMany(docs);
-    },
-    find: validateOnRead ? async (filter) => {
+    insert: wrapWrites ? async (doc) => {
+      if (schema) parseWrite(doc, "insert");
+      return col.insert(stamp(doc));
+    } : col.insert.bind(col),
+    insertMany: wrapWrites ? async (docs) => {
+      if (schema) docs.forEach((doc, i) => parseWrite(doc, `insertMany[${i}]`));
+      return col.insertMany(docs.map(stamp));
+    } : col.insertMany.bind(col),
+    find: wrapReads ? async (filter) => {
       const docs = await col.find(filter);
-      return docs.map((d) => parseRead(d));
+      const migrated = docs.map(migrateRead);
+      await persistAll(docs, migrated);
+      return migrated.map(validateRead);
     } : col.find.bind(col),
-    findOne: validateOnRead ? async (filter) => {
+    findOne: wrapReads ? async (filter) => {
       const doc = await col.findOne(filter);
-      return doc === null ? null : parseRead(doc);
-    } : col.findOne.bind(col)
+      if (doc === null) return null;
+      const migrated = migrateRead(doc);
+      await persistAll([doc], [migrated]);
+      return validateRead(migrated);
+    } : col.findOne.bind(col),
+    // Live queries feed every @taladb/react hook (useFind, useFindOne,
+    // useQueries). Leaving them unwrapped meant React components received the
+    // un-migrated shape while a direct find() returned the migrated one.
+    subscribe: wrapReads ? (filter, callback, onError) => col.subscribe(
+      filter,
+      (docs) => {
+        const migrated = docs.map(migrateRead);
+        let out;
+        try {
+          out = migrated.map(validateRead);
+        } catch (err) {
+          onError?.(err);
+          return;
+        }
+        callback(out);
+        void persistAll(docs, migrated);
+      },
+      onError
+    ) : col.subscribe.bind(col)
   };
 }
 function detectPlatform() {
@@ -250,7 +354,7 @@ function makePoller(findFn, callback, onError) {
     active = false;
   };
 }
-async function createBrowserDB(dbName, config, passphrase) {
+async function createBrowserDB(dbName, config, passphrase, migrations) {
   const workerUrl = new URL("@taladb/web/worker/taladb.worker.js", import.meta.url);
   const worker = new Worker(workerUrl, { type: "module", name: "taladb" });
   const proxy = new WorkerProxy(worker);
@@ -275,7 +379,9 @@ async function createBrowserDB(dbName, config, passphrase) {
       }
     };
   }
+  const syncSchemas = {};
   function wrapCollection(name, opts) {
+    if (opts?.syncSchema) syncSchemas[name] = opts.syncSchema;
     const s = JSON.stringify;
     const wrapped = {
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
@@ -413,6 +519,9 @@ async function createBrowserDB(dbName, config, passphrase) {
   const handle = {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: () => proxy.send("compact"),
+    flush: async () => {
+      await proxy.send("flush");
+    },
     syncStatus: async () => JSON.parse(await proxy.send("syncStatus")),
     flushSync: (timeoutMs = 5e3) => proxy.send("flushSync", { timeoutMs }),
     close: async () => {
@@ -428,18 +537,32 @@ async function createBrowserDB(dbName, config, passphrase) {
     // main thread — a sync pass never blocks rendering, whatever its size.
     exportChanges: (collections, sinceMs) => proxy.send("exportChangeset", { collectionsJson: JSON.stringify(collections), sinceMs }),
     importChanges: (changeset) => proxy.send("importChangeset", { changesetJson: changeset }),
+    importChangesValidated: async (changeset, schemasJson) => JSON.parse(await proxy.send("importChangesetValidated", { changesetJson: changeset, schemasJson })),
     listCollectionNames: async () => JSON.parse(await proxy.send("listCollections")),
-    sync: (adapter, options) => runSync(handle, adapter, options)
+    quarantined: async (collection) => JSON.parse(await proxy.send("quarantined", { collection })),
+    sync: (adapter, options) => runSync(handle, adapter, options, syncSchemas)
   };
+  if (migrations?.length) {
+    await runMigrations(
+      handle,
+      async () => proxy.send("userVersion"),
+      async (v) => {
+        await proxy.send("setUserVersion", { version: v });
+      },
+      migrations
+    );
+  }
   return handle;
 }
-async function createNodeDB(dbName, config, passphrase) {
+async function createNodeDB(dbName, config, passphrase, migrations) {
   const native = await import("./node-A4LKRSW5.mjs");
   const TalaDBNode = native.TalaDbNode ?? native.TalaDBNode;
   if (!TalaDBNode) throw new Error("@taladb/node loaded but exports no TalaDbNode class \u2014 rebuild the native module");
   const configJson = config !== void 0 ? JSON.stringify(config) : null;
   const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
+  const syncSchemas = {};
   function wrapCollection(name, opts) {
+    if (opts?.syncSchema) syncSchemas[name] = opts.syncSchema;
     const col = db.collection(name);
     const wrapped = {
       insert: async (doc) => col.insertAsync ? col.insertAsync(doc) : col.insert(doc),
@@ -478,14 +601,32 @@ async function createNodeDB(dbName, config, passphrase) {
     compact: async () => db.compact(),
     // Releases the native file handle/lock (no-op on older .node binaries).
     close: async () => db.close?.(),
+    flush: db.flush ? async () => {
+      db.flush();
+    } : void 0,
     exportChanges: async (collections, sinceMs) => db.exportChanges(sinceMs, collections),
     importChanges: async (changeset) => db.importChanges(changeset),
+    // Feature-detected: only present when the loaded .node binary supports it,
+    // so older prebuilt binaries fall back to plain importChanges.
+    importChangesValidated: db.importChangesValidated ? async (changeset, schemasJson) => db.importChangesValidated(changeset, schemasJson) : void 0,
     listCollectionNames: async () => db.listCollectionNames(),
-    sync: (adapter, options) => runSync(handle, adapter, options)
+    quarantined: async (collection) => db.quarantined ? db.quarantined(collection) : [],
+    sync: (adapter, options) => runSync(handle, adapter, options, syncSchemas)
   };
+  if (migrations?.length) {
+    if (typeof db.userVersion !== "function" || typeof db.setUserVersion !== "function") {
+      throw new Error("openDB({ migrations }) requires @taladb/node \u2265 0.9.2 \u2014 rebuild the native module");
+    }
+    await runMigrations(
+      handle,
+      async () => db.userVersion(),
+      async (v) => db.setUserVersion(v),
+      migrations
+    );
+  }
   return handle;
 }
-async function createNativeDB(_dbName) {
+async function createNativeDB(_dbName, migrations) {
   const maybeNative = globalThis.__TalaDB__;
   if (!maybeNative) {
     throw new Error(
@@ -493,7 +634,9 @@ async function createNativeDB(_dbName) {
     );
   }
   const native = maybeNative;
+  const syncSchemas = {};
   function wrapCollection(name, opts) {
+    if (opts?.syncSchema) syncSchemas[name] = opts.syncSchema;
     const wrapped = {
       insert: async (doc) => native.insert(name, doc),
       insertMany: async (docs) => native.insertMany(name, docs),
@@ -533,25 +676,64 @@ async function createNativeDB(_dbName) {
     return opts ? applySchema(wrapped, opts) : wrapped;
   }
   const syncSurface = typeof native.exportChanges === "function" && typeof native.importChanges === "function" && typeof native.listCollectionNames === "function" ? (() => {
-    const handle = {
+    const handle2 = {
       collection: (name, opts) => wrapCollection(name, opts),
       exportChanges: async (collections, sinceMs) => native.exportChanges(collections, sinceMs),
       importChanges: async (changeset) => native.importChanges(changeset),
+      // Feature-detected: present on 0.9.2+ JSI HostObjects; when absent,
+      // runSync falls back to unvalidated importChanges.
+      importChangesValidated: native.importChangesValidated ? async (changeset, schemasJson) => native.importChangesValidated(changeset, schemasJson) : void 0,
       listCollectionNames: async () => native.listCollectionNames(),
-      sync: (adapter, options) => runSync(handle, adapter, options)
+      sync: (adapter, options) => runSync(handle2, adapter, options, syncSchemas)
     };
     return {
-      exportChanges: handle.exportChanges,
-      importChanges: handle.importChanges,
-      sync: handle.sync
+      exportChanges: handle2.exportChanges,
+      importChanges: handle2.importChanges,
+      sync: handle2.sync
     };
   })() : unsupportedSync("react-native");
-  return {
+  const handle = {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => native.compact(),
     close: async () => native.close(),
+    flush: native.flush ? async () => {
+      native.flush();
+    } : void 0,
+    quarantined: native.quarantined ? async (collection) => native.quarantined(collection) : void 0,
     ...syncSurface
   };
+  if (migrations?.length) {
+    if (typeof native.userVersion !== "function" || typeof native.setUserVersion !== "function") {
+      throw new Error(
+        "openDB({ migrations }) is not available on this @taladb/react-native binary yet (the JSI HostObject does not expose userVersion/setUserVersion). Update the native module."
+      );
+    }
+    await runMigrations(
+      handle,
+      async () => native.userVersion(),
+      async (v) => native.setUserVersion(v),
+      migrations
+    );
+  }
+  return handle;
+}
+async function runMigrations(db, getVersion, setVersion, migrations) {
+  const sorted = [...migrations].sort((a, b) => a.version - b.version);
+  for (let i = 0; i < sorted.length; i++) {
+    const v = sorted[i].version;
+    if (!Number.isInteger(v) || v < 1) {
+      throw new Error(`TalaDB migration version must be a positive integer, got ${v}`);
+    }
+    if (i > 0 && v === sorted[i - 1].version) {
+      throw new Error(`TalaDB duplicate migration version ${v}`);
+    }
+  }
+  const current = await getVersion();
+  for (const m of sorted) {
+    if (m.version <= current) continue;
+    await m.up(db);
+    await setVersion(m.version);
+  }
 }
 async function openDB(dbName = "taladb.db", options) {
   if (options?.passphrase !== void 0 && options.passphrase.length === 0) {
@@ -564,21 +746,30 @@ async function openDB(dbName = "taladb.db", options) {
   } else {
     resolvedConfig = await loadConfig(options?.configPath);
   }
+  if (options?.durability) {
+    resolvedConfig = {
+      ...resolvedConfig,
+      durability: { ...resolvedConfig?.durability, ...options.durability }
+    };
+  }
   const platform = detectPlatform();
+  const migrations = options?.migrations;
   switch (platform) {
     case "browser":
-      return createBrowserDB(dbName, resolvedConfig, options?.passphrase);
+      return createBrowserDB(dbName, resolvedConfig, options?.passphrase, migrations);
     case "react-native":
       if (options?.passphrase !== void 0) {
         throw new Error("On React Native, pass the passphrase in the config JSON to TalaDBModule.initialize(); refusing to assume the already-open native database is encrypted");
       }
-      return createNativeDB(dbName);
+      return createNativeDB(dbName, migrations);
     case "node":
-      return createNodeDB(dbName, resolvedConfig, options?.passphrase);
+      return createNodeDB(dbName, resolvedConfig, options?.passphrase, migrations);
   }
 }
 export {
   HttpSyncAdapter,
   TalaDbValidationError,
-  openDB
+  applySchema,
+  openDB,
+  runMigrations
 };

package/dist/index.d.mts

@@ -96,6 +96,57 @@ type Update<T extends Document = Document> = {
 interface Schema<T> {
     parse(data: unknown): T;
 }
+/** Primitive field type for a {@link SyncSchema}. `'any'` requires presence
+ * without constraining the value's type. */
+type SyncFieldType = 'bool' | 'int' | 'float' | 'str' | 'bytes' | 'array' | 'object' | 'any';
+/**
+ * A tolerant, structural schema applied to documents **arriving via sync**
+ * (`db.sync()` pull). Distinct from {@link Schema} (Zod/Valibot), which is
+ * strict and runs on the *local* `insert` path: sync import is the boundary you
+ * don't control, so it validates structurally and never hard-rejects.
+ *
+ * On import, per document:
+ * - `_v` **below** `version` → upgraded in place (missing `defaults` filled,
+ *   `_v` stamped) — additive-only migration.
+ * - `_v` **above** `version` → accepted untouched (the peer is ahead).
+ * - a missing/`null` `required` field or a `types` mismatch → **quarantined**
+ *   (set aside, recoverable via {@link TalaDB.quarantined}), never dropped and
+ *   never aborting the batch.
+ *
+ * @example
+ * const users = db.collection<User>('users', {
+ *   schema: User,                     // strict, on insert
+ *   syncSchema: {                     // tolerant, on import
+ *     version: 1,
+ *     required: ['name'],
+ *     types: { name: 'str', age: 'int' },
+ *     defaults: { age: 0 },
+ *   },
+ * });
+ */
+interface SyncSchema {
+    /**
+     * Current document shape version. Omit or `0` to disable the migration step
+     * entirely — in which case {@link renames} and {@link defaults} never run, so
+     * declaring either without a `version` is rejected at `db.collection()` rather
+     * than silently quarantining the documents they were meant to upgrade.
+     */
+    version?: number;
+    /** Fields that must be present and non-null, or the document is quarantined. */
+    required?: string[];
+    /** Expected primitive type per field. Fields absent here accept any type. */
+    types?: Record<string, SyncFieldType>;
+    /** Values applied to missing fields when upgrading a below-`version` document. */
+    defaults?: Record<string, Value>;
+    /**
+     * Field renames applied when upgrading a below-`version` document, as
+     * `{ oldName: newName }`. If the old field is present and the new one absent,
+     * the value moves. Applied before {@link defaults}. Structural (runs in the
+     * engine at import) — for renames that need computation, use
+     * {@link CollectionOptions.migrateDocument}.
+     */
+    renames?: Record<string, string>;
+}
 /** Options passed to `db.collection()`. */
 interface CollectionOptions<T extends Document = Document> {
     /**
@@ -113,6 +164,53 @@ interface CollectionOptions<T extends Document = Document> {
      * Defaults to `false`.
      */
     validateOnRead?: boolean;
+    /**
+     * Tolerant structural schema applied to documents arriving via `db.sync()`.
+     * See {@link SyncSchema}. Enables validate-on-import ("validate, never cast")
+     * in the core sync path, with `_v` migration and quarantine of bad shapes.
+     * Wired on browser (OPFS worker), Node.js, and React Native; a binding whose
+     * native module predates 0.9.2 falls back to unvalidated import.
+     *
+     * Declaring a `version` also makes locally-inserted documents carry that `_v`,
+     * so they are never mistaken for legacy documents on read.
+     */
+    syncSchema?: SyncSchema;
+    /**
+     * Lazy, read-time document migration — the arbitrary-JS complement to the
+     * structural {@link SyncSchema}. When set, every document returned by `find`
+     * / `findOne` whose `_v` is **below** `syncSchema.version` is passed through
+     * `migrateDocument(doc, fromVersion)` and stamped to the current version
+     * before you see it, so application code always reads the current shape even
+     * for documents that predate the schema (renames, computed/derived fields,
+     * splits/merges). Runs on **every runtime** (it's a pure read transform in
+     * the client — no binding support needed).
+     *
+     * Requires `syncSchema.version` (the migration target). The transform is
+     * applied to the returned value only; it is not persisted back to storage —
+     * pair with `openDB({ migrations })` or a `syncSchema` rename to rewrite
+     * stored documents eagerly. Must be pure and deterministic.
+     *
+     * @example
+     * const users = db.collection<User>('users', {
+     *   syncSchema: { version: 2 },
+     *   migrateDocument: (doc, from) =>
+     *     from < 2 ? { ...doc, fullName: `${doc.first} ${doc.last}` } : doc,
+     * });
+     */
+    migrateDocument?: (doc: T, fromVersion: number) => T;
+    /**
+     * When `true`, a document upgraded by {@link migrateDocument} on read is
+     * **written back** to storage (a best-effort `updateOne` computing the
+     * `$set`/`$unset` diff) so the migration becomes permanent — after which
+     * filters and indexes on the new shape match it. Default `false` (the
+     * migrated shape is returned but not persisted).
+     *
+     * Trade-offs: reads that encounter un-migrated documents now issue writes
+     * (which fire live-query and sync-hook notifications like any other write);
+     * a failed write is swallowed and simply retried on the next read. For a
+     * one-shot eager rewrite instead, prefer `openDB({ migrations })`.
+     */
+    persistMigrations?: boolean;
 }
 /** A single MongoDB-style aggregation stage. */
 type AggregateStage<T extends Document = Document> = {
@@ -296,9 +394,30 @@ interface SyncResult {
     pushed: number;
     /** Number of documents changed locally by the pulled remote changeset. */
     pulled: number;
+    /**
+     * Documents in the pulled changeset skipped by an import validator (a
+     * collection this client does not model). Always `0` when no `syncSchema`
+     * applied to the pass.
+     */
+    skipped?: number;
+    /**
+     * Documents in the pulled changeset set aside by an import validator because
+     * they failed structural validation. Recoverable via {@link TalaDB.quarantined}.
+     * Always `0` when no `syncSchema` applied to the pass.
+     */
+    quarantined?: number;
     /** Active sync cursor. Currently `0` because timestamp adapters replay safely. */
     cursor: number;
 }
+/** A document set aside during a validated sync import, with its rejection reason. */
+interface QuarantinedDocument<T extends Document = Document> {
+    /** The rejected document, retained verbatim. */
+    document: T;
+    /** Human-readable reason the document was quarantined. */
+    reason: string;
+    /** The `changed_at` (ms epoch) the rejected change carried. */
+    changedAt: number;
+}
 interface TalaDB {
     collection<T extends Document = Document>(name: string, options?: CollectionOptions<T>): Collection<T>;
     /**
@@ -334,6 +453,20 @@ interface TalaDB {
      * await db.compact();
      */
     compact(): Promise<void>;
+    /**
+     * Return the documents set aside in `collection`'s quarantine table by a
+     * validated sync import (see {@link SyncSchema}). Empty when nothing was
+     * quarantined. Wired on browser and Node.js; resolves to `[]` on runtimes
+     * without support.
+     */
+    quarantined?<T extends Document = Document>(collection: string): Promise<QuarantinedDocument<T>[]>;
+    /**
+     * Force any batched (eventual-durability) writes to durable storage, and on
+     * the browser also write the IndexedDB fallback snapshot immediately. A
+     * no-op under the default `flush_every_write: true` durability. Use for
+     * "save now" moments (before checkout, on `visibilitychange`).
+     */
+    flush?(): Promise<void>;
     /** Browser HTTP-push queue health, when supported by the active binding. */
     syncStatus?(): Promise<{
         pending: number;
@@ -377,10 +510,28 @@ interface SyncConfig {
      */
     exclude_fields?: string[];
 }
+/** Storage durability settings. */
+interface DurabilityConfig {
+    /**
+     * When `true` (default), every write commit is fsync'd immediately — a crash
+     * never loses an acknowledged write. When `false`, commits are batched for
+     * higher write throughput; call `db.flush()` to force a durable sync. Applies
+     * to Node (file) and browser OPFS storage; in-memory ignores it.
+     */
+    flush_every_write?: boolean;
+    /**
+     * Browser IndexedDB-fallback snapshot debounce, in milliseconds (default
+     * 500). Only affects the non-OPFS browser fallback path — the OPFS and Node
+     * paths use `flush_every_write`.
+     */
+    flush_ms?: number;
+}
 /** Top-level TalaDB configuration. */
 interface TalaDbConfig {
     /** HTTP push sync configuration. Disabled by default. */
     sync?: SyncConfig;
+    /** Storage durability configuration. */
+    durability?: DurabilityConfig;
 }
 
 interface HttpSyncAdapterOptions {
@@ -430,11 +581,70 @@ declare class TalaDbValidationError extends Error {
     readonly cause: unknown;
     constructor(cause: unknown, context?: string);
 }
+/**
+ * Wraps a `Collection<T>` to intercept writes through a schema validator
+ * (`schema`), stamp `_v` on insert when a `syncSchema.version` is declared, and
+ * normalize reads through a lazy `migrateDocument`. Returns the collection
+ * unchanged when none of those apply.
+ *
+ * Read normalization covers `find`, `findOne`, and `subscribe` (live queries).
+ * It cannot cover `aggregate`, `findNearest`, or FTS `search`: those run inside
+ * the engine against the *stored* shape, so a below-version document is matched
+ * and projected as it sits on disk. Use `persistMigrations` or
+ * `openDB({ migrations })` to rewrite storage if you query old documents that way.
+ *
+ * @internal Exported for unit testing; not part of the public API surface.
+ */
+declare function applySchema<T extends Document>(col: Collection<T>, options: CollectionOptions<T>): Collection<T>;
 
+/**
+ * A single application schema migration, run once at `openDB` when its
+ * `version` is greater than the database's stored migration version.
+ */
+interface Migration {
+    /** Monotonic version. Must be a positive integer, unique across the array. */
+    version: number;
+    /** Optional human-readable label for logs. */
+    description?: string;
+    /**
+     * The migration body. Receives the open database and may use the full
+     * collection API. Runs to completion before the version is advanced.
+     *
+     * **Write migrations idempotently.** TalaDB checkpoints per version (the
+     * stored version advances only after `up` fully resolves), but a single `up`
+     * is not wrapped in one atomic transaction — if it throws partway, the writes
+     * it already made persist and `up` re-runs from the start on the next open.
+     */
+    up: (db: TalaDB) => Promise<void> | void;
+}
+/**
+ * Runtime-agnostic migration runner. Each binding supplies `getVersion` /
+ * `setVersion` (its own persisted counter); the loop is identical everywhere.
+ *
+ * Runs pending migrations (`version` > stored) in ascending order, advancing
+ * the stored version after each `up` resolves — checkpoint per version. If an
+ * `up` throws, the loop stops and the error propagates; the stored version
+ * reflects the last fully-applied migration, so the next open resumes there.
+ *
+ * @internal Exported for unit testing; not part of the public API surface.
+ */
+declare function runMigrations(db: TalaDB, getVersion: () => Promise<number>, setVersion: (v: number) => Promise<void>, migrations: Migration[]): Promise<void>;
 /** Options for `openDB`. */
 interface OpenDBOptions {
     /** Encrypt native database values at rest. Never hard-code this value. */
     passphrase?: string;
+    /**
+     * Ordered application schema migrations, run once each at open in ascending
+     * `version` order (only those newer than the stored migration version). The
+     * stored version advances after each migration succeeds — checkpoint per
+     * version, resuming from the last applied one on the next open.
+     *
+     * Supported on Node.js, the browser (via the OPFS worker), and React Native.
+     * On a binding whose native module predates 0.9.2 (no `userVersion` /
+     * `setUserVersion`), `openDB` throws rather than silently skipping the
+     * migrations — rebuild or update the native module.
+     */
+    migrations?: Migration[];
     /**
      * Explicit path to a `taladb.config.yml` / `taladb.config.json` file.
      * If omitted, TalaDB auto-discovers the file from `process.cwd()` on Node.js.
@@ -448,6 +658,14 @@ interface OpenDBOptions {
      * Useful for passing config programmatically without a config file on disk.
      */
     config?: TalaDbConfig;
+    /**
+     * Storage durability, e.g. `{ flush_every_write: false }` to batch commits
+     * for write throughput (call `db.flush()` to force a sync), or `{ flush_ms }`
+     * to tune the browser IndexedDB-fallback snapshot debounce. Merged into
+     * `config.durability`. Node + browser; on React Native pass it in the config
+     * JSON to `TalaDBModule.initialize`.
+     */
+    durability?: DurabilityConfig;
 }
 /**
  * Open a TalaDB database.
@@ -466,4 +684,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type Filter, HttpSyncAdapter, type OpenDBOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };
+export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, HttpSyncAdapter, type Migration, type OpenDBOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, applySchema, openDB, runMigrations };