elanous 0.2.13 → 0.2.15

package/src/intake-plane/wish-reply.ts

@@ -0,0 +1,72 @@
+import { commentLinearIssue } from '../connectors/linear.js';
+import { getSecretAsync } from '../nexus/config/secrets/index.js';
+import { appendMessage, adoptSession } from '../session/index.js';
+import { CardStore } from '../task-cards/card-store.js';
+import { resolveChannelBotToken } from '../channel-bot-token.js';
+import { getUserConfig } from '../user-config.js';
+import type { WishReplyTarget } from './wish-card.js';
+
+export interface WishReplySinks {
+  telegram: (target: Extract<WishReplyTarget, { surface: 'telegram' }>, text: string) => Promise<void>;
+  pwa: (sessionId: string, text: string) => Promise<void>;
+  linear: (issueId: string, text: string) => Promise<void>;
+}
+
+const defaultSinks: WishReplySinks = {
+  telegram: async (target, text) => {
+    const cfg = getUserConfig();
+    const primary = resolveChannelBotToken('telegram', cfg).token;
+    const token = !target.botId || primary.split(':')[0] === target.botId
+      ? primary
+      : cfg.telegram.channels?.find(channel => channel.botToken?.split(':')[0] === target.botId)?.botToken;
+    if (!token) throw new Error('Telegram 회신 봇 토큰이 없습니다');
+    let response: Response;
+    try {
+      response = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ chat_id: target.chatId, text, ...(target.threadId ? { message_thread_id: Number(target.threadId) } : {}) }),
+      });
+    } catch {
+      throw new Error('Telegram 회신 요청에 실패했습니다');
+    }
+    if (!response.ok || (await response.json() as { ok?: boolean }).ok !== true) throw new Error('Telegram 회신에 실패했습니다');
+  },
+  pwa: async (sessionId, text) => {
+    adoptSession(sessionId, { source: 'pwa', origin: 'pwa' });
+    appendMessage(sessionId, { role: 'assistant', content: text, ts: new Date().toISOString() });
+  },
+  linear: async (issueId, text) => {
+    const apiKey = await getSecretAsync('connector.linear.apiKey');
+    if (!apiKey) throw new Error('Linear 키가 없습니다');
+    await commentLinearIssue({ apiKey, issueId, body: text });
+  },
+};
+
+/** A later workflow needs only the card id and one line; the original intake section owns the destination. */
+export async function replyToWishCard(cardId: string, line: string, store?: CardStore, sinks: WishReplySinks = defaultSinks): Promise<void> {
+  if (!line.trim() || line.includes('\n') || line.includes('\r')) throw new Error('회신은 한 줄이어야 합니다');
+  const owned = !store;
+  const cards = store ?? new CardStore();
+  try {
+    const card = cards.getCard(cardId);
+    if (!card) throw new Error(`소원 카드를 찾을 수 없습니다: ${cardId}`);
+    const section = card.sections.find(item => item.key === 'intake:wish:0');
+    if (!section) throw new Error(`소원 회신 대상이 없습니다: ${cardId}`);
+    const { replyTo } = JSON.parse(section.content) as { replyTo?: WishReplyTarget };
+    if (!replyTo || typeof replyTo !== 'object' || !('surface' in replyTo)) throw new Error(`소원 회신 대상이 없습니다: ${cardId}`);
+    switch (replyTo.surface) {
+      case 'telegram': await sinks.telegram(replyTo, line); return;
+      case 'pwa': await sinks.pwa(replyTo.sessionId, line); return;
+      case 'linear': await sinks.linear(replyTo.issueId, line); return;
+      case 'tui': return;
+      default: throw new Error(`알 수 없는 소원 회신 대상: ${cardId}`);
+    }
+  } finally {
+    if (owned) cards.close();
+  }
+}
+
+/** FLOW1 원장 약속 이름(TC 21:15) — FLOW1a 가 동적 import 로 부른다. 동작은 replyToWishCard 와 같다. */
+export async function sendCardReply(cardId: string, text: string): Promise<void> {
+  return replyToWishCard(cardId, text);
+}

package/src/launch-head/seat-goal-queue-lock.fixture.ts

