latticesql 0.6.0 → 0.8.0

package/README.md

@@ -356,13 +356,16 @@ db.defineMulti('agent-context', {
 db.defineEntityContext(table: string, def: EntityContextDefinition): this
 ```
 
-Generate a **parallel file-system tree** for an entity type — one subdirectory per row, one file per declared relationship, and an optional combined context file. Must be called before `init()`.
+Generate a **parallel file-system tree** for an entity type — one subdirectory per row, one file per declared relationship, and an optional combined context file. Can be called before or after `init()`.
 
 ```typescript
 db.defineEntityContext('agents', {
   // Derive the subdirectory name for each entity
   slug: (row) => row.slug as string,
 
+  // Default query options for all relationship sources (v0.6+)
+  sourceDefaults: { softDelete: true },
+
   // Global index file listing all entities
   index: {
     outputFile: 'agents/AGENTS.md',
@@ -376,7 +379,8 @@ db.defineEntityContext('agents', {
       render: ([r]) => `# ${r.name as string}\n\n${r.bio as string ?? ''}`,
     },
     'TASKS.md': {
-      source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id' },
+      source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id',
+                orderBy: 'created_at', orderDir: 'desc', limit: 20 },
       render: (rows) => rows.map((r) => `- ${r.title as string}`).join('\n'),
       omitIfEmpty: true,                               // skip if no tasks
       budget: 4000,                                    // truncate at 4 000 chars
@@ -388,6 +392,7 @@ db.defineEntityContext('agents', {
         localKey: 'agent_id',
         remoteKey: 'skill_id',
         remoteTable: 'skills',
+        orderBy: 'name',                               // softDelete inherited from sourceDefaults
       },
       render: (rows) => rows.map((r) => `- ${r.name as string}`).join('\n'),
       omitIfEmpty: true,
@@ -423,11 +428,82 @@ context/
 | Type | What it queries |
 |---|---|
 | `{ type: 'self' }` | The entity row itself |
-| `{ type: 'hasMany', table, foreignKey, references? }` | Rows in `table` where `foreignKey = entityPk` |
-| `{ type: 'manyToMany', junctionTable, localKey, remoteKey, remoteTable, references? }` | Remote rows via a junction table |
-| `{ type: 'belongsTo', table, foreignKey, references? }` | Single parent row via FK on this entity (`null` FK → empty) |
+| `{ type: 'hasMany', table, foreignKey, ... }` | Rows in `table` where `foreignKey = entityPk` |
+| `{ type: 'manyToMany', junctionTable, localKey, remoteKey, remoteTable, ... }` | Remote rows via a junction table |
+| `{ type: 'belongsTo', table, foreignKey, ... }` | Single parent row via FK on this entity (`null` FK → empty) |
+| `{ type: 'enriched', include: { ... } }` | Entity row + related data attached as `_key` JSON fields (v0.7+) |
 | `{ type: 'custom', query: (row, adapter) => Row[] }` | Fully custom synchronous query |
 
+#### Source query options (v0.6+)
+
+`hasMany`, `manyToMany`, and `belongsTo` sources accept optional query refinements:
+
+```typescript
+{
+  type: 'hasMany',
+  table: 'tasks',
+  foreignKey: 'agent_id',
+  // Query options (all optional):
+  softDelete: true,          // exclude rows where deleted_at IS NULL
+  filters: [                 // additional WHERE clauses (uses existing Filter type)
+    { col: 'status', op: 'eq', val: 'active' },
+  ],
+  orderBy: 'created_at',    // ORDER BY column
+  orderDir: 'desc',         // 'asc' (default) or 'desc'
+  limit: 20,                // LIMIT N
+}
+```
+
+The `softDelete: true` shorthand is equivalent to `filters: [{ col: 'deleted_at', op: 'isNull' }]`.
+
+#### sourceDefaults (v0.6+)
+
+Set default query options for all relationship sources in an entity context:
+
+```typescript
+db.defineEntityContext('agents', {
+  slug: (row) => row.slug as string,
+  sourceDefaults: { softDelete: true },  // applied to all hasMany/manyToMany/belongsTo
+  files: {
+    'TASKS.md': {
+      // softDelete: true is inherited from sourceDefaults
+      source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id', orderBy: 'created_at' },
+      render: (rows) => rows.map((r) => `- ${r.title as string}`).join('\n'),
+    },
+  },
+});
+```
+
+Per-file source options override defaults. `custom`, `self`, and `enriched` sources are unaffected.
+
+#### Enriched source (v0.7+)
+
+Starts with the entity's own row and attaches related data as JSON string fields. Each key in `include` becomes a `_key` field containing `JSON.stringify(resolvedRows)`.
+
+```typescript
+'PROFILE.md': {
+  source: {
+    type: 'enriched',
+    include: {
+      // Declarative sub-lookups (support all query options)
+      skills:   { type: 'manyToMany', junctionTable: 'agent_skills',
+                  localKey: 'agent_id', remoteKey: 'skill_id',
+                  remoteTable: 'skills', softDelete: true },
+      projects: { type: 'hasMany', table: 'projects', foreignKey: 'org_id',
+                  softDelete: true, orderBy: 'name' },
+      // Custom sub-lookup for complex queries
+      stats:    { type: 'custom', query: (row, adapter) =>
+                    adapter.all('SELECT COUNT(*) as cnt FROM events WHERE actor_id = ?', [row.id]) },
+    },
+  },
+  render: ([row]) => {
+    const skills = JSON.parse(row._skills as string);
+    const projects = JSON.parse(row._projects as string);
+    return `# ${row.name}\n\nSkills: ${skills.length}\nProjects: ${projects.length}`;
+  },
+}
+```
+
 See [docs/entity-context.md](./docs/entity-context.md) for the complete guide.
 
 ---
@@ -924,6 +1000,71 @@ db.define('tickets', {
 
 ---
 
+## Markdown utilities (v0.6+)
+
+Composable helper functions for building render functions. Use inside `render: (rows) => ...` callbacks to reduce boilerplate.
+
+### `frontmatter(fields)`
+
+Generate a YAML-style frontmatter block. Automatically includes `generated_at` with the current ISO timestamp.
+
+```typescript
+import { frontmatter } from 'latticesql';
+
+const header = frontmatter({ agent: 'Alice', skill_count: 5 });
+// ---
+// generated_at: "2026-03-27T..."
+// agent: "Alice"
+// skill_count: 5
+// ---
+```
+
+### `markdownTable(rows, columns)`
+
+Generate a GitHub-Flavoured Markdown table from rows with explicit column configuration and optional per-cell formatters.
+
+```typescript
+import { markdownTable } from 'latticesql';
+
+const md = markdownTable(rows, [
+  { key: 'name',   header: 'Name' },
+  { key: 'status', header: 'Status', format: (v) => String(v || '—') },
+  { key: 'name',   header: 'Detail', format: (v, row) => `[view](${row.slug}/DETAIL.md)` },
+]);
+// | Name | Status | Detail |
+// | --- | --- | --- |
+// | Alice | active | [view](alice/DETAIL.md) |
+```
+
+Returns empty string for zero rows. The `format` callback receives `(cellValue, fullRow)`.
+
+### `slugify(name)`
+
+Generate a URL-safe slug from a display name — lowercases, strips diacritics, replaces non-alphanumeric runs with hyphens.
+
+```typescript
+import { slugify } from 'latticesql';
+
+slugify('My Agent Name');  // 'my-agent-name'
+slugify('Jose Garcia');    // 'jose-garcia'
+```
+
+### `truncate(content, maxChars, notice?)`
+
+Truncate content at a character budget. Appends a notice when truncation occurs.
+
+```typescript
+import { truncate } from 'latticesql';
+
+const md = truncate(longContent, 4000);
+// Appends: "\n\n*[truncated — context budget exceeded]*"
+
+const md2 = truncate(longContent, 4000, '\n\n[...truncated]');
+// Custom notice
+```
+
+---
+
 ## Entity context directories (v0.5+)
 
 `defineEntityContext()` is the high-level API for per-entity file generation — the pattern where each entity type gets its own directory tree, with a separate file for each relationship type.
@@ -1071,6 +1212,74 @@ interface SessionWriteEntry {
 
 The processor is responsible for applying the parsed entries to your DB and validating field names against your schema. The `parseSessionWrites` function is pure — no DB access, no side effects.
 
+### Full session parser (v0.5.2+)
+
+For parsing **all** entry types (not just writes), use `parseSessionMD`:
+
+```ts
+import { parseSessionMD, parseMarkdownEntries } from 'latticesql';
+
+// Parse YAML-delimited entries (--- header --- body ===)
+const result = parseSessionMD(content, startOffset);
+// result.entries: SessionEntry[]  — all types: event, learning, status, write, etc.
+// result.errors:  ParseError[]
+// result.lastOffset: number       — for incremental parsing
+
+// Parse markdown heading entries (## timestamp — description)
+const mdResult = parseMarkdownEntries(content, 'agent-name', startOffset);
+```
+
+#### Configurable entry types (v0.5.5+)
+
+By default, the parser validates against a built-in set of entry types. Override via `SessionParseOptions`:
+
+```ts
+import { parseSessionMD, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES } from 'latticesql';
+
+// Accept any type (no validation)
+parseSessionMD(content, 0, { validTypes: null });
+
+// Custom type set
+parseSessionMD(content, 0, {
+  validTypes: new Set(['alert', 'todo', 'write']),
+  typeAliases: { warning: 'alert', task: 'todo' },
+});
+```
+
+### Read-only header (v0.5.5+)
+
+All generated context files should carry a read-only header. Use the default or create a custom one:
+
+```ts
+import { READ_ONLY_HEADER, createReadOnlyHeader } from 'latticesql';
+
+// Default: "generated by Lattice"
+const header = READ_ONLY_HEADER;
+
+// Custom generator name and docs reference
+const custom = createReadOnlyHeader({
+  generator: 'my-sync-tool',
+  docsRef: 'https://example.com/docs/sessions',
+});
+```
+
+### Write applicator (v0.5.2+)
+
+Apply parsed write entries to a better-sqlite3 database with schema validation:
+
+```ts
+import { applyWriteEntry } from 'latticesql';
+
+const result = applyWriteEntry(db, writeEntry);
+if (result.ok) {
+  console.log(`Applied to ${result.table}, record ${result.recordId}`);
+} else {
+  console.error(result.reason);
+}
+```
+
+Validates table existence, field names against schema, and uses soft-delete when a `deleted_at` column exists.
+
 ---
 
 ## YAML config (v0.4+)

package/dist/cli.js

@@ -666,9 +666,18 @@ function appendQueryOptions(baseSql, params, opts, tableAlias) {
         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.orderBy) {
+    if (typeof opts.orderBy === "string") {
+      if (SAFE_COL_RE.test(opts.orderBy)) {
+        const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+        sql += ` ORDER BY ${prefix}"${opts.orderBy}" ${dir}`;
+      }
+    } else {
+      const clauses = opts.orderBy.filter((spec) => SAFE_COL_RE.test(spec.col)).map((spec) => `${prefix}"${spec.col}" ${spec.dir === "desc" ? "DESC" : "ASC"}`);
+      if (clauses.length > 0) {
+        sql += ` ORDER BY ${clauses.join(", ")}`;
+      }
+    }
   }
   if (opts.limit !== void 0 && opts.limit > 0) {
     sql += ` LIMIT ${Math.floor(opts.limit)}`;
@@ -691,7 +700,19 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
       const pkVal = entityRow[entityPk];
       const remotePk = source.references ?? "id";
       const params = [pkVal];
-      let sql = `SELECT r.* FROM "${source.remoteTable}" r
+      let selectCols = "r.*";
+      if (source.junctionColumns?.length) {
+        const jCols = source.junctionColumns.map((jc) => {
+          if (typeof jc === "string") {
+            if (!SAFE_COL_RE.test(jc)) return null;
+            return `j."${jc}"`;
+          }
+          if (!SAFE_COL_RE.test(jc.col) || !SAFE_COL_RE.test(jc.as)) return null;
+          return `j."${jc.col}" AS "${jc.as}"`;
+        }).filter(Boolean);
+        if (jCols.length > 0) selectCols += ", " + jCols.join(", ");
+      }
+      let sql = `SELECT ${selectCols} FROM "${source.remoteTable}" r
          JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
          WHERE j."${source.localKey}" = ?`;
       sql = appendQueryOptions(sql, params, source, "r");
@@ -716,6 +737,19 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
     }
     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) {
@@ -928,7 +962,8 @@ var RenderEngine = class {
         mkdirSync3(entityDir, { recursive: true });
         const renderedFiles = /* @__PURE__ */ new Map();
         for (const [filename, spec] of Object.entries(def.files)) {
-          const source = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" ? { ...def.sourceDefaults, ...spec.source } : spec.source;
+          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);

package/dist/index.cjs

@@ -408,9 +408,18 @@ function appendQueryOptions(baseSql, params, opts, tableAlias) {
         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.orderBy) {
+    if (typeof opts.orderBy === "string") {
+      if (SAFE_COL_RE.test(opts.orderBy)) {
+        const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+        sql += ` ORDER BY ${prefix}"${opts.orderBy}" ${dir}`;
+      }
+    } else {
+      const clauses = opts.orderBy.filter((spec) => SAFE_COL_RE.test(spec.col)).map((spec) => `${prefix}"${spec.col}" ${spec.dir === "desc" ? "DESC" : "ASC"}`);
+      if (clauses.length > 0) {
+        sql += ` ORDER BY ${clauses.join(", ")}`;
+      }
+    }
   }
   if (opts.limit !== void 0 && opts.limit > 0) {
     sql += ` LIMIT ${Math.floor(opts.limit)}`;
@@ -433,7 +442,19 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
       const pkVal = entityRow[entityPk];
       const remotePk = source.references ?? "id";
       const params = [pkVal];
-      let sql = `SELECT r.* FROM "${source.remoteTable}" r
+      let selectCols = "r.*";
+      if (source.junctionColumns?.length) {
+        const jCols = source.junctionColumns.map((jc) => {
+          if (typeof jc === "string") {
+            if (!SAFE_COL_RE.test(jc)) return null;
+            return `j."${jc}"`;
+          }
+          if (!SAFE_COL_RE.test(jc.col) || !SAFE_COL_RE.test(jc.as)) return null;
+          return `j."${jc.col}" AS "${jc.as}"`;
+        }).filter(Boolean);
+        if (jCols.length > 0) selectCols += ", " + jCols.join(", ");
+      }
+      let sql = `SELECT ${selectCols} FROM "${source.remoteTable}" r
          JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
          WHERE j."${source.localKey}" = ?`;
       sql = appendQueryOptions(sql, params, source, "r");
@@ -458,6 +479,19 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
     }
     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) {
@@ -670,7 +704,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 source = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" ? { ...def.sourceDefaults, ...spec.source } : spec.source;
+          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);

package/dist/index.d.cts

@@ -60,13 +60,33 @@ interface SourceQueryOptions {
      * 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'`. */
+    /**
+     * Column(s) to ORDER BY. Validated against `[a-zA-Z0-9_]`.
+     * - `string` — single column (use `orderDir` for direction)
+     * - `OrderBySpec[]` — multi-column with per-column direction
+     *
+     * @example
+     * ```ts
+     * orderBy: 'name'                                  // single column
+     * orderBy: [{ col: 'severity' }, { col: 'timestamp', dir: 'desc' }]  // multi
+     * ```
+     */
+    orderBy?: string | OrderBySpec[];
+    /** Sort direction when `orderBy` is a string. Defaults to `'asc'`. */
     orderDir?: 'asc' | 'desc';
     /** Maximum number of rows to return. */
     limit?: number;
 }
+/**
+ * A single ORDER BY column with optional direction.
+ * Used in the array form of `SourceQueryOptions.orderBy`.
+ */
+interface OrderBySpec {
+    /** Column name (validated against `[a-zA-Z0-9_]`). */
+    col: string;
+    /** Sort direction. Defaults to `'asc'`. */
+    dir?: 'asc' | 'desc';
+}
 /**
  * Yield the entity row itself as a single-element array.
  * Use for the primary entity file (e.g. `AGENT.md`).
@@ -125,6 +145,20 @@ interface ManyToManySource extends SourceQueryOptions {
      * Defaults to `'id'`.
      */
     references?: string;
+    /**
+     * Columns from the junction table to include in each result row.
+     * Use a string for the column name as-is, or `{ col, as }` to alias.
+     *
+     * @example
+     * ```ts
+     * junctionColumns: ['source', { col: 'role', as: 'agent_role' }]
+     * // Adds j."source" and j."role" AS "agent_role" to each row
+     * ```
+     */
+    junctionColumns?: Array<string | {
+        col: string;
+        as: string;
+    }>;
 }
 /**
  * Query the single row that this entity belongs to via a foreign key on
@@ -167,8 +201,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.
  *
@@ -1147,4 +1230,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 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 };
+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 OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, frontmatter, generateEntryId, generateWriteEntryId, manifestPath, markdownTable, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };

package/dist/index.d.ts

@@ -60,13 +60,33 @@ interface SourceQueryOptions {
      * 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'`. */
+    /**
+     * Column(s) to ORDER BY. Validated against `[a-zA-Z0-9_]`.
+     * - `string` — single column (use `orderDir` for direction)
+     * - `OrderBySpec[]` — multi-column with per-column direction
+     *
+     * @example
+     * ```ts
+     * orderBy: 'name'                                  // single column
+     * orderBy: [{ col: 'severity' }, { col: 'timestamp', dir: 'desc' }]  // multi
+     * ```
+     */
+    orderBy?: string | OrderBySpec[];
+    /** Sort direction when `orderBy` is a string. Defaults to `'asc'`. */
     orderDir?: 'asc' | 'desc';
     /** Maximum number of rows to return. */
     limit?: number;
 }
+/**
+ * A single ORDER BY column with optional direction.
+ * Used in the array form of `SourceQueryOptions.orderBy`.
+ */
+interface OrderBySpec {
+    /** Column name (validated against `[a-zA-Z0-9_]`). */
+    col: string;
+    /** Sort direction. Defaults to `'asc'`. */
+    dir?: 'asc' | 'desc';
+}
 /**
  * Yield the entity row itself as a single-element array.
  * Use for the primary entity file (e.g. `AGENT.md`).
@@ -125,6 +145,20 @@ interface ManyToManySource extends SourceQueryOptions {
      * Defaults to `'id'`.
      */
     references?: string;
+    /**
+     * Columns from the junction table to include in each result row.
+     * Use a string for the column name as-is, or `{ col, as }` to alias.
+     *
+     * @example
+     * ```ts
+     * junctionColumns: ['source', { col: 'role', as: 'agent_role' }]
+     * // Adds j."source" and j."role" AS "agent_role" to each row
+     * ```
+     */
+    junctionColumns?: Array<string | {
+        col: string;
+        as: string;
+    }>;
 }
 /**
  * Query the single row that this entity belongs to via a foreign key on
@@ -167,8 +201,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.
  *
@@ -1147,4 +1230,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 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 };
+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 OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, applyWriteEntry, createReadOnlyHeader, frontmatter, generateEntryId, generateWriteEntryId, manifestPath, markdownTable, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };

package/dist/index.js

@@ -352,9 +352,18 @@ function appendQueryOptions(baseSql, params, opts, tableAlias) {
         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.orderBy) {
+    if (typeof opts.orderBy === "string") {
+      if (SAFE_COL_RE.test(opts.orderBy)) {
+        const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+        sql += ` ORDER BY ${prefix}"${opts.orderBy}" ${dir}`;
+      }
+    } else {
+      const clauses = opts.orderBy.filter((spec) => SAFE_COL_RE.test(spec.col)).map((spec) => `${prefix}"${spec.col}" ${spec.dir === "desc" ? "DESC" : "ASC"}`);
+      if (clauses.length > 0) {
+        sql += ` ORDER BY ${clauses.join(", ")}`;
+      }
+    }
   }
   if (opts.limit !== void 0 && opts.limit > 0) {
     sql += ` LIMIT ${Math.floor(opts.limit)}`;
@@ -377,7 +386,19 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
       const pkVal = entityRow[entityPk];
       const remotePk = source.references ?? "id";
       const params = [pkVal];
-      let sql = `SELECT r.* FROM "${source.remoteTable}" r
+      let selectCols = "r.*";
+      if (source.junctionColumns?.length) {
+        const jCols = source.junctionColumns.map((jc) => {
+          if (typeof jc === "string") {
+            if (!SAFE_COL_RE.test(jc)) return null;
+            return `j."${jc}"`;
+          }
+          if (!SAFE_COL_RE.test(jc.col) || !SAFE_COL_RE.test(jc.as)) return null;
+          return `j."${jc.col}" AS "${jc.as}"`;
+        }).filter(Boolean);
+        if (jCols.length > 0) selectCols += ", " + jCols.join(", ");
+      }
+      let sql = `SELECT ${selectCols} FROM "${source.remoteTable}" r
          JOIN "${source.junctionTable}" j ON j."${source.remoteKey}" = r."${remotePk}"
          WHERE j."${source.localKey}" = ?`;
       sql = appendQueryOptions(sql, params, source, "r");
@@ -402,6 +423,19 @@ function resolveEntitySource(source, entityRow, entityPk, adapter) {
     }
     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) {
@@ -614,7 +648,8 @@ var RenderEngine = class {
         mkdirSync2(entityDir, { recursive: true });
         const renderedFiles = /* @__PURE__ */ new Map();
         for (const [filename, spec] of Object.entries(def.files)) {
-          const source = def.sourceDefaults && spec.source.type !== "self" && spec.source.type !== "custom" ? { ...def.sourceDefaults, ...spec.source } : spec.source;
+          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);

package/package.json

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