latticesql 0.5.5 → 0.7.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,32 +682,53 @@ 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);
+    case "enriched": {
+      const enriched = { ...entityRow };
+      for (const [key, lookup] of Object.entries(source.include)) {
+        const fieldName = `_${key}`;
+        if (lookup.type === "custom") {
+          enriched[fieldName] = JSON.stringify(lookup.query(entityRow, adapter));
+        } else {
+          const resolved = resolveEntitySource(lookup, entityRow, entityPk, adapter);
+          enriched[fieldName] = JSON.stringify(resolved);
+        }
+      }
+      return [enriched];
+    }
   }
 }
 function truncateContent(content, budget) {
@@ -851,7 +941,9 @@ 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 mergeDefaults = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" && spec.source.type !== "enriched";
+          const source = mergeDefaults ? { ...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

@@ -36,15 +36,19 @@ __export(index_exports, {
   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
 });
@@ -344,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":
@@ -351,32 +424,53 @@ 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);
+    case "enriched": {
+      const enriched = { ...entityRow };
+      for (const [key, lookup] of Object.entries(source.include)) {
+        const fieldName = `_${key}`;
+        if (lookup.type === "custom") {
+          enriched[fieldName] = JSON.stringify(lookup.query(entityRow, adapter));
+        } else {
+          const resolved = resolveEntitySource(lookup, entityRow, entityPk, adapter);
+          enriched[fieldName] = JSON.stringify(resolved);
+        }
+      }
+      return [enriched];
+    }
   }
 }
 function truncateContent(content, budget) {
@@ -589,7 +683,9 @@ 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 mergeDefaults = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" && spec.source.type !== "enriched";
+          const source = mergeDefaults ? { ...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);
@@ -1524,6 +1620,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) {
@@ -1929,15 +2058,19 @@ var READ_ONLY_HEADER = createReadOnlyHeader();
   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;
@@ -141,8 +167,57 @@ interface CustomSource {
     type: 'custom';
     query: (row: Row, adapter: StorageAdapter) => Row[];
 }
+/**
+ * Sub-lookup definition for an {@link EnrichedSource}.
+ * Each lookup resolves related rows and attaches them to the entity row
+ * as a `_key` JSON string field.
+ *
+ * Declarative lookups reuse the same types as file sources (with all
+ * query options). Custom lookups provide full control.
+ */
+type EnrichmentLookup = ({
+    as?: string;
+} & Omit<HasManySource, 'type'> & {
+    type: 'hasMany';
+}) | ({
+    as?: string;
+} & Omit<ManyToManySource, 'type'> & {
+    type: 'manyToMany';
+}) | ({
+    as?: string;
+} & Omit<BelongsToSource, 'type'> & {
+    type: 'belongsTo';
+}) | {
+    type: 'custom';
+    query: (row: Row, adapter: StorageAdapter) => Row[];
+};
+/**
+ * Start with the entity's own row (like `self`) and attach related data
+ * as JSON string fields.  Each key in `include` becomes a `_key` field
+ * on the returned row, containing `JSON.stringify(resolvedRows)`.
+ *
+ * Use when a single file needs the entity's own data plus related lists
+ * (e.g. an org profile that includes its agents and projects).
+ *
+ * @example
+ * ```ts
+ * source: {
+ *   type: 'enriched',
+ *   include: {
+ *     agents:   { type: 'hasMany', table: 'agents', foreignKey: 'org_id', softDelete: true },
+ *     projects: { type: 'hasMany', table: 'projects', foreignKey: 'org_id', softDelete: true },
+ *   },
+ * }
+ * // Result: [{ ...entityRow, _agents: '[...]', _projects: '[...]' }]
+ * ```
+ */
+interface EnrichedSource {
+    type: 'enriched';
+    /** Named lookups whose results are attached as `_key` JSON fields. */
+    include: Record<string, EnrichmentLookup>;
+}
 /** Union of all supported source types for {@link EntityFileSpec}. */
-type EntityFileSource = SelfSource | HasManySource | ManyToManySource | BelongsToSource | CustomSource;
+type EntityFileSource = SelfSource | HasManySource | ManyToManySource | BelongsToSource | CustomSource | EnrichedSource;
 /**
  * Specification for a single file generated inside an entity's directory.
  *
@@ -250,6 +325,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 +952,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;
@@ -1047,4 +1196,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 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 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 StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, 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 EnrichedSource, type EnrichmentLookup, 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;
@@ -141,8 +167,57 @@ interface CustomSource {
     type: 'custom';
     query: (row: Row, adapter: StorageAdapter) => Row[];
 }
+/**
+ * Sub-lookup definition for an {@link EnrichedSource}.
+ * Each lookup resolves related rows and attaches them to the entity row
+ * as a `_key` JSON string field.
+ *
+ * Declarative lookups reuse the same types as file sources (with all
+ * query options). Custom lookups provide full control.
+ */
+type EnrichmentLookup = ({
+    as?: string;
+} & Omit<HasManySource, 'type'> & {
+    type: 'hasMany';
+}) | ({
+    as?: string;
+} & Omit<ManyToManySource, 'type'> & {
+    type: 'manyToMany';
+}) | ({
+    as?: string;
+} & Omit<BelongsToSource, 'type'> & {
+    type: 'belongsTo';
+}) | {
+    type: 'custom';
+    query: (row: Row, adapter: StorageAdapter) => Row[];
+};
+/**
+ * Start with the entity's own row (like `self`) and attach related data
+ * as JSON string fields.  Each key in `include` becomes a `_key` field
+ * on the returned row, containing `JSON.stringify(resolvedRows)`.
+ *
+ * Use when a single file needs the entity's own data plus related lists
+ * (e.g. an org profile that includes its agents and projects).
+ *
+ * @example
+ * ```ts
+ * source: {
+ *   type: 'enriched',
+ *   include: {
+ *     agents:   { type: 'hasMany', table: 'agents', foreignKey: 'org_id', softDelete: true },
+ *     projects: { type: 'hasMany', table: 'projects', foreignKey: 'org_id', softDelete: true },
+ *   },
+ * }
+ * // Result: [{ ...entityRow, _agents: '[...]', _projects: '[...]' }]
+ * ```
+ */
+interface EnrichedSource {
+    type: 'enriched';
+    /** Named lookups whose results are attached as `_key` JSON fields. */
+    include: Record<string, EnrichmentLookup>;
+}
 /** Union of all supported source types for {@link EntityFileSpec}. */
-type EntityFileSource = SelfSource | HasManySource | ManyToManySource | BelongsToSource | CustomSource;
+type EntityFileSource = SelfSource | HasManySource | ManyToManySource | BelongsToSource | CustomSource | EnrichedSource;
 /**
  * Specification for a single file generated inside an entity's directory.
  *
@@ -250,6 +325,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 +952,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;
@@ -1047,4 +1196,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 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 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 StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, 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 EnrichedSource, type EnrichmentLookup, 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,32 +368,53 @@ 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);
+    case "enriched": {
+      const enriched = { ...entityRow };
+      for (const [key, lookup] of Object.entries(source.include)) {
+        const fieldName = `_${key}`;
+        if (lookup.type === "custom") {
+          enriched[fieldName] = JSON.stringify(lookup.query(entityRow, adapter));
+        } else {
+          const resolved = resolveEntitySource(lookup, entityRow, entityPk, adapter);
+          enriched[fieldName] = JSON.stringify(resolved);
+        }
+      }
+      return [enriched];
+    }
   }
 }
 function truncateContent(content, budget) {
@@ -537,7 +627,9 @@ 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 mergeDefaults = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" && spec.source.type !== "enriched";
+          const source = mergeDefaults ? { ...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 +1564,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) {
@@ -1876,15 +2001,19 @@ export {
   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.5",
+  "version": "0.7.0",
   "description": "Persistent structured memory for AI agent systems — SQLite ↔ LLM context bridge",
   "type": "module",
   "main": "./dist/index.js",