@monlite/core 0.3.0 → 0.6.0

package/dist/index.cjs

@@ -22,23 +22,73 @@ function isObjectId(value) {
 
 // src/errors.ts
 var MonliteError = class extends Error {
-  constructor(message) {
+  constructor(message, options) {
     super(message);
     this.name = "MonliteError";
+    if (options?.cause !== void 0) this.cause = options.cause;
   }
 };
 var MonliteQueryError = class extends MonliteError {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     this.name = "MonliteQueryError";
   }
 };
+var MonliteConstraintError = class extends MonliteError {
+  collection;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteConstraintError";
+    this.collection = options?.collection;
+  }
+};
+var MonliteUniqueConstraintError = class extends MonliteConstraintError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteUniqueConstraintError";
+  }
+};
+var MonliteNotNullError = class extends MonliteConstraintError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteNotNullError";
+  }
+};
+var MonliteForeignKeyError = class extends MonliteConstraintError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteForeignKeyError";
+  }
+};
+function normalizeDriverError(err, collection) {
+  if (err instanceof MonliteError) return err;
+  const code = err?.code ? String(err.code) : "";
+  const message = err instanceof Error ? err.message : String(err);
+  const blob = `${code} ${message}`;
+  const opts = { cause: err, collection };
+  if (/UNIQUE|PRIMARY KEY|constraint failed: .*\.(?:_id)\b/i.test(blob)) {
+    return new MonliteUniqueConstraintError(message, opts);
+  }
+  if (/NOT ?NULL/i.test(blob)) {
+    return new MonliteNotNullError(message, opts);
+  }
+  if (/FOREIGN ?KEY/i.test(blob)) {
+    return new MonliteForeignKeyError(message, opts);
+  }
+  if (/CONSTRAINT/i.test(blob)) {
+    return new MonliteConstraintError(message, opts);
+  }
+  return new MonliteError(message, { cause: err });
+}
 
 // src/query/sql.ts
 var RESERVED_FIELDS = /* @__PURE__ */ new Set(["_id", "created_at", "updated_at"]);
 function isReserved(field) {
   return RESERVED_FIELDS.has(field);
 }
