latticesql 0.9.0 → 0.11.0

package/README.md

@@ -456,6 +456,44 @@ context/
 
 The `softDelete: true` shorthand is equivalent to `filters: [{ col: 'deleted_at', op: 'isNull' }]`.
 
+#### Junction column projection (v0.8+)
+
+`manyToMany` sources can include columns from the junction table in results:
+
+```typescript
+{
+  type: 'manyToMany',
+  junctionTable: 'agent_projects',
+  localKey: 'agent_id',
+  remoteKey: 'project_id',
+  remoteTable: 'projects',
+  junctionColumns: [
+    'source',                            // included as-is
+    { col: 'role', as: 'agent_role' },   // aliased
+  ],
+}
+// Each result row includes both remote table columns AND junction columns
+```
+
+#### Multi-column ORDER BY (v0.8+)
+
+`orderBy` accepts an array for multi-column sorting:
+
+```typescript
+{
+  type: 'hasMany',
+  table: 'events',
+  foreignKey: 'project_id',
+  orderBy: [
+    { col: 'severity' },                  // ASC by default
+    { col: 'timestamp', dir: 'desc' },    // DESC
+  ],
+  limit: 20,
+}
+```
+
+The string form (`orderBy: 'name'`) still works for single-column sorting.
+
 #### sourceDefaults (v0.6+)
 
 Set default query options for all relationship sources in an entity context:
@@ -504,10 +542,100 @@ Starts with the entity's own row and attaches related data as JSON string fields
 }
 ```
 
+#### Entity render templates (v0.9+)
+
+`EntityFileSpec.render` accepts declarative template objects in addition to functions. Three built-in templates:
+
+**entity-table** — heading + GFM table:
+```typescript
+render: {
+  template: 'entity-table',
+  heading: 'Skills',
+  columns: [
+    { key: 'name', header: 'Name' },
+    { key: 'level', header: 'Level', format: (v) => String(v || '—') },
+  ],
+  emptyMessage: '*No skills assigned.*',
+  beforeRender: (rows) => rows.filter(r => r.active),  // optional
+}
+```
+
+**entity-profile** — heading + field-value pairs + enriched JSON sections:
+```typescript
+render: {
+  template: 'entity-profile',
+  heading: (r) => r.name as string,
+  fields: [
+    { key: 'status', label: 'Status' },
+    { key: 'role', label: 'Role' },
+  ],
+  sections: [
+    { key: 'skills', heading: 'Skills', render: 'table',
+      columns: [{ key: 'name', header: 'Name' }] },
+    { key: 'projects', heading: 'Projects', render: 'list',
+      formatItem: (p) => `${p.name} (${p.status})` },
+  ],
+  frontmatter: (r) => ({ agent: r.name as string }),
+}
+```
+
+**entity-sections** — per-row sections with metadata + body:
+```typescript
+render: {
+  template: 'entity-sections',
+  heading: 'Rules',
+  perRow: {
+    heading: (r) => r.title as string,
+    metadata: [
+      { key: 'scope', label: 'Scope' },
+      { key: 'category', label: 'Category' },
+    ],
+    body: (r) => r.rule_text as string,
+  },
+  emptyMessage: '*No rules defined.*',
+}
+```
+
+All templates auto-prepend a read-only header and YAML frontmatter. Functions still work — the union type is backward compatible.
+
 See [docs/entity-context.md](./docs/entity-context.md) for the complete guide.
 
 ---
 
+### `defineWriteHook()` (v0.10+)
+
+```typescript
+db.defineWriteHook(hook: WriteHook): this
+```
+
+Register a post-write lifecycle hook that fires after `insert()`, `update()`, or `delete()` operations. Useful for denormalization, fan-out, computed fields, and audit logging.
+
+```typescript
+db.defineWriteHook({
+  table: 'agents',
+  on: ['insert', 'update'],
+  watchColumns: ['team_id', 'division'],  // only fire when these change
+  handler: (ctx) => {
+    // ctx.table, ctx.op, ctx.row, ctx.pk, ctx.changedColumns
+    console.log(`${ctx.op} on ${ctx.table}: ${ctx.pk}`);
+    denormalizeRelatedData(ctx.pk, ctx.row);
+  },
+});
+```
+
+**Options:**
+
+| Field | Type | Description |
+|---|---|---|
+| `table` | `string` | Table to watch |
+| `on` | `Array<'insert' \| 'update' \| 'delete'>` | Operations that trigger the hook |
+| `watchColumns` | `string[]` (optional) | Only fire on update when these columns changed |
+| `handler` | `(ctx: WriteHookContext) => void` | Synchronous handler |
+
+Hook errors are caught and routed to error handlers — they never crash the caller. Multiple hooks per table are supported.
+
+---
+
 ### `defineWriteback()`
 
 ```typescript

package/dist/cli.js