@@ -0,0 +1,15 @@
+import { writeFileSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+
+const [dbPath, releasedMarker] = process.argv.slice(2);
+if (!dbPath || !releasedMarker) throw new Error('lock fixture requires database path and marker');
+const db = new Database(dbPath);
+try {
+  db.exec('BEGIN IMMEDIATE');
+  console.log('LOCKED');
+  await Bun.sleep(500);
+  writeFileSync(releasedMarker, 'released');
+  db.exec('COMMIT');
+} finally {
+  db.close();
+}

package/src/launch-head/seat-goal-queue.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { Database } from 'bun:sqlite';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { QueueSeat } from '../harness/harness-queue.js';
+
+export type SeatGoalStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'expired';
+export type SeatGoal = {
+  id: string;
+  seat: QueueSeat;
+  goal: string;
+  prerequisites: string[];
+  notBefore?: string;
+  endAt?: string;
+  queuedAt: string;
+  status: SeatGoalStatus;
+  startedAt?: string;
+  finishedAt?: string;
+};
+export type SeatGoalInput = {
+  id?: string;
+  seat: QueueSeat;
+  goal: string;
+  prerequisites?: string[];
+  notBefore?: string;
+  endAt?: string;
+};
+export type SeatGoalQueueOptions = { root?: string; now?: () => Date };
+export type SeatGoalScheduleOptions = SeatGoalQueueOptions & {
+  maxConcurrent: number;
+  seatCaps: Partial<Record<QueueSeat, number>>;
+  launch: (goal: SeatGoal) => Promise<void> | void;
+};
+export type SeatGoalScheduleResult = { outcome: 'started' | 'waiting' | 'empty'; goal?: SeatGoal; reason: string };
+
+const SEATS = new Set(['OP', 'TC', 'MK', 'UX']);
+const TERMINAL = new Set<SeatGoalStatus>(['succeeded', 'failed', 'expired']);
+
+export function seatGoalQueuePath(root = effectiveInstanceRoot()): string {
+  return join(root, 'launch-head', 'seat-goals.sqlite');
+}
+
+function openQueue(root: string): Database {
+  const path = seatGoalQueuePath(root);
+  mkdirSync(join(root, 'launch-head'), { recursive: true, mode: 0o700 });
+  const db = new Database(path, { create: true, strict: true });
+  db.exec('PRAGMA busy_timeout = 30000');
+  db.exec(`CREATE TABLE IF NOT EXISTS seat_goals (
+    id TEXT PRIMARY KEY, seat TEXT NOT NULL, goal TEXT NOT NULL, prerequisites TEXT NOT NULL,
+    not_before TEXT, end_at TEXT, queued_at TEXT NOT NULL, status TEXT NOT NULL,
+    started_at TEXT, finished_at TEXT
+  )`);
+  return db;
+}
+
+type GoalRow = {
+  id: string; seat: QueueSeat; goal: string; prerequisites: string;
+  not_before: string | null; end_at: string | null; queued_at: string;
+  status: SeatGoalStatus; started_at: string | null; finished_at: string | null;
+};
+
+function toGoal(row: GoalRow): SeatGoal {
+  return {
+    id: row.id, seat: row.seat, goal: row.goal, prerequisites: JSON.parse(row.prerequisites) as string[],
+    queuedAt: row.queued_at, status: row.status,
+    ...(row.not_before ? { notBefore: row.not_before } : {}),
+    ...(row.end_at ? { endAt: row.end_at } : {}),
+    ...(row.started_at ? { startedAt: row.started_at } : {}),
+    ...(row.finished_at ? { finishedAt: row.finished_at } : {}),
+  };
+}
+
+function rows(db: Database): SeatGoal[] {
+  return (db.query('SELECT * FROM seat_goals ORDER BY queued_at, rowid').all() as GoalRow[]).map(toGoal);
+}
+
+function instant(value: string, field: string): number {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) throw new Error(`seat goal queue: invalid ${field}`);
+  return time;
+}
+
+function clock(now?: () => Date): Date {
+  const date = now?.() ?? new Date();
+  if (!Number.isFinite(date.getTime())) throw new Error('seat goal queue: invalid clock');
+  return date;
+}
+
+function cap(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`seat goal queue: invalid ${field}`);
+  return value;
+}
+
+/** The launcher owns this store; producers enqueue only, never start a goal. */
+export function enqueueSeatGoal(input: SeatGoalInput, options: SeatGoalQueueOptions = {}): SeatGoal {
+  if (!SEATS.has(input.seat)) throw new Error('seat goal queue: invalid seat');
+  if (!input.goal?.trim()) throw new Error('seat goal queue: empty goal');
+  const id = input.id ?? `sg-${randomUUID()}`;
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(id)) throw new Error('seat goal queue: invalid id');
+  const prerequisites = input.prerequisites ?? [];
+  if (!Array.isArray(prerequisites) || prerequisites.some((key) => typeof key !== 'string' || !key.trim())
+    || new Set(prerequisites).size !== prerequisites.length || prerequisites.includes(id)) {
+    throw new Error('seat goal queue: invalid prerequisites');
+  }
+  const start = input.notBefore === undefined ? undefined : instant(input.notBefore, 'notBefore');
+  const end = input.endAt === undefined ? undefined : instant(input.endAt, 'endAt');
+  if (start !== undefined && end !== undefined && end <= start) throw new Error('seat goal queue: endAt must follow notBefore');
+  const queuedAt = clock(options.now).toISOString();
+  if (end !== undefined && end <= Date.parse(queuedAt)) throw new Error('seat goal queue: endAt has passed');
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  try {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const all = rows(db);
+      if (all.some((row) => row.id === id)) throw new Error(`seat goal queue: duplicate id ${id}`);
+      for (const key of prerequisites) {
+        if (!all.some((row) => row.id === key)) throw new Error(`seat goal queue: missing prerequisite ${key}`);
+      }
+      db.query(`INSERT INTO seat_goals (id, seat, goal, prerequisites, not_before, end_at, queued_at, status)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'queued')`).run(id, input.seat, input.goal, JSON.stringify(prerequisites),
+        input.notBefore ?? null, input.endAt ?? null, queuedAt);
+      db.exec('COMMIT');
+      return { id, seat: input.seat, goal: input.goal, prerequisites: [...prerequisites], queuedAt, status: 'queued',
+        ...(input.notBefore ? { notBefore: input.notBefore } : {}), ...(input.endAt ? { endAt: input.endAt } : {}) };
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  } finally { db.close(); }
+}
+
+export function listSeatGoals(options: SeatGoalQueueOptions = {}): SeatGoal[] {
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  try { return rows(db); } finally { db.close(); }
+}
+
+/** Completion is an explicit launcher receipt: an uncertain or crashed launch keeps its slot reserved. */
+export function finishSeatGoal(id: string, status: 'succeeded' | 'failed', options: SeatGoalQueueOptions = {}): SeatGoal {
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  try {
+    const finishedAt = clock(options.now).toISOString();
+    const result = db.query("UPDATE seat_goals SET status = ?, finished_at = ? WHERE id = ? AND status = 'running'")
+      .run(status, finishedAt, id);
+    if (result.changes !== 1) throw new Error(`seat goal queue: goal is not running: ${id}`);
+    return toGoal(db.query('SELECT * FROM seat_goals WHERE id = ?').get(id) as GoalRow);
+  } finally { db.close(); }
+}
+
+/** One tick claims at most one eligible goal atomically across launcher processes. */
+export async function scheduleSeatGoals(options: SeatGoalScheduleOptions): Promise<SeatGoalScheduleResult> {
+  const totalLimit = cap(options.maxConcurrent, 'maxConcurrent');
+  for (const [seat, value] of Object.entries(options.seatCaps)) {
+    if (!SEATS.has(seat) || value === undefined) throw new Error('seat goal queue: invalid seatCaps');
+    cap(value, `seatCaps.${seat}`);
+  }
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  let selected: SeatGoal | undefined;
+  let reason = 'empty';
+  try {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const at = clock(options.now);
+      const all = rows(db);
+      const byId = new Map(all.map((goal) => [goal.id, goal]));
+      for (const goal of all) {
+        if (goal.status !== 'queued') continue;
+        const failed = goal.prerequisites.some((id) => {
+          const prerequisite = byId.get(id);
+          return !prerequisite || (TERMINAL.has(prerequisite.status) && prerequisite.status !== 'succeeded');
+        });
+        if (failed || (goal.endAt && Date.parse(goal.endAt) <= at.getTime())) {
+          db.query("UPDATE seat_goals SET status = 'expired', finished_at = ? WHERE id = ? AND status = 'queued'")
+            .run(at.toISOString(), goal.id);
+          goal.status = 'expired';
+          goal.finishedAt = at.toISOString();
+        }
+      }
+      const running = all.filter((goal) => goal.status === 'running');
+      for (const goal of all) {
+        if (goal.status !== 'queued') continue;
+        if (goal.notBefore && Date.parse(goal.notBefore) > at.getTime()) { reason = 'not-before'; continue; }
+        if (goal.prerequisites.some((id) => byId.get(id)?.status !== 'succeeded')) { reason = 'prerequisites'; continue; }
+        if (running.length >= totalLimit) { reason = 'global-cap'; continue; }
+        if (running.filter((row) => row.seat === goal.seat).length >= (options.seatCaps[goal.seat] ?? totalLimit)) {
+          reason = 'seat-cap'; continue;
+        }
+        const startedAt = at.toISOString();
+        selected = { ...goal, status: 'running', startedAt };
+        db.query("UPDATE seat_goals SET status = 'running', started_at = ? WHERE id = ? AND status = 'queued'")
+          .run(startedAt, goal.id);
+        break;
+      }
+      db.exec('COMMIT');
+      if (!selected) return { outcome: all.some((goal) => goal.status === 'queued') ? 'waiting' : 'empty', reason };
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  } finally { db.close(); }
+  // Keep the claim on an uncertain launch. Only a positive completion receipt can release it.
+  await options.launch(selected);
+  return { outcome: 'started', goal: selected, reason: 'launched' };
+}

