latticesql 0.5.0

package/dist/index.cjs

@@ -0,0 +1,1514 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Lattice: () => Lattice,
+  manifestPath: () => manifestPath,
+  parseConfigFile: () => parseConfigFile,
+  parseConfigString: () => parseConfigString,
+  readManifest: () => readManifest,
+  writeManifest: () => writeManifest
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/lattice.ts
+var import_uuid = require("uuid");
+
+// src/lifecycle/manifest.ts
+var import_node_path2 = require("path");
+var import_node_fs2 = require("fs");
+
+// src/render/writer.ts
+var import_node_fs = require("fs");
+var import_node_crypto = require("crypto");
+var import_node_path = require("path");
+var import_node_os = require("os");
+var import_node_crypto2 = require("crypto");
+function atomicWrite(filePath, content) {
+  const dir = (0, import_node_path.dirname)(filePath);
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  const currentHash = existingHash(filePath);
+  const newHash = contentHash(content);
+  if (currentHash === newHash) return false;
+  const tmp = (0, import_node_path.join)((0, import_node_os.tmpdir)(), `lattice-${(0, import_node_crypto2.randomBytes)(8).toString("hex")}.tmp`);
+  (0, import_node_fs.writeFileSync)(tmp, content, "utf8");
+  (0, import_node_fs.renameSync)(tmp, filePath);
+  return true;
+}
+function existingHash(filePath) {
+  if (!(0, import_node_fs.existsSync)(filePath)) return null;
+  try {
+    return contentHash((0, import_node_fs.readFileSync)(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function contentHash(content) {
+  return (0, import_node_crypto.createHash)("sha256").update(content).digest("hex");
+}
+
+// src/lifecycle/manifest.ts
+function manifestPath(outputDir) {
+  return (0, import_node_path2.join)(outputDir, ".lattice", "manifest.json");
+}
+function readManifest(outputDir) {
+  const path = manifestPath(outputDir);
+  if (!(0, import_node_fs2.existsSync)(path)) return null;
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeManifest(outputDir, manifest) {
+  atomicWrite(manifestPath(outputDir), JSON.stringify(manifest, null, 2));
+}
+
+// src/db/sqlite.ts
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var SQLiteAdapter = class {
+  _db = null;
+  _path;
+  _wal;
+  _busyTimeout;
+  constructor(path, options) {
+    this._path = path;
+    this._wal = options?.wal ?? true;
+    this._busyTimeout = options?.busyTimeout ?? 5e3;
+  }
+  get db() {
+    if (!this._db) throw new Error("SQLiteAdapter: not open \u2014 call open() first");
+    return this._db;
+  }
+  open() {
+    this._db = new import_better_sqlite3.default(this._path);
+    this._db.pragma(`busy_timeout = ${this._busyTimeout.toString()}`);
+    if (this._wal) {
+      this._db.pragma("journal_mode = WAL");
+    }
+  }
+  close() {
+    this._db?.close();
+    this._db = null;
+  }
+  run(sql, params = []) {
+    this.db.prepare(sql).run(...params);
+  }
+  get(sql, params = []) {
+    return this.db.prepare(sql).get(...params);
+  }
+  all(sql, params = []) {
+    return this.db.prepare(sql).all(...params);
+  }
+  prepare(sql) {
+    const stmt = this.db.prepare(sql);
+    return {
+      run: (...params) => stmt.run(...params),
+      get: (...params) => stmt.get(...params),
+      all: (...params) => stmt.all(...params)
+    };
+  }
+};
+
+// src/schema/manager.ts
+var SchemaManager = class {
+  _tables = /* @__PURE__ */ new Map();
+  /** Normalised primary key columns per table (always an array). */
+  _tablePK = /* @__PURE__ */ new Map();
+  _multis = /* @__PURE__ */ new Map();
+  _entityContexts = /* @__PURE__ */ new Map();
+  define(table, def) {
+    if (this._tables.has(table)) {
+      throw new Error(`Table "${table}" is already defined`);
+    }
+    this._tables.set(table, def);
+    if (def.primaryKey === void 0 || def.primaryKey === "id") {
+      this._tablePK.set(table, ["id"]);
+    } else if (Array.isArray(def.primaryKey)) {
+      if (def.primaryKey.length === 0) {
+        throw new Error(`Table "${table}": primaryKey array must not be empty`);
+      }
+      this._tablePK.set(table, def.primaryKey);
+    } else {
+      this._tablePK.set(table, [def.primaryKey]);
+    }
+  }
+  defineMulti(name, def) {
+    if (this._multis.has(name)) {
+      throw new Error(`Multi-render "${name}" is already defined`);
+    }
+    this._multis.set(name, def);
+  }
+  /**
+   * Register an entity context definition.
+   * Throws if a context for the same table has already been registered.
+   */
+  defineEntityContext(table, def) {
+    if (this._entityContexts.has(table)) {
+      throw new Error(`Entity context for table "${table}" is already defined`);
+    }
+    this._entityContexts.set(table, def);
+  }
+  getTables() {
+    return this._tables;
+  }
+  getMultis() {
+    return this._multis;
+  }
+  getEntityContexts() {
+    return this._entityContexts;
+  }
+  /**
+   * Return the normalised primary key column list for a table.
+   * Falls back to `['id']` for tables that were not registered via `define()`
+   * (e.g. tables accessed through the raw `.db` escape hatch).
+   */
+  getPrimaryKey(table) {
+    return this._tablePK.get(table) ?? ["id"];
+  }
+  /**
+   * Return the declared relationships for a table, keyed by relation name.
+   * Returns an empty object for tables with no `relations` definition.
+   */
+  getRelations(table) {
+    return this._tables.get(table)?.relations ?? {};
+  }
+  /**
+   * Apply schema: create missing tables, add missing columns.
+   * Never drops tables or columns.
+   */
+  applySchema(adapter) {
+    for (const [name, def] of this._tables) {
+      this._ensureTable(adapter, name, def.columns, def.tableConstraints);
+    }
+    this._ensureTable(adapter, "__lattice_migrations", {
+      version: "INTEGER PRIMARY KEY",
+      applied_at: "TEXT NOT NULL"
+    });
+  }
+  /** Run explicit versioned migrations in order, idempotently */
+  applyMigrations(adapter, migrations) {
+    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    for (const m of sorted) {
+      const exists = adapter.get("SELECT 1 FROM __lattice_migrations WHERE version = ?", [
+        m.version
+      ]);
+      if (!exists) {
+        adapter.run(m.sql);
+        adapter.run("INSERT INTO __lattice_migrations (version, applied_at) VALUES (?, ?)", [
+          m.version,
+          (/* @__PURE__ */ new Date()).toISOString()
+        ]);
+      }
+    }
+  }
+  /** Query all rows from a registered table */
+  queryTable(adapter, name) {
+    if (!this._tables.has(name)) {
+      throw new Error(`Unknown table: "${name}"`);
+    }
+    return adapter.all(`SELECT * FROM "${name}"`);
+  }
+  _ensureTable(adapter, name, columns, tableConstraints) {
+    const colDefs = Object.entries(columns).map(([col, type]) => `"${col}" ${type}`).join(", ");
+    const constraintDefs = tableConstraints && tableConstraints.length > 0 ? ", " + tableConstraints.join(", ") : "";
+    adapter.run(`CREATE TABLE IF NOT EXISTS "${name}" (${colDefs}${constraintDefs})`);
+    this._addMissingColumns(adapter, name, columns);
+  }
+  _addMissingColumns(adapter, table, columns) {
+    const existing = adapter.all(`PRAGMA table_info("${table}")`).map((r) => r.name);
+    for (const [col, type] of Object.entries(columns)) {
+      if (!existing.includes(col)) {
+        adapter.run(`ALTER TABLE "${table}" ADD COLUMN "${col}" ${type}`);
+      }
+    }
+  }
+};
+
+// src/security/sanitize.ts
+var SUSPICIOUS_PATTERNS = [
+  /(\bdrop\b|\bdelete\b|\btruncate\b|\binsert\b|\bupdate\b)\s+\b(table|from|into)\b/i,
+  /<script[\s\S]*?>/i,
+  /javascript:/i,
+  /\.\.[/\\]/,
+  // Intentional null-byte check — eslint-disable to allow control char in regex
+  // eslint-disable-next-line no-control-regex
+  /\x00/
+];
+var NULL_BYTE_RE = /\x00/g;
+var CONTROL_CHAR_RE = /[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+var Sanitizer = class {
+  _options;
+  _auditHandlers = [];
+  constructor(options = {}) {
+    this._options = {
+      sanitize: options.sanitize ?? true,
+      auditTables: options.auditTables ?? [],
+      fieldLimits: options.fieldLimits ?? {}
+    };
+  }
+  onAudit(handler) {
+    this._auditHandlers.push(handler);
+  }
+  sanitizeRow(row) {
+    if (!this._options.sanitize) return row;
+    const out = {};
+    for (const [key, val] of Object.entries(row)) {
+      if (typeof val === "string") {
+        let s = val.replace(NULL_BYTE_RE, "").replace(CONTROL_CHAR_RE, "");
+        const limit = this._options.fieldLimits[key];
+        if (limit !== void 0 && s.length > limit) {
+          s = s.slice(0, limit);
+        }
+        for (const pattern of SUSPICIOUS_PATTERNS) {
+          if (pattern.test(s)) {
+            console.warn(`[lattice/security] Suspicious content in field "${key}"`);
+            break;
+          }
+        }
+        out[key] = s;
+      } else {
+        out[key] = val;
+      }
+    }
+    return out;
+  }
+  emitAudit(table, operation, id) {
+    if (!this._options.auditTables.includes(table)) return;
+    const event = {
+      table,
+      operation,
+      id,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    for (const handler of this._auditHandlers) {
+      handler(event);
+    }
+  }
+  isAuditTable(table) {
+    return this._options.auditTables.includes(table);
+  }
+};
+
+// src/render/engine.ts
+var import_node_path4 = require("path");
+var import_node_fs4 = require("fs");
+
+// src/render/entity-query.ts
+function resolveEntitySource(source, entityRow, entityPk, adapter) {
+  switch (source.type) {
+    case "self":
+      return [entityRow];
+    case "hasMany": {
+      const ref = source.references ?? entityPk;
+      const pkVal = entityRow[ref];
+      return adapter.all(
+        `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`,
+        [pkVal]
+      );
+    }
+    case "manyToMany": {
+      const pkVal = entityRow[entityPk];
+      const remotePk = source.references ?? "id";
+      return adapter.all(
+        `SELECT r.* FROM "${source.remoteTable}" r
+         JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
+         WHERE j."${source.localKey}" = ?`,
+        [pkVal]
+      );
+    }
+    case "belongsTo": {
+      const fkVal = entityRow[source.foreignKey];
+      if (fkVal == null) return [];
+      const related = adapter.get(
+        `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`,
+        [fkVal]
+      );
+      return related ? [related] : [];
+    }
+    case "custom":
+      return source.query(entityRow, adapter);
+  }
+}
+function truncateContent(content, budget) {
+  if (budget === void 0 || content.length <= budget) return content;
+  return content.slice(0, budget) + "\n\n*[truncated \u2014 context budget exceeded]*";
+}
+
+// src/lifecycle/cleanup.ts
+var import_node_path3 = require("path");
+var import_node_fs3 = require("fs");
+function cleanupEntityContexts(outputDir, entityContexts, currentSlugsByTable, manifest, options = {}, newManifest) {
+  const result = {
+    directoriesRemoved: [],
+    filesRemoved: [],
+    directoriesSkipped: [],
+    warnings: []
+  };
+  if (manifest === null) return result;
+  for (const [table, def] of entityContexts) {
+    const entry = manifest.entityContexts[table];
+    if (!entry) continue;
+    const directoryRoot = entry.directoryRoot;
+    const currentSlugs = currentSlugsByTable.get(table) ?? /* @__PURE__ */ new Set();
+    const globalProtected = /* @__PURE__ */ new Set([
+      ...def.protectedFiles ?? [],
+      ...options.protectedFiles ?? []
+    ]);
+    const rootPath = (0, import_node_path3.join)(outputDir, directoryRoot);
+    if (!(0, import_node_fs3.existsSync)(rootPath)) continue;
+    if (options.removeOrphanedDirectories !== false && !def.directory) {
+      let actualDirs;
+      try {
+        actualDirs = (0, import_node_fs3.readdirSync)(rootPath).filter((name) => {
+          try {
+            return (0, import_node_fs3.statSync)((0, import_node_path3.join)(rootPath, name)).isDirectory();
+          } catch {
+            return false;
+          }
+        });
+      } catch {
+        actualDirs = [];
+      }
+      for (const dirName of actualDirs) {
+        if (currentSlugs.has(dirName)) continue;
+        if (!Object.prototype.hasOwnProperty.call(entry.entities, dirName)) continue;
+        const entityDir = (0, import_node_path3.join)(rootPath, dirName);
+        const managedFiles = entry.entities[dirName] ?? [];
+        for (const filename of managedFiles) {
+          if (globalProtected.has(filename)) continue;
+          const filePath = (0, import_node_path3.join)(entityDir, filename);
+          if (!(0, import_node_fs3.existsSync)(filePath)) continue;
+          if (!options.dryRun) (0, import_node_fs3.unlinkSync)(filePath);
+          options.onOrphan?.(filePath, "file");
+          result.filesRemoved.push(filePath);
+        }
+        let remaining;
+        try {
+          remaining = (0, import_node_fs3.existsSync)(entityDir) ? (0, import_node_fs3.readdirSync)(entityDir) : [];
+        } catch {
+          remaining = [];
+        }
+        if (remaining.length === 0) {
+          if (!options.dryRun) {
+            try {
+              (0, import_node_fs3.rmdirSync)(entityDir);
+            } catch {
+            }
+          }
+          options.onOrphan?.(entityDir, "directory");
+          result.directoriesRemoved.push(entityDir);
+        } else {
+          result.directoriesSkipped.push(entityDir);
+          result.warnings.push(
+            `${entityDir}: left in place (contains user files: ${remaining.join(", ")})`
+          );
+        }
+      }
+    }
+    if (options.removeOrphanedFiles !== false) {
+      const newEntry = newManifest?.entityContexts[table];
+      const declaredFiles = new Set(Object.keys(def.files));
+      if (def.combined) declaredFiles.add(def.combined.outputFile);
+      for (const slug of currentSlugs) {
+        const entityDir = def.directory ? null : (0, import_node_path3.join)(rootPath, slug);
+        if (!entityDir || !(0, import_node_fs3.existsSync)(entityDir)) continue;
+        const previouslyWritten = entry.entities[slug] ?? [];
+        const currentlyWritten = new Set(newEntry?.entities[slug] ?? []);
+        for (const filename of previouslyWritten) {
+          if (newEntry !== void 0) {
+            if (currentlyWritten.has(filename)) continue;
+          } else {
+            if (declaredFiles.has(filename)) continue;
+          }
+          if (globalProtected.has(filename)) continue;
+          const filePath = (0, import_node_path3.join)(entityDir, filename);
+          if (!(0, import_node_fs3.existsSync)(filePath)) continue;
+          if (!options.dryRun) (0, import_node_fs3.unlinkSync)(filePath);
+          options.onOrphan?.(filePath, "file");
+          result.filesRemoved.push(filePath);
+        }
+      }
+    }
+  }
+  return result;
+}
+
+// src/render/engine.ts
+var RenderEngine = class {
+  _schema;
+  _adapter;
+  constructor(schema, adapter) {
+    this._schema = schema;
+    this._adapter = adapter;
+  }
+  async render(outputDir) {
+    const start = Date.now();
+    const filesWritten = [];
+    const counters = { skipped: 0 };
+    for (const [name, def] of this._schema.getTables()) {
+      let rows = this._schema.queryTable(this._adapter, name);
+      if (def.filter) rows = def.filter(rows);
+      const content = def.render(rows);
+      const filePath = (0, import_node_path4.join)(outputDir, def.outputFile);
+      if (atomicWrite(filePath, content)) {
+        filesWritten.push(filePath);
+      } else {
+        counters.skipped++;
+      }
+    }
+    for (const [, def] of this._schema.getMultis()) {
+      const keys = await def.keys();
+      const tables = {};
+      if (def.tables) {
+        for (const t of def.tables) {
+          tables[t] = this._schema.queryTable(this._adapter, t);
+        }
+      }
+      for (const key of keys) {
+        const content = def.render(key, tables);
+        const filePath = (0, import_node_path4.join)(outputDir, def.outputFile(key));
+        if (atomicWrite(filePath, content)) {
+          filesWritten.push(filePath);
+        } else {
+          counters.skipped++;
+        }
+      }
+    }
+    const entityContextManifest = this._renderEntityContexts(outputDir, filesWritten, counters);
+    if (this._schema.getEntityContexts().size > 0) {
+      writeManifest(outputDir, {
+        version: 1,
+        generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        entityContexts: entityContextManifest
+      });
+    }
+    return {
+      filesWritten,
+      filesSkipped: counters.skipped,
+      durationMs: Date.now() - start
+    };
+  }
+  /**
+   * Run orphan cleanup using the previous manifest.
+   * Called by reconcile() and optionally by the watch loop.
+   *
+   * @param newManifest - Optional: the manifest just written by render().
+   *   When provided, step 2 (stale files in surviving entity dirs) compares
+   *   old vs new manifest entries, catching omitIfEmpty files that were written
+   *   before but skipped in the current render cycle.
+   */
+  cleanup(outputDir, prevManifest, options = {}, newManifest) {
+    const entityContexts = this._schema.getEntityContexts();
+    const currentSlugsByTable = /* @__PURE__ */ new Map();
+    for (const [table, def] of entityContexts) {
+      const rows = this._schema.queryTable(this._adapter, table);
+      const slugs = new Set(rows.map((row) => def.slug(row)));
+      currentSlugsByTable.set(table, slugs);
+    }
+    return cleanupEntityContexts(outputDir, entityContexts, currentSlugsByTable, prevManifest, options, newManifest);
+  }
+  /**
+   * Render all entity context definitions.
+   * Mutates `filesWritten` and `counters` in place.
+   * Returns manifest data for the entity contexts rendered this cycle.
+   */
+  _renderEntityContexts(outputDir, filesWritten, counters) {
+    const manifestData = {};
+    for (const [table, def] of this._schema.getEntityContexts()) {
+      const entityPk = this._schema.getPrimaryKey(table)[0] ?? "id";
+      const allRows = this._schema.queryTable(this._adapter, table);
+      const directoryRoot = def.directoryRoot ?? table;
+      const manifestEntry = {
+        directoryRoot,
+        ...def.index ? { indexFile: def.index.outputFile } : {},
+        declaredFiles: Object.keys(def.files),
+        protectedFiles: def.protectedFiles ?? [],
+        entities: {}
+      };
+      if (def.index) {
+        const indexPath = (0, import_node_path4.join)(outputDir, def.index.outputFile);
+        if (atomicWrite(indexPath, def.index.render(allRows))) {
+          filesWritten.push(indexPath);
+        } else {
+          counters.skipped++;
+        }
+      }
+      for (const entityRow of allRows) {
+        const slug = def.slug(entityRow);
+        const entityDir = def.directory ? (0, import_node_path4.join)(outputDir, def.directory(entityRow)) : (0, import_node_path4.join)(outputDir, directoryRoot, slug);
+        (0, import_node_fs4.mkdirSync)(entityDir, { recursive: true });
+        const renderedFiles = /* @__PURE__ */ new Map();
+        for (const [filename, spec] of Object.entries(def.files)) {
+          const rows = resolveEntitySource(spec.source, entityRow, entityPk, this._adapter);
+          if (spec.omitIfEmpty && rows.length === 0) continue;
+          const content = truncateContent(spec.render(rows), spec.budget);
+          renderedFiles.set(filename, content);
+          const filePath = (0, import_node_path4.join)(entityDir, filename);
+          if (atomicWrite(filePath, content)) {
+            filesWritten.push(filePath);
+          } else {
+            counters.skipped++;
+          }
+        }
+        if (def.combined && renderedFiles.size > 0) {
+          const excluded = new Set(def.combined.exclude ?? []);
+          const parts = [];
+          for (const filename of Object.keys(def.files)) {
+            if (!excluded.has(filename) && renderedFiles.has(filename)) {
+              parts.push(renderedFiles.get(filename));
+            }
+          }
+          if (parts.length > 0) {
+            const combinedPath = (0, import_node_path4.join)(entityDir, def.combined.outputFile);
+            if (atomicWrite(combinedPath, parts.join("\n\n---\n\n"))) {
+              filesWritten.push(combinedPath);
+            } else {
+              counters.skipped++;
+            }
+            renderedFiles.set(def.combined.outputFile, parts.join("\n\n---\n\n"));
+          }
+        }
+        manifestEntry.entities[slug] = [...renderedFiles.keys()];
+      }
+      manifestData[table] = manifestEntry;
+    }
+    return manifestData;
+  }
+};
+
+// src/sync/loop.ts
+var SyncLoop = class {
+  _engine;
+  constructor(engine) {
+    this._engine = engine;
+  }
+  watch(outputDir, options = {}) {
+    const interval = options.interval ?? 5e3;
+    let timer = null;
+    let stopped = false;
+    const tick = () => {
+      if (stopped) return;
+      const prevManifest = options.cleanup ? readManifest(outputDir) : null;
+      void this._engine.render(outputDir).then((result) => {
+        options.onRender?.(result);
+        if (options.cleanup) {
+          const cleanupResult = this._engine.cleanup(outputDir, prevManifest, options.cleanup);
+          options.onCleanup?.(cleanupResult);
+        }
+      }).catch((err) => {
+        options.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }).finally(() => {
+        if (!stopped) {
+          timer = setTimeout(tick, interval);
+        }
+      });
+    };
+    timer = setTimeout(tick, interval);
+    return () => {
+      stopped = true;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+  }
+};
+
+// src/writeback/pipeline.ts
+var import_node_fs5 = require("fs");
+var import_node_path5 = require("path");
+var WritebackPipeline = class {
+  _definitions = [];
+  _fileState = /* @__PURE__ */ new Map();
+  _seen = /* @__PURE__ */ new Map();
+  define(def) {
+    this._definitions.push(def);
+  }
+  async process() {
+    let total = 0;
+    for (const def of this._definitions) {
+      total += await this._processDef(def);
+    }
+    return total;
+  }
+  async _processDef(def) {
+    const paths = this._expandGlob(def.file);
+    let processed = 0;
+    for (const filePath of paths) {
+      if (!(0, import_node_fs5.existsSync)(filePath)) continue;
+      const stat = (0, import_node_fs5.statSync)(filePath);
+      const currentSize = stat.size;
+      const state = this._fileState.get(filePath) ?? { offset: 0, size: 0 };
+      if (currentSize < state.size) {
+        this._fileState.set(filePath, { offset: 0, size: 0 });
+        state.offset = 0;
+      }
+      if (currentSize === state.offset) continue;
+      const content = (0, import_node_fs5.readFileSync)(filePath, "utf8");
+      const { entries, nextOffset } = def.parse(content, state.offset);
+      this._fileState.set(filePath, { offset: nextOffset, size: currentSize });
+      for (const entry of entries) {
+        const key = def.dedupeKey ? def.dedupeKey(entry) : null;
+        if (key !== null) {
+          const seenForFile = this._seen.get(filePath) ?? /* @__PURE__ */ new Set();
+          if (seenForFile.has(key)) continue;
+          seenForFile.add(key);
+          this._seen.set(filePath, seenForFile);
+        }
+        await def.persist(entry, filePath);
+        processed++;
+      }
+    }
+    return processed;
+  }
+  _expandGlob(pattern) {
+    if (!pattern.includes("*") && !pattern.includes("?")) {
+      return [pattern];
+    }
+    const dir = (0, import_node_path5.dirname)(pattern);
+    const filePattern = (0, import_node_path5.basename)(pattern);
+    if (!(0, import_node_fs5.existsSync)(dir)) return [];
+    const regexStr = filePattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    const regex = new RegExp(`^${regexStr}$`);
+    return (0, import_node_fs5.readdirSync)(dir).filter((f) => regex.test(f)).map((f) => (0, import_node_path5.join)(dir, f));
+  }
+};
+
+// src/render/interpolate.ts
+function interpolate(template, row) {
+  return template.replace(/\{\{([^}]+)\}\}/g, (_, path) => {
+    const parts = path.trim().split(".");
+    let val = row;
+    for (const part of parts) {
+      if (val == null || typeof val !== "object") return "";
+      val = val[part];
+    }
+    return val == null ? "" : String(val);
+  });
+}
+
+// src/render/templates.ts
+function compileRender(def, tableName, schema, adapter) {
+  const { renderFn, templateName, hooks } = _normalizeSpec(def.render);
+  if (renderFn) {
+    if (hooks?.beforeRender) {
+      const bh = hooks.beforeRender;
+      return (rows) => renderFn(bh(rows));
+    }
+    return renderFn;
+  }
+  return (rows) => {
+    const processed = hooks?.beforeRender ? hooks.beforeRender(rows) : rows;
+    const enriched = processed.map((row) => _enrichRow(row, def, schema, adapter));
+    switch (templateName) {
+      case "default-list":
+        return _renderList(enriched, hooks?.formatRow);
+      case "default-table":
+        return _renderTable(enriched);
+      case "default-detail":
+        return _renderDetail(enriched, tableName, schema, hooks?.formatRow);
+      case "default-json":
+        return JSON.stringify(processed, null, 2);
+      default:
+        return "";
+    }
+  };
+}
+function _normalizeSpec(render) {
+  if (typeof render === "function") {
+    return { renderFn: render };
+  }
+  if (typeof render === "string") {
+    return { templateName: render };
+  }
+  const spec = render;
+  return { templateName: spec.template, hooks: spec.hooks };
+}
+function _enrichRow(row, def, schema, adapter) {
+  if (!def.relations) return row;
+  const enriched = { ...row };
+  for (const [relName, rel] of Object.entries(def.relations)) {
+    if (rel.type !== "belongsTo") continue;
+    const fkValue = row[rel.foreignKey];
+    if (fkValue == null) continue;
+    try {
+      const refCol = rel.references ?? schema.getPrimaryKey(rel.table)[0] ?? "id";
+      const relRow = adapter.get(`SELECT * FROM "${rel.table}" WHERE "${refCol}" = ?`, [fkValue]);
+      if (relRow) {
+        enriched[relName] = relRow;
+      }
+    } catch {
+    }
+  }
+  return enriched;
+}
+function _applyFormatRow(row, formatRow) {
+  if (formatRow == null) {
+    return Object.entries(row).map(([k, v]) => `${k}: ${v == null ? "" : String(v)}`).join(", ");
+  }
+  if (typeof formatRow === "function") return formatRow(row);
+  return interpolate(formatRow, row);
+}
+function _renderList(rows, formatRow) {
+  if (rows.length === 0) return "";
+  return rows.map((row) => `- ${_applyFormatRow(row, formatRow)}`).join("\n");
+}
+function _renderTable(rows) {
+  if (rows.length === 0) return "";
+  const firstRow = rows[0];
+  if (!firstRow) return "";
+  const headers = Object.keys(firstRow);
+  const headerRow = `| ${headers.join(" | ")} |`;
+  const separatorRow = `| ${headers.map(() => "---").join(" | ")} |`;
+  const bodyRows = rows.map(
+    (row) => `| ${headers.map((h) => {
+      const v = row[h];
+      return v == null ? "" : String(v);
+    }).join(" | ")} |`
+  ).join("\n");
+  return [headerRow, separatorRow, bodyRows].join("\n");
+}
+function _renderDetail(rows, tableName, schema, formatRow) {
+  if (rows.length === 0) return "";
+  const pkCols = schema.getPrimaryKey(tableName);
+  return rows.map((row) => {
+    const pkVal = pkCols.map((col) => {
+      const v = row[col];
+      return v == null ? "" : String(v);
+    }).join(":");
+    const heading = `## ${pkVal}`;
+    let body;
+    if (formatRow != null) {
+      body = typeof formatRow === "function" ? formatRow(row) : interpolate(formatRow, row);
+    } else {
+      body = Object.entries(row).map(([k, v]) => `${k}: ${v == null ? "" : String(v)}`).join("\n");
+    }
+    return `${heading}
+
+${body}`;
+  }).join("\n\n---\n\n");
+}
+
+// src/config/parser.ts
+var import_node_fs6 = require("fs");
+var import_node_path6 = require("path");
+var import_yaml = require("yaml");
+function parseConfigFile(configPath) {
+  const absPath = (0, import_node_path6.resolve)(configPath);
+  const configDir = (0, import_node_path6.dirname)(absPath);
+  let raw;
+  try {
+    raw = (0, import_node_fs6.readFileSync)(absPath, "utf-8");
+  } catch (e) {
+    throw new Error(`Lattice: cannot read config file at "${absPath}": ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = (0, import_yaml.parse)(raw);
+  } catch (e) {
+    throw new Error(`Lattice: YAML parse error in "${absPath}": ${e.message}`);
+  }
+  return buildParsedConfig(parsed, absPath, configDir);
+}
+function parseConfigString(yamlContent, configDir) {
+  let parsed;
+  try {
+    parsed = (0, import_yaml.parse)(yamlContent);
+  } catch (e) {
+    throw new Error(`Lattice: YAML parse error: ${e.message}`);
+  }
+  return buildParsedConfig(parsed, "<string>", configDir);
+}
+function buildParsedConfig(raw, sourceName, configDir) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `Lattice: config "${sourceName}" must be a YAML object with "db" and "entities" keys`
+    );
+  }
+  const cfg = raw;
+  if (typeof cfg.db !== "string") {
+    throw new Error(`Lattice: config.db must be a string path (got ${typeof cfg.db})`);
+  }
+  if (!cfg.entities || typeof cfg.entities !== "object" || Array.isArray(cfg.entities)) {
+    throw new Error(`Lattice: config.entities must be an object`);
+  }
+  const config = raw;
+  const dbPath = (0, import_node_path6.resolve)(configDir, config.db);
+  const tables = [];
+  for (const [entityName, entityDef] of Object.entries(config.entities)) {
+    const definition = entityToTableDef(entityName, entityDef, configDir);
+    tables.push({ name: entityName, definition });
+  }
+  const entityContexts = parseEntityContexts(config.entityContexts);
+  return { dbPath, tables, entityContexts };
+}
+function entityToTableDef(entityName, entity, configDir) {
+  const rawFields = entity.fields;
+  if (!rawFields || typeof rawFields !== "object" || Array.isArray(rawFields)) {
+    throw new Error(`Lattice: entity "${entityName}" must have a "fields" object`);
+  }
+  const columns = {};
+  const relations = {};
+  let pkFromField;
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    columns[fieldName] = fieldToSqliteSpec(field);
+    if (field.primaryKey) {
+      pkFromField = fieldName;
+    }
+    if (field.ref) {
+      const relName = fieldName.endsWith("_id") ? fieldName.slice(0, -3) : fieldName;
+      relations[relName] = {
+        type: "belongsTo",
+        table: field.ref,
+        foreignKey: fieldName
+      };
+    }
+  }
+  const primaryKey = entity.primaryKey ?? pkFromField;
+  const render = parseEntityRender(entity.render);
+  const outputFile = (0, import_node_path6.resolve)(configDir, entity.outputFile);
+  return {
+    columns,
+    render,
+    outputFile,
+    ...primaryKey !== void 0 ? { primaryKey } : {},
+    ...Object.keys(relations).length > 0 ? { relations } : {}
+  };
+}
+function fieldToSqliteSpec(field) {
+  const parts = [fieldToSqliteBaseType(field.type)];
+  if (field.primaryKey) {
+    parts.push("PRIMARY KEY");
+  } else if (field.required) {
+    parts.push("NOT NULL");
+  }
+  if (field.default !== void 0) {
+    const dv = field.default;
+    if (typeof dv === "string") {
+      parts.push(`DEFAULT '${dv.replace(/'/g, "''")}'`);
+    } else {
+      parts.push(`DEFAULT ${String(dv)}`);
+    }
+  }
+  return parts.join(" ");
+}
+function fieldToSqliteBaseType(type) {
+  switch (type) {
+    case "uuid":
+    case "text":
+    case "datetime":
+    case "date":
+      return "TEXT";
+    case "integer":
+    case "int":
+    case "boolean":
+    case "bool":
+      return "INTEGER";
+    case "real":
+    case "float":
+      return "REAL";
+    case "blob":
+      return "BLOB";
+  }
+}
+function parseEntityRender(render) {
+  if (!render) {
+    return "default-list";
+  }
+  if (typeof render === "string") {
+    return render;
+  }
+  const spec = render;
+  if (spec.formatRow) {
+    return {
+      template: spec.template,
+      hooks: { formatRow: spec.formatRow }
+    };
+  }
+  return spec.template;
+}
+function renderFnForTemplate(templateName) {
+  switch (templateName) {
+    case "default-list":
+      return (rows) => {
+        if (rows.length === 0) return "";
+        return rows.map(
+          (row) => `- ${Object.entries(row).map(([k, v]) => `${k}: ${v == null ? "" : String(v)}`).join(", ")}`
+        ).join("\n");
+      };
+    case "default-table":
+      return (rows) => {
+        if (rows.length === 0) return "";
+        const firstRow = rows[0];
+        if (!firstRow) return "";
+        const headers = Object.keys(firstRow);
+        const headerRow = `| ${headers.join(" | ")} |`;
+        const separatorRow = `| ${headers.map(() => "---").join(" | ")} |`;
+        const bodyRows = rows.map(
+          (row) => `| ${headers.map((h) => {
+            const v = row[h];
+            return v == null ? "" : String(v);
+          }).join(" | ")} |`
+        ).join("\n");
+        return [headerRow, separatorRow, bodyRows].join("\n");
+      };
+    case "default-detail":
+      return (rows) => {
+        if (rows.length === 0) return "";
+        return rows.map((row) => {
+          const body = Object.entries(row).map(([k, v]) => `${k}: ${v == null ? "" : String(v)}`).join("\n");
+          return `## ${String(Object.values(row)[0] ?? "")}
+
+${body}`;
+        }).join("\n\n---\n\n");
+      };
+    case "default-json":
+      return (rows) => JSON.stringify(rows, null, 2);
+    default:
+      return (rows) => JSON.stringify(rows, null, 2);
+  }
+}
+function parseEntitySource(sourceDef) {
+  if (sourceDef === "self") {
+    return { type: "self" };
+  }
+  return sourceDef;
+}
+function extractSlugField(slugTemplate) {
+  const match = /^\{\{(\w+)\}\}$/.exec(slugTemplate);
+  if (match?.[1]) {
+    const field = match[1];
+    return (row) => row[field];
+  }
+  return () => slugTemplate;
+}
+function parseEntityContexts(entityContexts) {
+  if (!entityContexts) return [];
+  const result = [];
+  for (const [tableName, ctxDef] of Object.entries(entityContexts)) {
+    const slugFn = extractSlugField(ctxDef.slug);
+    const files = {};
+    for (const [filename, fileDef] of Object.entries(ctxDef.files)) {
+      files[filename] = {
+        source: parseEntitySource(fileDef.source),
+        render: renderFnForTemplate(fileDef.template),
+        ...fileDef.budget !== void 0 ? { budget: fileDef.budget } : {},
+        ...fileDef.omitIfEmpty !== void 0 ? { omitIfEmpty: fileDef.omitIfEmpty } : {}
+      };
+    }
+    const definition = {
+      slug: slugFn,
+      files,
+      ...ctxDef.directoryRoot !== void 0 ? { directoryRoot: ctxDef.directoryRoot } : {},
+      ...ctxDef.protectedFiles !== void 0 ? { protectedFiles: ctxDef.protectedFiles } : {},
+      ...ctxDef.index !== void 0 ? {
+        index: {
+          outputFile: ctxDef.index.outputFile,
+          render: renderFnForTemplate(ctxDef.index.render)
+        }
+      } : {},
+      ...ctxDef.combined !== void 0 ? { combined: ctxDef.combined } : {}
+    };
+    result.push({ table: tableName, definition });
+  }
+  return result;
+}
+
+// src/lattice.ts
+var Lattice = class {
+  _adapter;
+  _schema;
+  _sanitizer;
+  _render;
+  _loop;
+  _writeback;
+  _initialized = false;
+  /** Cache of actual table columns (from PRAGMA), populated after init(). */
+  _columnCache = /* @__PURE__ */ new Map();
+  _auditHandlers = [];
+  _renderHandlers = [];
+  _writebackHandlers = [];
+  _errorHandlers = [];
+  constructor(pathOrConfig, options = {}) {
+    let dbPath;
+    let configTables;
+    let configEntityContexts;
+    if (typeof pathOrConfig === "string") {
+      dbPath = pathOrConfig;
+    } else {
+      const parsed = parseConfigFile(pathOrConfig.config);
+      dbPath = parsed.dbPath;
+      configTables = [...parsed.tables];
+      configEntityContexts = [...parsed.entityContexts];
+      if (pathOrConfig.options) {
+        options = { ...pathOrConfig.options, ...options };
+      }
+    }
+    const adapterOpts = {};
+    if (options.wal !== void 0) adapterOpts.wal = options.wal;
+    if (options.busyTimeout !== void 0) adapterOpts.busyTimeout = options.busyTimeout;
+    this._adapter = new SQLiteAdapter(dbPath, adapterOpts);
+    this._schema = new SchemaManager();
+    this._sanitizer = new Sanitizer(options.security);
+    this._render = new RenderEngine(this._schema, this._adapter);
+    this._loop = new SyncLoop(this._render);
+    this._writeback = new WritebackPipeline();
+    this._sanitizer.onAudit((event) => {
+      for (const h of this._auditHandlers) h(event);
+    });
+    if (configTables) {
+      for (const { name, definition } of configTables) {
+        this.define(name, definition);
+      }
+    }
+    if (configEntityContexts) {
+      for (const { table, definition } of configEntityContexts) {
+        this.defineEntityContext(table, definition);
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Setup
+  // -------------------------------------------------------------------------
+  define(table, def) {
+    this._assertNotInit("define");
+    const compiledDef = {
+      ...def,
+      render: compileRender(def, table, this._schema, this._adapter)
+    };
+    this._schema.define(table, compiledDef);
+    return this;
+  }
+  defineMulti(name, def) {
+    this._assertNotInit("defineMulti");
+    this._schema.defineMulti(name, def);
+    return this;
+  }
+  defineEntityContext(table, def) {
+    this._assertNotInit("defineEntityContext");
+    this._schema.defineEntityContext(table, def);
+    return this;
+  }
+  defineWriteback(def) {
+    this._writeback.define(def);
+    return this;
+  }
+  init(options = {}) {
+    if (this._initialized) {
+      return Promise.reject(new Error("Lattice: init() has already been called"));
+    }
+    this._adapter.open();
+    this._schema.applySchema(this._adapter);
+    if (options.migrations?.length) {
+      this._schema.applyMigrations(this._adapter, options.migrations);
+    }
+    for (const tableName of this._schema.getTables().keys()) {
+      const rows = this._adapter.all(`PRAGMA table_info("${tableName}")`);
+      this._columnCache.set(tableName, new Set(rows.map((r) => r.name)));
+    }
+    this._initialized = true;
+    return Promise.resolve();
+  }
+  close() {
+    this._adapter.close();
+    this._columnCache.clear();
+    this._initialized = false;
+  }
+  // -------------------------------------------------------------------------
+  // CRUD
+  // -------------------------------------------------------------------------
+  insert(table, row) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(row));
+    const pkCols = this._schema.getPrimaryKey(table);
+    const isDefaultPk = pkCols.length === 1 && pkCols[0] === "id";
+    let rowWithPk;
+    if (isDefaultPk) {
+      const id = sanitized.id ?? (0, import_uuid.v4)();
+      rowWithPk = { ...sanitized, id };
+    } else {
+      rowWithPk = sanitized;
+    }
+    const cols = Object.keys(rowWithPk).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(rowWithPk).map(() => "?").join(", ");
+    const values = Object.values(rowWithPk);
+    this._adapter.run(`INSERT INTO "${table}" (${cols}) VALUES (${placeholders})`, values);
+    const pkCol = pkCols[0] ?? "id";
+    const rawPk = rowWithPk[pkCol];
+    const pkValue = rawPk != null ? String(rawPk) : "";
+    this._sanitizer.emitAudit(table, "insert", pkValue);
+    return Promise.resolve(pkValue);
+  }
+  upsert(table, row) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(row));
+    const pkCols = this._schema.getPrimaryKey(table);
+    const isDefaultPk = pkCols.length === 1 && pkCols[0] === "id";
+    let rowWithPk;
+    if (isDefaultPk) {
+      const id = sanitized.id ?? (0, import_uuid.v4)();
+      rowWithPk = { ...sanitized, id };
+    } else {
+      rowWithPk = sanitized;
+    }
+    const cols = Object.keys(rowWithPk).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(rowWithPk).map(() => "?").join(", ");
+    const conflictCols = pkCols.map((c) => `"${c}"`).join(", ");
+    const updateCols = Object.keys(rowWithPk).filter((c) => !pkCols.includes(c)).map((c) => `"${c}" = excluded."${c}"`).join(", ");
+    const values = Object.values(rowWithPk);
+    this._adapter.run(
+      `INSERT INTO "${table}" (${cols}) VALUES (${placeholders}) ON CONFLICT(${conflictCols}) DO UPDATE SET ${updateCols}`,
+      values
+    );
+    const pkCol = pkCols[0] ?? "id";
+    const rawPk = rowWithPk[pkCol];
+    const pkValue = rawPk != null ? String(rawPk) : "";
+    this._sanitizer.emitAudit(table, "update", pkValue);
+    return Promise.resolve(pkValue);
+  }
+  upsertBy(table, col, val, row) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const existing = this._adapter.get(`SELECT * FROM "${table}" WHERE "${col}" = ?`, [val]);
+    if (existing) {
+      const pkCols = this._schema.getPrimaryKey(table);
+      const pkLookup = pkCols.length === 1 ? String(existing[pkCols[0] ?? "id"]) : Object.fromEntries(pkCols.map((c) => [c, existing[c]]));
+      return this.update(table, pkLookup, row).then(
+        () => typeof pkLookup === "string" ? pkLookup : JSON.stringify(pkLookup)
+      );
+    }
+    return this.insert(table, { ...row, [col]: val });
+  }
+  update(table, id, row) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(row));
+    const setCols = Object.keys(sanitized).map((c) => `"${c}" = ?`).join(", ");
+    const { clause, params: pkParams } = this._pkWhere(table, id);
+    const values = [...Object.values(sanitized), ...pkParams];
+    this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE ${clause}`, values);
+    const auditId = typeof id === "string" ? id : JSON.stringify(id);
+    this._sanitizer.emitAudit(table, "update", auditId);
+    return Promise.resolve();
+  }
+  delete(table, id) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const { clause, params } = this._pkWhere(table, id);
+    this._adapter.run(`DELETE FROM "${table}" WHERE ${clause}`, params);
+    const auditId = typeof id === "string" ? id : JSON.stringify(id);
+    this._sanitizer.emitAudit(table, "delete", auditId);
+    return Promise.resolve();
+  }
+  get(table, id) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const { clause, params } = this._pkWhere(table, id);
+    return Promise.resolve(
+      this._adapter.get(`SELECT * FROM "${table}" WHERE ${clause}`, params) ?? null
+    );
+  }
+  query(table, opts = {}) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const colErr = this._invalidColumnError(table, [
+      ...Object.keys(opts.where ?? {}),
+      ...(opts.filters ?? []).map((f) => f.col),
+      ...opts.orderBy ? [opts.orderBy] : []
+    ]);
+    if (colErr) return colErr;
+    let sql = `SELECT * FROM "${table}"`;
+    const params = [];
+    const whereClauses = [];
+    if (opts.where && Object.keys(opts.where).length > 0) {
+      for (const [col, val] of Object.entries(opts.where)) {
+        whereClauses.push(`"${col}" = ?`);
+        params.push(val);
+      }
+    }
+    if (opts.filters && opts.filters.length > 0) {
+      const { clauses, params: fp } = this._buildFilters(opts.filters);
+      whereClauses.push(...clauses);
+      params.push(...fp);
+    }
+    if (whereClauses.length > 0) {
+      sql += ` WHERE ${whereClauses.join(" AND ")}`;
+    }
+    if (opts.orderBy) {
+      const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+      sql += ` ORDER BY "${opts.orderBy}" ${dir}`;
+    }
+    if (opts.limit !== void 0) {
+      sql += ` LIMIT ${opts.limit.toString()}`;
+    }
+    if (opts.offset !== void 0) {
+      if (opts.limit === void 0) sql += " LIMIT -1";
+      sql += ` OFFSET ${opts.offset.toString()}`;
+    }
+    return Promise.resolve(this._adapter.all(sql, params));
+  }
+  count(table, opts = {}) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const colErr = this._invalidColumnError(table, [
+      ...Object.keys(opts.where ?? {}),
+      ...(opts.filters ?? []).map((f) => f.col)
+    ]);
+    if (colErr) return colErr;
+    let sql = `SELECT COUNT(*) as n FROM "${table}"`;
+    const params = [];
+    const whereClauses = [];
+    if (opts.where && Object.keys(opts.where).length > 0) {
+      for (const [col, val] of Object.entries(opts.where)) {
+        whereClauses.push(`"${col}" = ?`);
+        params.push(val);
+      }
+    }
+    if (opts.filters && opts.filters.length > 0) {
+      const { clauses, params: fp } = this._buildFilters(opts.filters);
+      whereClauses.push(...clauses);
+      params.push(...fp);
+    }
+    if (whereClauses.length > 0) {
+      sql += ` WHERE ${whereClauses.join(" AND ")}`;
+    }
+    const row = this._adapter.get(sql, params);
+    return Promise.resolve(Number(row?.n ?? 0));
+  }
+  // -------------------------------------------------------------------------
+  // Sync
+  // -------------------------------------------------------------------------
+  async render(outputDir) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const result = await this._render.render(outputDir);
+    for (const h of this._renderHandlers) h(result);
+    return result;
+  }
+  async sync(outputDir) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const renderResult = await this._render.render(outputDir);
+    for (const h of this._renderHandlers) h(renderResult);
+    const writebackProcessed = await this._writeback.process();
+    return { ...renderResult, writebackProcessed };
+  }
+  async reconcile(outputDir, options = {}) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const prevManifest = readManifest(outputDir);
+    const renderResult = await this._render.render(outputDir);
+    for (const h of this._renderHandlers) h(renderResult);
+    const newManifest = readManifest(outputDir);
+    const cleanup = this._render.cleanup(outputDir, prevManifest, options, newManifest);
+    return { ...renderResult, cleanup };
+  }
+  watch(outputDir, opts = {}) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const stop = this._loop.watch(outputDir, {
+      ...opts,
+      onRender: (result) => {
+        opts.onRender?.(result);
+        for (const h of this._renderHandlers) h(result);
+      },
+      onError: (err) => {
+        opts.onError?.(err);
+        for (const h of this._errorHandlers) h(err);
+      }
+    });
+    return Promise.resolve(stop);
+  }
+  on(event, handler) {
+    switch (event) {
+      case "audit":
+        this._auditHandlers.push(handler);
+        break;
+      case "render":
+        this._renderHandlers.push(handler);
+        break;
+      case "writeback":
+        this._writebackHandlers.push(
+          handler
+        );
+        break;
+      case "error":
+        this._errorHandlers.push(handler);
+        break;
+    }
+    return this;
+  }
+  // -------------------------------------------------------------------------
+  // Escape hatch
+  // -------------------------------------------------------------------------
+  get db() {
+    return this._adapter.db;
+  }
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+  /**
+   * Filter a sanitized row to only include columns that actually exist in the
+   * table (verified via PRAGMA after init). Unregistered tables (accessed
+   * through the raw `.db` handle) are passed through unchanged.
+   *
+   * This is a defence-in-depth guard: column names from caller-supplied `row`
+   * objects are interpolated into SQL, so stripping unknown keys eliminates
+   * any theoretical injection vector from crafted object keys.
+   */
+  _filterToSchemaColumns(table, row) {
+    const cols = this._columnCache.get(table);
+    if (!cols) return row;
+    const keys = Object.keys(row);
+    if (keys.every((k) => cols.has(k))) return row;
+    return Object.fromEntries(keys.filter((k) => cols.has(k)).map((k) => [k, row[k]]));
+  }
+  /**
+   * Build the WHERE clause and params for a PK lookup.
+   * - `string` → matches against the table's first PK column.
+   * - `Record` → matches every PK column; all must be present in the object.
+   */
+  _pkWhere(table, id) {
+    const pkCols = this._schema.getPrimaryKey(table);
+    if (typeof id === "string") {
+      const firstCol = pkCols[0] ?? "id";
+      return { clause: `"${firstCol}" = ?`, params: [id] };
+    }
+    const clauses = pkCols.map((col) => `"${col}" = ?`);
+    const params = pkCols.map((col) => id[col]);
+    return { clause: clauses.join(" AND "), params };
+  }
+  /**
+   * Convert Filter objects into SQL clause strings and bound params.
+   * An `in` filter with an empty array is silently ignored (produces no clause).
+   */
+  _buildFilters(filters) {
+    const clauses = [];
+    const params = [];
+    for (const f of filters) {
+      const col = `"${f.col}"`;
+      switch (f.op) {
+        case "eq":
+          clauses.push(`${col} = ?`);
+          params.push(f.val);
+          break;
+        case "ne":
+          clauses.push(`${col} != ?`);
+          params.push(f.val);
+          break;
+        case "gt":
+          clauses.push(`${col} > ?`);
+          params.push(f.val);
+          break;
+        case "gte":
+          clauses.push(`${col} >= ?`);
+          params.push(f.val);
+          break;
+        case "lt":
+          clauses.push(`${col} < ?`);
+          params.push(f.val);
+          break;
+        case "lte":
+          clauses.push(`${col} <= ?`);
+          params.push(f.val);
+          break;
+        case "like":
+          clauses.push(`${col} LIKE ?`);
+          params.push(f.val);
+          break;
+        case "in": {
+          const list = f.val;
+          if (Array.isArray(list) && list.length > 0) {
+            clauses.push(`${col} IN (${list.map(() => "?").join(", ")})`);
+            params.push(...list);
+          }
+          break;
+        }
+        case "isNull":
+          clauses.push(`${col} IS NULL`);
+          break;
+        case "isNotNull":
+          clauses.push(`${col} IS NOT NULL`);
+          break;
+      }
+    }
+    return { clauses, params };
+  }
+  /** Returns a rejected Promise if not initialized; null if ready. */
+  _notInitError() {
+    if (!this._initialized) {
+      return Promise.reject(
+        new Error("Lattice: call await db.init() before using CRUD or sync methods")
+      );
+    }
+    return null;
+  }
+  /**
+   * Returns a rejected Promise if any of the given column names are not present
+   * in the table's schema; null if all columns are valid.
+   *
+   * Applied on the read path (query/count) to validate WHERE and filter column
+   * names before they are interpolated into SQL. The write path strips unknown
+   * columns via _filterToSchemaColumns; the read path rejects instead to avoid
+   * silently discarding intended filter conditions.
+   *
+   * Unregistered tables (accessed via the raw `.db` handle) are passed through.
+   */
+  _invalidColumnError(table, cols) {
+    const known = this._columnCache.get(table);
+    if (!known) return null;
+    for (const col of cols) {
+      if (!known.has(col)) {
+        return Promise.reject(
+          new Error(`Lattice: unknown column "${col}" in table "${table}"`)
+        );
+      }
+    }
+    return null;
+  }
+  _assertNotInit(method) {
+    if (this._initialized) {
+      throw new Error(`Lattice: ${method}() must be called before init()`);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Lattice,
+  manifestPath,
+  parseConfigFile,
+  parseConfigString,
+  readManifest,
+  writeManifest
+});