+function isColumn(field, columns) {
+  return isReserved(field) || (columns?.has(field) ?? false);
+}
 function jsonPath(field) {
   let path = "$";
   for (const seg of field.split(".")) {
@@ -55,10 +105,13 @@ function jsonPath(field) {
 function pathLiteral(field) {
   return "'" + jsonPath(field).replace(/'/g, "''") + "'";
 }
-function fieldExpr(field) {
-  if (isReserved(field)) return `"${field}"`;
+function fieldExpr(field, columns) {
+  if (isColumn(field, columns)) return quoteIdent(field);
   return `json_extract(data, ${pathLiteral(field)})`;
 }
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
 function bindable(value) {
   if (value === void 0 || value === null) return null;
   if (typeof value === "boolean") return value ? 1 : 0;
@@ -103,16 +156,17 @@ function isFilterObject(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date) && !Buffer.isBuffer(v) && (v.constructor === Object || v.constructor === void 0);
 }
 function translateField(field, condition, ctx) {
-  if (ctx.onPath && !isReserved(field)) ctx.onPath(field);
-  const expr = fieldExpr(field);
+  if (ctx.onPath && !isColumn(field, ctx.columns)) ctx.onPath(field);
+  const expr = fieldExpr(field, ctx.columns);
   if (!isFilterObject(condition)) {
     return eqExpr(expr, condition, ctx);
   }
   const filter = condition;
+  const ci = filter.mode === "insensitive";
   const clauses = [];
   for (const op of Object.keys(filter)) {
     const v = filter[op];
-    if (v === void 0) continue;
+    if (v === void 0 || op === "mode") continue;
     switch (op) {
       case "equals":
         clauses.push(eqExpr(expr, v, ctx));
@@ -139,22 +193,26 @@ function translateField(field, condition, ctx) {
         clauses.push(inExpr(expr, v, ctx, true));
         break;
       case "contains":
-        clauses.push(containsExpr(field, expr, v, ctx));
+        clauses.push(containsExpr(field, expr, v, ctx, ci));
         break;
       case "startsWith":
         ctx.params.push(bindable(v));
-        clauses.push(`instr(${expr}, ?) = 1`);
+        clauses.push(
+          ci ? `instr(lower(${expr}), lower(?)) = 1` : `instr(${expr}, ?) = 1`
+        );
         break;
       case "endsWith":
         ctx.params.push(bindable(v));
         ctx.params.push(bindable(v));
-        clauses.push(`substr(${expr}, -length(?)) = ?`);
+        clauses.push(
+          ci ? `substr(lower(${expr}), -length(?)) = lower(?)` : `substr(${expr}, -length(?)) = ?`
+        );
         break;
       case "has":
         clauses.push(hasExpr(field, expr, v, ctx));
         break;
       case "exists":
-        clauses.push(existsExpr(field, expr, !!v));
+        clauses.push(existsExpr(field, expr, !!v, ctx.columns));
         break;
       default:
         throw new MonliteQueryError(
@@ -192,23 +250,25 @@ function inExpr(expr, arr, ctx, negate) {
   }).join(", ");
   return negate ? `(${expr} IS NULL OR ${expr} NOT IN (${placeholders}))` : `${expr} IN (${placeholders})`;
 }
-function containsExpr(field, expr, v, ctx) {
-  if (isReserved(field)) {
+function containsExpr(field, expr, v, ctx, ci) {
+  const sub = ci ? `instr(lower(${expr}), lower(?)) > 0` : `instr(${expr}, ?) > 0`;
+  if (isColumn(field, ctx.columns)) {
     ctx.params.push(bindable(v));
-    return `instr(${expr}, ?) > 0`;
+    return sub;
   }
   const path = pathLiteral(field);
+  const member = ci ? `lower(value) = lower(?)` : `value = ?`;
   ctx.params.push(bindable(v));
   ctx.params.push(bindable(v));
-  return `(CASE WHEN json_type(data, ${path}) = 'array' THEN EXISTS (SELECT 1 FROM json_each(data, ${path}) WHERE value = ?) ELSE instr(${expr}, ?) > 0 END)`;
+  return `(CASE WHEN json_type(data, ${path}) = 'array' THEN EXISTS (SELECT 1 FROM json_each(data, ${path}) WHERE ${member}) ELSE ${sub} END)`;
 }
 function hasExpr(field, expr, v, ctx) {
   ctx.params.push(bindable(v));
-  if (isReserved(field)) return `${expr} = ?`;
+  if (isColumn(field, ctx.columns)) return `${expr} = ?`;
   return `EXISTS (SELECT 1 FROM json_each(data, ${pathLiteral(field)}) WHERE value = ?)`;
 }
-function existsExpr(field, expr, want) {
-  if (isReserved(field)) {
+function existsExpr(field, expr, want, columns) {
+  if (isColumn(field, columns)) {
     return want ? `${expr} IS NOT NULL` : `${expr} IS NULL`;
   }
   const path = pathLiteral(field);
@@ -216,7 +276,7 @@ function existsExpr(field, expr, want) {
 }
 
 // src/query/order.ts
-function buildOrderBy(orderBy, onPath) {
+function buildOrderBy(orderBy, onPath, columns) {
   if (!orderBy) return "";
   const list = Array.isArray(orderBy) ? orderBy : [orderBy];
   const parts = [];
@@ -224,25 +284,35 @@ function buildOrderBy(orderBy, onPath) {
     for (const field of Object.keys(obj)) {
       const dir = obj[field];
       if (dir === void 0) continue;
-      if (onPath && !isReserved(field)) onPath(field);
+      if (onPath && !isColumn(field, columns)) onPath(field);
       const d = String(dir).toLowerCase() === "desc" ? "DESC" : "ASC";
-      parts.push(`${fieldExpr(field)} ${d}`);
+      parts.push(`${fieldExpr(field, columns)} ${d}`);
     }
   }
   return parts.length ? "ORDER BY " + parts.join(", ") : "";
 }
 
 // src/query/path.ts
+var FORBIDDEN = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function safeSegments(path) {
+  const segs = path.split(".");
+  for (const seg of segs) {
+    if (FORBIDDEN.has(seg)) {
+      throw new MonliteQueryError(`Illegal path segment "${seg}" in "${path}"`);
+    }
+  }
+  return segs;
+}
 function getPath(obj, path) {
   let cur = obj;
-  for (const seg of path.split(".")) {
+  for (const seg of safeSegments(path)) {
     if (cur == null) return void 0;
     cur = cur[seg];
   }
   return cur;
 }
 function setPath(obj, path, value) {
-  const segs = path.split(".");
+  const segs = safeSegments(path);
   let cur = obj;
   for (let i = 0; i < segs.length - 1; i++) {
     const seg = segs[i];
@@ -252,7 +322,7 @@ function setPath(obj, path, value) {
   cur[segs[segs.length - 1]] = value;
 }
 function unsetPath(obj, path) {
-  const segs = path.split(".");
+  const segs = safeSegments(path);
   let cur = obj;
   for (let i = 0; i < segs.length - 1; i++) {
     const seg = segs[i];
@@ -305,8 +375,13 @@ function applyUpdate(doc, data) {
   }
   if (ops.$inc) {
     for (const [path, by] of Object.entries(ops.$inc)) {
+      if (typeof by !== "number" || !Number.isFinite(by)) {
+        throw new MonliteQueryError(
+          `$inc on "${path}" requires a finite number, got ${JSON.stringify(by)}`
+        );
+      }
       const cur = getPath(next, path);
-      setPath(next, path, (typeof cur === "number" ? cur : 0) + Number(by));
+      setPath(next, path, (typeof cur === "number" ? cur : 0) + by);
     }
   }
   if (ops.$push) {
@@ -347,7 +422,7 @@ var SQL_FN = {
   _min: "MIN",
   _max: "MAX"
 };
-function buildAccumulators(args, onPath) {
+function buildAccumulators(args, onPath, columns) {
   const selects = [];
   const cols = [];
   let i = 0;
@@ -356,9 +431,9 @@ function buildAccumulators(args, onPath) {
     if (!selection) continue;
     for (const field of Object.keys(selection)) {
       if (!selection[field]) continue;
-      onPath(field);
+      if (!isColumn(field, columns)) onPath(field);
       const alias = `agg_${kind.slice(1)}_${i++}`;
-      selects.push(`${SQL_FN[kind]}(${fieldExpr(field)}) AS ${alias}`);
+      selects.push(`${SQL_FN[kind]}(${fieldExpr(field, columns)}) AS ${alias}`);
       cols.push({ alias, kind, field });
     }
   }
@@ -366,8 +441,12 @@ function buildAccumulators(args, onPath) {
 }
 function aggregate(ctx, args) {
   const params = [];
-  const where = buildWhere(args.where, { params, onPath: ctx.onPath });
-  const { selects, cols } = buildAccumulators(args, ctx.onPath);
+  const where = buildWhere(args.where, {
+    params,
+    onPath: ctx.onPath,
+    columns: ctx.columns
+  });
+  const { selects, cols } = buildAccumulators(args, ctx.onPath, ctx.columns);
   const allSelects = [`COUNT(*) AS agg_count`, ...selects];
   const sql = `SELECT ${allSelects.join(", ")} FROM "${ctx.table}" WHERE ${where}`;
   const row = ctx.db.prepare(sql).get(...params) ?? {};
@@ -403,7 +482,7 @@ function comparisonSql(expr, cmp2, params) {
   }
   return out;
 }
-function buildHaving(having, params) {
+function buildHaving(having, params, columns) {
   const parts = [];
   if (having._count) {
     parts.push(...comparisonSql("COUNT(*)", having._count, params));
@@ -412,31 +491,40 @@ function buildHaving(having, params) {
     const selection = having[kind];
     if (!selection) continue;
     for (const field of Object.keys(selection)) {
-      parts.push(...comparisonSql(`${fn}(${fieldExpr(field)})`, selection[field], params));
+      parts.push(
+        ...comparisonSql(`${fn}(${fieldExpr(field, columns)})`, selection[field], params)
+      );
     }
   }
   return parts.join(" AND ");
 }
 function groupBy(ctx, args) {
   if (!Array.isArray(args.by) || args.by.length === 0) {
-    throw new Error("groupBy requires a non-empty `by` array");
+    throw new MonliteQueryError("groupBy requires a non-empty `by` array");
   }
   const params = [];
-  const where = buildWhere(args.where, { params, onPath: ctx.onPath });
+  const where = buildWhere(args.where, {
+    params,
+    onPath: ctx.onPath,
+    columns: ctx.columns
+  });
   const groupExprs = [];
+  const groupCols = [];
   const selects = [];
-  for (const field of args.by) {
-    ctx.onPath(field);
-    const expr = fieldExpr(field);
+  args.by.forEach((field, gi) => {
+    if (!isColumn(field, ctx.columns)) ctx.onPath(field);
+    const expr = fieldExpr(field, ctx.columns);
+    const alias = `grp_${gi}`;
     groupExprs.push(expr);
-    selects.push(`${expr} AS "${field}"`);
-  }
+    selects.push(`${expr} AS ${alias}`);
+    groupCols.push({ alias, field });
+  });
   selects.push(`COUNT(*) AS agg_count`);
-  const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath);
+  const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath, ctx.columns);
   selects.push(...accSelects);
   let sql = `SELECT ${selects.join(", ")} FROM "${ctx.table}" WHERE ${where} GROUP BY ${groupExprs.join(", ")}`;
   if (args.having) {
-    const havingSql = buildHaving(args.having, params);
+    const havingSql = buildHaving(args.having, params, ctx.columns);
     if (havingSql) sql += ` HAVING ${havingSql}`;
   }
   if (args.orderBy) {
@@ -444,7 +532,7 @@ function groupBy(ctx, args) {
     for (const key of Object.keys(args.orderBy)) {
       const dir = String(args.orderBy[key]).toLowerCase() === "desc" ? "DESC" : "ASC";
       if (key === "_count") parts.push(`agg_count ${dir}`);
-      else parts.push(`${fieldExpr(key)} ${dir}`);
+      else parts.push(`${fieldExpr(key, ctx.columns)} ${dir}`);
     }
     if (parts.length) sql += ` ORDER BY ${parts.join(", ")}`;
   }
@@ -459,7 +547,7 @@ function groupBy(ctx, args) {
   const rows = ctx.db.prepare(sql).all(...params);
   return rows.map((row) => {
     const out = {};
-    for (const field of args.by) out[field] = row[field];
+    for (const { alias, field } of groupCols) out[field] = row[alias];
     if (args._count) out._count = row.agg_count;
     for (const col of cols) {
       (out[col.kind] ??= {})[col.field] = row[col.alias] ?? null;
@@ -469,82 +557,256 @@ function groupBy(ctx, args) {
 }
 
 // src/collection.ts
-var SELECT_COLS = `_id, data, created_at, updated_at`;
 function stripSystem(obj) {
   const { _id, created_at, updated_at, ...rest } = obj;
   return rest;
 }
+var NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function sqliteType(type) {
+  return type === "JSON" ? "TEXT" : type;
+}
+function formatDefault(value) {
+  if (value === null) return "NULL";
+  if (typeof value === "number") return String(value);
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
 var Collection = class {
-  constructor(mon, name) {
+  constructor(mon, name, options = {}) {
     this.mon = mon;
     this.name = name;
+    this.mode = options.schema ? "structured" : "document";
+    if (options.schema) {
+      for (const [field, def] of Object.entries(options.schema)) {
+        if (!NAME_RE.test(field)) {
+          throw new MonliteError(`Invalid column name "${field}"`);
+        }
+        if (RESERVED_FIELDS.has(field) || field === "data") {
+          throw new MonliteError(
+            `Column "${field}" is reserved by monlite and cannot be declared`
+          );
+        }
+        const normalized = typeof def === "string" ? { type: def } : def;
+        if (normalized.references && !/^[A-Za-z_][A-Za-z0-9_]*(\([A-Za-z_][A-Za-z0-9_]*\))?$/.test(
+          normalized.references
+        )) {
+          throw new MonliteError(
+            `Invalid references "${normalized.references}" on column "${field}"`
+          );
+        }
+        this.columnDefs[field] = normalized;
+        this.columnOrder.push(field);
+        this.columns.add(field);
+        if (normalized.type === "JSON") this.jsonColumns.add(field);
+      }
+    }
   }
   mon;
   name;
+  mode;
   initialized = false;
+  columnDefs = {};
+  columnOrder = [];
+  /** Declared native columns (empty in document mode). */
+  columns = /* @__PURE__ */ new Set();
+  jsonColumns = /* @__PURE__ */ new Set();
+  insertSqlCache;
   trackPath = (path) => this.mon.autoIndexer.track(this.name, path);
   get db() {
     return this.mon.driver;
   }
+  /** Run a DB operation, normalizing driver errors into typed MonliteErrors. */
+  guard(fn) {
+    try {
+      return fn();
+    } catch (err) {
+      throw normalizeDriverError(err, this.name);
+    }
+  }
+  /** Native column names declared for this collection (structured mode). */
+  get columnNames() {
+    return [...this.columnOrder];
+  }
   ensureTable() {
     if (this.initialized) return;
-    this.db.exec(
-      `CREATE TABLE IF NOT EXISTS "${this.name}" (
-        _id        TEXT    PRIMARY KEY,
-        data       TEXT    NOT NULL,
-        created_at INTEGER NOT NULL,
-        updated_at INTEGER NOT NULL
-      )`
-    );
+    if (this.mode === "document") {
+      this.db.exec(
+        `CREATE TABLE IF NOT EXISTS "${this.name}" (
+          _id        TEXT    PRIMARY KEY,
+          data       TEXT    NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )`
+      );
+    } else {
+      const lines = [
+        `_id        TEXT    PRIMARY KEY`,
+        `created_at INTEGER NOT NULL`,
+        `updated_at INTEGER NOT NULL`,
+        `data       TEXT    NOT NULL DEFAULT '{}'`
+      ];
+      for (const field of this.columnOrder) {
+        const def = this.columnDefs[field];
+        let line = `"${field}" ${sqliteType(def.type)}`;
+        if (def.notNull) line += " NOT NULL";
+        if (def.unique) line += " UNIQUE";
+        if (def.default !== void 0) line += ` DEFAULT ${formatDefault(def.default)}`;
+        if (def.references) line += ` REFERENCES ${def.references}`;
+        lines.push(line);
+      }
+      this.db.exec(
+        `CREATE TABLE IF NOT EXISTS "${this.name}" (
+  ${lines.join(",\n  ")}
+)`
+      );
+      for (const field of this.columnOrder) {
+        if (this.columnDefs[field].index) {
+          this.db.exec(
+            `CREATE INDEX IF NOT EXISTS "idx_${this.name}_${field}" ON "${this.name}"("${field}")`
+          );
+        }
+      }
+    }
     this.initialized = true;
   }
+  /* --------------------------- row <-> doc -------------------------- */
   rowToDoc(row) {
-    const doc = JSON.parse(row.data);
+    const doc = this.mode === "document" ? JSON.parse(row.data) : JSON.parse(row.data ?? "{}");
+    if (this.mode === "structured") {
+      for (const field of this.columnOrder) {
+        const value = row[field];
+        if (value === void 0) continue;
+        if (value === null) {
+          doc[field] = null;
+          continue;
+        }
+        doc[field] = this.jsonColumns.has(field) ? JSON.parse(value) : value;
+      }
+    }
     doc._id = row._id;
     doc.created_at = row.created_at;
     doc.updated_at = row.updated_at;
     return doc;
   }
-  prepareInsert(input) {
+  encodeColumn(field, value) {
+    if (this.jsonColumns.has(field)) {
+      return value === void 0 ? null : JSON.stringify(value);
+    }
+    if (value !== null && typeof value === "object" && !(value instanceof Date) && !Buffer.isBuffer(value)) {
+      throw new MonliteQueryError(
+        `Column "${field}" cannot store an object/array. Declare it as { type: "JSON" } to store structured values.`
+      );
+    }
+    return bindable(value);
+  }
+  insertColumns() {
+    return this.mode === "document" ? ["_id", "data", "created_at", "updated_at"] : ["_id", "created_at", "updated_at", "data", ...this.columnOrder];
+  }
+  insertSql() {
+    if (this.insertSqlCache) return this.insertSqlCache;
+    const cols = this.insertColumns();
+    const list = cols.map((c) => `"${c}"`).join(", ");
+    const placeholders = cols.map(() => "?").join(", ");
+    return this.insertSqlCache = `INSERT INTO "${this.name}" (${list}) VALUES (${placeholders})`;
+  }
+  /** Split an input document into a row aligned with `insertColumns()`. */
+  buildInsert(input) {
     const now = Date.now();
     const id = input._id != null ? String(input._id) : objectId();
     const doc = stripSystem(input);
-    return {
-      _id: id,
-      data: JSON.stringify(doc),
-      created_at: now,
-      updated_at: now
-    };
+    const returned = { ...doc, _id: id, created_at: now, updated_at: now };
+    if (this.mode === "document") {
+      return {
+        _id: id,
+        created_at: now,
+        updated_at: now,
+        values: [id, JSON.stringify(doc), now, now],
+        returned
+      };
+    }
+    const overflow = {};
+    const colValues = {};
+    for (const [k, v] of Object.entries(doc)) {
+      if (this.columns.has(k)) colValues[k] = v;
+      else overflow[k] = v;
+    }
+    const values = [
+      id,
+      now,
+      now,
+      JSON.stringify(overflow),
+      ...this.columnOrder.map(
+        (c) => c in colValues ? this.encodeColumn(c, colValues[c]) : null
+      )
+    ];
+    return { _id: id, created_at: now, updated_at: now, values, returned };
+  }
+  /** Build the `SET` clause + values to persist an updated document. */
+  buildUpdateSet(updatedDoc, now) {
+    if (this.mode === "document") {
+      return {
+        setSql: `data = ?, updated_at = ?`,
+        values: [JSON.stringify(updatedDoc), now]
+      };
+    }
+    const overflow = {};
+    const colValues = {};
+    for (const [k, v] of Object.entries(updatedDoc)) {
+      if (this.columns.has(k)) colValues[k] = v;
+      else overflow[k] = v;
+    }
+    const setParts = this.columnOrder.map((c) => `"${c}" = ?`);
+    setParts.push(`data = ?`, `updated_at = ?`);
+    const values = [
+      ...this.columnOrder.map(
+        (c) => c in colValues ? this.encodeColumn(c, colValues[c]) : null
+      ),
+      JSON.stringify(overflow),
+      now
+    ];
+    return { setSql: setParts.join(", "), values };
+  }
+  /** Sync store, but only for document collections (structured sync is future work). */
+  get recorder() {
+    return this.mode === "document" ? this.mon.$sync : void 0;
   }
   /* ----------------------------- create ----------------------------- */
   async create(args) {
     this.ensureTable();
-    const row = this.prepareInsert(args.data);
-    this.db.prepare(
-      `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)`
-    ).run(row._id, row.data, row.created_at, row.updated_at);
-    return this.rowToDoc(row);
+    const row = this.buildInsert(args.data);
+    const recorder = this.recorder;
+    const write = () => {
+      this.db.prepare(this.insertSql()).run(...row.values);
+      recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
+    };
+    this.guard(() => recorder ? this.db.transaction(write) : write());
+    return row.returned;
   }
   async createMany(args) {
     this.ensureTable();
-    const stmt = this.db.prepare(
-      `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)`
+    const stmt = this.db.prepare(this.insertSql());
+    const recorder = this.recorder;
+    this.guard(
+      () => this.db.transaction(() => {
+        for (const item of args.data) {
+          const row = this.buildInsert(item);
+          stmt.run(...row.values);
+          recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
+        }
+      })
     );
-    this.db.transaction(() => {
-      for (const item of args.data) {
-        const row = this.prepareInsert(item);
-        stmt.run(row._id, row.data, row.created_at, row.updated_at);
-      }
-    });
     return { count: args.data.length };
   }
   /* ------------------------------ read ------------------------------ */
   async findMany(args = {}) {
     this.ensureTable();
     const params = [];
-    const where = buildWhere(args.where, { params, onPath: this.trackPath });
-    let sql = `SELECT ${SELECT_COLS} FROM "${this.name}" WHERE ${where}`;
-    const order = buildOrderBy(args.orderBy, this.trackPath);
+    const where = buildWhere(args.where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    let sql = `SELECT * FROM "${this.name}" WHERE ${where}`;
+    const order = buildOrderBy(args.orderBy, this.trackPath, this.columns);
     if (order) sql += " " + order;
     if (args.take != null) {
       sql += " LIMIT ?";
@@ -555,72 +817,108 @@ var Collection = class {
       params.push(args.skip);
     }
     const rows = this.db.prepare(sql).all(...params);
-    return rows.map(
-      (r) => project(this.rowToDoc(r), args.select)
-    );
+    return rows.map((r) => project(this.rowToDoc(r), args.select));
   }
   async findFirst(args = {}) {
     const rows = await this.findMany({ ...args, take: 1 });
     return rows[0] ?? null;
   }
+  /** Alias of {@link findFirst} for Prisma familiarity. */
+  async findUnique(args = {}) {
+    return this.findFirst(args);
+  }
+  /** Like {@link findFirst} but throws if no document matches. */
+  async findFirstOrThrow(args = {}) {
+    const doc = await this.findFirst(args);
+    if (!doc) throw new MonliteError(`No document found in "${this.name}"`);
+    return doc;
+  }
+  /** True if at least one document matches. */
+  async exists(where) {
+    this.ensureTable();
+    const params = [];
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    const row = this.db.prepare(`SELECT 1 FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params);
+    return row != null;
+  }
   async findById(id) {
     this.ensureTable();
-    const row = this.db.prepare(`SELECT ${SELECT_COLS} FROM "${this.name}" WHERE _id = ?`).get(id);
+    const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE _id = ?`).get(id);
     return row ? this.rowToDoc(row) : null;
   }
   async count(args = {}) {
     this.ensureTable();
     const params = [];
-    const where = buildWhere(args.where, { params, onPath: this.trackPath });
+    const where = buildWhere(args.where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
     const row = this.db.prepare(`SELECT COUNT(*) AS n FROM "${this.name}" WHERE ${where}`).get(...params);
     return row.n;
   }
   /**
-   * Return the distinct values of a field across the collection. Array fields
-   * are unwound (each element counts as a value), matching MongoDB's `distinct`.
+   * Return the distinct values of a field. Array fields stored in JSON are
+   * unwound (each element counts as a value), matching MongoDB's `distinct`.
    */
   async distinct(field, where) {
     this.ensureTable();
     const params = [];
-    const clause = buildWhere(where, { params, onPath: this.trackPath });
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
     let sql;
-    if (isReserved(field)) {
-      sql = `SELECT DISTINCT ${fieldExpr(field)} AS v FROM "${this.name}" WHERE ${clause} ORDER BY v`;
+    if (isColumn(field, this.columns)) {
+      sql = `SELECT DISTINCT ${fieldExpr(field, this.columns)} AS v FROM "${this.name}" WHERE ${clause} ORDER BY v`;
     } else {
       this.trackPath(field);
       sql = `SELECT DISTINCT je.value AS v FROM "${this.name}" CROSS JOIN json_each("${this.name}".data, ${pathLiteral(field)}) je WHERE ${clause} ORDER BY v`;
     }
-    const rows = this.db.prepare(sql).all(...params);
-    return rows.map((r) => r.v);
+    return this.guard(() => {
+      const rows = this.db.prepare(sql).all(...params);
+      return rows.map((r) => r.v);
+    });
   }
   /* ----------------------------- update ----------------------------- */
   runUpdate(where, data, single) {
     this.ensureTable();
     const params = [];
-    const clause = buildWhere(where, { params, onPath: this.trackPath });
-    let selectSql = `SELECT ${SELECT_COLS} FROM "${this.name}" WHERE ${clause}`;
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    let selectSql = `SELECT * FROM "${this.name}" WHERE ${clause}`;
     if (single) selectSql += " LIMIT 1";
     const rows = this.db.prepare(selectSql).all(...params);
     if (!rows.length) return [];
     const now = Date.now();
-    const stmt = this.db.prepare(
-      `UPDATE "${this.name}" SET data = ?, updated_at = ? WHERE _id = ?`
+    const recorder = this.recorder;
+    return this.guard(
+      () => this.db.transaction(() => {
+        const out = [];
+        for (const row of rows) {
+          const current = stripSystem(this.rowToDoc(row));
+          const updated = stripSystem(applyUpdate(current, data));
+          const { setSql, values } = this.buildUpdateSet(updated, now);
+          this.db.prepare(`UPDATE "${this.name}" SET ${setSql} WHERE _id = ?`).run(...values, row._id);
+          recorder?.recordLocal(this.name, row._id, "upsert", now);
+          out.push({
+            ...updated,
+            _id: row._id,
+            created_at: row.created_at,
+            updated_at: now
+          });
+        }
+        return out;
+      })
     );
-    return this.db.transaction(() => {
-      const out = [];
-      for (const row of rows) {
-        const current = JSON.parse(row.data);
-        const updated = stripSystem(applyUpdate(current, data));
-        stmt.run(JSON.stringify(updated), now, row._id);
-        out.push({
-          ...updated,
-          _id: row._id,
-          created_at: row.created_at,
-          updated_at: now
-        });
-      }
-      return out;
-    });
   }
   async update(args) {
     return this.runUpdate(args.where, args.data, true)[0] ?? null;
@@ -630,29 +928,61 @@ var Collection = class {
   }
   async upsert(args) {
     this.ensureTable();
-    const existing = await this.findFirst({ where: args.where });
-    if (existing) {
-      const updated = await this.update({
-        where: { _id: existing._id },
-        data: args.update
-      });
-      return updated;
-    }
-    return this.create({ data: args.create });
+    return this.guard(
+      () => this.db.transaction(() => {
+        const params = [];
+        const clause = buildWhere(args.where, {
+          params,
+          onPath: this.trackPath,
+          columns: this.columns
+        });
+        const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params);
+        const now = Date.now();
+        const recorder = this.recorder;
+        if (row) {
+          const current = stripSystem(this.rowToDoc(row));
+          const updated = stripSystem(applyUpdate(current, args.update));
+          const { setSql, values } = this.buildUpdateSet(updated, now);
+          this.db.prepare(`UPDATE "${this.name}" SET ${setSql} WHERE _id = ?`).run(...values, row._id);
+          recorder?.recordLocal(this.name, row._id, "upsert", now);
+          return {
+            ...updated,
+            _id: row._id,
+            created_at: row.created_at,
+            updated_at: now
+          };
+        }
+        const ins = this.buildInsert(args.create);
+        this.db.prepare(this.insertSql()).run(...ins.values);
+        recorder?.recordLocal(this.name, ins._id, "upsert", ins.created_at);
+        return ins.returned;
+      })
+    );
   }
   /* ----------------------------- delete ----------------------------- */
   runDelete(where, single) {
     this.ensureTable();
     const params = [];
-    const clause = buildWhere(where, { params, onPath: this.trackPath });
-    let selectSql = `SELECT ${SELECT_COLS} FROM "${this.name}" WHERE ${clause}`;
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    let selectSql = `SELECT * FROM "${this.name}" WHERE ${clause}`;
     if (single) selectSql += " LIMIT 1";
     const rows = this.db.prepare(selectSql).all(...params);
     if (!rows.length) return [];
     const stmt = this.db.prepare(`DELETE FROM "${this.name}" WHERE _id = ?`);
-    this.db.transaction(() => {
-      for (const row of rows) stmt.run(row._id);
-    });
+    const recorder = this.recorder;
+    const now = Date.now();
+    this.guard(
+      () => this.db.transaction(() => {
+        for (const row of rows) {
+          stmt.run(row._id);
+          recorder?.recordLocal(this.name, row._id, "delete", now);
+        }
+      })
+    );
     return rows.map((r) => this.rowToDoc(r));
   }
   async delete(args) {
@@ -664,16 +994,20 @@ var Collection = class {
   /* --------------------------- aggregation -------------------------- */
   async aggregate(args = {}) {
     this.ensureTable();
-    return aggregate(
-      { db: this.db, table: this.name, onPath: this.trackPath },
-      args
+    return this.guard(
+      () => aggregate(
+        { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
+        args
+      )
     );
   }
   async groupBy(args) {
     this.ensureTable();
-    return groupBy(
-      { db: this.db, table: this.name, onPath: this.trackPath },
-      args
+    return this.guard(
+      () => groupBy(
+        { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
+        args
+      )
     );
   }
 };
@@ -731,15 +1065,19 @@ var AutoIndexer = class {
 };
 
 // src/driver/better-sqlite3.ts
+var STMT_CACHE_MAX = 256;
 var BetterSqlite3Driver = class {
   name = "better-sqlite3";
   raw;
   verbose;
+  cache = /* @__PURE__ */ new Map();
   constructor(BetterSqlite3, filename, options) {
     this.verbose = options.verbose;
     this.raw = new BetterSqlite3(filename, {
       readonly: options.readonly ?? false
     });
+    this.raw.pragma("foreign_keys = ON");
+    this.raw.pragma(`busy_timeout = ${options.busyTimeout ?? 5e3}`);
     if (!options.readonly && (options.wal ?? true)) {
       this.raw.pragma("journal_mode = WAL");
     }
@@ -750,21 +1088,35 @@ var BetterSqlite3Driver = class {
   }
   prepare(sql) {
     this.verbose?.(sql);
-    return this.raw.prepare(sql);
+    const cached = this.cache.get(sql);
+    if (cached) return cached;
+    const stmt = this.raw.prepare(sql);
+    this.cacheStmt(sql, stmt);
+    return stmt;
+  }
+  cacheStmt(sql, stmt) {
+    if (this.cache.size >= STMT_CACHE_MAX) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(sql, stmt);
   }
   transaction(fn) {
     return this.raw.transaction(fn)();
   }
   close() {
+    this.cache.clear();
     this.raw.close();
   }
 };
 
 // src/driver/node-sqlite.ts
+var STMT_CACHE_MAX2 = 256;
 var NodeSqliteDriver = class {
   name = "node:sqlite";
   raw;
   verbose;
+  cache = /* @__PURE__ */ new Map();
   depth = 0;
   constructor(nodeSqlite, filename, options) {
     this.verbose = options.verbose;
@@ -772,6 +1124,7 @@ var NodeSqliteDriver = class {
     this.raw = new DatabaseSync(filename, {
       readOnly: options.readonly ?? false
     });
+    this.raw.exec(`PRAGMA busy_timeout = ${options.busyTimeout ?? 5e3}`);
     if (!options.readonly && (options.wal ?? true)) {
       this.raw.exec("PRAGMA journal_mode = WAL");
     }
@@ -782,12 +1135,20 @@ var NodeSqliteDriver = class {
   }
   prepare(sql) {
     this.verbose?.(sql);
+    const cached = this.cache.get(sql);
+    if (cached) return cached;
     const stmt = this.raw.prepare(sql);
-    return {
+    const wrapped = {
       run: (...p) => stmt.run(...p),
       get: (...p) => stmt.get(...p),
       all: (...p) => stmt.all(...p)
     };
+    if (this.cache.size >= STMT_CACHE_MAX2) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(sql, wrapped);
+    return wrapped;
   }
   transaction(fn) {
     const savepoint = `monlite_sp_${this.depth}`;
@@ -802,12 +1163,21 @@ var NodeSqliteDriver = class {
       return result;
     } catch (err) {
       this.depth--;
-      if (this.depth === 0) this.raw.exec("ROLLBACK");
-      else this.raw.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      try {
+        if (this.depth === 0) this.raw.exec("ROLLBACK");
+        else this.raw.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      } catch {
+        this.depth = 0;
+        try {
+          this.raw.exec("ROLLBACK");
+        } catch {
+        }
+      }
       throw err;
     }
   }
   close() {
+    this.cache.clear();
     this.raw.close();
   }
 };
@@ -858,6 +1228,360 @@ function createDriver(filename, options = {}) {
   );
 }
 
+// src/sync/version.ts
+var TS_WIDTH = 15;
+var SEQ_WIDTH = 12;
+function makeVersion(ts, nodeId, seq) {
+  const base = String(ts).padStart(TS_WIDTH, "0") + ":" + nodeId;
+  return seq === void 0 ? base : base + ":" + String(seq).padStart(SEQ_WIDTH, "0");
+}
+function compareVersions(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function versionTs(v) {
+  const i = v.indexOf(":");
+  return Number(i === -1 ? v : v.slice(0, i));
+}
+
+// src/sync/store.ts
+var NAME_RE2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertName(name) {
+  if (!NAME_RE2.test(name)) throw new Error(`Invalid collection name "${name}"`);
+}
+function stripSystem2(obj) {
+  const { _id, created_at, updated_at, ...rest } = obj;
+  return rest;
+}
+var SyncStore = class {
+  constructor(db, nodeId) {
+    this.db = db;
+    this.init();
+    this.nodeId = this.resolveNodeId(nodeId);
+  }
+  db;
+  nodeId;
+  versionSeq = 0;
+  init() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _monlite_changes (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        coll TEXT NOT NULL,
+        doc_id TEXT NOT NULL,
+        op TEXT NOT NULL,
+        version TEXT NOT NULL,
+        ts INTEGER NOT NULL,
+        source TEXT NOT NULL DEFAULT 'local',
+        pushed INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS _idx_changes_doc ON _monlite_changes(coll, doc_id, seq);
+      CREATE INDEX IF NOT EXISTS _idx_changes_push ON _monlite_changes(source, pushed, seq);
+      CREATE TABLE IF NOT EXISTS _monlite_sync_state (
+        remote TEXT PRIMARY KEY,
+        cursor TEXT,
+        last_pull_at INTEGER,
+        last_push_seq INTEGER,
+        last_push_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS _monlite_conflicts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        coll TEXT, doc_id TEXT,
+        local_version TEXT, remote_version TEXT,
+        winner TEXT, ts INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS _monlite_meta (key TEXT PRIMARY KEY, value TEXT);
+    `);
+  }
+  resolveNodeId(explicit) {
+    if (explicit) {
+      this.db.prepare(`INSERT OR REPLACE INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`).run(explicit);
+      return explicit;
+    }
+    const row = this.db.prepare(`SELECT value FROM _monlite_meta WHERE key = 'nodeId'`).get();
+    if (row?.value) return row.value;
+    const generated = objectId();
+    this.db.prepare(`INSERT INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`).run(generated);
+    return generated;
+  }
+  /** True if this database tracks sync metadata (always, once constructed). */
+  get enabled() {
+    return true;
+  }
+  /* ----------------------- local change recording ----------------------- */
+  /** Append a locally-originated change to the feed. Call inside a write txn. */
+  recordLocal(collection, id, op, ts) {
+    const version = makeVersion(ts, this.nodeId, this.versionSeq++);
+    this.db.prepare(
+      `INSERT INTO _monlite_changes (coll, doc_id, op, version, ts, source, pushed)
+         VALUES (?, ?, ?, ?, ?, 'local', 0)`
+    ).run(collection, id, op, version, ts);
+    return version;
+  }
+  /** Current (latest) version of a document, or null if never recorded. */
+  currentVersion(collection, id) {
+    const row = this.db.prepare(
+      `SELECT version FROM _monlite_changes
+         WHERE coll = ? AND doc_id = ? ORDER BY seq DESC LIMIT 1`
+    ).get(collection, id);
+    return row?.version ?? null;
+  }
+  /* ----------------------------- push side ----------------------------- */
+  /** Latest unpushed local change per document (the push queue). */
+  pending(collections, limit) {
+    const params = [];
+    let collFilter = "";
+    if (collections && collections.length) {
+      collFilter = ` AND coll IN (${collections.map(() => "?").join(", ")})`;
+      params.push(...collections);
+    }
+    let limitClause = "";
+    if (limit != null && limit > 0) {
+      limitClause = " LIMIT ?";
+      params.push(limit);
+    }
+    const rows = this.db.prepare(
+      `SELECT c.seq, c.coll, c.doc_id, c.op, c.version, c.ts
+         FROM _monlite_changes c
+         JOIN (
+           SELECT coll, doc_id, MAX(seq) AS mseq
+           FROM _monlite_changes
+           WHERE source = 'local' AND pushed = 0${collFilter}
+           GROUP BY coll, doc_id
+         ) m ON c.coll = m.coll AND c.doc_id = m.doc_id AND c.seq = m.mseq
+         ORDER BY c.seq${limitClause}`
+    ).all(...params);
+    return rows.map((r) => {
+      const change = {
+        seq: r.seq,
+        collection: r.coll,
+        _id: r.doc_id,
+        op: r.op,
+        version: r.version,
+        ts: r.ts
+      };
+      if (r.op === "upsert") {
+        const doc = this.readDoc(r.coll, r.doc_id);
+        if (doc) change.doc = doc;
+        else change.op = "delete";
+      }
+      return change;
+    });
+  }
+  /** Mark the given changes (and any earlier local rows per doc) as pushed. */
+  markPushed(changes) {
+    if (!changes.length) return;
+    const stmt = this.db.prepare(
+      `UPDATE _monlite_changes SET pushed = 1
+       WHERE coll = ? AND doc_id = ? AND seq <= ? AND source = 'local'`
+    );
+    this.db.transaction(() => {
+      for (const c of changes) stmt.run(c.collection, c._id, c.seq);
+    });
+  }
+  /* ----------------------------- pull side ----------------------------- */
+  /**
+   * Apply a remote change, resolving conflicts against the local version.
+   * Remote-applied changes are recorded with `source='remote'` so they are
+   * never pushed back (echo prevention).
+   */
+  applyRemote(change, resolver) {
+    assertName(change.collection);
+    return this.db.transaction(() => {
+      const localVersion = this.currentVersion(change.collection, change._id);
+      let winner;
+      if (localVersion === null) {
+        winner = "remote";
+      } else if (change.version === localVersion) {
+        return { applied: false, conflict: false, winner: "none" };
+      } else {
+        winner = resolver ? resolver({
+          collection: change.collection,
+          _id: change._id,
+          local: { version: localVersion },
+          remote: { version: change.version, doc: change.doc }
+        }) : compareVersions(change.version, localVersion) > 0 ? "remote" : "local";
+        this.recordConflict(
+          change.collection,
+          change._id,
+          localVersion,
+          change.version,
+          winner
+        );
+      }
+      if (winner !== "remote") {
+        return { applied: false, conflict: localVersion !== null, winner };
+      }
+      this.applyData(change);
+      this.db.prepare(
+        `INSERT INTO _monlite_changes (coll, doc_id, op, version, ts, source, pushed)
+           VALUES (?, ?, ?, ?, ?, 'remote', 1)`
+      ).run(
+        change.collection,
+        change._id,
+        change.op,
+        change.version,
+        versionTs(change.version)
+      );
+      return { applied: true, conflict: localVersion !== null, winner: "remote" };
+    });
+  }
+  applyData(change) {
+    const { collection: coll, _id, op } = change;
+    this.ensureCollTable(coll);
+    if (op === "delete") {
+      this.db.prepare(`DELETE FROM "${coll}" WHERE _id = ?`).run(_id);
+      return;
+    }
+    const doc = change.doc ?? {};
+    const data = JSON.stringify(stripSystem2(doc));
+    const ts = versionTs(change.version);
+    const createdAt = typeof doc.created_at === "number" ? doc.created_at : ts;
+    this.db.prepare(
+      `INSERT INTO "${coll}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(_id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`
+    ).run(_id, data, createdAt, ts);
+  }
+  /**
+   * Latest change per document with `seq` greater than the given watermark,
+   * as RemoteChanges (used when this database acts as a sync *source*, e.g. the
+   * monlite-as-remote adapter). Returns the new watermark to resume from.
+   */
+  changesSince(seq, collections, limit) {
+    const params = [seq];
+    let collFilter = "";
+    if (collections && collections.length) {
+      collFilter = ` AND coll IN (${collections.map(() => "?").join(", ")})`;
+      params.push(...collections);
+    }
+    let limitClause = "";
+    if (limit != null && limit > 0) {
+      limitClause = " LIMIT ?";
+      params.push(limit);
+    }
+    const rows = this.db.prepare(
+      `SELECT c.seq, c.coll, c.doc_id, c.op, c.version, c.ts
+         FROM _monlite_changes c
+         JOIN (
+           SELECT coll, doc_id, MAX(seq) AS mseq
+           FROM _monlite_changes
+           WHERE seq > ?${collFilter}
+           GROUP BY coll, doc_id
+         ) m ON c.coll = m.coll AND c.doc_id = m.doc_id AND c.seq = m.mseq
+         ORDER BY c.seq${limitClause}`
+    ).all(...params);
+    const changes = rows.map((r) => {
+      const change = {
+        collection: r.coll,
+        _id: r.doc_id,
+        op: r.op,
+        version: r.version
+      };
+      if (r.op === "upsert") {
+        const doc = this.readDoc(r.coll, r.doc_id);
+        if (doc) change.doc = doc;
+        else change.op = "delete";
+      }
+      return change;
+    });
+    const maxSeq = rows.length ? rows[rows.length - 1].seq : seq;
+    return { changes, maxSeq };
+  }
+  /* ------------------------------ bootstrap ----------------------------- */
+  /**
+   * Enqueue existing documents (created before sync was enabled, or never
+   * recorded) as local upserts so they can be pushed. Idempotent.
+   */
+  seed(collections) {
+    let count = 0;
+    this.db.transaction(() => {
+      for (const coll of collections) {
+        assertName(coll);
+        const docs = this.db.prepare(`SELECT _id, updated_at FROM "${coll}"`).all();
+        for (const d of docs) {
+          if (this.currentVersion(coll, d._id) !== null) continue;
+          this.recordLocal(coll, d._id, "upsert", d.updated_at);
+          count++;
+        }
+      }
+    });
+    return count;
+  }
+  /* ------------------------------- state -------------------------------- */
+  getState(remote) {
+    const row = this.db.prepare(`SELECT * FROM _monlite_sync_state WHERE remote = ?`).get(remote);
+    return {
+      remote,
+      cursor: row?.cursor ?? null,
+      lastPullAt: row?.last_pull_at ?? null,
+      lastPushSeq: row?.last_push_seq ?? null,
+      lastPushAt: row?.last_push_at ?? null
+    };
+  }
+  setState(remote, patch) {
+    const cur = this.getState(remote);
+    const next = { ...cur, ...patch };
+    this.db.prepare(
+      `INSERT INTO _monlite_sync_state (remote, cursor, last_pull_at, last_push_seq, last_push_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(remote) DO UPDATE SET
+           cursor = excluded.cursor,
+           last_pull_at = excluded.last_pull_at,
+           last_push_seq = excluded.last_push_seq,
+           last_push_at = excluded.last_push_at`
+    ).run(
+      remote,
+      next.cursor,
+      next.lastPullAt,
+      next.lastPushSeq,
+      next.lastPushAt
+    );
+  }
+  /* ----------------------------- conflicts ------------------------------ */
+  recordConflict(coll, id, localVersion, remoteVersion, winner) {
+    this.db.prepare(
+      `INSERT INTO _monlite_conflicts (coll, doc_id, local_version, remote_version, winner, ts)
+         VALUES (?, ?, ?, ?, ?, ?)`
+    ).run(coll, id, localVersion, remoteVersion, winner, versionTs(remoteVersion));
+  }
+  conflicts() {
+    const rows = this.db.prepare(
+      `SELECT coll, doc_id, local_version, remote_version, winner, ts
+         FROM _monlite_conflicts ORDER BY id`
+    ).all();
+    return rows.map((r) => ({
+      collection: r.coll,
+      _id: r.doc_id,
+      localVersion: r.local_version,
+      remoteVersion: r.remote_version,
+      winner: r.winner,
+      ts: r.ts
+    }));
+  }
+  /* ------------------------------ helpers ------------------------------- */
+  readDoc(coll, id) {
+    assertName(coll);
+    const row = this.db.prepare(
+      `SELECT _id, data, created_at, updated_at FROM "${coll}" WHERE _id = ?`
+    ).get(id);
+    if (!row) return null;
+    const doc = JSON.parse(row.data);
+    doc._id = row._id;
+    doc.created_at = row.created_at;
+    doc.updated_at = row.updated_at;
+    return doc;
+  }
+  ensureCollTable(coll) {
+    assertName(coll);
+    this.db.exec(
+      `CREATE TABLE IF NOT EXISTS "${coll}" (
+        _id TEXT PRIMARY KEY,
+        data TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )`
+    );
+  }
+};
+
 // src/db.ts
 function validateName(name) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
@@ -883,6 +1607,8 @@ var Monlite = class {
   driver;
   /** @internal */
   autoIndexer;
+  /** @internal Sync metadata store; present only when `{ sync: true }`. */
+  $sync;
   collections = /* @__PURE__ */ new Map();
   closed = false;
   constructor(filename, options = {}) {
@@ -890,6 +1616,7 @@ var Monlite = class {
       driver: options.driver,
       readonly: options.readonly,
       wal: options.wal,
+      busyTimeout: options.busyTimeout,
       verbose: options.verbose
     });
     this.autoIndexer = new AutoIndexer(
@@ -897,6 +1624,13 @@ var Monlite = class {
       options.autoIndex ?? true,
       options.autoIndexAfter ?? 10
     );
+    if (options.sync) {
+      this.$sync = new SyncStore(this.driver, options.nodeId);
+    }
+  }
+  /** Stable node id for LWW tie-breaking (only when sync is enabled). */
+  get nodeId() {
+    return this.$sync?.nodeId;
   }
   /** The underlying native database handle (escape hatch). */
   get sqlite() {
@@ -906,17 +1640,44 @@ var Monlite = class {
   get driverName() {
     return this.driver.name;
   }
-  /** Get (or lazily create) a typed collection handle. */
-  collection(name) {
+  /**
+   * Get (or lazily create) a typed collection handle. Pass `{ schema }` to make
+   * it a structured collection backed by native SQL columns; omit for the
+   * default schema-free document mode. Options apply only on first access.
+   */
+  collection(name, options) {
     this.assertOpen();
     validateName(name);
     let col = this.collections.get(name);
     if (!col) {
-      col = new Collection(this, name);
+      col = new Collection(this, name, options);
       this.collections.set(name, col);
+    } else if (options?.schema) {
+      const requested = Object.keys(options.schema);
+      const existing = new Set(col.columnNames);
+      const sameShape = col.mode === "structured" && requested.length === existing.size && requested.every((c) => existing.has(c));
+      if (!sameShape) {
+        throw new MonliteError(
+          `Collection "${name}" was already opened with a different schema/mode. A collection's storage mode is fixed on first access.`
+        );
+      }
     }
     return col;
   }
+  /** Inspect a collection's physical columns (PRAGMA table_info). */
+  $schema(name) {
+    this.assertOpen();
+    validateName(name);
+    const rows = this.driver.prepare(`PRAGMA table_info("${name}")`).all();
+    return Promise.resolve(
+      rows.map((r) => ({
+        name: r.name,
+        type: r.type,
+        notNull: !!r.notnull,
+        primaryKey: !!r.pk
+      }))
+    );
+  }
   /** Tagged-template SQL query returning rows. Values are safely parameterized. */
   $queryRaw(strings, ...values) {
     this.assertOpen();
@@ -934,7 +1695,11 @@ var Monlite = class {
   $executeRaw(strings, ...values) {
     this.assertOpen();
     const { sql, params } = buildTagged(strings, values);
-    return Promise.resolve(this.driver.prepare(sql).run(...params).changes);
+    try {
+      return Promise.resolve(this.driver.prepare(sql).run(...params).changes);
+    } catch (err) {
+      throw normalizeDriverError(err);
+    }
   }
   /** Like {@link $executeRaw} but takes a raw SQL string and positional params. */
   $executeRawUnsafe(sql, ...params) {
@@ -956,7 +1721,9 @@ var Monlite = class {
     this.assertOpen();
     const rows = this.driver.prepare(
       `SELECT name FROM sqlite_master
-         WHERE type='table' AND name NOT LIKE 'sqlite_%'
+         WHERE type='table'
+           AND name NOT LIKE 'sqlite_%'
+           AND name NOT LIKE '\\_monlite\\_%' ESCAPE '\\'
          ORDER BY name`
     ).all();
     return Promise.resolve(rows.map((r) => r.name));
@@ -992,10 +1759,19 @@ function createDb(filename, options) {
 
 exports.Collection = Collection;
 exports.Monlite = Monlite;
+exports.MonliteConstraintError = MonliteConstraintError;
 exports.MonliteError = MonliteError;
+exports.MonliteForeignKeyError = MonliteForeignKeyError;
+exports.MonliteNotNullError = MonliteNotNullError;
 exports.MonliteQueryError = MonliteQueryError;
+exports.MonliteUniqueConstraintError = MonliteUniqueConstraintError;
+exports.SyncStore = SyncStore;
+exports.compareVersions = compareVersions;
 exports.createDb = createDb;
 exports.isObjectId = isObjectId;
+exports.makeVersion = makeVersion;
+exports.normalizeDriverError = normalizeDriverError;
 exports.objectId = objectId;
+exports.versionTs = versionTs;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map