Documentation

// String path
new Lattice('./app.db')

// In-memory (tests)
new Lattice(':memory:')

// From YAML config
new Lattice({ config: './lattice.config.yml' })

// With options
new Lattice('./app.db', {
  wal: true,
  busyTimeout: 10_000,
  security: {
    sanitize: true,
    auditTables: ['users', 'credentials'],
    fieldLimits: { notes: 50_000, bio: 2_000 },
  },
})

db.define('agents', {
  columns: {
    id: 'TEXT PRIMARY KEY',
    name: 'TEXT NOT NULL',
    persona: 'TEXT',
    active: 'INTEGER DEFAULT 1',
  },
  render(rows) {
    return rows
      .filter((r) => r.active)
      .map((r) => `## ${r.name}\n\n${r.persona ?? ''}`)
      .join('\n\n---\n\n');
  },
  outputFile: 'AGENTS.md',
});

db.defineMulti('agent-context', {
  // One file per active agent
  keys: () => db.query('agents', { where: { active: 1 } }),
  outputFile: (agent) => `agents/${agent.slug}/CONTEXT.md`,
  tables: ['tasks', 'notes'],
  render(agent, { tasks, notes }) {
    const myTasks = tasks.filter((t) => t.assigned_to === agent.id);
    const myNotes = notes.filter((n) => n.agent_id === agent.id);
    return [
      `# ${agent.name} — context`,
      '',
      '## Pending tasks',
      myTasks.map((t) => `- ${t.title}`).join('\n') || '_none_',
      '',
      '## Notes',
      myNotes.map((n) => `- ${n.body}`).join('\n') || '_none_',
    ].join('\n');
  },
});

db.defineEntityContext('agents', {
  slug: (row) => row.slug as string,

  index: {
    outputFile: 'agents/AGENTS.md',
    render: (rows) => `# Agents\n\n${rows.map((r) => `- ${r.name}`).join('\n')}`,
  },

  files: {
    'AGENT.md': {
      source: { type: 'self' },
      render: ([r]) => `# ${r.name}\n\n${r.bio ?? ''}`,
    },
    'TASKS.md': {
      source: { type: 'hasMany', table: 'tasks', foreignKey: 'agent_id' },
      render: (rows) => rows.map((r) => `- ${r.title}`).join('\n'),
      omitIfEmpty: true,
      budget: 4000,
    },
    'SKILLS.md': {
      source: {
        type: 'manyToMany',
        junctionTable: 'agent_skills',
        localKey: 'agent_id',
        remoteKey: 'skill_id',
        remoteTable: 'skills',
      },
      render: (rows) => rows.map((r) => `- ${r.name}`).join('\n'),
      omitIfEmpty: true,
    },
  },

  combined: { outputFile: 'CONTEXT.md', exclude: [] },
  protectedFiles: ['SESSION.md'],
});

db.defineWriteback({
  file: './context/agents/*/SESSION.md',

  parse(content, fromOffset) {
    const newContent = content.slice(fromOffset);
    const entries = parseMarkdownItems(newContent);
    return { entries, nextOffset: content.length };
  },

  async persist(entry, filePath) {
    await db.insert('events', {
      source_file: filePath,
      ...(entry as Row),
    });
  },

  dedupeKey: (entry) => (entry as { id: string }).id,
});

await db.init({
  migrations: [
    { version: 1, sql: 'ALTER TABLE tasks ADD COLUMN due_date TEXT' },
    { version: 2, sql: 'ALTER TABLE tasks ADD COLUMN priority INTEGER DEFAULT 0' },
  ],
});

// Migrations are idempotent — each version is applied exactly once.
// Safe to call init() on every process start.

db.close(); // call on process exit

// Insert — returns the generated id
const id = await db.insert('tasks', { title: 'Write docs', status: 'open' });

// Upsert by PK
await db.upsert('tasks', { id: 'task-001', title: 'Updated', status: 'done' });

// Upsert by arbitrary column
await db.upsertBy('users', 'email', 'alice@example.com', { name: 'Alice' });

// Update specific fields
await db.update('tasks', 'task-001', { status: 'done' });

// Get by PK
const task = await db.get('tasks', 'task-001');

// Query with filters
const open = await db.query('tasks', {
  where: { status: 'open' },
  filters: [{ col: 'priority', op: 'gte', val: 3 }],
  orderBy: 'created_at',
  orderDir: 'desc',
  limit: 20,
});

// Count
const n = await db.count('tasks', { where: { status: 'open' } });

// Delete
await db.delete('tasks', 'task-001');

// One-shot render
const result = await db.render('./context');
// { filesWritten: ['context/TASKS.md'], filesSkipped: 2, durationMs: 12 }

// render() + writeback pipeline
const syncResult = await db.sync('./context');

// Watch with polling
const stop = await db.watch('./context', {
  interval: 5_000,
  onRender: (r) => console.log('rendered', r.filesWritten.length, 'files'),
  onError: (e) => console.error(e.message),
  cleanup: {
    removeOrphanedDirectories: true,
    removeOrphanedFiles: true,
    protectedFiles: ['SESSION.md'],
  },
});

// One-shot render + orphan cleanup
const reconcileResult = await db.reconcile('./context', {
  removeOrphanedDirectories: true,
  removeOrphanedFiles: true,
  protectedFiles: ['SESSION.md'],
  dryRun: false,
});

db.on('audit',     ({ table, operation, id, timestamp }) => {
  auditLog.write({ table, operation, id, timestamp });
});

db.on('render',    ({ filesWritten, filesSkipped, durationMs }) => {
  console.log(`Rendered ${filesWritten.length} files in ${durationMs}ms`);
});

db.on('writeback', ({ filePath, entriesProcessed }) => {
  console.log(`Processed ${entriesProcessed} entries from ${filePath}`);
});

db.on('error',     (err: Error) => {
  console.error('Lattice error:', err.message);
});