latticesql 0.5.0

package/dist/cli.js

@@ -0,0 +1,1880 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { resolve as resolve3, dirname as dirname5 } from "path";
+import { readFileSync as readFileSync5 } from "fs";
+import { parse as parse2 } from "yaml";
+
+// src/codegen/generate.ts
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, dirname as dirname2, resolve as resolve2 } from "path";
+
+// src/config/parser.ts
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { parse } from "yaml";
+function parseConfigFile(configPath) {
+  const absPath = resolve(configPath);
+  const configDir = dirname(absPath);
+  let raw;
+  try {
+    raw = readFileSync(absPath, "utf-8");
+  } catch (e) {
+    throw new Error(`Lattice: cannot read config file at "${absPath}": ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = parse(raw);
+  } catch (e) {
+    throw new Error(`Lattice: YAML parse error in "${absPath}": ${e.message}`);
+  }
+  return buildParsedConfig(parsed, absPath, 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 = 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 = 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/codegen/generate.ts
+function generateAll(opts) {
+  const { config, configDir, outDir, scaffold } = opts;
+  const filesWritten = [];
+  mkdirSync(outDir, { recursive: true });
+  mkdirSync(join(outDir, "migrations"), { recursive: true });
+  const tsPath = join(outDir, "types.ts");
+  writeFileSync(tsPath, generateTypes(config), "utf-8");
+  filesWritten.push(tsPath);
+  const sqlPath = join(outDir, "migrations", "0001_initial.sql");
+  writeFileSync(sqlPath, generateMigration(config), "utf-8");
+  filesWritten.push(sqlPath);
+  if (scaffold) {
+    for (const [, entityDef] of Object.entries(config.entities)) {
+      const outPath = resolve2(configDir, entityDef.outputFile);
+      if (!existsSync(outPath)) {
+        mkdirSync(dirname2(outPath), { recursive: true });
+        writeFileSync(outPath, "", "utf-8");
+        filesWritten.push(outPath);
+      }
+    }
+  }
+  return { filesWritten };
+}
+function generateTypes(config) {
+  const lines = ["// Auto-generated by `lattice generate`. Do not edit manually.", ""];
+  for (const [entityName, entityDef] of Object.entries(config.entities)) {
+    const typeName = toPascalCase(entityName);
+    lines.push(`export interface ${typeName} {`);
+    for (const [fieldName, field] of Object.entries(entityDef.fields)) {
+      const tsType = toTsType(field.type);
+      const optional = !field.primaryKey && !field.required;
+      const mark = optional ? "?" : "";
+      const comment = field.ref ? `  // \u2192 ${field.ref}` : "";
+      lines.push(`  ${fieldName}${mark}: ${tsType};${comment}`);
+    }
+    lines.push("}", "");
+  }
+  return lines.join("\n");
+}
+function generateMigration(config) {
+  const lines = ["-- Auto-generated by `lattice generate`. Do not edit manually.", ""];
+  for (const [entityName, entityDef] of Object.entries(config.entities)) {
+    lines.push(`CREATE TABLE IF NOT EXISTS "${entityName}" (`);
+    const colDefs = entityColDefs(entityDef);
+    lines.push(colDefs.map((c) => `  ${c}`).join(",\n"));
+    lines.push(");", "");
+  }
+  return lines.join("\n");
+}
+function entityColDefs(entity) {
+  return Object.entries(entity.fields).map(([fieldName, field]) => {
+    const parts = [`"${fieldName}"`, 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;
+      parts.push(
+        typeof dv === "string" ? `DEFAULT '${dv.replace(/'/g, "''")}'` : `DEFAULT ${String(dv)}`
+      );
+    }
+    return parts.join(" ");
+  });
+}
+function toTsType(type) {
+  switch (type) {
+    case "uuid":
+    case "text":
+    case "datetime":
+    case "date":
+      return "string";
+    case "integer":
+    case "int":
+    case "real":
+    case "float":
+      return "number";
+    case "boolean":
+    case "bool":
+      return "boolean";
+    case "blob":
+      return "Buffer";
+  }
+}
+function toPascalCase(s) {
+  return s.replace(/(^|[_-])([a-z])/g, (_, __, c) => c.toUpperCase());
+}
+
+// src/lattice.ts
+import { v4 as uuidv4 } from "uuid";
+
+// src/lifecycle/manifest.ts
+import { join as join3 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+
+// src/render/writer.ts
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, renameSync, existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { createHash } from "crypto";
+import { dirname as dirname3, join as join2 } from "path";
+import { tmpdir } from "os";
+import { randomBytes } from "crypto";
+function atomicWrite(filePath, content) {
+  const dir = dirname3(filePath);
+  mkdirSync2(dir, { recursive: true });
+  const currentHash = existingHash(filePath);
+  const newHash = contentHash(content);
+  if (currentHash === newHash) return false;
+  const tmp = join2(tmpdir(), `lattice-${randomBytes(8).toString("hex")}.tmp`);
+  writeFileSync2(tmp, content, "utf8");
+  renameSync(tmp, filePath);
+  return true;
+}
+function existingHash(filePath) {
+  if (!existsSync2(filePath)) return null;
+  try {
+    return contentHash(readFileSync2(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function contentHash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+// src/lifecycle/manifest.ts
+function manifestPath(outputDir) {
+  return join3(outputDir, ".lattice", "manifest.json");
+}
+function readManifest(outputDir) {
+  const path = manifestPath(outputDir);
+  if (!existsSync3(path)) return null;
+  try {
+    return JSON.parse(readFileSync3(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeManifest(outputDir, manifest) {
+  atomicWrite(manifestPath(outputDir), JSON.stringify(manifest, null, 2));
+}
+
+// src/db/sqlite.ts
+import Database from "better-sqlite3";
+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 Database(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
+import { join as join5 } from "path";
+import { mkdirSync as mkdirSync3 } from "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
+import { join as join4 } from "path";
+import { existsSync as existsSync4, readdirSync, unlinkSync, rmdirSync, statSync } from "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 = join4(outputDir, directoryRoot);
+    if (!existsSync4(rootPath)) continue;
+    if (options.removeOrphanedDirectories !== false && !def.directory) {
+      let actualDirs;
+      try {
+        actualDirs = readdirSync(rootPath).filter((name) => {
+          try {
+            return statSync(join4(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 = join4(rootPath, dirName);
+        const managedFiles = entry.entities[dirName] ?? [];
+        for (const filename of managedFiles) {
+          if (globalProtected.has(filename)) continue;
+          const filePath = join4(entityDir, filename);
+          if (!existsSync4(filePath)) continue;
+          if (!options.dryRun) unlinkSync(filePath);
+          options.onOrphan?.(filePath, "file");
+          result.filesRemoved.push(filePath);
+        }
+        let remaining;
+        try {
+          remaining = existsSync4(entityDir) ? readdirSync(entityDir) : [];
+        } catch {
+          remaining = [];
+        }
+        if (remaining.length === 0) {
+          if (!options.dryRun) {
+            try {
+              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 : join4(rootPath, slug);
+        if (!entityDir || !existsSync4(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 = join4(entityDir, filename);
+          if (!existsSync4(filePath)) continue;
+          if (!options.dryRun) 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 = join5(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 = join5(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 = join5(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 ? join5(outputDir, def.directory(entityRow)) : join5(outputDir, directoryRoot, slug);
+        mkdirSync3(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 = join5(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 = join5(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
+import { readFileSync as readFileSync4, statSync as statSync2, existsSync as existsSync5, readdirSync as readdirSync2 } from "fs";
+import { join as join6, dirname as dirname4, basename } from "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 (!existsSync5(filePath)) continue;
+      const stat = statSync2(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 = readFileSync4(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 = dirname4(pattern);
+    const filePattern = basename(pattern);
+    if (!existsSync5(dir)) return [];
+    const regexStr = filePattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    const regex = new RegExp(`^${regexStr}$`);
+    return readdirSync2(dir).filter((f) => regex.test(f)).map((f) => join6(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/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 ?? uuidv4();
+      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 ?? uuidv4();
+      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()`);
+    }
+  }
+};
+
+// src/cli.ts
+function parseArgs(argv) {
+  let command;
+  let config = "./lattice.config.yml";
+  let out = "./generated";
+  let output = "./context";
+  let scaffold = false;
+  let help = false;
+  let version = false;
+  let dryRun = false;
+  let noOrphanDirs = false;
+  let noOrphanFiles = false;
+  const protectedFiles = [];
+  let interval = 5e3;
+  let cleanup = false;
+  let i = 0;
+  if (argv[0] !== void 0 && !argv[0].startsWith("-")) {
+    command = argv[0];
+    i = 1;
+  }
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+    } else if (arg === "--version" || arg === "-v") {
+      version = true;
+    } else if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
+      i++;
+      config = argv[i] ?? config;
+    } else if ((arg === "--out" || arg === "-o") && i + 1 < argv.length) {
+      i++;
+      out = argv[i] ?? out;
+    } else if ((arg === "--output" || arg === "--output-dir") && i + 1 < argv.length) {
+      i++;
+      output = argv[i] ?? output;
+    } else if (arg === "--scaffold") {
+      scaffold = true;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--no-orphan-dirs") {
+      noOrphanDirs = true;
+    } else if (arg === "--no-orphan-files") {
+      noOrphanFiles = true;
+    } else if (arg === "--protected" && i + 1 < argv.length) {
+      i++;
+      const csv = argv[i] ?? "";
+      protectedFiles.push(...csv.split(",").filter(Boolean));
+    } else if (arg === "--interval" && i + 1 < argv.length) {
+      i++;
+      const parsed = parseInt(argv[i] ?? "5000", 10);
+      if (!isNaN(parsed)) interval = parsed;
+    } else if (arg === "--cleanup") {
+      cleanup = true;
+    }
+    i++;
+  }
+  return {
+    command,
+    config,
+    out,
+    output,
+    scaffold,
+    help,
+    version,
+    dryRun,
+    noOrphanDirs,
+    noOrphanFiles,
+    protected: protectedFiles,
+    interval,
+    cleanup
+  };
+}
+function printHelp() {
+  console.log(
+    [
+      "lattice \u2014 latticesql CLI",
+      "",
+      "Usage:",
+      "  lattice <command> [options]",
+      "",
+      "Commands:",
+      "  generate    Generate TypeScript types, SQL migration, and scaffold files",
+      "  render      One-shot context generation (writes entity context directories)",
+      "  reconcile   Render + cleanup orphaned entity directories and files",
+      "  status      Dry-run reconcile \u2014 show what would change without writing",
+      "  watch       Poll for changes and re-render on each cycle",
+      "",
+      "Options (generate):",
+      "  --config, -c <path>    Path to config file (default: ./lattice.config.yml)",
+      "  --out, -o <dir>        Output directory for generated files (default: ./generated)",
+      "  --scaffold             Also create empty scaffold render output files",
+      "",
+      "Options (render):",
+      "  --config, -c <path>    Path to config file (default: ./lattice.config.yml)",
+      "  --output <dir>         Output directory for rendered context (default: ./context)",
+      "",
+      "Options (reconcile):",
+      "  --config, -c <path>    Path to config file (default: ./lattice.config.yml)",
+      "  --output <dir>         Output directory for rendered context (default: ./context)",
+      "  --dry-run              Report orphans but do not delete anything",
+      "  --no-orphan-dirs       Skip removal of orphaned entity directories",
+      "  --no-orphan-files      Skip removal of orphaned files inside entity dirs",
+      "  --protected <csv>      Comma-separated list of protected filenames",
+      "",
+      "Options (status):",
+      "  --config, -c <path>    Path to config file (default: ./lattice.config.yml)",
+      "  --output <dir>         Output directory for rendered context (default: ./context)",
+      "",
+      "Options (watch):",
+      "  --config, -c <path>    Path to config file (default: ./lattice.config.yml)",
+      "  --output <dir>         Output directory for rendered context (default: ./context)",
+      "  --interval <ms>        Poll interval in milliseconds (default: 5000)",
+      "  --cleanup              Enable orphan cleanup after each render cycle",
+      "  --no-orphan-dirs       Skip removal of orphaned entity directories (with --cleanup)",
+      "  --no-orphan-files      Skip removal of orphaned files inside entity dirs (with --cleanup)",
+      "  --protected <csv>      Comma-separated list of protected filenames (with --cleanup)",
+      "",
+      "Options (global):",
+      "  --help, -h             Show this help message",
+      "  --version, -v          Print the version number"
+    ].join("\n")
+  );
+}
+function printVersion() {
+  try {
+    const pkgPath = new URL("../package.json", import.meta.url).pathname;
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
+    console.log(pkg.version);
+  } catch {
+    console.log("unknown");
+  }
+}
+function runGenerate(args) {
+  const configPath = resolve3(args.config);
+  let raw;
+  try {
+    raw = readFileSync5(configPath, "utf-8");
+  } catch {
+    console.error(`Error: cannot read config file at "${configPath}"`);
+    process.exit(1);
+  }
+  let config;
+  try {
+    config = parse2(raw);
+  } catch (e) {
+    console.error(`Error: YAML parse error in "${configPath}": ${e.message}`);
+    process.exit(1);
+  }
+  if (!config.entities) {
+    console.error('Error: config must have an "entities" key');
+    process.exit(1);
+  }
+  const configDir = dirname5(configPath);
+  const outDir = resolve3(args.out);
+  try {
+    const result = generateAll({ config, configDir, outDir, scaffold: args.scaffold });
+    console.log(`Generated ${String(result.filesWritten.length)} file(s):`);
+    for (const f of result.filesWritten) {
+      console.log(`  \u2713 ${f}`);
+    }
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+async function runRender(args) {
+  const outputDir = resolve3(args.output);
+  let parsed;
+  try {
+    parsed = parseConfigFile(resolve3(args.config));
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+  const db = new Lattice({ config: resolve3(args.config) });
+  try {
+    await db.init();
+    const start = Date.now();
+    const result = await db.render(outputDir);
+    const durationMs = Date.now() - start;
+    console.log(`Rendered ${String(result.filesWritten.length)} files in ${String(durationMs)}ms`);
+    for (const f of result.filesWritten) {
+      console.log(`  \u2713 ${f}`);
+    }
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+  void parsed;
+}
+async function runReconcile(args, isDryRun) {
+  const outputDir = resolve3(args.output);
+  const db = new Lattice({ config: resolve3(args.config) });
+  try {
+    await db.init();
+    const start = Date.now();
+    const reconcileOpts = {
+      dryRun: isDryRun,
+      removeOrphanedDirectories: !args.noOrphanDirs,
+      removeOrphanedFiles: !args.noOrphanFiles
+    };
+    if (args.protected.length > 0) {
+      reconcileOpts.protectedFiles = args.protected;
+    }
+    const result = await db.reconcile(outputDir, reconcileOpts);
+    const durationMs = Date.now() - start;
+    if (isDryRun) {
+      console.log("DRY RUN \u2014 no changes made");
+    }
+    console.log(`Rendered ${String(result.filesWritten.length)} files in ${String(durationMs)}ms`);
+    for (const f of result.filesWritten) {
+      console.log(`  \u2713 ${f}`);
+    }
+    const { cleanup } = result;
+    const totalRemoved = cleanup.directoriesRemoved.length + cleanup.filesRemoved.length;
+    if (totalRemoved > 0 || cleanup.directoriesSkipped.length > 0) {
+      console.log(
+        `Cleanup: removed ${String(cleanup.directoriesRemoved.length)} directories, ${String(cleanup.filesRemoved.length)} files`
+      );
+      for (const d of cleanup.directoriesRemoved) {
+        console.log(`  \u2713 Removed ${d}`);
+      }
+      for (const f of cleanup.filesRemoved) {
+        console.log(`  \u2713 Removed ${f}`);
+      }
+      for (const d of cleanup.directoriesSkipped) {
+        console.log(`  \u2717 Left ${d} (protected files remain)`);
+      }
+    }
+    if (cleanup.warnings.length > 0) {
+      console.log(`Warnings: ${String(cleanup.warnings.length)}`);
+      for (const w of cleanup.warnings) {
+        console.warn(`  ! ${w}`);
+      }
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}
+function formatTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  const hh = String(now.getHours()).padStart(2, "0");
+  const mm = String(now.getMinutes()).padStart(2, "0");
+  const ss = String(now.getSeconds()).padStart(2, "0");
+  return `${hh}:${mm}:${ss}`;
+}
+async function runWatch(args) {
+  const outputDir = resolve3(args.output);
+  const db = new Lattice({ config: resolve3(args.config) });
+  try {
+    await db.init();
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+  const cleanupOpts = args.cleanup ? {
+    removeOrphanedDirectories: !args.noOrphanDirs,
+    removeOrphanedFiles: !args.noOrphanFiles,
+    ...args.protected.length > 0 ? { protectedFiles: args.protected } : {}
+  } : void 0;
+  const stop = await db.watch(outputDir, {
+    interval: args.interval,
+    onRender: (result) => {
+      console.log(
+        `[${formatTimestamp()}] Rendered ${String(result.filesWritten.length)} files in ${String(result.durationMs)}ms`
+      );
+    },
+    onError: (err) => {
+      console.error(`[${formatTimestamp()}] Error: ${err.message}`);
+    },
+    ...cleanupOpts !== void 0 ? { cleanup: cleanupOpts } : {},
+    ...cleanupOpts !== void 0 ? {
+      onCleanup: (result) => {
+        console.log(
+          `[${formatTimestamp()}] Cleanup: removed ${String(result.directoriesRemoved.length)} dirs, ${String(result.filesRemoved.length)} files`
+        );
+      }
+    } : {}
+  });
+  const shutdown = () => {
+    stop();
+    db.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.version) {
+    printVersion();
+    return;
+  }
+  if (args.help || args.command === void 0) {
+    printHelp();
+    process.exit(args.command === void 0 && !args.help ? 1 : 0);
+  }
+  switch (args.command) {
+    case "generate":
+      runGenerate(args);
+      break;
+    case "render":
+      void runRender(args);
+      break;
+    case "reconcile":
+      void runReconcile(args, args.dryRun);
+      break;
+    case "status":
+      void runReconcile(args, true);
+      break;
+    case "watch":
+      void runWatch(args);
+      break;
+    default:
+      console.error(`Unknown command: ${args.command}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+main();