latticesql 0.5.4 → 0.6.0

package/dist/cli.js

@@ -606,6 +606,75 @@ import { join as join5 } from "path";
 import { mkdirSync as mkdirSync3 } from "fs";
 
 // src/render/entity-query.ts
+var SAFE_COL_RE = /^[a-zA-Z0-9_]+$/;
+function effectiveFilters(opts) {
+  const filters = opts.filters ? [...opts.filters] : [];
+  if (opts.softDelete && !filters.some((f) => f.col === "deleted_at")) {
+    filters.unshift({ col: "deleted_at", op: "isNull" });
+  }
+  return filters;
+}
+function appendQueryOptions(baseSql, params, opts, tableAlias) {
+  let sql = baseSql;
+  const prefix = tableAlias ? `${tableAlias}.` : "";
+  for (const f of effectiveFilters(opts)) {
+    if (!SAFE_COL_RE.test(f.col)) continue;
+    switch (f.op) {
+      case "eq":
+        sql += ` AND ${prefix}"${f.col}" = ?`;
+        params.push(f.val);
+        break;
+      case "ne":
+        sql += ` AND ${prefix}"${f.col}" != ?`;
+        params.push(f.val);
+        break;
+      case "gt":
+        sql += ` AND ${prefix}"${f.col}" > ?`;
+        params.push(f.val);
+        break;
+      case "gte":
+        sql += ` AND ${prefix}"${f.col}" >= ?`;
+        params.push(f.val);
+        break;
+      case "lt":
+        sql += ` AND ${prefix}"${f.col}" < ?`;
+        params.push(f.val);
+        break;
+      case "lte":
+        sql += ` AND ${prefix}"${f.col}" <= ?`;
+        params.push(f.val);
+        break;
+      case "like":
+        sql += ` AND ${prefix}"${f.col}" LIKE ?`;
+        params.push(f.val);
+        break;
+      case "in": {
+        const arr = f.val;
+        if (arr.length === 0) {
+          sql += " AND 0";
+        } else {
+          sql += ` AND ${prefix}"${f.col}" IN (${arr.map(() => "?").join(", ")})`;
+          params.push(...arr);
+        }
+        break;
+      }
+      case "isNull":
+        sql += ` AND ${prefix}"${f.col}" IS NULL`;
+        break;
+      case "isNotNull":
+        sql += ` AND ${prefix}"${f.col}" IS NOT NULL`;
+        break;
+    }
+  }
+  if (opts.orderBy && SAFE_COL_RE.test(opts.orderBy)) {
+    const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+    sql += ` ORDER BY ${prefix}"${opts.orderBy}" ${dir}`;
+  }
+  if (opts.limit !== void 0 && opts.limit > 0) {
+    sql += ` LIMIT ${Math.floor(opts.limit)}`;
+  }
+  return sql;
+}
 function resolveEntitySource(source, entityRow, entityPk, adapter) {
   switch (source.type) {
     case "self":
@@ -613,29 +682,37 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
     case "hasMany": {
       const ref = source.references ?? entityPk;
       const pkVal = entityRow[ref];
-      return adapter.all(
-        `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`,
-        [pkVal]
-      );
+      const params = [pkVal];
+      let sql = `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`;
+      sql = appendQueryOptions(sql, params, source);
+      return adapter.all(sql, params);
     }
     case "manyToMany": {
       const pkVal = entityRow[entityPk];
       const remotePk = source.references ?? "id";
-      return adapter.all(
-        `SELECT r.* FROM "${source.remoteTable}" r
+      const params = [pkVal];
+      let sql = `SELECT r.* FROM "${source.remoteTable}" r
          JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
-         WHERE j."${source.localKey}" = ?`,
-        [pkVal]
-      );
+         WHERE j."${source.localKey}" = ?`;
+      sql = appendQueryOptions(sql, params, source, "r");
+      return adapter.all(sql, params);
     }
     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] : [];
+      const hasOptions = source.filters?.length || source.softDelete || source.orderBy || source.limit;
+      if (!hasOptions) {
+        const related = adapter.get(
+          `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`,
+          [fkVal]
+        );
+        return related ? [related] : [];
+      }
+      const params = [fkVal];
+      let sql = `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`;
+      sql = appendQueryOptions(sql, params, source);
+      const rows = adapter.all(sql, params);
+      return rows.length > 0 ? [rows[0]] : [];
     }
     case "custom":
       return source.query(entityRow, adapter);
@@ -851,7 +928,8 @@ var RenderEngine = class {
         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);
+          const source = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" ? { ...def.sourceDefaults, ...spec.source } : spec.source;
+          const rows = resolveEntitySource(source, entityRow, entityPk, this._adapter);
           if (spec.omitIfEmpty && rows.length === 0) continue;
           const content = truncateContent(spec.render(rows), spec.budget);
           renderedFiles.set(filename, content);

package/dist/index.cjs

@@ -30,18 +30,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_ENTRY_TYPES: () => DEFAULT_ENTRY_TYPES,
+  DEFAULT_TYPE_ALIASES: () => DEFAULT_TYPE_ALIASES,
   Lattice: () => Lattice,
   READ_ONLY_HEADER: () => READ_ONLY_HEADER,
   applyWriteEntry: () => applyWriteEntry,
+  createReadOnlyHeader: () => createReadOnlyHeader,
+  frontmatter: () => frontmatter,
   generateEntryId: () => generateEntryId,
   generateWriteEntryId: () => generateWriteEntryId,
   manifestPath: () => manifestPath,
+  markdownTable: () => markdownTable,
   parseConfigFile: () => parseConfigFile,
   parseConfigString: () => parseConfigString,
   parseMarkdownEntries: () => parseMarkdownEntries,
   parseSessionMD: () => parseSessionMD,
   parseSessionWrites: () => parseSessionWrites,
   readManifest: () => readManifest,
+  slugify: () => slugify,
+  truncate: () => truncate,
   validateEntryId: () => validateEntryId,
   writeManifest: () => writeManifest
 });
@@ -341,6 +348,75 @@ var import_node_path4 = require("path");
 var import_node_fs4 = require("fs");
 
 // src/render/entity-query.ts