package/src/lessons/lesson-import.ts

@@ -0,0 +1,106 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { LessonLedger } from './lesson-ledger.js';
+
+export interface LessonImportItem { id: string; incident: string; cause: string; remedy: string; source: string }
+export interface LessonImportSkipped { source: string; reason: string }
+export interface LessonScan { files: number; items: LessonImportItem[]; skipped: LessonImportSkipped[] }
+
+function firstParagraph(lines: string[], heading: RegExp): string {
+  const start = lines.findIndex(line => {
+    const match = line.match(/^##\s+(.+)$/);
+    if (!match) return false;
+    const title = match[1]!.replace(/^(?:(?:\d+[.)]|§\s*\d+\.?|[a-z][.)]|[①-⑳])\s*|[\p{Extended_Pictographic}\uFE0F\u200D]+\s*|\s)+/giu, '');
+    return heading.test(title);
+  });
+  if (start === -1) return '';
+  const paragraph: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^#{1,2}\s+/.test(line)) break;
+    if (/^#{3,6}\s+/.test(line)) {
+      if (paragraph.length) break;
+      continue;
+    }
+    if (!line.trim()) {
+      if (paragraph.length) break;
+      continue;
+    }
+    if (/^```|^~~~/.test(line.trim())) break;
+    paragraph.push(line.trim());
+  }
+  return paragraph.join(' ');
+}
+
+export function scanLessonDocs(root: string): LessonScan {
+  const sources: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(join(root, directory), { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const source = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) {
+        if (source !== 'docs/goals' && source !== 'docs/archive') visit(source);
+      } else if (entry.isFile() && /^(?:INCIDENT|FINDING)-.*\.md$/.test(entry.name)) {
+        sources.push(source);
+      }
+    }
+  };
+  if (existsSync(join(root, 'docs')) && lstatSync(join(root, 'docs')).isDirectory()) visit('docs');
+  sources.sort();
+  const items: LessonImportItem[] = [];
+  const skipped: LessonImportSkipped[] = [];
+  for (const source of sources) {
+    const lines = readFileSync(join(root, source), 'utf8').split(/\r?\n/);
+    const title = lines.find(line => /^#\s+/.test(line));
+    const incident = title?.replace(/^#\s+/, '').replace(/^(?:INCIDENT|FINDING)\s*[—–-]\s*/i, '').trim() ?? '';
+    const cause = firstParagraph(lines, /^(?:원인|근본|기전|Root cause|Why|Complication|C$)/i);
+    const remedy = firstParagraph(lines, /^(?:교훈|재발 방지|처방|대응|수리|Fix|Answer|A$)/i);
+    if (!incident || (!cause && !remedy)) {
+      skipped.push({ source, reason: !incident ? 'missing incident title' : 'missing cause and remedy' });
+      continue;
+    }
+    const filename = basename(source, '.md');
+    const date = filename.match(/\d{4}-\d{2}-\d{2}/)?.[0];
+    const slug = filename.replace(/^(?:INCIDENT|FINDING)-/, '').replace(/(?:^|-)\d{4}-\d{2}-\d{2}(?=-|$)/, '')
+      .replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60).replace(/-+$/g, '');
+    const base = slug || 'lesson';
+    // Include the source fingerprint even before a collision is observed: a later document cannot rename an earlier ID.
+    const fingerprint = createHash('sha256').update(source).digest('hex');
+    const id = `${base}-${date ?? 'undated'}-${fingerprint}`;
+    items.push({ id, incident, cause, remedy, source });
+  }
+  debug.log('lessons.import', 'scanned', { files: sources.length, items: items.length, skipped: skipped.length, written: 0 });
+  return { files: sources.length, items, skipped };
+}
+
+export function importLessons(ledger: LessonLedger, items: LessonImportItem[], options: { apply: boolean; by: string }): {
+  items: LessonImportItem[]; skipped: LessonImportSkipped[]; written: number;
+} {
+  const pending: LessonImportItem[] = [];
+  const skipped: LessonImportSkipped[] = [];
+  const seenIds = new Set<string>();
+  const seenSources = new Set<string>(existsSync(ledger.path) ? ledger.importedSources() : []);
+  for (const item of items) {
+    if (seenIds.has(item.id) || seenSources.has(item.source)) {
+      skipped.push({ source: item.source, reason: 'already imported or duplicate in scan' });
+      continue;
+    }
+    let exists = false;
+    if (existsSync(ledger.path)) {
+      try { ledger.get(item.id); exists = true; }
+      catch (error) {
+        if (!(error instanceof Error) || !error.message.startsWith('lesson not found:')) throw error;
+      }
+    }
+    if (exists) {
+      skipped.push({ source: item.source, reason: 'already imported' });
+      continue;
+    }
+    seenIds.add(item.id);
+    seenSources.add(item.source);
+    pending.push(item);
+    if (options.apply) ledger.importDocument({ ...item, owner: options.by, by: options.by });
+  }
+  return { items: pending, skipped, written: options.apply ? pending.length : 0 };
+}

package/src/lessons/lesson-ledger.ts

@@ -0,0 +1,206 @@
+import { Database } from 'bun:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+
+export type LessonStatus = 'open' | 'enforced' | 'candidate' | 'promoted';
+export interface LessonRow {
+  id: string;
+  incident: string;
+  cause: string;
+  remedy: string;
+  enforced_by: string;
+  disproof: string | null;
+  owner: string;
+  status: LessonStatus;
+  created_at: string;
+  updated_at: string;
+  occurrence_count: number;
+}
+export interface LessonOccurrence { lesson_id: string; at: string; source: string; note: string }
+export interface LessonHistory { lesson_id: string; at: string; by: string; event: 'add' | 'recur' | 'enforce' | 'promote'; detail: string }
+export interface LessonDetail extends LessonRow { occurrences: LessonOccurrence[]; history: LessonHistory[] }
+export interface LessonLedgerOptions { stateDir?: string; now?: () => Date }
+export interface LessonAddInput { id: string; incident: string; cause: string; remedy: string; owner: string; source: string; enforcedBy?: string; disproof?: string; by?: string }
+
+export class LessonInputError extends Error {
+  override name = 'LessonInputError';
+}
+
+function required(value: string, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new LessonInputError(`${field} is required`);
+  return value.trim();
+}
+
+function enforcement(value: string): string {
+  if (typeof value !== 'string') throw new LessonInputError('enforcedBy is required');
+  return value.split(',').map(part => required(part, 'enforcedBy')).join(',');
+}
+
+export class LessonLedger {
+  readonly path: string;
+  private readonly now: () => Date;
+
+  constructor(options: LessonLedgerOptions = {}) {
+    this.path = join(options.stateDir ?? elanousStateRoot(), 'lessons', 'lessons.sqlite');
+    this.now = options.now ?? (() => new Date());
+  }
+
+  private open(): Database {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const db = new Database(this.path, { create: true, strict: true });
+    try {
+      chmodSync(this.path, 0o600);
+      db.exec('PRAGMA busy_timeout = 10000');
+      db.exec('PRAGMA journal_mode = WAL');
+      db.exec('PRAGMA foreign_keys = ON');
+      db.exec(`CREATE TABLE IF NOT EXISTS lessons (
+        id TEXT PRIMARY KEY, incident TEXT NOT NULL, cause TEXT NOT NULL, remedy TEXT NOT NULL,
+        enforced_by TEXT NOT NULL DEFAULT '', disproof TEXT, owner TEXT NOT NULL,
+        status TEXT NOT NULL CHECK(status IN ('open','enforced','candidate','promoted')),
+        created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS occurrences (
+          lesson_id TEXT NOT NULL REFERENCES lessons(id), at TEXT NOT NULL, source TEXT NOT NULL, note TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS history (
+          lesson_id TEXT NOT NULL REFERENCES lessons(id), at TEXT NOT NULL, by TEXT NOT NULL,
+          event TEXT NOT NULL, detail TEXT NOT NULL);`);
+      return db;
+    } catch (error) { db.close(); throw error; }
+  }
+
+  private using<T>(work: (db: Database) => T): T {
+    const db = this.open();
+    try { return work(db); } finally { db.close(); }
+  }
+
+  private transaction<T>(db: Database, work: () => T): T {
+    db.exec('BEGIN IMMEDIATE');
+    try { const result = work(); db.exec('COMMIT'); return result; }
+    catch (error) { db.exec('ROLLBACK'); throw error; }
+  }
+
+  private row(db: Database, id: string): LessonRow {
+    const row = db.query(`SELECT l.*, (SELECT count(*) FROM occurrences WHERE lesson_id = l.id) AS occurrence_count
+      FROM lessons l WHERE l.id = ?`).get(id) as LessonRow | null;
+    if (!row) throw new LessonInputError(`lesson not found: ${id}`);
+    return row;
+  }
+
+  private record(db: Database, id: string, at: string, by: string, event: LessonHistory['event'], detail: string): void {
+    db.query('INSERT INTO history (lesson_id, at, by, event, detail) VALUES (?, ?, ?, ?, ?)').run(id, at, by, event, detail);
+  }
+
+  private log(event: LessonHistory['event'], row: LessonRow): void {
+    debug.log('lessons.ledger', event, { id: row.id, status: row.status, occurrences: row.occurrence_count });
+  }
+
+  add(input: LessonAddInput): LessonRow {
+    return this.addValidated(input, false);
+  }
+
+  importDocument(input: LessonAddInput): LessonRow {
+    return this.addValidated(input, true);
+  }
+
+  importedSources(): string[] {
+    return this.using(db => (db.query("SELECT detail AS source FROM history WHERE event = 'add' AND detail LIKE 'docs/%'").all() as { source: string }[]).map(row => row.source));
+  }
+
+  private addValidated(input: LessonAddInput, allowPartial: boolean): LessonRow {
+    const id = required(input.id, 'id');
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(id)) throw new LessonInputError('invalid lesson id');
+    const incident = required(input.incident, 'incident');
+    const cause = allowPartial ? input.cause.trim() : required(input.cause, 'cause');
+    const remedy = allowPartial ? input.remedy.trim() : required(input.remedy, 'remedy');
+    if (!cause && !remedy) throw new LessonInputError('cause or remedy is required');
+    const owner = required(input.owner, 'owner');
+    const source = required(input.source, 'source');
+    const enforcedBy = input.enforcedBy === undefined || !input.enforcedBy.trim() ? '' : enforcement(input.enforcedBy);
+    const disproof = input.disproof === undefined || !input.disproof.trim() ? null : required(input.disproof, 'disproof');
+    return this.using(db => this.transaction(db, () => {
+      const at = this.now().toISOString();
+      db.query(`INSERT INTO lessons (id, incident, cause, remedy, enforced_by, disproof, owner, status, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, incident, cause, remedy, enforcedBy, disproof, owner, enforcedBy ? 'enforced' : 'open', at, at);
+      db.query('INSERT INTO occurrences (lesson_id, at, source, note) VALUES (?, ?, ?, ?)').run(id, at, source, '');
+      this.record(db, id, at, input.by === undefined ? owner : required(input.by, 'by'), 'add', source);
+      const row = this.row(db, id);
+      this.log('add', row);
+      return row;
+    }));
+  }
+
+  recur(id: string, input: { source: string; note?: string; by: string }): LessonRow {
+    const source = required(input.source, 'source');
+    const by = required(input.by, 'by');
+    const note = input.note ?? '';
+    return this.using(db => this.transaction(db, () => {
+      const previous = this.row(db, id);
+      const at = this.now().toISOString();
+      db.query('INSERT INTO occurrences (lesson_id, at, source, note) VALUES (?, ?, ?, ?)').run(id, at, source, note);
+      const status = previous.status === 'promoted' ? 'promoted' : 'candidate';
+      db.query('UPDATE lessons SET status = ?, updated_at = ? WHERE id = ?').run(status, at, id);
+      this.record(db, id, at, by, 'recur', `${source}${note ? ` · ${note}` : ''}`);
+      const row = this.row(db, id);
+      this.log('recur', row);
+      return row;
+    }));
+  }
+
+  enforce(id: string, input: { enforcedBy: string; by: string }): LessonRow {
+    const enforcedBy = enforcement(input.enforcedBy);
+    const by = required(input.by, 'by');
+    return this.using(db => this.transaction(db, () => {
+      const previous = this.row(db, id);
+      const at = this.now().toISOString();
+      const paths = [...new Set([...previous.enforced_by.split(',').filter(Boolean), ...enforcedBy.split(',')])].join(',');
+      const status = previous.status === 'promoted' ? 'promoted' : 'enforced';
+      db.query('UPDATE lessons SET enforced_by = ?, status = ?, updated_at = ? WHERE id = ?').run(paths, status, at, id);
+      this.record(db, id, at, by, 'enforce', enforcedBy);
+      const row = this.row(db, id);
+      this.log('enforce', row);
+      return row;
+    }));
+  }
+
+  promote(id: string, input: { rulePath: string; by: string }): LessonRow {
+    const rulePath = required(input.rulePath, 'rulePath');
+    const by = required(input.by, 'by');
+    return this.using(db => this.transaction(db, () => {
+      const previous = this.row(db, id);
+      if (!previous.disproof?.trim()) throw new LessonInputError('disproof is required to promote a lesson');
+      const at = this.now().toISOString();
+      const paths = [...new Set([...previous.enforced_by.split(',').filter(Boolean), rulePath])].join(',');
+      db.query("UPDATE lessons SET enforced_by = ?, status = 'promoted', updated_at = ? WHERE id = ?").run(paths, at, id);
+      this.record(db, id, at, by, 'promote', rulePath);
+      const row = this.row(db, id);
+      this.log('promote', row);
+      return row;
+    }));
+  }
+
+  find(query: string): LessonRow[] {
+    const term = required(query, 'query').toLowerCase();
+    return this.using(db => (db.query(`SELECT l.*, (SELECT count(*) FROM occurrences WHERE lesson_id = l.id) AS occurrence_count
+      FROM lessons l WHERE instr(lower(incident), ?) > 0 OR instr(lower(cause), ?) > 0 OR instr(lower(remedy), ?) > 0
+      ORDER BY occurrence_count DESC, l.created_at, l.id`).all(term, term, term) as LessonRow[]));
+  }
+
+  list(filters: { status?: LessonStatus } = {}): LessonRow[] {
+    return this.using(db => (db.query(`SELECT l.*, (SELECT count(*) FROM occurrences WHERE lesson_id = l.id) AS occurrence_count
+      FROM lessons l WHERE (? IS NULL OR l.status = ?)
+      ORDER BY occurrence_count DESC, l.updated_at DESC, l.id`).all(filters.status ?? null, filters.status ?? null) as LessonRow[]));
+  }
+
+  candidates(): LessonRow[] {
+    return this.using(db => db.query(`SELECT l.*, (SELECT count(*) FROM occurrences WHERE lesson_id = l.id) AS occurrence_count
+      FROM lessons l WHERE l.status = 'candidate' ORDER BY occurrence_count DESC, l.created_at, l.id`).all() as LessonRow[]);
+  }
+
+  get(id: string): LessonDetail {
+    return this.using(db => ({ ...this.row(db, id),
+      occurrences: db.query('SELECT lesson_id, at, source, note FROM occurrences WHERE lesson_id = ? ORDER BY rowid').all(id) as LessonOccurrence[],
+      history: db.query('SELECT lesson_id, at, by, event, detail FROM history WHERE lesson_id = ? ORDER BY rowid').all(id) as LessonHistory[],
+    }));
+  }
+}