@@ -1389,6 +1389,7 @@ var Lattice = class {
   _renderHandlers = [];
   _writebackHandlers = [];
   _errorHandlers = [];
+  _writeHooks = [];
   constructor(pathOrConfig, options = {}) {
     let dbPath;
     let configTables;
@@ -1448,6 +1449,14 @@ var Lattice = class {
     this._schema.defineEntityContext(table, def);
     return this;
   }
+  /**
+   * Register a write hook that fires after insert/update/delete operations.
+   * Hooks run synchronously after the DB write and audit emit.
+   */
+  defineWriteHook(hook) {
+    this._writeHooks.push(hook);
+    return this;
+  }
   defineWriteback(def) {
     this._writeback.define(def);
     return this;
@@ -1497,6 +1506,7 @@ var Lattice = class {
     const rawPk = rowWithPk[pkCol];
     const pkValue = rawPk != null ? String(rawPk) : "";
     this._sanitizer.emitAudit(table, "insert", pkValue);
+    this._fireWriteHooks(table, "insert", rowWithPk, pkValue);
     return Promise.resolve(pkValue);
   }
   upsert(table, row) {
@@ -1550,6 +1560,7 @@ var Lattice = class {
     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);
+    this._fireWriteHooks(table, "update", sanitized, auditId, Object.keys(sanitized));
     return Promise.resolve();
   }
   delete(table, id) {
@@ -1559,6 +1570,7 @@ var Lattice = class {
     this._adapter.run(`DELETE FROM "${table}" WHERE ${clause}`, params);
     const auditId = typeof id === "string" ? id : JSON.stringify(id);
     this._sanitizer.emitAudit(table, "delete", auditId);
+    this._fireWriteHooks(table, "delete", { id: auditId }, auditId);
     return Promise.resolve();
   }
   get(table, id) {
@@ -1569,6 +1581,160 @@ var Lattice = class {
       this._adapter.get(`SELECT * FROM "${table}" WHERE ${clause}`, params) ?? null
     );
   }
+  // -------------------------------------------------------------------------
+  // Generic CRUD — works on ANY table (v0.11+)
+  // -------------------------------------------------------------------------
+  /**
+   * Upsert a record by natural key. If a non-deleted record with the given
+   * natural key exists, update it. Otherwise insert with a new UUID.
+   * Auto-handles `org_id`, `updated_at`, `deleted_at`, `source_file`, `source_hash`.
+   */
+  upsertByNaturalKey(table, naturalKeyCol, naturalKeyVal, data, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(data));
+    const withConventions = { ...sanitized };
+    if (cols.has("updated_at")) withConventions.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    if (opts?.sourceFile && cols.has("source_file")) withConventions.source_file = opts.sourceFile;
+    if (opts?.sourceHash && cols.has("source_hash")) withConventions.source_hash = opts.sourceHash;
+    const existing = this._adapter.get(
+      `SELECT id FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+      [naturalKeyVal]
+    );
+    if (existing) {
+      const entries = Object.entries(withConventions).filter(([k]) => k !== "id");
+      if (entries.length === 0) return Promise.resolve(existing.id);
+      const setCols = entries.map(([k]) => `"${k}" = ?`).join(", ");
+      this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE id = ?`, [...entries.map(([, v]) => v), existing.id]);
+      this._fireWriteHooks(table, "update", withConventions, existing.id, Object.keys(sanitized));
+      return Promise.resolve(existing.id);
+    }
+    const id = sanitized.id ?? uuidv4();
+    const insertData = { ...withConventions, id, [naturalKeyCol]: naturalKeyVal };
+    if (opts?.orgId && cols.has("org_id") && !insertData.org_id) insertData.org_id = opts.orgId;
+    if (cols.has("deleted_at")) insertData.deleted_at = null;
+    if (cols.has("created_at") && !insertData.created_at) insertData.created_at = (/* @__PURE__ */ new Date()).toISOString();
+    const filtered = this._filterToSchemaColumns(table, insertData);
+    const colNames = Object.keys(filtered).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(filtered).map(() => "?").join(", ");
+    this._adapter.run(`INSERT INTO "${table}" (${colNames}) VALUES (${placeholders})`, Object.values(filtered));
+    this._fireWriteHooks(table, "insert", filtered, id);
+    return Promise.resolve(id);
+  }
+  /**
+   * Sparse update by natural key — only writes non-null fields on an existing record.
+   * Returns true if a row was found and updated.
+   */
+  enrichByNaturalKey(table, naturalKeyCol, naturalKeyVal, data) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const existing = this._adapter.get(
+      `SELECT id FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+      [naturalKeyVal]
+    );
+    if (!existing) return Promise.resolve(false);
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(data));
+    const entries = Object.entries(sanitized).filter(([k, v]) => v !== null && v !== void 0 && k !== "id");
+    if (entries.length === 0) return Promise.resolve(true);
+    const cols = this._ensureColumnCache(table);
+    const withTs = [...entries];
+    if (cols.has("updated_at")) withTs.push(["updated_at", (/* @__PURE__ */ new Date()).toISOString()]);
+    const setCols = withTs.map(([k]) => `"${k}" = ?`).join(", ");
+    this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE id = ?`, [...withTs.map(([, v]) => v), existing.id]);
+    this._fireWriteHooks(table, "update", Object.fromEntries(entries), existing.id, entries.map(([k]) => k));
+    return Promise.resolve(true);
+  }
+  /**
+   * Soft-delete records from a source file whose natural key is NOT in the given set.
+   * Returns count of rows soft-deleted.
+   */
+  softDeleteMissing(table, naturalKeyCol, sourceFile, currentKeys) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    if (currentKeys.length === 0) return Promise.resolve(0);
+    const placeholders = currentKeys.map(() => "?").join(", ");
+    const countRow = this._adapter.get(
+      `SELECT COUNT(*) as cnt FROM "${table}"
+       WHERE source_file = ? AND "${naturalKeyCol}" NOT IN (${placeholders})
+       AND (deleted_at IS NULL OR deleted_at = '')`,
+      [sourceFile, ...currentKeys]
+    );
+    const count = countRow?.cnt ?? 0;
+    if (count > 0) {
+      this._adapter.run(
+        `UPDATE "${table}" SET deleted_at = datetime('now'), updated_at = datetime('now')
+         WHERE source_file = ? AND "${naturalKeyCol}" NOT IN (${placeholders})
+         AND (deleted_at IS NULL OR deleted_at = '')`,
+        [sourceFile, ...currentKeys]
+      );
+    }
+    return Promise.resolve(count);
+  }
+  /**
+   * Get all non-deleted rows from a table, ordered by the given column.
+   * Works on any table, not just defined ones.
+   */
+  getActive(table, orderBy = "name") {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const hasDeletedAt = cols.has("deleted_at");
+    const where = hasDeletedAt ? ` WHERE deleted_at IS NULL` : "";
+    const order = cols.has(orderBy) ? ` ORDER BY "${orderBy}"` : "";
+    return Promise.resolve(this._adapter.all(`SELECT * FROM "${table}"${where}${order}`));
+  }
+  /**
+   * Count non-deleted rows in a table.
+   */
+  countActive(table) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const hasDeletedAt = cols.has("deleted_at");
+    const where = hasDeletedAt ? ` WHERE deleted_at IS NULL` : "";
+    const row = this._adapter.get(`SELECT COUNT(*) as cnt FROM "${table}"${where}`);
+    return Promise.resolve(row.cnt);
+  }
+  /**
+   * Lookup a single row by natural key (non-deleted).
+   */
+  getByNaturalKey(table, naturalKeyCol, naturalKeyVal) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    return Promise.resolve(
+      this._adapter.get(
+        `SELECT * FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+        [naturalKeyVal]
+      ) ?? null
+    );
+  }
+  /**
+   * Insert a row into a junction table. Uses INSERT OR IGNORE by default
+   * (idempotent). Pass `{ upsert: true }` for INSERT OR REPLACE.
+   */
+  link(junctionTable, data, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const filtered = this._filterToSchemaColumns(junctionTable, data);
+    const colNames = Object.keys(filtered).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(filtered).map(() => "?").join(", ");
+    const verb = opts?.upsert ? "INSERT OR REPLACE" : "INSERT OR IGNORE";
+    this._adapter.run(`${verb} INTO "${junctionTable}" (${colNames}) VALUES (${placeholders})`, Object.values(filtered));
+    return Promise.resolve();
+  }
+  /**
+   * Delete rows from a junction table matching all given conditions.
+   */
+  unlink(junctionTable, conditions) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const entries = Object.entries(conditions);
+    if (entries.length === 0) return Promise.resolve();
+    const where = entries.map(([k]) => `"${k}" = ?`).join(" AND ");
+    this._adapter.run(`DELETE FROM "${junctionTable}" WHERE ${where}`, entries.map(([, v]) => v));
+    return Promise.resolve();
+  }
   query(table, opts = {}) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -1717,9 +1883,19 @@ var Lattice = class {
    * objects are interpolated into SQL, so stripping unknown keys eliminates
    * any theoretical injection vector from crafted object keys.
    */
+  /** Lazily populate column cache for tables not registered via define(). */
+  _ensureColumnCache(table) {
+    let cols = this._columnCache.get(table);
+    if (!cols) {
+      const rows = this._adapter.all(`PRAGMA table_info("${table}")`);
+      cols = new Set(rows.map((r) => r.name));
+      if (cols.size > 0) this._columnCache.set(table, cols);
+    }
+    return cols;
+  }
   _filterToSchemaColumns(table, row) {
-    const cols = this._columnCache.get(table);
-    if (!cols) return row;
+    const cols = this._ensureColumnCache(table);
+    if (!cols || cols.size === 0) 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]]));
@@ -1796,6 +1972,22 @@ var Lattice = class {
     return { clauses, params };
   }
   /** Returns a rejected Promise if not initialized; null if ready. */
+  _fireWriteHooks(table, op, row, pk, changedColumns) {
+    for (const hook of this._writeHooks) {
+      if (hook.table !== table) continue;
+      if (!hook.on.includes(op)) continue;
+      if (op === "update" && hook.watchColumns && changedColumns) {
+        if (!hook.watchColumns.some((c) => changedColumns.includes(c))) continue;
+      }
+      try {
+        const ctx = { table, op, row, pk };
+        if (changedColumns) ctx.changedColumns = changedColumns;
+        hook.handler(ctx);
+      } catch (err) {
+        for (const h of this._errorHandlers) h(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
   _notInitError() {
     if (!this._initialized) {
       return Promise.reject(

package/dist/index.cjs

@@ -1363,6 +1363,7 @@ var Lattice = class {
   _renderHandlers = [];
   _writebackHandlers = [];
   _errorHandlers = [];
+  _writeHooks = [];
   constructor(pathOrConfig, options = {}) {
     let dbPath;
     let configTables;
@@ -1422,6 +1423,14 @@ var Lattice = class {
     this._schema.defineEntityContext(table, def);
     return this;
   }
+  /**
+   * Register a write hook that fires after insert/update/delete operations.
+   * Hooks run synchronously after the DB write and audit emit.
+   */
+  defineWriteHook(hook) {
+    this._writeHooks.push(hook);
+    return this;
+  }
   defineWriteback(def) {
     this._writeback.define(def);
     return this;
@@ -1471,6 +1480,7 @@ var Lattice = class {
     const rawPk = rowWithPk[pkCol];
     const pkValue = rawPk != null ? String(rawPk) : "";
     this._sanitizer.emitAudit(table, "insert", pkValue);
+    this._fireWriteHooks(table, "insert", rowWithPk, pkValue);
     return Promise.resolve(pkValue);
   }
   upsert(table, row) {
@@ -1524,6 +1534,7 @@ var Lattice = class {
     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);
+    this._fireWriteHooks(table, "update", sanitized, auditId, Object.keys(sanitized));
     return Promise.resolve();
   }
   delete(table, id) {
@@ -1533,6 +1544,7 @@ var Lattice = class {
     this._adapter.run(`DELETE FROM "${table}" WHERE ${clause}`, params);
     const auditId = typeof id === "string" ? id : JSON.stringify(id);
     this._sanitizer.emitAudit(table, "delete", auditId);
+    this._fireWriteHooks(table, "delete", { id: auditId }, auditId);
     return Promise.resolve();
   }
   get(table, id) {
@@ -1543,6 +1555,160 @@ var Lattice = class {
       this._adapter.get(`SELECT * FROM "${table}" WHERE ${clause}`, params) ?? null
     );
   }
+  // -------------------------------------------------------------------------
+  // Generic CRUD — works on ANY table (v0.11+)
+  // -------------------------------------------------------------------------
+  /**
+   * Upsert a record by natural key. If a non-deleted record with the given
+   * natural key exists, update it. Otherwise insert with a new UUID.
+   * Auto-handles `org_id`, `updated_at`, `deleted_at`, `source_file`, `source_hash`.
+   */
+  upsertByNaturalKey(table, naturalKeyCol, naturalKeyVal, data, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(data));
+    const withConventions = { ...sanitized };
+    if (cols.has("updated_at")) withConventions.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    if (opts?.sourceFile && cols.has("source_file")) withConventions.source_file = opts.sourceFile;
+    if (opts?.sourceHash && cols.has("source_hash")) withConventions.source_hash = opts.sourceHash;
+    const existing = this._adapter.get(
+      `SELECT id FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+      [naturalKeyVal]
+    );
+    if (existing) {
+      const entries = Object.entries(withConventions).filter(([k]) => k !== "id");
+      if (entries.length === 0) return Promise.resolve(existing.id);
+      const setCols = entries.map(([k]) => `"${k}" = ?`).join(", ");
+      this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE id = ?`, [...entries.map(([, v]) => v), existing.id]);
+      this._fireWriteHooks(table, "update", withConventions, existing.id, Object.keys(sanitized));
+      return Promise.resolve(existing.id);
+    }
+    const id = sanitized.id ?? (0, import_uuid.v4)();
+    const insertData = { ...withConventions, id, [naturalKeyCol]: naturalKeyVal };
+    if (opts?.orgId && cols.has("org_id") && !insertData.org_id) insertData.org_id = opts.orgId;
+    if (cols.has("deleted_at")) insertData.deleted_at = null;
+    if (cols.has("created_at") && !insertData.created_at) insertData.created_at = (/* @__PURE__ */ new Date()).toISOString();
+    const filtered = this._filterToSchemaColumns(table, insertData);
+    const colNames = Object.keys(filtered).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(filtered).map(() => "?").join(", ");
+    this._adapter.run(`INSERT INTO "${table}" (${colNames}) VALUES (${placeholders})`, Object.values(filtered));
+    this._fireWriteHooks(table, "insert", filtered, id);
+    return Promise.resolve(id);
+  }
+  /**
+   * Sparse update by natural key — only writes non-null fields on an existing record.
+   * Returns true if a row was found and updated.
+   */
+  enrichByNaturalKey(table, naturalKeyCol, naturalKeyVal, data) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const existing = this._adapter.get(
+      `SELECT id FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+      [naturalKeyVal]
+    );
+    if (!existing) return Promise.resolve(false);
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(data));
+    const entries = Object.entries(sanitized).filter(([k, v]) => v !== null && v !== void 0 && k !== "id");
+    if (entries.length === 0) return Promise.resolve(true);
+    const cols = this._ensureColumnCache(table);
+    const withTs = [...entries];
+    if (cols.has("updated_at")) withTs.push(["updated_at", (/* @__PURE__ */ new Date()).toISOString()]);
+    const setCols = withTs.map(([k]) => `"${k}" = ?`).join(", ");
+    this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE id = ?`, [...withTs.map(([, v]) => v), existing.id]);
+    this._fireWriteHooks(table, "update", Object.fromEntries(entries), existing.id, entries.map(([k]) => k));
+    return Promise.resolve(true);
+  }
+  /**
+   * Soft-delete records from a source file whose natural key is NOT in the given set.
+   * Returns count of rows soft-deleted.
+   */
+  softDeleteMissing(table, naturalKeyCol, sourceFile, currentKeys) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    if (currentKeys.length === 0) return Promise.resolve(0);
+    const placeholders = currentKeys.map(() => "?").join(", ");
+    const countRow = this._adapter.get(
+      `SELECT COUNT(*) as cnt FROM "${table}"
+       WHERE source_file = ? AND "${naturalKeyCol}" NOT IN (${placeholders})
+       AND (deleted_at IS NULL OR deleted_at = '')`,
+      [sourceFile, ...currentKeys]
+    );
+    const count = countRow?.cnt ?? 0;
+    if (count > 0) {
+      this._adapter.run(
+        `UPDATE "${table}" SET deleted_at = datetime('now'), updated_at = datetime('now')
+         WHERE source_file = ? AND "${naturalKeyCol}" NOT IN (${placeholders})
+         AND (deleted_at IS NULL OR deleted_at = '')`,
+        [sourceFile, ...currentKeys]
+      );
+    }
+    return Promise.resolve(count);
+  }
+  /**
+   * Get all non-deleted rows from a table, ordered by the given column.
+   * Works on any table, not just defined ones.
+   */
+  getActive(table, orderBy = "name") {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const hasDeletedAt = cols.has("deleted_at");
+    const where = hasDeletedAt ? ` WHERE deleted_at IS NULL` : "";
+    const order = cols.has(orderBy) ? ` ORDER BY "${orderBy}"` : "";
+    return Promise.resolve(this._adapter.all(`SELECT * FROM "${table}"${where}${order}`));
+  }
+  /**
+   * Count non-deleted rows in a table.
+   */
+  countActive(table) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const hasDeletedAt = cols.has("deleted_at");
+    const where = hasDeletedAt ? ` WHERE deleted_at IS NULL` : "";
+    const row = this._adapter.get(`SELECT COUNT(*) as cnt FROM "${table}"${where}`);
+    return Promise.resolve(row.cnt);
+  }
+  /**
+   * Lookup a single row by natural key (non-deleted).
+   */
+  getByNaturalKey(table, naturalKeyCol, naturalKeyVal) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    return Promise.resolve(
+      this._adapter.get(
+        `SELECT * FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+        [naturalKeyVal]
+      ) ?? null
+    );
+  }
+  /**
+   * Insert a row into a junction table. Uses INSERT OR IGNORE by default
+   * (idempotent). Pass `{ upsert: true }` for INSERT OR REPLACE.
+   */
+  link(junctionTable, data, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const filtered = this._filterToSchemaColumns(junctionTable, data);
+    const colNames = Object.keys(filtered).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(filtered).map(() => "?").join(", ");
+    const verb = opts?.upsert ? "INSERT OR REPLACE" : "INSERT OR IGNORE";
+    this._adapter.run(`${verb} INTO "${junctionTable}" (${colNames}) VALUES (${placeholders})`, Object.values(filtered));
+    return Promise.resolve();
+  }
+  /**
+   * Delete rows from a junction table matching all given conditions.
+   */
+  unlink(junctionTable, conditions) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const entries = Object.entries(conditions);
+    if (entries.length === 0) return Promise.resolve();
+    const where = entries.map(([k]) => `"${k}" = ?`).join(" AND ");
+    this._adapter.run(`DELETE FROM "${junctionTable}" WHERE ${where}`, entries.map(([, v]) => v));
+    return Promise.resolve();
+  }
   query(table, opts = {}) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -1691,9 +1857,19 @@ var Lattice = class {
    * objects are interpolated into SQL, so stripping unknown keys eliminates
    * any theoretical injection vector from crafted object keys.
    */
+  /** Lazily populate column cache for tables not registered via define(). */
+  _ensureColumnCache(table) {
+    let cols = this._columnCache.get(table);
+    if (!cols) {
+      const rows = this._adapter.all(`PRAGMA table_info("${table}")`);
+      cols = new Set(rows.map((r) => r.name));
+      if (cols.size > 0) this._columnCache.set(table, cols);
+    }
+    return cols;
+  }
   _filterToSchemaColumns(table, row) {
-    const cols = this._columnCache.get(table);
-    if (!cols) return row;
+    const cols = this._ensureColumnCache(table);
+    if (!cols || cols.size === 0) 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]]));
@@ -1770,6 +1946,22 @@ var Lattice = class {
     return { clauses, params };
   }
   /** Returns a rejected Promise if not initialized; null if ready. */