+var SAFE_COL_RE = /^[a-zA-Z0-9_]+$/;
+function effectiveFilters(opts) {
+  const filters = opts.filters ? [...opts.filters] : [];
+  if (opts.softDelete && !filters.some((f) => f.col === "deleted_at")) {
+    filters.unshift({ col: "deleted_at", op: "isNull" });
+  }
+  return filters;
+}
+function appendQueryOptions(baseSql, params, opts, tableAlias) {
+  let sql = baseSql;
+  const prefix = tableAlias ? `${tableAlias}.` : "";
+  for (const f of effectiveFilters(opts)) {
+    if (!SAFE_COL_RE.test(f.col)) continue;
+    switch (f.op) {
+      case "eq":
+        sql += ` AND ${prefix}"${f.col}" = ?`;
+        params.push(f.val);
+        break;
+      case "ne":
+        sql += ` AND ${prefix}"${f.col}" != ?`;
+        params.push(f.val);
+        break;
+      case "gt":
+        sql += ` AND ${prefix}"${f.col}" > ?`;
+        params.push(f.val);
+        break;
+      case "gte":
+        sql += ` AND ${prefix}"${f.col}" >= ?`;
+        params.push(f.val);
+        break;
+      case "lt":
+        sql += ` AND ${prefix}"${f.col}" < ?`;
+        params.push(f.val);
+        break;
+      case "lte":
+        sql += ` AND ${prefix}"${f.col}" <= ?`;
+        params.push(f.val);
+        break;
+      case "like":
+        sql += ` AND ${prefix}"${f.col}" LIKE ?`;
+        params.push(f.val);
+        break;
+      case "in": {
+        const arr = f.val;
+        if (arr.length === 0) {
+          sql += " AND 0";
+        } else {
+          sql += ` AND ${prefix}"${f.col}" IN (${arr.map(() => "?").join(", ")})`;
+          params.push(...arr);
+        }
+        break;
+      }
+      case "isNull":
+        sql += ` AND ${prefix}"${f.col}" IS NULL`;
+        break;
+      case "isNotNull":
+        sql += ` AND ${prefix}"${f.col}" IS NOT NULL`;
+        break;
+    }
+  }
+  if (opts.orderBy && SAFE_COL_RE.test(opts.orderBy)) {
+    const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+    sql += ` ORDER BY ${prefix}"${opts.orderBy}" ${dir}`;
+  }
+  if (opts.limit !== void 0 && opts.limit > 0) {
+    sql += ` LIMIT ${Math.floor(opts.limit)}`;
+  }
+  return sql;
+}
 function resolveEntitySource(source, entityRow, entityPk, adapter) {
   switch (source.type) {
     case "self":
@@ -348,29 +424,37 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
     case "hasMany": {
       const ref = source.references ?? entityPk;
       const pkVal = entityRow[ref];
-      return adapter.all(
-        `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`,
-        [pkVal]
-      );
+      const params = [pkVal];
+      let sql = `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`;
+      sql = appendQueryOptions(sql, params, source);
+      return adapter.all(sql, params);
     }
     case "manyToMany": {
       const pkVal = entityRow[entityPk];
       const remotePk = source.references ?? "id";
-      return adapter.all(
-        `SELECT r.* FROM "${source.remoteTable}" r
+      const params = [pkVal];
+      let sql = `SELECT r.* FROM "${source.remoteTable}" r
          JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
-         WHERE j."${source.localKey}" = ?`,
-        [pkVal]
-      );
+         WHERE j."${source.localKey}" = ?`;
+      sql = appendQueryOptions(sql, params, source, "r");
+      return adapter.all(sql, params);
     }
     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] : [];
+      const hasOptions = source.filters?.length || source.softDelete || source.orderBy || source.limit;
+      if (!hasOptions) {
+        const related = adapter.get(
+          `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`,
+          [fkVal]
+        );
+        return related ? [related] : [];
+      }
+      const params = [fkVal];
+      let sql = `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`;
+      sql = appendQueryOptions(sql, params, source);
+      const rows = adapter.all(sql, params);
+      return rows.length > 0 ? [rows[0]] : [];
     }
     case "custom":
       return source.query(entityRow, adapter);
@@ -586,7 +670,8 @@ var RenderEngine = class {
         (0, import_node_fs4.mkdirSync)(entityDir, { recursive: true });
         const renderedFiles = /* @__PURE__ */ new Map();
         for (const [filename, spec] of Object.entries(def.files)) {
-          const rows = resolveEntitySource(spec.source, entityRow, entityPk, this._adapter);
+          const source = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" ? { ...def.sourceDefaults, ...spec.source } : spec.source;
+          const rows = resolveEntitySource(source, entityRow, entityPk, this._adapter);
           if (spec.omitIfEmpty && rows.length === 0) continue;
           const content = truncateContent(spec.render(rows), spec.budget);
           renderedFiles.set(filename, content);
@@ -1521,6 +1606,39 @@ var Lattice = class {
   }
 };
 
+// src/render/markdown.ts
+function frontmatter(fields) {
+  const lines = [`generated_at: "${(/* @__PURE__ */ new Date()).toISOString()}"`];
+  for (const [key, val] of Object.entries(fields)) {
+    lines.push(typeof val === "string" ? `${key}: "${val}"` : `${key}: ${String(val)}`);
+  }
+  return `---
+${lines.join("\n")}
+---
+
+`;
+}
+function markdownTable(rows, columns) {
+  if (rows.length === 0 || columns.length === 0) return "";
+  const header = "| " + columns.map((c) => c.header).join(" | ") + " |";
+  const separator = "| " + columns.map(() => "---").join(" | ") + " |";
+  const body = rows.map((row) => {
+    const cells = columns.map((col) => {
+      const raw = row[col.key];
+      return col.format ? col.format(raw, row) : String(raw ?? "");
+    });
+    return "| " + cells.join(" | ") + " |";
+  });
+  return [header, separator, ...body].join("\n") + "\n";
+}
+function slugify(name) {
+  return name.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/\u0131/g, "i").replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function truncate(content, maxChars, notice = "\n\n*[truncated \u2014 context budget exceeded]*") {
+  if (content.length <= maxChars) return content;
+  return content.slice(0, maxChars) + notice;
+}
+
 // src/session/parser.ts
 var import_node_crypto3 = require("crypto");
 function generateWriteEntryId(timestamp, agentName, op, table, target) {
@@ -1634,7 +1752,7 @@ function parseBlock(block) {
 
 // src/session/entries.ts
 var import_node_crypto4 = require("crypto");
-var VALID_TYPES = /* @__PURE__ */ new Set([
+var DEFAULT_ENTRY_TYPES = /* @__PURE__ */ new Set([
   "event",
   "learning",
   "status",
@@ -1644,7 +1762,7 @@ var VALID_TYPES = /* @__PURE__ */ new Set([
   "handoff",
   "write"
 ]);
-var TYPE_ALIASES = {
+var DEFAULT_TYPE_ALIASES = {
   task_completion: "event",
   completion: "event",
   heartbeat: "status",
@@ -1654,7 +1772,7 @@ var TYPE_ALIASES = {
   note: "event"
 };
 var FIELD_NAME_RE2 = /^[a-zA-Z0-9_]+$/;
-function parseSessionMD(content, startOffset = 0) {
+function parseSessionMD(content, startOffset = 0, options) {
   const entries = [];
   const errors = [];
   const text = content.slice(startOffset);
@@ -1710,7 +1828,7 @@ function parseSessionMD(content, startOffset = 0) {
     }
     const body = bodyLines.join("\n").trim();
     const rawType = headers["type"] ?? "";
-    const resolvedType = normalizeType(rawType);
+    const resolvedType = normalizeType(rawType, options);
     if (!resolvedType) {
       errors.push({ line: entryStartLine + 1, message: `Unknown entry type: ${rawType}` });
       continue;
@@ -1760,7 +1878,7 @@ function parseSessionMD(content, startOffset = 0) {
   }
   return { entries, errors, lastOffset: currentByteOffset };
 }
-function parseMarkdownEntries(content, agentName, startOffset = 0) {
+function parseMarkdownEntries(content, agentName, startOffset = 0, options) {
   const entries = [];
   const errors = [];
   const text = content.slice(startOffset);
@@ -1802,7 +1920,7 @@ function parseMarkdownEntries(content, agentName, startOffset = 0) {
       continue;
     }
     const rawType = bodyType ?? start.headingType ?? "event";
-    const resolvedType = normalizeType(rawType) ?? "event";
+    const resolvedType = normalizeType(rawType, options) ?? "event";
     const id = generateEntryId(start.timestamp, agentName, body);
     entries.push({
       id,
@@ -1825,13 +1943,25 @@ function validateEntryId(id, body) {
   const expectedHash = (0, import_node_crypto4.createHash)("sha256").update(body).digest("hex").slice(0, 6);
   return hash === expectedHash;
 }
-function normalizeType(raw) {
+function normalizeType(raw, options) {
   const lower = raw.toLowerCase().trim();
-  if (VALID_TYPES.has(lower)) return lower;
-  const normalized = lower.replace(/-/g, "_");
-  if (TYPE_ALIASES[normalized]) return TYPE_ALIASES[normalized];
-  for (const alias of Object.keys(TYPE_ALIASES)) {
-    if (normalized.startsWith(alias)) return TYPE_ALIASES[alias];
+  if (!lower) return null;
+  const validTypes = options?.validTypes === void 0 ? DEFAULT_ENTRY_TYPES : options.validTypes;
+  const aliases = options?.typeAliases === void 0 ? DEFAULT_TYPE_ALIASES : options.typeAliases;
+  if (validTypes === null) {
+    if (aliases) {
+      const normalized = lower.replace(/-/g, "_");
+      if (aliases[normalized]) return aliases[normalized];
+    }
+    return lower;
+  }
+  if (validTypes.has(lower)) return lower;
+  if (aliases) {
+    const normalized = lower.replace(/-/g, "_");
+    if (aliases[normalized]) return aliases[normalized];
+    for (const alias of Object.keys(aliases)) {
+      if (normalized.startsWith(alias)) return aliases[alias];
+    }
   }
   return null;
 }
@@ -1895,26 +2025,38 @@ function applyWriteEntry(db, entry) {
 }
 
 // src/session/constants.ts
-var READ_ONLY_HEADER = `<!-- READ ONLY \u2014 generated by lattice-sync. Do not edit directly.
+function createReadOnlyHeader(options) {
+  const generator = options?.generator ?? "Lattice";
+  const docsRef = options?.docsRef ?? "the Lattice documentation";
+  return `<!-- READ ONLY \u2014 generated by ${generator}. Do not edit directly.
      To update data in Lattice: write entries to SESSION.md in this directory.
      Format: type: write | op: create/update/delete | table: <name> | target: <id>
-     See agents/shared/SESSION-FORMAT.md for the full spec. -->
+     See ${docsRef} for the SESSION.md format spec. -->
 
 `;
+}
+var READ_ONLY_HEADER = createReadOnlyHeader();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_ENTRY_TYPES,
+  DEFAULT_TYPE_ALIASES,
   Lattice,
   READ_ONLY_HEADER,
   applyWriteEntry,
+  createReadOnlyHeader,
+  frontmatter,
   generateEntryId,
   generateWriteEntryId,
   manifestPath,
+  markdownTable,
   parseConfigFile,
   parseConfigString,
   parseMarkdownEntries,
   parseSessionMD,
   parseSessionWrites,
   readManifest,
+  slugify,
+  truncate,
   validateEntryId,
   writeManifest
 });

package/dist/index.d.cts

@@ -41,6 +41,32 @@ interface PreparedStatement {
     all(...params: unknown[]): Row[];
 }
 
+/**
+ * Optional query refinements shared by `hasMany`, `manyToMany`, and
+ * `belongsTo` sources.  All fields are additive — omitting them preserves
+ * the v0.5 behaviour (bare `SELECT *`).
+ */
+interface SourceQueryOptions {
+    /**
+     * Additional WHERE clauses applied after the relationship join condition.
+     * Uses the existing {@link Filter} type.
+     *
+     * @example `filters: [{ col: 'status', op: 'eq', val: 'active' }]`
+     */
+    filters?: Filter[];
+    /**
+     * Shorthand for `filters: [{ col: 'deleted_at', op: 'isNull' }]`.
+     * When `true`, soft-deleted rows are excluded.  If both `softDelete`
+     * and an explicit `deleted_at` filter are present, the explicit filter wins.
+     */
+    softDelete?: boolean;
+    /** Column to ORDER BY. Validated against `[a-zA-Z0-9_]`. */
+    orderBy?: string;
+    /** Sort direction. Defaults to `'asc'`. */
+    orderDir?: 'asc' | 'desc';
+    /** Maximum number of rows to return. */
+    limit?: number;
+}
 /**
  * Yield the entity row itself as a single-element array.
  * Use for the primary entity file (e.g. `AGENT.md`).
@@ -57,7 +83,7 @@ interface SelfSource {
  * source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id' }
  * ```
  */
-interface HasManySource {
+interface HasManySource extends SourceQueryOptions {
     type: 'hasMany';
     /** The related table to query */
     table: string;
@@ -84,7 +110,7 @@ interface HasManySource {
  * }
  * ```
  */
-interface ManyToManySource {
+interface ManyToManySource extends SourceQueryOptions {
     type: 'manyToMany';
     /** The junction / association table */
     junctionTable: string;
@@ -111,7 +137,7 @@ interface ManyToManySource {
  * source: { type: 'belongsTo', table: 'teams', foreignKey: 'team_id' }
  * ```
  */
-interface BelongsToSource {
+interface BelongsToSource extends SourceQueryOptions {
     type: 'belongsTo';
     /** The related table to look up */
     table: string;
@@ -250,6 +276,17 @@ interface EntityContextDefinition {
      * Defaults to `[]`.
      */
     protectedFiles?: string[];
+    /**
+     * Default query options merged into every `hasMany`, `manyToMany`, and
+     * `belongsTo` source in this context.  Per-file source options override
+     * these defaults.  `custom` and `self` sources are unaffected.
+     *
+     * @example
+     * ```ts
+     * sourceDefaults: { softDelete: true }   // exclude soft-deleted rows everywhere
+     * ```
+     */
+    sourceDefaults?: SourceQueryOptions;
 }
 
 interface CleanupOptions {
@@ -866,6 +903,69 @@ declare function parseConfigFile(configPath: string): ParsedConfig;
  */
 declare function parseConfigString(yamlContent: string, configDir: string): ParsedConfig;
 
+/**
+ * Column definition for {@link markdownTable}.
+ */
+interface MarkdownTableColumn {
+    /** Row property to read (e.g. `'name'`, `'status'`). */
+    key: string;
+    /** Column header text displayed in the table. */
+    header: string;
+    /**
+     * Optional per-cell formatter.  Receives the raw cell value and the full
+     * row so formatters can derive display values from multiple fields.
+     *
+     * @example `(val) => String(val ?? '—')`
+     * @example `(_, row) => \`[\${row.name}](\${row.slug}/DETAIL.md)\``
+     */
+    format?: (val: unknown, row: Row) => string;
+}
+/**
+ * Generate a YAML-style frontmatter block.
+ * Automatically includes `generated_at` with the current ISO timestamp.
+ *
+ * @example
+ * ```ts
+ * frontmatter({ agent: 'Alice', skill_count: 5 })
+ * // "---\ngenerated_at: 2026-03-27T...\nagent: Alice\nskill_count: 5\n---\n\n"
+ * ```
+ */
+declare function frontmatter(fields: Record<string, string | number | boolean>): string;
+/**
+ * Generate a GitHub-Flavoured Markdown table from rows with explicit column
+ * configuration.  Returns an empty string when `rows` is empty.
+ *
+ * @example
+ * ```ts
+ * markdownTable(rows, [
+ *   { key: 'name',   header: 'Name' },
+ *   { key: 'status', header: 'Status', format: (v) => String(v ?? '—') },
+ * ])
+ * ```
+ */
+declare function markdownTable(rows: Row[], columns: MarkdownTableColumn[]): string;
+/**
+ * Generate a URL-safe slug from a display name.
+ *
+ * - Lowercases, strips diacritics, replaces non-alphanumeric runs with `-`,
+ *   and trims leading/trailing hyphens.
+ *
+ * @example `slugify('My Agent Name')  // 'my-agent-name'`
+ * @example `slugify('José García')    // 'jose-garcia'`
+ */
+declare function slugify(name: string): string;
+/**
+ * Truncate content at a character budget.
+ *
+ * When `content.length > maxChars`, slices to `maxChars` and appends `notice`.
+ * Returns `content` unchanged when the budget is not exceeded.
+ *
+ * @param content  - The rendered content to truncate
+ * @param maxChars - Maximum character count
+ * @param notice   - Appended after truncation (default: standard budget notice)
+ */
+declare function truncate(content: string, maxChars: number, notice?: string): string;
+
 type SessionWriteOp = 'create' | 'update' | 'delete';
 interface SessionWriteEntry {
     id: string;
@@ -896,9 +996,10 @@ declare function generateWriteEntryId(timestamp: string, agentName: string, op:
 declare function parseSessionWrites(content: string): SessionWriteParseResult;
 
 /**
- * A single parsed SESSION.md entry. Covers all entry types:
- * event, learning, status, correction, discovery, metric, handoff, write.
+ * A single parsed SESSION.md entry.
  *
+ * The `type` field holds the resolved entry type (from the built-in set or
+ * custom types supplied via {@link SessionParseOptions}).
  * When `type === 'write'`, the op/table/target/reason/fields fields are set.
  */
 interface SessionEntry {
@@ -929,6 +1030,39 @@ interface ParseResult {
     /** Byte offset after the last fully parsed entry — used for incremental parsing. */
     lastOffset: number;
 }
+/**
+ * Options for {@link parseSessionMD} and {@link parseMarkdownEntries}.
+ *
+ * All fields are optional — omitting them preserves the default behaviour
+ * (built-in type set + built-in aliases), so existing callers are unaffected.
+ */
+interface SessionParseOptions {
+    /**
+     * Set of valid entry type names.
+     * - Omit (or `undefined`) → use {@link DEFAULT_ENTRY_TYPES}.
+     * - `null` → accept **any** type string without validation.
+     * - Provide a custom `Set<string>` to restrict to your own taxonomy.
+     */
+    validTypes?: Set<string> | null;
+    /**
+     * Map of non-standard type names to their canonical form.
+     * - Omit (or `undefined`) → use {@link DEFAULT_TYPE_ALIASES}.
+     * - `null` → disable alias resolution.
+     * - Provide a custom `Record<string, string>` for your own aliases.
+     */
+    typeAliases?: Record<string, string> | null;
+}
+/**
+ * Default set of valid entry types shipped with latticesql.
+ * Suitable for LLM-agent context systems; override via {@link SessionParseOptions.validTypes}.
+ */
+declare const DEFAULT_ENTRY_TYPES: ReadonlySet<string>;
+/**
+ * Default type aliases shipped with latticesql.
+ * Maps commonly-seen alternative names to their canonical type.
+ * Override via {@link SessionParseOptions.typeAliases}.
+ */
+declare const DEFAULT_TYPE_ALIASES: Readonly<Record<string, string>>;
 /**
  * Parse SESSION.md YAML-delimited entries starting at `startOffset` bytes.
  *
@@ -942,15 +1076,18 @@ interface ParseResult {
  * Entry body text here.
  * ===
  * ```
+ *
+ * Pass {@link SessionParseOptions} to customise which entry types are accepted
+ * and how aliases are resolved. Defaults match the built-in type set.
  */
-declare function parseSessionMD(content: string, startOffset?: number): ParseResult;
+declare function parseSessionMD(content: string, startOffset?: number, options?: SessionParseOptions): ParseResult;
 /**
- * Parse free-form Markdown SESSION.md entries. Agents sometimes write entries
- * as `## {timestamp} — {description}` headings rather than YAML blocks.
+ * Parse free-form Markdown SESSION.md entries written as
+ * `## {timestamp} — {description}` headings rather than YAML blocks.
  *
  * Runs alongside `parseSessionMD`; the two parsers are merged by caller.
  */
-declare function parseMarkdownEntries(content: string, agentName: string, startOffset?: number): ParseResult;
+declare function parseMarkdownEntries(content: string, agentName: string, startOffset?: number, options?: SessionParseOptions): ParseResult;
 /**
  * Generate a content-addressed entry ID.
  * Format: `{timestamp}-{agentName}-{6-char-sha256-prefix}`
@@ -988,12 +1125,26 @@ type ApplyWriteResult = {
 declare function applyWriteEntry(db: Database.Database, entry: SessionWriteEntry): ApplyWriteResult;
 
 /**
- * Read-only header prepended to all Lattice-generated context files.
+ * Options for {@link createReadOnlyHeader}.
+ */
+interface ReadOnlyHeaderOptions {
+    /** Name shown as the generator (default: `"Lattice"`). */
+    generator?: string;
+    /** Where to find the SESSION.md format spec (default: `"the Lattice documentation"`). */
+    docsRef?: string;
+}
+/**
+ * Build a read-only header for Lattice-generated context files.
+ *
+ * The header tells consumers (human or LLM) that the file is auto-generated
+ * and that writes should go through SESSION.md instead.
+ */
+declare function createReadOnlyHeader(options?: ReadOnlyHeaderOptions): string;
+/**
+ * Default read-only header prepended to all Lattice-generated context files.
  *
- * Directs agents to SESSION.md for writes rather than editing generated files
- * directly. Include at the top of every rendered markdown context file so
- * agents see it at the start of their context window.
+ * For a customised header, use {@link createReadOnlyHeader} instead.
  */
-declare const READ_ONLY_HEADER = "<!-- READ ONLY \u2014 generated by lattice-sync. Do not edit directly.\n     To update data in Lattice: write entries to SESSION.md in this directory.\n     Format: type: write | op: create/update/delete | table: <name> | target: <id>\n     See agents/shared/SESSION-FORMAT.md for the full spec. -->\n\n";
+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, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, 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 Migration, type MultiTableDefinition, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type SessionEntry, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, generateEntryId, generateWriteEntryId, manifestPath, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, 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 EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, 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 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 };

package/dist/index.d.ts

@@ -41,6 +41,32 @@ interface PreparedStatement {
     all(...params: unknown[]): Row[];
 }
 
+/**
+ * Optional query refinements shared by `hasMany`, `manyToMany`, and
+ * `belongsTo` sources.  All fields are additive — omitting them preserves
+ * the v0.5 behaviour (bare `SELECT *`).
+ */
+interface SourceQueryOptions {
+    /**
+     * Additional WHERE clauses applied after the relationship join condition.
+     * Uses the existing {@link Filter} type.
+     *
+     * @example `filters: [{ col: 'status', op: 'eq', val: 'active' }]`
+     */
+    filters?: Filter[];
+    /**
+     * Shorthand for `filters: [{ col: 'deleted_at', op: 'isNull' }]`.
+     * When `true`, soft-deleted rows are excluded.  If both `softDelete`
+     * and an explicit `deleted_at` filter are present, the explicit filter wins.
+     */
+    softDelete?: boolean;
+    /** Column to ORDER BY. Validated against `[a-zA-Z0-9_]`. */
+    orderBy?: string;
+    /** Sort direction. Defaults to `'asc'`. */
+    orderDir?: 'asc' | 'desc';
+    /** Maximum number of rows to return. */
+    limit?: number;
+}
 /**
  * Yield the entity row itself as a single-element array.
  * Use for the primary entity file (e.g. `AGENT.md`).
@@ -57,7 +83,7 @@ interface SelfSource {
  * source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id' }
  * ```
  */
-interface HasManySource {
+interface HasManySource extends SourceQueryOptions {
     type: 'hasMany';
     /** The related table to query */
     table: string;
@@ -84,7 +110,7 @@ interface HasManySource {
  * }
  * ```
  */
-interface ManyToManySource {
+interface ManyToManySource extends SourceQueryOptions {
     type: 'manyToMany';
     /** The junction / association table */
     junctionTable: string;
@@ -111,7 +137,7 @@ interface ManyToManySource {
  * source: { type: 'belongsTo', table: 'teams', foreignKey: 'team_id' }
  * ```
  */
-interface BelongsToSource {
+interface BelongsToSource extends SourceQueryOptions {
     type: 'belongsTo';
     /** The related table to look up */
     table: string;
@@ -250,6 +276,17 @@ interface EntityContextDefinition {
      * Defaults to `[]`.
      */
     protectedFiles?: string[];
+    /**
+     * Default query options merged into every `hasMany`, `manyToMany`, and
+     * `belongsTo` source in this context.  Per-file source options override
+     * these defaults.  `custom` and `self` sources are unaffected.
+     *
+     * @example
+     * ```ts
+     * sourceDefaults: { softDelete: true }   // exclude soft-deleted rows everywhere
+     * ```
+     */
+    sourceDefaults?: SourceQueryOptions;
 }
 
 interface CleanupOptions {
@@ -866,6 +903,69 @@ declare function parseConfigFile(configPath: string): ParsedConfig;
  */
 declare function parseConfigString(yamlContent: string, configDir: string): ParsedConfig;
 
+/**
+ * Column definition for {@link markdownTable}.
+ */
+interface MarkdownTableColumn {
+    /** Row property to read (e.g. `'name'`, `'status'`). */
+    key: string;
+    /** Column header text displayed in the table. */
+    header: string;
+    /**
+     * Optional per-cell formatter.  Receives the raw cell value and the full
+     * row so formatters can derive display values from multiple fields.
+     *
+     * @example `(val) => String(val ?? '—')`
+     * @example `(_, row) => \`[\${row.name}](\${row.slug}/DETAIL.md)\``
+     */
+    format?: (val: unknown, row: Row) => string;
+}
+/**
+ * Generate a YAML-style frontmatter block.
+ * Automatically includes `generated_at` with the current ISO timestamp.
+ *
+ * @example
+ * ```ts
+ * frontmatter({ agent: 'Alice', skill_count: 5 })
+ * // "---\ngenerated_at: 2026-03-27T...\nagent: Alice\nskill_count: 5\n---\n\n"
+ * ```
+ */
+declare function frontmatter(fields: Record<string, string | number | boolean>): string;
+/**
+ * Generate a GitHub-Flavoured Markdown table from rows with explicit column
+ * configuration.  Returns an empty string when `rows` is empty.
+ *
+ * @example
+ * ```ts
+ * markdownTable(rows, [
+ *   { key: 'name',   header: 'Name' },
+ *   { key: 'status', header: 'Status', format: (v) => String(v ?? '—') },
+ * ])
+ * ```
+ */
+declare function markdownTable(rows: Row[], columns: MarkdownTableColumn[]): string;
+/**
+ * Generate a URL-safe slug from a display name.
+ *
+ * - Lowercases, strips diacritics, replaces non-alphanumeric runs with `-`,
+ *   and trims leading/trailing hyphens.
+ *
+ * @example `slugify('My Agent Name')  // 'my-agent-name'`
+ * @example `slugify('José García')    // 'jose-garcia'`
+ */
+declare function slugify(name: string): string;
+/**
+ * Truncate content at a character budget.
+ *
+ * When `content.length > maxChars`, slices to `maxChars` and appends `notice`.
+ * Returns `content` unchanged when the budget is not exceeded.
+ *
+ * @param content  - The rendered content to truncate
+ * @param maxChars - Maximum character count
+ * @param notice   - Appended after truncation (default: standard budget notice)
+ */
+declare function truncate(content: string, maxChars: number, notice?: string): string;
+
 type SessionWriteOp = 'create' | 'update' | 'delete';
 interface SessionWriteEntry {
     id: string;
@@ -896,9 +996,10 @@ declare function generateWriteEntryId(timestamp: string, agentName: string, op:
 declare function parseSessionWrites(content: string): SessionWriteParseResult;
 
 /**
- * A single parsed SESSION.md entry. Covers all entry types:
- * event, learning, status, correction, discovery, metric, handoff, write.
+ * A single parsed SESSION.md entry.
  *
+ * The `type` field holds the resolved entry type (from the built-in set or
+ * custom types supplied via {@link SessionParseOptions}).
  * When `type === 'write'`, the op/table/target/reason/fields fields are set.
  */
 interface SessionEntry {
@@ -929,6 +1030,39 @@ interface ParseResult {
     /** Byte offset after the last fully parsed entry — used for incremental parsing. */
     lastOffset: number;
 }
+/**
+ * Options for {@link parseSessionMD} and {@link parseMarkdownEntries}.
+ *
+ * All fields are optional — omitting them preserves the default behaviour
+ * (built-in type set + built-in aliases), so existing callers are unaffected.
+ */
+interface SessionParseOptions {
+    /**
+     * Set of valid entry type names.
+     * - Omit (or `undefined`) → use {@link DEFAULT_ENTRY_TYPES}.
+     * - `null` → accept **any** type string without validation.
+     * - Provide a custom `Set<string>` to restrict to your own taxonomy.
+     */
+    validTypes?: Set<string> | null;
+    /**
+     * Map of non-standard type names to their canonical form.
+     * - Omit (or `undefined`) → use {@link DEFAULT_TYPE_ALIASES}.
+     * - `null` → disable alias resolution.
+     * - Provide a custom `Record<string, string>` for your own aliases.
+     */
+    typeAliases?: Record<string, string> | null;
+}
+/**
+ * Default set of valid entry types shipped with latticesql.
+ * Suitable for LLM-agent context systems; override via {@link SessionParseOptions.validTypes}.
+ */
+declare const DEFAULT_ENTRY_TYPES: ReadonlySet<string>;
+/**
+ * Default type aliases shipped with latticesql.
+ * Maps commonly-seen alternative names to their canonical type.
+ * Override via {@link SessionParseOptions.typeAliases}.
+ */
+declare const DEFAULT_TYPE_ALIASES: Readonly<Record<string, string>>;
 /**
  * Parse SESSION.md YAML-delimited entries starting at `startOffset` bytes.
  *
@@ -942,15 +1076,18 @@ interface ParseResult {
  * Entry body text here.
  * ===
  * ```
+ *
+ * Pass {@link SessionParseOptions} to customise which entry types are accepted
+ * and how aliases are resolved. Defaults match the built-in type set.
  */
-declare function parseSessionMD(content: string, startOffset?: number): ParseResult;
+declare function parseSessionMD(content: string, startOffset?: number, options?: SessionParseOptions): ParseResult;
 /**
- * Parse free-form Markdown SESSION.md entries. Agents sometimes write entries
- * as `## {timestamp} — {description}` headings rather than YAML blocks.
+ * Parse free-form Markdown SESSION.md entries written as
+ * `## {timestamp} — {description}` headings rather than YAML blocks.
  *
  * Runs alongside `parseSessionMD`; the two parsers are merged by caller.
  */
-declare function parseMarkdownEntries(content: string, agentName: string, startOffset?: number): ParseResult;
+declare function parseMarkdownEntries(content: string, agentName: string, startOffset?: number, options?: SessionParseOptions): ParseResult;
 /**
  * Generate a content-addressed entry ID.
  * Format: `{timestamp}-{agentName}-{6-char-sha256-prefix}`
@@ -988,12 +1125,26 @@ type ApplyWriteResult = {
 declare function applyWriteEntry(db: Database.Database, entry: SessionWriteEntry): ApplyWriteResult;
 
 /**
- * Read-only header prepended to all Lattice-generated context files.
+ * Options for {@link createReadOnlyHeader}.
+ */
+interface ReadOnlyHeaderOptions {
+    /** Name shown as the generator (default: `"Lattice"`). */
+    generator?: string;
+    /** Where to find the SESSION.md format spec (default: `"the Lattice documentation"`). */
+    docsRef?: string;
+}
+/**
+ * Build a read-only header for Lattice-generated context files.
+ *
+ * The header tells consumers (human or LLM) that the file is auto-generated
+ * and that writes should go through SESSION.md instead.
+ */
+declare function createReadOnlyHeader(options?: ReadOnlyHeaderOptions): string;
+/**
+ * Default read-only header prepended to all Lattice-generated context files.
  *
- * Directs agents to SESSION.md for writes rather than editing generated files
- * directly. Include at the top of every rendered markdown context file so
- * agents see it at the start of their context window.
+ * For a customised header, use {@link createReadOnlyHeader} instead.
  */
-declare const READ_ONLY_HEADER = "<!-- READ ONLY \u2014 generated by lattice-sync. Do not edit directly.\n     To update data in Lattice: write entries to SESSION.md in this directory.\n     Format: type: write | op: create/update/delete | table: <name> | target: <id>\n     See agents/shared/SESSION-FORMAT.md for the full spec. -->\n\n";
+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, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, 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 Migration, type MultiTableDefinition, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type SessionEntry, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, generateEntryId, generateWriteEntryId, manifestPath, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, 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 EntityContextDefinition, type EntityContextManifestEntry, type EntityFileSource, type EntityFileSpec, 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 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 };

package/dist/index.js

@@ -292,6 +292,75 @@ import { join as join4 } from "path";
 import { mkdirSync as mkdirSync2 } from "fs";
 
 // src/render/entity-query.ts
+var SAFE_COL_RE = /^[a-zA-Z0-9_]+$/;
+function effectiveFilters(opts) {
+  const filters = opts.filters ? [...opts.filters] : [];
+  if (opts.softDelete && !filters.some((f) => f.col === "deleted_at")) {
+    filters.unshift({ col: "deleted_at", op: "isNull" });
+  }
+  return filters;
+}
+function appendQueryOptions(baseSql, params, opts, tableAlias) {
+  let sql = baseSql;
+  const prefix = tableAlias ? `${tableAlias}.` : "";
+  for (const f of effectiveFilters(opts)) {
+    if (!SAFE_COL_RE.test(f.col)) continue;
+    switch (f.op) {
+      case "eq":
+        sql += ` AND ${prefix}"${f.col}" = ?`;
+        params.push(f.val);
+        break;
+      case "ne":
+        sql += ` AND ${prefix}"${f.col}" != ?`;
+        params.push(f.val);
+        break;
+      case "gt":
+        sql += ` AND ${prefix}"${f.col}" > ?`;
+        params.push(f.val);
+        break;
+      case "gte":
+        sql += ` AND ${prefix}"${f.col}" >= ?`;
+        params.push(f.val);
+        break;
+      case "lt":
+        sql += ` AND ${prefix}"${f.col}" < ?`;
+        params.push(f.val);
+        break;
+      case "lte":
+        sql += ` AND ${prefix}"${f.col}" <= ?`;
+        params.push(f.val);
+        break;
+      case "like":
+        sql += ` AND ${prefix}"${f.col}" LIKE ?`;
+        params.push(f.val);
+        break;
+      case "in": {
+        const arr = f.val;
+        if (arr.length === 0) {
+          sql += " AND 0";
+        } else {
+          sql += ` AND ${prefix}"${f.col}" IN (${arr.map(() => "?").join(", ")})`;
+          params.push(...arr);
+        }
+        break;
+      }
+      case "isNull":
+        sql += ` AND ${prefix}"${f.col}" IS NULL`;
+        break;
+      case "isNotNull":
+        sql += ` AND ${prefix}"${f.col}" IS NOT NULL`;
+        break;
+    }
+  }
+  if (opts.orderBy && SAFE_COL_RE.test(opts.orderBy)) {
+    const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+    sql += ` ORDER BY ${prefix}"${opts.orderBy}" ${dir}`;
+  }
+  if (opts.limit !== void 0 && opts.limit > 0) {
+    sql += ` LIMIT ${Math.floor(opts.limit)}`;
+  }
+  return sql;
+}
 function resolveEntitySource(source, entityRow, entityPk, adapter) {
   switch (source.type) {
     case "self":
@@ -299,29 +368,37 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
     case "hasMany": {
       const ref = source.references ?? entityPk;
       const pkVal = entityRow[ref];
-      return adapter.all(
-        `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`,
-        [pkVal]
-      );
+      const params = [pkVal];
+      let sql = `SELECT * FROM "${source.table}" WHERE "${source.foreignKey}" = ?`;
+      sql = appendQueryOptions(sql, params, source);
+      return adapter.all(sql, params);
     }
     case "manyToMany": {
       const pkVal = entityRow[entityPk];
       const remotePk = source.references ?? "id";
-      return adapter.all(
-        `SELECT r.* FROM "${source.remoteTable}" r
+      const params = [pkVal];
+      let sql = `SELECT r.* FROM "${source.remoteTable}" r
          JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
-         WHERE j."${source.localKey}" = ?`,
-        [pkVal]
-      );
+         WHERE j."${source.localKey}" = ?`;
+      sql = appendQueryOptions(sql, params, source, "r");
+      return adapter.all(sql, params);
     }
     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] : [];
+      const hasOptions = source.filters?.length || source.softDelete || source.orderBy || source.limit;
+      if (!hasOptions) {
+        const related = adapter.get(
+          `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`,
+          [fkVal]
+        );
+        return related ? [related] : [];
+      }
+      const params = [fkVal];
+      let sql = `SELECT * FROM "${source.table}" WHERE "${source.references ?? "id"}" = ?`;
+      sql = appendQueryOptions(sql, params, source);
+      const rows = adapter.all(sql, params);
+      return rows.length > 0 ? [rows[0]] : [];
     }
     case "custom":
       return source.query(entityRow, adapter);
@@ -537,7 +614,8 @@ var RenderEngine = class {
         mkdirSync2(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);
+          const source = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" ? { ...def.sourceDefaults, ...spec.source } : spec.source;
+          const rows = resolveEntitySource(source, entityRow, entityPk, this._adapter);
           if (spec.omitIfEmpty && rows.length === 0) continue;
           const content = truncateContent(spec.render(rows), spec.budget);
           renderedFiles.set(filename, content);
@@ -1472,6 +1550,39 @@ var Lattice = class {
   }
 };
 
+// src/render/markdown.ts
+function frontmatter(fields) {
+  const lines = [`generated_at: "${(/* @__PURE__ */ new Date()).toISOString()}"`];
+  for (const [key, val] of Object.entries(fields)) {
+    lines.push(typeof val === "string" ? `${key}: "${val}"` : `${key}: ${String(val)}`);
+  }
+  return `---
+${lines.join("\n")}
+---
+
+`;
+}
+function markdownTable(rows, columns) {
+  if (rows.length === 0 || columns.length === 0) return "";
+  const header = "| " + columns.map((c) => c.header).join(" | ") + " |";
+  const separator = "| " + columns.map(() => "---").join(" | ") + " |";
+  const body = rows.map((row) => {
+    const cells = columns.map((col) => {
+      const raw = row[col.key];
+      return col.format ? col.format(raw, row) : String(raw ?? "");
+    });
+    return "| " + cells.join(" | ") + " |";
+  });
+  return [header, separator, ...body].join("\n") + "\n";
+}
+function slugify(name) {
+  return name.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/\u0131/g, "i").replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function truncate(content, maxChars, notice = "\n\n*[truncated \u2014 context budget exceeded]*") {
+  if (content.length <= maxChars) return content;
+  return content.slice(0, maxChars) + notice;
+}
+
 // src/session/parser.ts
 import { createHash as createHash2 } from "crypto";
 function generateWriteEntryId(timestamp, agentName, op, table, target) {
@@ -1585,7 +1696,7 @@ function parseBlock(block) {
 
 // src/session/entries.ts
 import { createHash as createHash3 } from "crypto";
-var VALID_TYPES = /* @__PURE__ */ new Set([
+var DEFAULT_ENTRY_TYPES = /* @__PURE__ */ new Set([
   "event",
   "learning",
   "status",
@@ -1595,7 +1706,7 @@ var VALID_TYPES = /* @__PURE__ */ new Set([
   "handoff",
   "write"
 ]);
-var TYPE_ALIASES = {
+var DEFAULT_TYPE_ALIASES = {
   task_completion: "event",
   completion: "event",
   heartbeat: "status",
@@ -1605,7 +1716,7 @@ var TYPE_ALIASES = {
   note: "event"
 };
 var FIELD_NAME_RE2 = /^[a-zA-Z0-9_]+$/;
-function parseSessionMD(content, startOffset = 0) {
+function parseSessionMD(content, startOffset = 0, options) {
   const entries = [];
   const errors = [];
   const text = content.slice(startOffset);
@@ -1661,7 +1772,7 @@ function parseSessionMD(content, startOffset = 0) {
     }
     const body = bodyLines.join("\n").trim();
     const rawType = headers["type"] ?? "";
-    const resolvedType = normalizeType(rawType);
+    const resolvedType = normalizeType(rawType, options);
     if (!resolvedType) {
       errors.push({ line: entryStartLine + 1, message: `Unknown entry type: ${rawType}` });
       continue;
@@ -1711,7 +1822,7 @@ function parseSessionMD(content, startOffset = 0) {
   }
   return { entries, errors, lastOffset: currentByteOffset };
 }
-function parseMarkdownEntries(content, agentName, startOffset = 0) {
+function parseMarkdownEntries(content, agentName, startOffset = 0, options) {
   const entries = [];
   const errors = [];
   const text = content.slice(startOffset);
@@ -1753,7 +1864,7 @@ function parseMarkdownEntries(content, agentName, startOffset = 0) {
       continue;
     }
     const rawType = bodyType ?? start.headingType ?? "event";
-    const resolvedType = normalizeType(rawType) ?? "event";
+    const resolvedType = normalizeType(rawType, options) ?? "event";
     const id = generateEntryId(start.timestamp, agentName, body);
     entries.push({
       id,
@@ -1776,13 +1887,25 @@ function validateEntryId(id, body) {
   const expectedHash = createHash3("sha256").update(body).digest("hex").slice(0, 6);
   return hash === expectedHash;
 }
-function normalizeType(raw) {
+function normalizeType(raw, options) {
   const lower = raw.toLowerCase().trim();
-  if (VALID_TYPES.has(lower)) return lower;
-  const normalized = lower.replace(/-/g, "_");
-  if (TYPE_ALIASES[normalized]) return TYPE_ALIASES[normalized];
-  for (const alias of Object.keys(TYPE_ALIASES)) {
-    if (normalized.startsWith(alias)) return TYPE_ALIASES[alias];
+  if (!lower) return null;
+  const validTypes = options?.validTypes === void 0 ? DEFAULT_ENTRY_TYPES : options.validTypes;
+  const aliases = options?.typeAliases === void 0 ? DEFAULT_TYPE_ALIASES : options.typeAliases;
+  if (validTypes === null) {
+    if (aliases) {
+      const normalized = lower.replace(/-/g, "_");
+      if (aliases[normalized]) return aliases[normalized];
+    }
+    return lower;
+  }
+  if (validTypes.has(lower)) return lower;
+  if (aliases) {
+    const normalized = lower.replace(/-/g, "_");
+    if (aliases[normalized]) return aliases[normalized];
+    for (const alias of Object.keys(aliases)) {
+      if (normalized.startsWith(alias)) return aliases[alias];
+    }
   }
   return null;
 }
@@ -1846,25 +1969,37 @@ function applyWriteEntry(db, entry) {
 }
 
 // src/session/constants.ts
-var READ_ONLY_HEADER = `<!-- READ ONLY \u2014 generated by lattice-sync. Do not edit directly.
+function createReadOnlyHeader(options) {
+  const generator = options?.generator ?? "Lattice";
+  const docsRef = options?.docsRef ?? "the Lattice documentation";
+  return `<!-- READ ONLY \u2014 generated by ${generator}. Do not edit directly.
      To update data in Lattice: write entries to SESSION.md in this directory.
      Format: type: write | op: create/update/delete | table: <name> | target: <id>
-     See agents/shared/SESSION-FORMAT.md for the full spec. -->
+     See ${docsRef} for the SESSION.md format spec. -->
 
 `;
+}
+var READ_ONLY_HEADER = createReadOnlyHeader();
 export {
+  DEFAULT_ENTRY_TYPES,
+  DEFAULT_TYPE_ALIASES,
   Lattice,
   READ_ONLY_HEADER,
   applyWriteEntry,
+  createReadOnlyHeader,
+  frontmatter,
   generateEntryId,
   generateWriteEntryId,
   manifestPath,
+  markdownTable,
   parseConfigFile,
   parseConfigString,
   parseMarkdownEntries,
   parseSessionMD,
   parseSessionWrites,
   readManifest,
+  slugify,
+  truncate,
   validateEntryId,
   writeManifest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latticesql",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Persistent structured memory for AI agent systems — SQLite ↔ LLM context bridge",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,11 +34,12 @@
     "lint:fix": "eslint src tests --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "check:generic": "bash scripts/check-generic.sh",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "docs": "typedoc --out docs-generated src/index.ts",
-    "prepublishOnly": "npm run build && npm run typecheck && npm test"
+    "prepublishOnly": "npm run check:generic && npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
     "better-sqlite3": "^12.8.0",