latticesql 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,869 @@
+import Database from 'better-sqlite3';
+
+interface LatticeManifest {
+    version: 1;
+    generated_at: string;
+    entityContexts: Record<string, EntityContextManifestEntry>;
+}
+interface EntityContextManifestEntry {
+    directoryRoot: string;
+    indexFile?: string;
+    declaredFiles: string[];
+    protectedFiles: string[];
+    /** Key = slug, value = filenames actually written (omitIfEmpty files may be absent) */
+    entities: Record<string, string[]>;
+}
+declare function manifestPath(outputDir: string): string;
+declare function readManifest(outputDir: string): LatticeManifest | null;
+declare function writeManifest(outputDir: string, manifest: LatticeManifest): void;
+
+/** Pluggable storage backend interface */
+interface StorageAdapter {
+    /** Execute a statement with no return value */
+    run(sql: string, params?: unknown[]): void;
+    /** Execute a statement and return one row or undefined */
+    get(sql: string, params?: unknown[]): Row | undefined;
+    /** Execute a statement and return all rows */
+    all(sql: string, params?: unknown[]): Row[];
+    /** Prepare and cache a statement for repeated execution */
+    prepare(sql: string): PreparedStatement;
+    /** Open the connection */
+    open(): void;
+    /** Close the connection */
+    close(): void;
+}
+interface PreparedStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): Row | undefined;
+    all(...params: unknown[]): Row[];
+}
+
+/**
+ * Yield the entity row itself as a single-element array.
+ * Use for the primary entity file (e.g. `AGENT.md`).
+ */
+interface SelfSource {
+    type: 'self';
+}
+/**
+ * Query rows from another table where a foreign key on that table points back
+ * to this entity (e.g. all tasks where `tasks.agent_id = agent.id`).
+ *
+ * @example
+ * ```ts
+ * source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id' }
+ * ```
+ */
+interface HasManySource {
+    type: 'hasMany';
+    /** The related table to query */
+    table: string;
+    /** Column on the RELATED table that holds the FK pointing to this entity */
+    foreignKey: string;
+    /**
+     * Column on THIS entity's table that is referenced.
+     * Defaults to the entity table's first primary key column.
+     */
+    references?: string;
+}
+/**
+ * Query rows from a remote table via a junction table
+ * (e.g. skills for an agent via `agent_skills`).
+ *
+ * @example
+ * ```ts
+ * source: {
+ *   type: 'manyToMany',
+ *   junctionTable: 'agent_skills',
+ *   localKey:  'agent_id',   // FK in junction → this entity
+ *   remoteKey: 'skill_id',   // FK in junction → remote entity
+ *   remoteTable: 'skills',
+ * }
+ * ```
+ */
+interface ManyToManySource {
+    type: 'manyToMany';
+    /** The junction / association table */
+    junctionTable: string;
+    /** Column in the junction table that points to THIS entity */
+    localKey: string;
+    /** Column in the junction table that points to the REMOTE entity */
+    remoteKey: string;
+    /** The remote table to JOIN and return rows from */
+    remoteTable: string;
+    /**
+     * Primary key column on `remoteTable` that `remoteKey` references.
+     * Defaults to `'id'`.
+     */
+    references?: string;
+}
+/**
+ * Query the single row that this entity belongs to via a foreign key on
+ * THIS entity's table (e.g. the team a bot belongs to via `bot.team_id`).
+ *
+ * Returns `[]` when the FK column is NULL; returns `[row]` when found.
+ *
+ * @example
+ * ```ts
+ * source: { type: 'belongsTo', table: 'teams', foreignKey: 'team_id' }
+ * ```
+ */
+interface BelongsToSource {
+    type: 'belongsTo';
+    /** The related table to look up */
+    table: string;
+    /** Column on THIS entity's table that holds the FK */
+    foreignKey: string;
+    /**
+     * Column on the RELATED table being referenced.
+     * Defaults to `'id'`.
+     */
+    references?: string;
+}
+/**
+ * Fully custom query — caller receives the entity row and the raw SQLite
+ * adapter, returns whatever rows they need.  Use a closure to capture any
+ * additional context (other table names, filter conditions, etc.).
+ *
+ * @example
+ * ```ts
+ * source: {
+ *   type: 'custom',
+ *   query: (row, adapter) =>
+ *     adapter.all('SELECT * FROM events WHERE actor_id = ? ORDER BY ts DESC LIMIT 20', [row.id]),
+ * }
+ * ```
+ */
+interface CustomSource {
+    type: 'custom';
+    query: (row: Row, adapter: StorageAdapter) => Row[];
+}
+/** Union of all supported source types for {@link EntityFileSpec}. */
+type EntityFileSource = SelfSource | HasManySource | ManyToManySource | BelongsToSource | CustomSource;
+/**
+ * Specification for a single file generated inside an entity's directory.
+ *
+ * @example
+ * ```ts
+ * 'SKILLS.md': {
+ *   source: { type: 'manyToMany', junctionTable: 'agent_skills', localKey: 'agent_id',
+ *             remoteKey: 'skill_id', remoteTable: 'skills' },
+ *   render: (rows) => `# Skills\n\n${rows.map(r => `- ${r.name}`).join('\n')}`,
+ *   omitIfEmpty: true,
+ *   budget: 2000,
+ * }
+ * ```
+ */
+interface EntityFileSpec {
+    /** Determines what rows are passed to {@link render}. */
+    source: EntityFileSource;
+    /**
+     * Converts the resolved rows into the file's markdown content.
+     * For `self` sources, `rows` is always a single-element array.
+     */
+    render: (rows: Row[]) => string;
+    /**
+     * Maximum number of characters allowed in the rendered output.
+     * Content exceeding this limit is truncated with a notice appended.
+     */
+    budget?: number;
+    /**
+     * When `true`, skip writing this file if the source returns zero rows.
+     * Defaults to `false`.
+     */
+    omitIfEmpty?: boolean;
+}
+/**
+ * Defines the parallel file-system structure for one entity type.
+ *
+ * Lattice uses this to generate:
+ * - An optional global index file listing all entities
+ * - A per-entity subdirectory with one file per declared {@link files} entry
+ * - An optional combined context file (CONTEXT.md) concatenating all files
+ *
+ * @example
+ * ```ts
+ * db.defineEntityContext('agents', {
+ *   slug: (row) => row.slug as string,
+ *   index: { outputFile: 'agents/AGENTS.md', render: (rows) => `# Agents\n...` },
+ *   files: {
+ *     'AGENT.md':   { source: { type: 'self' }, render: ([r]) => `# ${r.name}` },
+ *     'SKILLS.md':  { source: { type: 'manyToMany', ... }, render, omitIfEmpty: true },
+ *   },
+ *   combined: { outputFile: 'CONTEXT.md' },
+ * });
+ * ```
+ */
+interface EntityContextDefinition {
+    /**
+     * Derives the directory slug for this entity from its row.
+     * Used as the subdirectory name under {@link directoryRoot}.
+     *
+     * @example `(row) => row.slug as string`
+     */
+    slug: (row: Row) => string;
+    /**
+     * Optional global index file written once per render cycle (not per entity).
+     * Lists all entities of this type.
+     */
+    index?: {
+        /** Path relative to the `outputDir` passed to `render()` / `watch()` */
+        outputFile: string;
+        render: (rows: Row[]) => string;
+    };
+    /**
+     * Files written inside each entity's directory.
+     * Keys are filenames (e.g. `'AGENT.md'`); values define the source and renderer.
+     * Files are written in iteration order.
+     */
+    files: Record<string, EntityFileSpec>;
+    /**
+     * Optional combined context file inside each entity's directory.
+     * Lattice concatenates all per-entity files with `\n\n---\n\n` dividers.
+     * Files listed in `exclude` are omitted from the combined output.
+     */
+    combined?: {
+        /** Filename for the combined file (e.g. `'CONTEXT.md'`) */
+        outputFile: string;
+        /** Filenames to exclude from the combined output */
+        exclude?: string[];
+    };
+    /**
+     * Override the per-entity directory path relative to `outputDir`.
+     * Defaults to `'{directoryRoot}/{slug}'`.
+     *
+     * @example `(row) => \`custom-dir/${row.slug as string}/\``
+     */
+    directory?: (row: Row) => string;
+    /**
+     * Top-level directory owned by this entity context.
+     * Used by `reconcile()` to scan for orphaned subdirectories.
+     * Defaults to the table name.
+     */
+    directoryRoot?: string;
+    /**
+     * Files inside each entity's directory that Lattice must never delete
+     * during cleanup or reconciliation (e.g. agent-writable files like `SESSION.md`).
+     * Defaults to `[]`.
+     */
+    protectedFiles?: string[];
+}
+
+interface CleanupOptions {
+    /** Remove entity directories whose slug is no longer in the DB. Default: true. */
+    removeOrphanedDirectories?: boolean;
+    /** Remove files inside entity dirs that are no longer declared. Default: true. */
+    removeOrphanedFiles?: boolean;
+    /** Additional globally protected files (merged with per-entity protectedFiles). */
+    protectedFiles?: string[];
+    /** Report orphans but do not delete anything. */
+    dryRun?: boolean;
+    /** Called for each orphan before removal (or instead of removal in dryRun mode). */
+    onOrphan?: (path: string, kind: 'directory' | 'file') => void;
+}
+interface CleanupResult {
+    directoriesRemoved: string[];
+    filesRemoved: string[];
+    /** Directories with user files that were left in place. */
+    directoriesSkipped: string[];
+    warnings: string[];
+}
+
+type Row = Record<string, unknown>;
+interface LatticeOptions {
+    wal?: boolean;
+    busyTimeout?: number;
+    security?: SecurityOptions;
+}
+interface SecurityOptions {
+    sanitize?: boolean;
+    auditTables?: string[];
+    fieldLimits?: Record<string, number>;
+}
+/**
+ * The primary key of a table. Either a single column name (string) or an
+ * ordered list of column names for composite keys.
+ *
+ * Defaults to `'id'` when omitted from a TableDefinition. When the default
+ * `'id'` is used and the `id` field is absent on insert, a UUID v4 is
+ * generated automatically. For custom single or composite keys the caller
+ * must supply all PK column values.
+ */
+type PrimaryKey = string | string[];
+/**
+ * A foreign-key relationship where THIS table holds the FK pointing to another
+ * table (e.g. `comment.post_id → posts.id`).
+ */
+interface BelongsToRelation {
+    type: 'belongsTo';
+    /** The related table */
+    table: string;
+    /** Column on THIS table that holds the foreign key */
+    foreignKey: string;
+    /**
+     * Column on the RELATED table being referenced.
+     * Defaults to that table's first primary key column.
+     */
+    references?: string;
+}
+/**
+ * A relationship where ANOTHER table holds the FK pointing back to this table
+ * (e.g. `posts.id ← comments.post_id`).
+ */
+interface HasManyRelation {
+    type: 'hasMany';
+    /** The related table */
+    table: string;
+    /** Column on the RELATED table that points back to this table */
+    foreignKey: string;
+    /**
+     * Column on THIS table being referenced.
+     * Defaults to this table's first primary key column.
+     */
+    references?: string;
+}
+/** A declared relationship between two tables. */
+type Relation = BelongsToRelation | HasManyRelation;
+/**
+ * Comparison operators available in a {@link Filter}.
+ *
+ * - `eq` / `ne`  — equality / inequality
+ * - `gt` / `gte` / `lt` / `lte` — numeric or lexicographic comparison
+ * - `like`       — SQL LIKE pattern (`%` is the wildcard)
+ * - `in`         — column value is one of a list
+ * - `isNull` / `isNotNull` — NULL checks (no `val` needed)
+ */
+type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'isNull' | 'isNotNull';
+/**
+ * A single filter clause with an explicit operator.
+ *
+ * @example
+ * ```ts
+ * { col: 'score',      op: 'gte',    val: 80 }
+ * { col: 'deleted_at', op: 'isNull'           }
+ * { col: 'status',     op: 'in',     val: ['open', 'pending'] }
+ * { col: 'name',       op: 'like',   val: 'A%' }
+ * ```
+ */
+interface Filter {
+    /** Column name to filter on */
+    col: string;
+    /** Comparison operator */
+    op: FilterOp;
+    /**
+     * Operand value. Not required for `isNull` / `isNotNull`.
+     * For `in`, must be an array.
+     */
+    val?: unknown;
+}
+/**
+ * Names of the four built-in render templates.
+ *
+ * - `default-list`   — one bullet per row (supports `formatRow` hook)
+ * - `default-table`  — GitHub-flavoured Markdown table
+ * - `default-detail` — section per row with all fields (supports `formatRow` hook)
+ * - `default-json`   — `JSON.stringify(rows, null, 2)`
+ */
+type BuiltinTemplateName = 'default-list' | 'default-table' | 'default-detail' | 'default-json';
+/**
+ * Lifecycle hooks that customise a built-in template.
+ *
+ * - `beforeRender(rows)` — transform or filter the row array before rendering.
+ * - `formatRow` — control how each row is serialised to a string.
+ *   Can be a plain function or a `{{field}}` interpolation template string.
+ *   Supported by `default-list` and `default-detail`.
+ *   `belongsTo` relation fields are available as `{{relationName.field}}`.
+ *
+ * @example
+ * ```ts
+ * hooks: {
+ *   beforeRender: (rows) => rows.filter(r => r.active),
+ *   formatRow: '{{title}} — {{status}}',
+ * }
+ * ```
+ */
+interface RenderHooks {
+    beforeRender?: (rows: Row[]) => Row[];
+    formatRow?: ((row: Row) => string) | string;
+}
+/**
+ * Use a built-in template, optionally with lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * render: { template: 'default-list', hooks: { formatRow: '- {{title}} ({{status}})' } }
+ * ```
+ */
+interface TemplateRenderSpec {
+    template: BuiltinTemplateName;
+    hooks?: RenderHooks;
+}
+/**
+ * The accepted value for `TableDefinition.render`:
+ *
+ * - A plain `(rows: Row[]) => string` function — full control, unchanged from v0.1/v0.2.
+ * - A `BuiltinTemplateName` string — use a built-in template with default settings.
+ * - A `TemplateRenderSpec` object — use a built-in template with lifecycle hooks.
+ */
+type RenderSpec = ((rows: Row[]) => string) | BuiltinTemplateName | TemplateRenderSpec;
+interface TableDefinition {
+    /** Column name → SQLite type spec (e.g. `'TEXT PRIMARY KEY'`) */
+    columns: Record<string, string>;
+    /**
+     * How to render DB rows into text content for the context file.
+     *
+     * - Pass a `(rows: Row[]) => string` function for full control (v0.1/v0.2 behaviour).
+     * - Pass a `BuiltinTemplateName` string (`'default-list'`, `'default-table'`,
+     *   `'default-detail'`, `'default-json'`) to use a built-in template.
+     * - Pass a `TemplateRenderSpec` to use a built-in template with lifecycle hooks.
+     */
+    render: RenderSpec;
+    /** Output path relative to the outputDir passed to render/watch */
+    outputFile: string;
+    /** Optional pre-filter applied before render */
+    filter?: (rows: Row[]) => Row[];
+    /**
+     * Primary key column name or names.
+     *
+     * - Omit (or `'id'`): default behaviour — UUID auto-generated on insert when absent.
+     * - Custom string (e.g. `'slug'`): caller must supply the value on every insert.
+     * - Array (e.g. `['org_id', 'seq']`): composite key — caller must supply all columns.
+     *
+     * @example
+     * ```ts
+     * primaryKey: 'slug'
+     * primaryKey: ['tenant_id', 'ticket_id']
+     * ```
+     */
+    primaryKey?: PrimaryKey;
+    /**
+     * Optional table-level SQL constraints appended after the column list.
+     * Required for composite primary keys and multi-column unique constraints,
+     * which cannot be expressed in the per-column `columns` spec.
+     *
+     * @example
+     * ```ts
+     * tableConstraints: ['PRIMARY KEY (tenant_id, seq)']
+     * tableConstraints: ['PRIMARY KEY (a, b)', 'UNIQUE (email, org_id)']
+     * ```
+     */
+    tableConstraints?: string[];
+    /**
+     * Declared relationships to other registered tables.
+     * Stored as metadata in v0.2; used by template rendering in v0.3+.
+     *
+     * @example
+     * ```ts
+     * relations: {
+     *   author:   { type: 'belongsTo', table: 'users',    foreignKey: 'author_id' },
+     *   comments: { type: 'hasMany',   table: 'comments', foreignKey: 'post_id'   },
+     * }
+     * ```
+     */
+    relations?: Record<string, Relation>;
+}
+interface MultiTableDefinition {
+    /** Returns the "anchor" entities — one output file is produced per anchor */
+    keys: () => Promise<Row[]>;
+    /** Derive the output file path from the anchor entity */
+    outputFile: (key: Row) => string;
+    /** Transform an anchor entity + related table data into text content */
+    render: (key: Row, tables: Record<string, Row[]>) => string;
+    /** Additional table names to query and pass into render */
+    tables?: string[];
+}
+interface WritebackDefinition {
+    /** Path or glob to agent-written files */
+    file: string;
+    /** Parse new file content starting at fromOffset; return entries and next offset */
+    parse: (content: string, fromOffset: number) => {
+        entries: unknown[];
+        nextOffset: number;
+    };
+    /** Persist a single parsed entry; called exactly once per unique dedupeKey */
+    persist: (entry: unknown, filePath: string) => Promise<void>;
+    /** Optional dedup key — if omitted, every entry is processed */
+    dedupeKey?: (entry: unknown) => string;
+}
+interface QueryOptions {
+    /**
+     * Equality filters — shorthand for `filters: [{ col, op: 'eq', val }]`.
+     * Fully backward compatible with pre-v0.2 usage.
+     */
+    where?: Record<string, unknown>;
+    /**
+     * Advanced filter clauses with full operator support.
+     * Combined with `where` using AND.
+     *
+     * @example
+     * ```ts
+     * filters: [
+     *   { col: 'priority',   op: 'gte',    val: 3 },
+     *   { col: 'deleted_at', op: 'isNull'          },
+     *   { col: 'tag',        op: 'in',     val: ['bug', 'feature'] },
+     * ]
+     * ```
+     */
+    filters?: Filter[];
+    orderBy?: string;
+    orderDir?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+interface CountOptions {
+    /** Equality filters (same as QueryOptions.where) */
+    where?: Record<string, unknown>;
+    /** Advanced filter clauses (same as QueryOptions.filters) */
+    filters?: Filter[];
+}
+interface InitOptions {
+    migrations?: Migration[];
+}
+interface Migration {
+    version: number;
+    sql: string;
+}
+interface WatchOptions {
+    /** Poll interval in milliseconds (default: 5000) */
+    interval?: number;
+    onRender?: (result: RenderResult) => void;
+    onError?: (err: Error) => void;
+    /**
+     * If set, runs orphan cleanup after each render cycle using the previous manifest.
+     * Safe to enable in long-running daemons — never removes protectedFiles.
+     */
+    cleanup?: CleanupOptions;
+    /** Called after each cleanup cycle (only when cleanup option is set). */
+    onCleanup?: (result: CleanupResult) => void;
+}
+interface RenderResult {
+    filesWritten: string[];
+    filesSkipped: number;
+    durationMs: number;
+}
+interface SyncResult extends RenderResult {
+    writebackProcessed: number;
+}
+type StopFn = () => void;
+interface AuditEvent {
+    table: string;
+    operation: 'insert' | 'update' | 'delete';
+    id: string;
+    timestamp: string;
+}
+interface ReconcileOptions {
+    /** Remove entity directories whose slug is no longer in the DB. Default: true. */
+    removeOrphanedDirectories?: boolean;
+    /** Remove files inside entity dirs that are no longer declared. Default: true. */
+    removeOrphanedFiles?: boolean;
+    /** Additional globally protected files. */
+    protectedFiles?: string[];
+    /** Report orphans but do not delete anything. */
+    dryRun?: boolean;
+    /** Called for each orphan before removal. */
+    onOrphan?: (path: string, kind: 'directory' | 'file') => void;
+}
+interface ReconcileResult extends RenderResult {
+    cleanup: CleanupResult;
+}
+
+/**
+ * Initialise Lattice from a YAML config file instead of an explicit path.
+ *
+ * @example
+ * ```ts
+ * const db = new Lattice({ config: './lattice.config.yml' });
+ * await db.init();
+ * ```
+ */
+interface LatticeConfigInput {
+    /** Path to `lattice.config.yml` (absolute or relative to `process.cwd()`) */
+    config: string;
+    /** Optional Lattice runtime options */
+    options?: LatticeOptions;
+}
+type EventHandler<T> = (data: T) => void;
+/**
+ * A primary key lookup value.
+ * - `string` — the value of the table's single PK column (backward compatible).
+ * - `Record<string, unknown>` — column → value map for composite PKs.
+ */
+type PkLookup = string | Record<string, unknown>;
+declare class Lattice {
+    private readonly _adapter;
+    private readonly _schema;
+    private readonly _sanitizer;
+    private readonly _render;
+    private readonly _loop;
+    private readonly _writeback;
+    private _initialized;
+    /** Cache of actual table columns (from PRAGMA), populated after init(). */
+    private readonly _columnCache;
+    private readonly _auditHandlers;
+    private readonly _renderHandlers;
+    private readonly _writebackHandlers;
+    private readonly _errorHandlers;
+    constructor(pathOrConfig: string | LatticeConfigInput, options?: LatticeOptions);
+    define(table: string, def: TableDefinition): this;
+    defineMulti(name: string, def: MultiTableDefinition): this;
+    defineEntityContext(table: string, def: EntityContextDefinition): this;
+    defineWriteback(def: WritebackDefinition): this;
+    init(options?: InitOptions): Promise<void>;
+    close(): void;
+    insert(table: string, row: Row): Promise<string>;
+    upsert(table: string, row: Row): Promise<string>;
+    upsertBy(table: string, col: string, val: unknown, row: Row): Promise<string>;
+    update(table: string, id: PkLookup, row: Partial<Row>): Promise<void>;
+    delete(table: string, id: PkLookup): Promise<void>;
+    get(table: string, id: PkLookup): Promise<Row | null>;
+    query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    count(table: string, opts?: CountOptions): Promise<number>;
+    render(outputDir: string): Promise<RenderResult>;
+    sync(outputDir: string): Promise<SyncResult>;
+    reconcile(outputDir: string, options?: ReconcileOptions): Promise<ReconcileResult>;
+    watch(outputDir: string, opts?: WatchOptions): Promise<StopFn>;
+    on(event: 'audit', handler: EventHandler<AuditEvent>): this;
+    on(event: 'render', handler: EventHandler<RenderResult>): this;
+    on(event: 'writeback', handler: EventHandler<{
+        filePath: string;
+        entriesProcessed: number;
+    }>): this;
+    on(event: 'error', handler: EventHandler<Error>): this;
+    get db(): Database.Database;
+    /**
+     * Filter a sanitized row to only include columns that actually exist in the
+     * table (verified via PRAGMA after init). Unregistered tables (accessed
+     * through the raw `.db` handle) are passed through unchanged.
+     *
+     * This is a defence-in-depth guard: column names from caller-supplied `row`
+     * objects are interpolated into SQL, so stripping unknown keys eliminates
+     * any theoretical injection vector from crafted object keys.
+     */
+    private _filterToSchemaColumns;
+    /**
+     * Build the WHERE clause and params for a PK lookup.
+     * - `string` → matches against the table's first PK column.
+     * - `Record` → matches every PK column; all must be present in the object.
+     */
+    private _pkWhere;
+    /**
+     * Convert Filter objects into SQL clause strings and bound params.
+     * An `in` filter with an empty array is silently ignored (produces no clause).
+     */
+    private _buildFilters;
+    /** Returns a rejected Promise if not initialized; null if ready. */
+    private _notInitError;
+    /**
+     * Returns a rejected Promise if any of the given column names are not present
+     * in the table's schema; null if all columns are valid.
+     *
+     * Applied on the read path (query/count) to validate WHERE and filter column
+     * names before they are interpolated into SQL. The write path strips unknown
+     * columns via _filterToSchemaColumns; the read path rejects instead to avoid
+     * silently discarding intended filter conditions.
+     *
+     * Unregistered tables (accessed via the raw `.db` handle) are passed through.
+     */
+    private _invalidColumnError;
+    private _assertNotInit;
+}
+
+/**
+ * Scalar types recognised in `lattice.config.yml` field definitions.
+ *
+ * | YAML type   | SQLite type | TypeScript type |
+ * | ----------- | ----------- | --------------- |
+ * | `uuid`      | TEXT        | string          |
+ * | `text`      | TEXT        | string          |
+ * | `integer`   | INTEGER     | number          |
+ * | `int`       | INTEGER     | number          |
+ * | `real`      | REAL        | number          |
+ * | `float`     | REAL        | number          |
+ * | `boolean`   | INTEGER     | boolean         |
+ * | `bool`      | INTEGER     | boolean         |
+ * | `datetime`  | TEXT        | string          |
+ * | `date`      | TEXT        | string          |
+ * | `blob`      | BLOB        | Buffer          |
+ */
+type LatticeFieldType = 'uuid' | 'text' | 'integer' | 'int' | 'real' | 'float' | 'boolean' | 'bool' | 'datetime' | 'date' | 'blob';
+/**
+ * A single field (column) definition in a `lattice.config.yml` entity.
+ *
+ * @example
+ * ```yaml
+ * id:          { type: uuid,    primaryKey: true }
+ * title:       { type: text,    required: true }
+ * status:      { type: text,    default: open }
+ * assignee_id: { type: uuid,    ref: user }
+ * score:       { type: integer, default: 0 }
+ * ```
+ */
+interface LatticeFieldDef {
+    /** Column data type */
+    type: LatticeFieldType;
+    /** Mark this column as the table's primary key */
+    primaryKey?: boolean;
+    /** Column is NOT NULL */
+    required?: boolean;
+    /** SQL DEFAULT value */
+    default?: string | number | boolean;
+    /**
+     * Foreign-key reference to another entity (table name).
+     * Creates a `belongsTo` relation automatically.
+     * The relation name is derived from the field name — `_id` suffix is stripped
+     * (e.g. `assignee_id: { ref: user }` → relation name `assignee`).
+     */
+    ref?: string;
+}
+/**
+ * Inline render spec inside YAML — a flat object alternative to `TemplateRenderSpec`.
+ *
+ * @example
+ * ```yaml
+ * render:
+ *   template: default-list
+ *   formatRow: "{{title}} — {{status}}"
+ * ```
+ */
+interface LatticeEntityRenderSpec {
+    template: string;
+    formatRow?: string;
+}
+/**
+ * A single entity (table) definition in `lattice.config.yml`.
+ *
+ * @example
+ * ```yaml
+ * ticket:
+ *   fields:
+ *     id:    { type: uuid, primaryKey: true }
+ *     title: { type: text, required: true }
+ *   render: default-list
+ *   outputFile: context/TICKETS.md
+ * ```
+ */
+interface LatticeEntityDef {
+    /** Column definitions */
+    fields: Record<string, LatticeFieldDef>;
+    /**
+     * How to render rows into context text.
+     * Accepts the same forms as `TableDefinition.render`:
+     * - A `BuiltinTemplateName` string (e.g. `default-list`)
+     * - A `{ template, formatRow }` object for hooks
+     */
+    render?: string | LatticeEntityRenderSpec;
+    /** Render output file path (relative to the config file directory) */
+    outputFile: string;
+    /**
+     * Optional explicit primary key override.
+     * If omitted, the field with `primaryKey: true` is used.
+     * Accepts a single column name or an array for composite keys.
+     */
+    primaryKey?: string | string[];
+}
+/**
+ * The top-level `lattice.config.yml` document.
+ *
+ * @example
+ * ```yaml
+ * db: ./data/app.db
+ * entities:
+ *   ticket:
+ *     fields:
+ *       id: { type: uuid, primaryKey: true }
+ *       title: { type: text, required: true }
+ *     render: default-list
+ *     outputFile: context/TICKETS.md
+ * ```
+ */
+interface LatticeConfig {
+    /** Path to the SQLite database file (relative to the config file) */
+    db: string;
+    /** Entity (table) definitions */
+    entities: Record<string, LatticeEntityDef>;
+    /** Entity context directory definitions */
+    entityContexts?: Record<string, LatticeEntityContextDef>;
+}
+/**
+ * Source spec in YAML config — either the shorthand string 'self' or an object.
+ */
+type LatticeEntityContextSourceDef = 'self' | {
+    type: 'hasMany';
+    table: string;
+    foreignKey: string;
+    references?: string;
+} | {
+    type: 'manyToMany';
+    junctionTable: string;
+    localKey: string;
+    remoteKey: string;
+    remoteTable: string;
+    references?: string;
+} | {
+    type: 'belongsTo';
+    table: string;
+    foreignKey: string;
+    references?: string;
+};
+/** A single per-entity file spec in YAML config */
+interface LatticeEntityContextFileDef {
+    source: LatticeEntityContextSourceDef;
+    template: string;
+    budget?: number;
+    omitIfEmpty?: boolean;
+}
+/** Entity context definition in YAML config */
+interface LatticeEntityContextDef {
+    slug: string;
+    directoryRoot?: string;
+    protectedFiles?: string[];
+    index?: {
+        outputFile: string;
+        render: string;
+    };
+    files: Record<string, LatticeEntityContextFileDef>;
+    combined?: {
+        outputFile: string;
+        exclude?: string[];
+    };
+}
+
+/** Output of a successful config parse — ready to hand to Lattice. */
+interface ParsedConfig {
+    /** Absolute path to the SQLite database file */
+    dbPath: string;
+    /** Table definitions in declaration order */
+    tables: readonly {
+        name: string;
+        definition: TableDefinition;
+    }[];
+    /** Entity context definitions in declaration order */
+    entityContexts: readonly {
+        table: string;
+        definition: EntityContextDefinition;
+    }[];
+}
+/**
+ * Read, parse, and validate a `lattice.config.yml` file.
+ *
+ * Paths inside the config (e.g. `db`, `outputFile`) are resolved relative to
+ * the config file's directory.
+ *
+ * @throws If the file cannot be read, the YAML is malformed, or required
+ *         keys are missing.
+ */
+declare function parseConfigFile(configPath: string): ParsedConfig;
+/**
+ * Parse and validate a raw YAML string as a Lattice config.
+ *
+ * `configDir` is used to resolve relative `db` and `outputFile` paths.
+ * Typically this should be the directory that contains `lattice.config.yml`.
+ *
+ * Useful for testing without touching the filesystem.
+ */
+declare function parseConfigString(yamlContent: string, configDir: string): ParsedConfig;
+
+export { 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 ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type Row, type SecurityOptions, type SelfSource, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type WatchOptions, type WritebackDefinition, manifestPath, parseConfigFile, parseConfigString, readManifest, writeManifest };