+  _fireWriteHooks(table, op, row, pk, changedColumns) {
+    for (const hook of this._writeHooks) {
+      if (hook.table !== table) continue;
+      if (!hook.on.includes(op)) continue;
+      if (op === "update" && hook.watchColumns && changedColumns) {
+        if (!hook.watchColumns.some((c) => changedColumns.includes(c))) continue;
+      }
+      try {
+        const ctx = { table, op, row, pk };
+        if (changedColumns) ctx.changedColumns = changedColumns;
+        hook.handler(ctx);
+      } catch (err) {
+        for (const h of this._errorHandlers) h(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
   _notInitError() {
     if (!this._initialized) {
       return Promise.reject(

package/dist/index.d.cts

@@ -749,6 +749,107 @@ interface AuditEvent {
     id: string;
     timestamp: string;
 }
+/**
+ * Options for {@link Lattice.upsertByNaturalKey}.
+ */
+interface UpsertByNaturalKeyOptions {
+    /** Source file path for change tracking (stored in `source_file` column if present). */
+    sourceFile?: string;
+    /** Content hash of the source (stored in `source_hash` column if present). */
+    sourceHash?: string;
+    /** Organization ID — auto-set on insert when the table has an `org_id` column and data lacks it. */
+    orgId?: string;
+}
+/**
+ * Options for {@link Lattice.link}.
+ */
+interface LinkOptions {
+    /** Use INSERT OR REPLACE instead of INSERT OR IGNORE. Set true when junction has updateable columns. */
+    upsert?: boolean;
+}
+/**
+ * Result from {@link Lattice.seed}.
+ */
+interface SeedResult {
+    upserted: number;
+    linked: number;
+    softDeleted: number;
+}
+/**
+ * Link specification for {@link SeedConfig}.
+ */
+interface SeedLinkSpec {
+    /** Junction table name. */
+    junction: string;
+    /** FK column in the junction that points to the linked entity. */
+    foreignKey: string;
+    /** Column on the target table used to resolve names to IDs. */
+    resolveBy: string;
+    /** Target table name (defaults to the link key). */
+    resolveTable?: string;
+    /** Additional static columns to set on each junction row. */
+    extras?: Record<string, unknown>;
+}
+/**
+ * Configuration for {@link Lattice.seed}.
+ */
+interface SeedConfig {
+    /** Array of records to seed (caller loads from YAML/JSON). */
+    data: Record<string, unknown>[];
+    /** Target table. */
+    table: string;
+    /** Column used as the natural key for upserting. */
+    naturalKey: string;
+    /** Source file for soft-delete tracking. */
+    sourceFile?: string;
+    /** Content hash. */
+    sourceHash?: string;
+    /** Junction table links — key is the field name on each data record containing an array of names. */
+    linkTo?: Record<string, SeedLinkSpec>;
+    /** Soft-delete records not in data. */
+    softDeleteMissing?: boolean;
+    /** Organization ID for org-scoped tables. */
+    orgId?: string;
+}
+/**
+ * Context passed to write hook handlers.
+ */
+interface WriteHookContext {
+    /** Table that was modified. */
+    table: string;
+    /** The operation that triggered the hook. */
+    op: 'insert' | 'update' | 'delete';
+    /** The row data (for insert: full row; for update: changed fields; for delete: { id }). */
+    row: Row;
+    /** Primary key value(s) of the affected row. */
+    pk: string;
+    /** For updates: the column names that were changed. */
+    changedColumns?: string[];
+}
+/**
+ * A write hook fires after insert/update/delete operations.
+ *
+ * @example
+ * ```ts
+ * db.defineWriteHook({
+ *   table: 'agents',
+ *   on: ['insert', 'update'],
+ *   watchColumns: ['team_id'],
+ *   handler: (ctx) => { denormalizeTeamFields(ctx.pk); },
+ * });
+ * ```
+ */
+interface WriteHook {
+    /** Table the hook fires on. */
+    table: string;
+    /** Operations that trigger the hook. */
+    on: Array<'insert' | 'update' | 'delete'>;
+    /** Only fire on update when these columns changed. Omit = fire on any change. */
+    watchColumns?: string[];
+    /** Handler function. Runs synchronously after the DB write. */
+    handler: (ctx: WriteHookContext) => void;
+}
+
 interface ReconcileOptions {
     /** Remove entity directories whose slug is no longer in the DB. Default: true. */
     removeOrphanedDirectories?: boolean;
@@ -801,10 +902,16 @@ declare class Lattice {
     private readonly _renderHandlers;
     private readonly _writebackHandlers;
     private readonly _errorHandlers;
+    private readonly _writeHooks;
     constructor(pathOrConfig: string | LatticeConfigInput, options?: LatticeOptions);
     define(table: string, def: TableDefinition): this;
     defineMulti(name: string, def: MultiTableDefinition): this;
     defineEntityContext(table: string, def: EntityContextDefinition): this;
+    /**
+     * Register a write hook that fires after insert/update/delete operations.
+     * Hooks run synchronously after the DB write and audit emit.
+     */
+    defineWriteHook(hook: WriteHook): this;
     defineWriteback(def: WritebackDefinition): this;
     init(options?: InitOptions): Promise<void>;
     close(): void;
@@ -814,6 +921,44 @@ declare class Lattice {
     update(table: string, id: PkLookup, row: Partial<Row>): Promise<void>;
     delete(table: string, id: PkLookup): Promise<void>;
     get(table: string, id: PkLookup): Promise<Row | null>;
+    /**
+     * Upsert a record by natural key. If a non-deleted record with the given
+     * natural key exists, update it. Otherwise insert with a new UUID.
+     * Auto-handles `org_id`, `updated_at`, `deleted_at`, `source_file`, `source_hash`.
+     */
+    upsertByNaturalKey(table: string, naturalKeyCol: string, naturalKeyVal: string, data: Row, opts?: UpsertByNaturalKeyOptions): Promise<string>;
+    /**
+     * Sparse update by natural key — only writes non-null fields on an existing record.
+     * Returns true if a row was found and updated.
+     */
+    enrichByNaturalKey(table: string, naturalKeyCol: string, naturalKeyVal: string, data: Row): Promise<boolean>;
+    /**
+     * Soft-delete records from a source file whose natural key is NOT in the given set.
+     * Returns count of rows soft-deleted.
+     */
+    softDeleteMissing(table: string, naturalKeyCol: string, sourceFile: string, currentKeys: string[]): Promise<number>;
+    /**
+     * Get all non-deleted rows from a table, ordered by the given column.
+     * Works on any table, not just defined ones.
+     */
+    getActive(table: string, orderBy?: string): Promise<Row[]>;
+    /**
+     * Count non-deleted rows in a table.
+     */
+    countActive(table: string): Promise<number>;
+    /**
+     * Lookup a single row by natural key (non-deleted).
+     */
+    getByNaturalKey(table: string, naturalKeyCol: string, naturalKeyVal: string): Promise<Row | null>;
+    /**
+     * Insert a row into a junction table. Uses INSERT OR IGNORE by default
+     * (idempotent). Pass `{ upsert: true }` for INSERT OR REPLACE.
+     */
+    link(junctionTable: string, data: Row, opts?: LinkOptions): Promise<void>;
+    /**
+     * Delete rows from a junction table matching all given conditions.
+     */
+    unlink(junctionTable: string, conditions: Row): Promise<void>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
     count(table: string, opts?: CountOptions): Promise<number>;
     render(outputDir: string): Promise<RenderResult>;
@@ -837,6 +982,8 @@ declare class Lattice {
      * objects are interpolated into SQL, so stripping unknown keys eliminates
      * any theoretical injection vector from crafted object keys.
      */
+    /** Lazily populate column cache for tables not registered via define(). */
+    private _ensureColumnCache;
     private _filterToSchemaColumns;
     /**
      * Build the WHERE clause and params for a PK lookup.
@@ -850,6 +997,7 @@ declare class Lattice {
      */
     private _buildFilters;
     /** Returns a rejected Promise if not initialized; null if ready. */
+    private _fireWriteHooks;
     private _notInitError;
     /**
      * Returns a rejected Promise if any of the given column names are not present
@@ -1305,4 +1453,4 @@ declare function createReadOnlyHeader(options?: ReadOnlyHeaderOptions): string;
  */
 declare const READ_ONLY_HEADER: string;
 
-export { type ApplyWriteResult, type AuditEvent, type BelongsToRelation, type BelongsToSource, type BuiltinTemplateName, type CleanupOptions, type CleanupResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type Filter, type FilterOp, type HasManyRelation, type HasManySource, type InitOptions, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type ManyToManySource, type MarkdownTableColumn, type Migration, type MultiTableDefinition, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, frontmatter, generateEntryId, generateWriteEntryId, manifestPath, markdownTable, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };
+export { type ApplyWriteResult, type AuditEvent, type BelongsToRelation, type BelongsToSource, type BuiltinTemplateName, type CleanupOptions, type CleanupResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type Filter, type FilterOp, type HasManyRelation, type HasManySource, type InitOptions, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type ManyToManySource, type MarkdownTableColumn, type Migration, type MultiTableDefinition, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SeedConfig, type SeedLinkSpec, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type UpsertByNaturalKeyOptions, type WatchOptions, type WriteHook, type WriteHookContext, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, frontmatter, generateEntryId, generateWriteEntryId, manifestPath, markdownTable, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };

package/dist/index.d.ts

@@ -749,6 +749,107 @@ interface AuditEvent {
     id: string;
     timestamp: string;
 }
+/**
+ * Options for {@link Lattice.upsertByNaturalKey}.
+ */
+interface UpsertByNaturalKeyOptions {
+    /** Source file path for change tracking (stored in `source_file` column if present). */
+    sourceFile?: string;
+    /** Content hash of the source (stored in `source_hash` column if present). */
+    sourceHash?: string;
+    /** Organization ID — auto-set on insert when the table has an `org_id` column and data lacks it. */
+    orgId?: string;
+}
+/**
+ * Options for {@link Lattice.link}.
+ */
+interface LinkOptions {
+    /** Use INSERT OR REPLACE instead of INSERT OR IGNORE. Set true when junction has updateable columns. */
+    upsert?: boolean;
+}
+/**
+ * Result from {@link Lattice.seed}.
+ */
+interface SeedResult {
+    upserted: number;
+    linked: number;
+    softDeleted: number;
+}
+/**
+ * Link specification for {@link SeedConfig}.
+ */
+interface SeedLinkSpec {
+    /** Junction table name. */
+    junction: string;
+    /** FK column in the junction that points to the linked entity. */
+    foreignKey: string;
+    /** Column on the target table used to resolve names to IDs. */
+    resolveBy: string;
+    /** Target table name (defaults to the link key). */
+    resolveTable?: string;
+    /** Additional static columns to set on each junction row. */
+    extras?: Record<string, unknown>;
+}
+/**
+ * Configuration for {@link Lattice.seed}.
+ */
+interface SeedConfig {
+    /** Array of records to seed (caller loads from YAML/JSON). */
+    data: Record<string, unknown>[];
+    /** Target table. */
+    table: string;
+    /** Column used as the natural key for upserting. */
+    naturalKey: string;
+    /** Source file for soft-delete tracking. */
+    sourceFile?: string;
+    /** Content hash. */
+    sourceHash?: string;
+    /** Junction table links — key is the field name on each data record containing an array of names. */
+    linkTo?: Record<string, SeedLinkSpec>;
+    /** Soft-delete records not in data. */
+    softDeleteMissing?: boolean;
+    /** Organization ID for org-scoped tables. */
+    orgId?: string;
+}
+/**
+ * Context passed to write hook handlers.
+ */
+interface WriteHookContext {
+    /** Table that was modified. */
+    table: string;
+    /** The operation that triggered the hook. */
+    op: 'insert' | 'update' | 'delete';
+    /** The row data (for insert: full row; for update: changed fields; for delete: { id }). */
+    row: Row;
+    /** Primary key value(s) of the affected row. */
+    pk: string;
+    /** For updates: the column names that were changed. */
+    changedColumns?: string[];
+}
+/**
+ * A write hook fires after insert/update/delete operations.
+ *
+ * @example
+ * ```ts
+ * db.defineWriteHook({
+ *   table: 'agents',
+ *   on: ['insert', 'update'],
+ *   watchColumns: ['team_id'],
+ *   handler: (ctx) => { denormalizeTeamFields(ctx.pk); },
+ * });
+ * ```
+ */
+interface WriteHook {
+    /** Table the hook fires on. */
+    table: string;
+    /** Operations that trigger the hook. */
+    on: Array<'insert' | 'update' | 'delete'>;
+    /** Only fire on update when these columns changed. Omit = fire on any change. */
+    watchColumns?: string[];
+    /** Handler function. Runs synchronously after the DB write. */
+    handler: (ctx: WriteHookContext) => void;
+}
+
 interface ReconcileOptions {
     /** Remove entity directories whose slug is no longer in the DB. Default: true. */
     removeOrphanedDirectories?: boolean;
@@ -801,10 +902,16 @@ declare class Lattice {
     private readonly _renderHandlers;
     private readonly _writebackHandlers;
     private readonly _errorHandlers;
+    private readonly _writeHooks;
     constructor(pathOrConfig: string | LatticeConfigInput, options?: LatticeOptions);
     define(table: string, def: TableDefinition): this;
     defineMulti(name: string, def: MultiTableDefinition): this;
     defineEntityContext(table: string, def: EntityContextDefinition): this;
+    /**
+     * Register a write hook that fires after insert/update/delete operations.
+     * Hooks run synchronously after the DB write and audit emit.
+     */
+    defineWriteHook(hook: WriteHook): this;
     defineWriteback(def: WritebackDefinition): this;
     init(options?: InitOptions): Promise<void>;
     close(): void;
@@ -814,6 +921,44 @@ declare class Lattice {
     update(table: string, id: PkLookup, row: Partial<Row>): Promise<void>;
     delete(table: string, id: PkLookup): Promise<void>;
     get(table: string, id: PkLookup): Promise<Row | null>;
+    /**
+     * Upsert a record by natural key. If a non-deleted record with the given
+     * natural key exists, update it. Otherwise insert with a new UUID.
+     * Auto-handles `org_id`, `updated_at`, `deleted_at`, `source_file`, `source_hash`.
+     */
+    upsertByNaturalKey(table: string, naturalKeyCol: string, naturalKeyVal: string, data: Row, opts?: UpsertByNaturalKeyOptions): Promise<string>;
+    /**
+     * Sparse update by natural key — only writes non-null fields on an existing record.
+     * Returns true if a row was found and updated.
+     */
+    enrichByNaturalKey(table: string, naturalKeyCol: string, naturalKeyVal: string, data: Row): Promise<boolean>;
+    /**
+     * Soft-delete records from a source file whose natural key is NOT in the given set.
+     * Returns count of rows soft-deleted.
+     */
+    softDeleteMissing(table: string, naturalKeyCol: string, sourceFile: string, currentKeys: string[]): Promise<number>;
+    /**
+     * Get all non-deleted rows from a table, ordered by the given column.
+     * Works on any table, not just defined ones.
+     */
+    getActive(table: string, orderBy?: string): Promise<Row[]>;
+    /**
+     * Count non-deleted rows in a table.
+     */
+    countActive(table: string): Promise<number>;
+    /**
+     * Lookup a single row by natural key (non-deleted).
+     */
+    getByNaturalKey(table: string, naturalKeyCol: string, naturalKeyVal: string): Promise<Row | null>;
+    /**
+     * Insert a row into a junction table. Uses INSERT OR IGNORE by default
+     * (idempotent). Pass `{ upsert: true }` for INSERT OR REPLACE.
+     */
+    link(junctionTable: string, data: Row, opts?: LinkOptions): Promise<void>;
+    /**
+     * Delete rows from a junction table matching all given conditions.
+     */
+    unlink(junctionTable: string, conditions: Row): Promise<void>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
     count(table: string, opts?: CountOptions): Promise<number>;
     render(outputDir: string): Promise<RenderResult>;
@@ -837,6 +982,8 @@ declare class Lattice {
      * objects are interpolated into SQL, so stripping unknown keys eliminates
      * any theoretical injection vector from crafted object keys.
      */
+    /** Lazily populate column cache for tables not registered via define(). */
+    private _ensureColumnCache;
     private _filterToSchemaColumns;
     /**
      * Build the WHERE clause and params for a PK lookup.
@@ -850,6 +997,7 @@ declare class Lattice {
      */
     private _buildFilters;
     /** Returns a rejected Promise if not initialized; null if ready. */
+    private _fireWriteHooks;
     private _notInitError;
     /**
      * Returns a rejected Promise if any of the given column names are not present
@@ -1305,4 +1453,4 @@ declare function createReadOnlyHeader(options?: ReadOnlyHeaderOptions): string;
  */
 declare const READ_ONLY_HEADER: string;
 
-export { type ApplyWriteResult, type AuditEvent, type BelongsToRelation, type BelongsToSource, type BuiltinTemplateName, type CleanupOptions, type CleanupResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type Filter, type FilterOp, type HasManyRelation, type HasManySource, type InitOptions, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type ManyToManySource, type MarkdownTableColumn, type Migration, type MultiTableDefinition, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, frontmatter, generateEntryId, generateWriteEntryId, manifestPath, markdownTable, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };
+export { type ApplyWriteResult, type AuditEvent, type BelongsToRelation, type BelongsToSource, type BuiltinTemplateName, type CleanupOptions, type CleanupResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type Filter, type FilterOp, type HasManyRelation, type HasManySource, type InitOptions, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type ManyToManySource, type MarkdownTableColumn, type Migration, type MultiTableDefinition, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SeedConfig, type SeedLinkSpec, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type UpsertByNaturalKeyOptions, type WatchOptions, type WriteHook, type WriteHookContext, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, frontmatter, generateEntryId, generateWriteEntryId, manifestPath, markdownTable, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };

package/dist/index.js

@@ -1307,6 +1307,7 @@ var Lattice = class {
   _renderHandlers = [];
   _writebackHandlers = [];
   _errorHandlers = [];
+  _writeHooks = [];
   constructor(pathOrConfig, options = {}) {
     let dbPath;
     let configTables;
@@ -1366,6 +1367,14 @@ var Lattice = class {
     this._schema.defineEntityContext(table, def);
     return this;
   }
+  /**
+   * Register a write hook that fires after insert/update/delete operations.
+   * Hooks run synchronously after the DB write and audit emit.
+   */
+  defineWriteHook(hook) {
+    this._writeHooks.push(hook);
+    return this;
+  }
   defineWriteback(def) {
     this._writeback.define(def);
     return this;
@@ -1415,6 +1424,7 @@ var Lattice = class {
     const rawPk = rowWithPk[pkCol];
     const pkValue = rawPk != null ? String(rawPk) : "";
     this._sanitizer.emitAudit(table, "insert", pkValue);
+    this._fireWriteHooks(table, "insert", rowWithPk, pkValue);
     return Promise.resolve(pkValue);
   }
   upsert(table, row) {
@@ -1468,6 +1478,7 @@ var Lattice = class {
     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);
+    this._fireWriteHooks(table, "update", sanitized, auditId, Object.keys(sanitized));
     return Promise.resolve();
   }
   delete(table, id) {
@@ -1477,6 +1488,7 @@ var Lattice = class {
     this._adapter.run(`DELETE FROM "${table}" WHERE ${clause}`, params);
     const auditId = typeof id === "string" ? id : JSON.stringify(id);
     this._sanitizer.emitAudit(table, "delete", auditId);
+    this._fireWriteHooks(table, "delete", { id: auditId }, auditId);
     return Promise.resolve();
   }
   get(table, id) {
@@ -1487,6 +1499,160 @@ var Lattice = class {
       this._adapter.get(`SELECT * FROM "${table}" WHERE ${clause}`, params) ?? null
     );
   }
+  // -------------------------------------------------------------------------
+  // Generic CRUD — works on ANY table (v0.11+)
+  // -------------------------------------------------------------------------
+  /**
+   * Upsert a record by natural key. If a non-deleted record with the given
+   * natural key exists, update it. Otherwise insert with a new UUID.
+   * Auto-handles `org_id`, `updated_at`, `deleted_at`, `source_file`, `source_hash`.
+   */
+  upsertByNaturalKey(table, naturalKeyCol, naturalKeyVal, data, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(data));
+    const withConventions = { ...sanitized };
+    if (cols.has("updated_at")) withConventions.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    if (opts?.sourceFile && cols.has("source_file")) withConventions.source_file = opts.sourceFile;
+    if (opts?.sourceHash && cols.has("source_hash")) withConventions.source_hash = opts.sourceHash;
+    const existing = this._adapter.get(
+      `SELECT id FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+      [naturalKeyVal]
+    );
+    if (existing) {
+      const entries = Object.entries(withConventions).filter(([k]) => k !== "id");
+      if (entries.length === 0) return Promise.resolve(existing.id);
+      const setCols = entries.map(([k]) => `"${k}" = ?`).join(", ");
+      this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE id = ?`, [...entries.map(([, v]) => v), existing.id]);
+      this._fireWriteHooks(table, "update", withConventions, existing.id, Object.keys(sanitized));
+      return Promise.resolve(existing.id);
+    }
+    const id = sanitized.id ?? uuidv4();
+    const insertData = { ...withConventions, id, [naturalKeyCol]: naturalKeyVal };
+    if (opts?.orgId && cols.has("org_id") && !insertData.org_id) insertData.org_id = opts.orgId;
+    if (cols.has("deleted_at")) insertData.deleted_at = null;
+    if (cols.has("created_at") && !insertData.created_at) insertData.created_at = (/* @__PURE__ */ new Date()).toISOString();
+    const filtered = this._filterToSchemaColumns(table, insertData);
+    const colNames = Object.keys(filtered).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(filtered).map(() => "?").join(", ");
+    this._adapter.run(`INSERT INTO "${table}" (${colNames}) VALUES (${placeholders})`, Object.values(filtered));
+    this._fireWriteHooks(table, "insert", filtered, id);
+    return Promise.resolve(id);
+  }
+  /**
+   * Sparse update by natural key — only writes non-null fields on an existing record.
+   * Returns true if a row was found and updated.
+   */
+  enrichByNaturalKey(table, naturalKeyCol, naturalKeyVal, data) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const existing = this._adapter.get(
+      `SELECT id FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+      [naturalKeyVal]
+    );
+    if (!existing) return Promise.resolve(false);
+    const sanitized = this._filterToSchemaColumns(table, this._sanitizer.sanitizeRow(data));
+    const entries = Object.entries(sanitized).filter(([k, v]) => v !== null && v !== void 0 && k !== "id");
+    if (entries.length === 0) return Promise.resolve(true);
+    const cols = this._ensureColumnCache(table);
+    const withTs = [...entries];
+    if (cols.has("updated_at")) withTs.push(["updated_at", (/* @__PURE__ */ new Date()).toISOString()]);
+    const setCols = withTs.map(([k]) => `"${k}" = ?`).join(", ");
+    this._adapter.run(`UPDATE "${table}" SET ${setCols} WHERE id = ?`, [...withTs.map(([, v]) => v), existing.id]);
+    this._fireWriteHooks(table, "update", Object.fromEntries(entries), existing.id, entries.map(([k]) => k));
+    return Promise.resolve(true);
+  }
+  /**
+   * Soft-delete records from a source file whose natural key is NOT in the given set.
+   * Returns count of rows soft-deleted.
+   */
+  softDeleteMissing(table, naturalKeyCol, sourceFile, currentKeys) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    if (currentKeys.length === 0) return Promise.resolve(0);
+    const placeholders = currentKeys.map(() => "?").join(", ");
+    const countRow = this._adapter.get(
+      `SELECT COUNT(*) as cnt FROM "${table}"
+       WHERE source_file = ? AND "${naturalKeyCol}" NOT IN (${placeholders})
+       AND (deleted_at IS NULL OR deleted_at = '')`,
+      [sourceFile, ...currentKeys]
+    );
+    const count = countRow?.cnt ?? 0;
+    if (count > 0) {
+      this._adapter.run(
+        `UPDATE "${table}" SET deleted_at = datetime('now'), updated_at = datetime('now')
+         WHERE source_file = ? AND "${naturalKeyCol}" NOT IN (${placeholders})
+         AND (deleted_at IS NULL OR deleted_at = '')`,
+        [sourceFile, ...currentKeys]
+      );
+    }
+    return Promise.resolve(count);
+  }
+  /**
+   * Get all non-deleted rows from a table, ordered by the given column.
+   * Works on any table, not just defined ones.
+   */
+  getActive(table, orderBy = "name") {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const hasDeletedAt = cols.has("deleted_at");
+    const where = hasDeletedAt ? ` WHERE deleted_at IS NULL` : "";
+    const order = cols.has(orderBy) ? ` ORDER BY "${orderBy}"` : "";
+    return Promise.resolve(this._adapter.all(`SELECT * FROM "${table}"${where}${order}`));
+  }
+  /**
+   * Count non-deleted rows in a table.
+   */
+  countActive(table) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const cols = this._ensureColumnCache(table);
+    const hasDeletedAt = cols.has("deleted_at");
+    const where = hasDeletedAt ? ` WHERE deleted_at IS NULL` : "";
+    const row = this._adapter.get(`SELECT COUNT(*) as cnt FROM "${table}"${where}`);
+    return Promise.resolve(row.cnt);
+  }
+  /**
+   * Lookup a single row by natural key (non-deleted).
+   */
+  getByNaturalKey(table, naturalKeyCol, naturalKeyVal) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    return Promise.resolve(
+      this._adapter.get(
+        `SELECT * FROM "${table}" WHERE "${naturalKeyCol}" = ? AND (deleted_at IS NULL OR deleted_at = '')`,
+        [naturalKeyVal]
+      ) ?? null
+    );
+  }
+  /**
+   * Insert a row into a junction table. Uses INSERT OR IGNORE by default
+   * (idempotent). Pass `{ upsert: true }` for INSERT OR REPLACE.
+   */
+  link(junctionTable, data, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const filtered = this._filterToSchemaColumns(junctionTable, data);
+    const colNames = Object.keys(filtered).map((c) => `"${c}"`).join(", ");
+    const placeholders = Object.keys(filtered).map(() => "?").join(", ");
+    const verb = opts?.upsert ? "INSERT OR REPLACE" : "INSERT OR IGNORE";
+    this._adapter.run(`${verb} INTO "${junctionTable}" (${colNames}) VALUES (${placeholders})`, Object.values(filtered));
+    return Promise.resolve();
+  }
+  /**
+   * Delete rows from a junction table matching all given conditions.
+   */
+  unlink(junctionTable, conditions) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const entries = Object.entries(conditions);
+    if (entries.length === 0) return Promise.resolve();
+    const where = entries.map(([k]) => `"${k}" = ?`).join(" AND ");
+    this._adapter.run(`DELETE FROM "${junctionTable}" WHERE ${where}`, entries.map(([, v]) => v));
+    return Promise.resolve();
+  }
   query(table, opts = {}) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -1635,9 +1801,19 @@ var Lattice = class {
    * objects are interpolated into SQL, so stripping unknown keys eliminates
    * any theoretical injection vector from crafted object keys.
    */
+  /** Lazily populate column cache for tables not registered via define(). */
+  _ensureColumnCache(table) {
+    let cols = this._columnCache.get(table);
+    if (!cols) {
+      const rows = this._adapter.all(`PRAGMA table_info("${table}")`);
+      cols = new Set(rows.map((r) => r.name));
+      if (cols.size > 0) this._columnCache.set(table, cols);
+    }
+    return cols;
+  }
   _filterToSchemaColumns(table, row) {
-    const cols = this._columnCache.get(table);
-    if (!cols) return row;
+    const cols = this._ensureColumnCache(table);
+    if (!cols || cols.size === 0) 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]]));
@@ -1714,6 +1890,22 @@ var Lattice = class {
     return { clauses, params };
   }
   /** Returns a rejected Promise if not initialized; null if ready. */
+  _fireWriteHooks(table, op, row, pk, changedColumns) {
+    for (const hook of this._writeHooks) {
+      if (hook.table !== table) continue;
+      if (!hook.on.includes(op)) continue;
+      if (op === "update" && hook.watchColumns && changedColumns) {
+        if (!hook.watchColumns.some((c) => changedColumns.includes(c))) continue;
+      }
+      try {
+        const ctx = { table, op, row, pk };
+        if (changedColumns) ctx.changedColumns = changedColumns;
+        hook.handler(ctx);
+      } catch (err) {
+        for (const h of this._errorHandlers) h(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
   _notInitError() {
     if (!this._initialized) {
       return Promise.reject(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latticesql",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Persistent structured memory for AI agent systems — SQLite ↔ LLM context bridge",
   "type": "module",
   "main": "./dist/index.js",