elanous 0.2.12 → 0.2.14

package/src/intake-plane/wish-benchmark-ledger.ts

@@ -0,0 +1,129 @@
+import { debug } from '../debug/log.js';
+import { constants, closeSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, writeSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
+import { dlopen, FFIType } from 'bun:ffi';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+
+/** Bench samples live in the instance's private state, never in a repository or card response. */
+export function wishBenchmarkLedgerPath(root: string = elanousStateRoot()): string {
+  // OP D 길 원장(채널 10-04 22:48)과 같은 파일·같은 줄 꼴 — OP 가 손으로 더하는 줄과 섞여 한 표본이 된다.
+  return join(root, 'bench', 'goal-bench-requirements.jsonl');
+}
+
+function privateDirectory(path: string, privateMode: boolean): void {
+  try { mkdirSync(path, { mode: 0o700 }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
+  const state = lstatSync(path);
+  if (state.isSymbolicLink() || !state.isDirectory()) throw new Error(`Unsafe wish benchmark directory: ${path}`);
+  const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    if (privateMode) fchmodSync(fd, 0o700);
+    const opened = fstatSync(fd);
+    if (opened.dev !== state.dev || opened.ino !== state.ino) {
+      throw new Error(`Wish benchmark directory changed while opening: ${path}`);
+    }
+  } finally { closeSync(fd); }
+}
+
+function realExistingPrefix(path: string): string {
+  let head = path; const tail: string[] = [];
+  for (;;) {
+    try { return join(realpathSync(head), ...tail.reverse()); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      const parent = dirname(head); if (parent === head) return path;
+      tail.push(basename(head)); head = parent;
+    }
+  }
+}
+
+function preparePrivateDirectory(root: string): string {
+  // 맥에서 `/var` 는 `/private/var` 링크다 — 이미 있는 상위 경로는 실제 경로로 풀고, 새로 만들 아래 칸만 링크를 막는다.
+  const absolute = realExistingPrefix(resolve(root));
+  let current = parse(absolute).root;
+  const parts = absolute.slice(current.length).split(/[\\/]/).filter(Boolean);
+  for (const part of parts) {
+    current = join(current, part);
+    // A sample cannot be written inside a source checkout, even if the state root was overridden.
+    try {
+      lstatSync(join(current, '.git'));
+      throw new Error(`Wish benchmark state root is inside a repository: ${current}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    privateDirectory(current, false);
+  }
+  for (const part of ['bench']) {
+    current = join(current, part);
+    privateDirectory(current, true);
+  }
+  return current;
+}
+
+// Advisory locks belong to the open descriptor, not the pathname: SIGKILL closes it automatically.
+// Keep the lock file itself in place so no competing writer can lock a different inode.
+const libc = dlopen(process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : 'libc.so.6', {
+  flock: { args: [FFIType.int, FFIType.int], returns: FFIType.int },
+});
+
+function withLedgerLock(dir: string, action: () => void): void {
+  const lock = join(dir, '.wish-cards.lock');
+  const fd = openSync(lock, constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.nlink !== 1) throw new Error('Unsafe wish benchmark lock');
+    fchmodSync(fd, 0o600);
+    // LOCK_EX blocks rather than stealing a live writer's lock. Kernel releases it on crash.
+    if (libc.symbols.flock(fd, 2) !== 0) throw new Error('Wish benchmark ledger lock failed');
+    const current = lstatSync(lock);
+    if (opened.dev !== current.dev || opened.ino !== current.ino) throw new Error('Wish benchmark lock changed while waiting');
+    action();
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function recordWishBenchmarkSample(
+  sample: { cardId: string; at: string; surface: string; text: string },
+): void {
+  const stateRoot = elanousStateRoot();
+  const dir = preparePrivateDirectory(stateRoot);
+  const expected = lstatSync(dir);
+  const path = wishBenchmarkLedgerPath(stateRoot);
+  withLedgerLock(dir, () => {
+    const current = lstatSync(dir);
+    if (!current.isDirectory() || current.dev !== expected.dev || current.ino !== expected.ino) {
+      throw new Error('Wish benchmark directory changed while waiting for lock');
+    }
+    // Re-check under the lock: another process may have recorded this card while we waited.
+    const fd = openSync(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+      const state = fstatSync(fd);
+      if (!state.isFile() || state.nlink !== 1) throw new Error('Wish benchmark ledger is not a private regular file');
+      fchmodSync(fd, 0o600);
+      if (readFileSync(fd, 'utf8').split('\n').some(line => {
+        if (!line) return false;
+        const row = JSON.parse(line) as { id?: string; cardId?: string };
+        return (row.id ?? row.cardId) === sample.cardId;
+      })) return;
+      // 줄 꼴 = OP 원장과 같다: id · at · surface · text(원문 그대로) · chars · op_cells(참조 칸 — OP 가 채운다) · note.
+      const line = JSON.stringify({ id: sample.cardId, at: sample.at, surface: sample.surface, text: sample.text,
+        chars: Array.from(sample.text).length, op_cells: [], note: 'wish-card' }) + '\n';
+      writeSync(fd, line);
+    } finally {
+      closeSync(fd);
+    }
+  });
+}
+
+/** 카드 생성 경로용: 벤치 원장 쓰기가 실패해도(저장소 안 상태 루트 · 권한 · 링크) 소원 카드는 만들어져야 한다.
+ *  실패는 관측 한 줄로만 남긴다(원문은 싣지 않는다). */
+export function recordWishBenchmarkSampleSafely(sample: Parameters<typeof recordWishBenchmarkSample>[0]): boolean {
+  try {
+    recordWishBenchmarkSample(sample);
+    return true;
+  } catch (error) {
+    debug.log('intake.wish-bench', 'skipped', { cardId: sample.cardId, surface: sample.surface, reason: String((error as Error)?.message ?? error).split(':')[0] });
+    return false;
+  }
+}

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

@@ -1,13 +1,54 @@
 import { debug } from '../debug/log.js';
 import { CardStore } from '../task-cards/card-store.js';
+import { recordWishBenchmarkSampleSafely } from './wish-benchmark-ledger.js';
+
+export type WishReplyTarget =
+  | { surface: 'telegram'; chatId: string; threadId?: string; botId?: string }
+  | { surface: 'pwa'; sessionId: string }
+  | { surface: 'linear'; issueId: string }
+  | { surface: 'tui' };
+
+/** `intake:reply:0` 섹션 꼴 — surface ⊕ 표면 안 주소(텔레그램 대화 · PWA 세션 · Linear 이슈 · TUI 없음). */
+export function replySection(target: WishReplyTarget): { surface: WishReplyTarget['surface']; address: string | null } {
+  switch (target.surface) {
+    case 'telegram': return { surface: 'telegram', address: target.threadId ? `${target.chatId}:${target.threadId}` : target.chatId };
+    case 'pwa': return { surface: 'pwa', address: target.sessionId };
+    case 'linear': return { surface: 'linear', address: target.issueId };
+    case 'tui': return { surface: 'tui', address: null };
+  }
+}
+
+export type WishInput = {
+  text: string;
+  source: WishReplyTarget['surface'];
+  ref: string;
+  replyTo?: WishReplyTarget;
+};
+
+function replyTarget(input: WishInput): WishReplyTarget {
+  if (input.replyTo) {
+    if (input.replyTo.surface !== input.source) throw new Error('소원 출처와 회신 대상이 다릅니다');
+    return input.replyTo;
+  }
+  switch (input.source) {
+    case 'telegram': return { surface: 'telegram', chatId: input.ref.split(':', 1)[0]! };
+    case 'pwa':
+    case 'linear': throw new Error('소원 회신 대상을 명시하세요');
+    case 'tui': return { surface: 'tui' };
+  }
+}
 
 export function createWishCard(
-  { text, source, ref }: { text: string; source: 'telegram' | 'pwa' | 'tui'; ref: string },
+  { text, source, ref, replyTo }: WishInput,
   store: CardStore = new CardStore(),
 ): { cardId: string; title: string; created: boolean } {
   const title = text.trim().split(/\r?\n/, 1)[0]!.trim().slice(0, 80);
   if (!title) throw new Error('소원 글을 입력하세요');
   if (!ref?.trim()) throw new Error('소원 참조가 필요합니다');
+  const target = replyTarget({ text, source, ref, replyTo });
+  if (target.surface === 'telegram' && !/^-?\d+$/.test(target.chatId)
+    || target.surface === 'pwa' && !target.sessionId.trim()
+    || target.surface === 'linear' && !target.issueId.trim()) throw new Error('소원 회신 대상이 필요합니다');
   const goalId = `wish:${source}:${ref}`;
   const old = store.listCards().find(card => card.goalId === goalId);
   const card = old ?? store.createCard({ goalId, title });
@@ -22,12 +63,22 @@ export function createWishCard(
       key: 'intake:wish:0',
       owner: 'steward',
       content: JSON.stringify({
-        source, ref, title: card.title, text: sameRequest ? text : null, at: new Date().toISOString(),
+        source, ref, replyTo: target, title: card.title, text: sameRequest ? text : null, at: new Date().toISOString(),
         ...(old ? { recovered: true } : {}), ...(sameRequest ? {} : { mismatch: true }),
       }),
     });
     if (!sameRequest) debug.log('intake.wish', 'recovered-mismatch', { source, cardId: card.id });
   }
+  // FLOW1 원장 약속(TC 21:15): 회신 주소를 `intake:reply:0 {surface, address}` 로도(원장 섹션 허용 목록상 `intake` 아래) 남긴다 — FLOW1a 는 이 꼴을 읽고
+  // 보내기는 `sendCardReply(cardId, text)` 만 부른다(wish-reply.ts). 원천은 위 intake 섹션의 replyTo 그대로.
+  if (!card.sections.some(section => section.key === 'intake:reply:0')) {
+    store.appendSection(card.id, { key: 'intake:reply:0', owner: 'steward', content: JSON.stringify(replySection(target)) });
+  }
+  const originalIntake = store.getCard(card.id)?.sections.find(section => section.key === 'intake:wish:0');
+  if (originalIntake) {
+    const first = JSON.parse(originalIntake.content) as { source: WishInput['source']; text: string | null; at: string };
+    if (first.text !== null) recordWishBenchmarkSampleSafely({ cardId: card.id, at: first.at, surface: first.source, text: first.text });
+  }
   debug.log('intake.wish', created ? 'created' : 'duplicate', { source, cardId: card.id });
   return { cardId: card.id, title: card.title, created };
 }

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

@@ -1,6 +1,7 @@
 import { readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';
 import { basename, join, relative } from 'node:path';
 import { CardStore } from '../task-cards/card-store.js';
+import { recordWishBenchmarkSampleSafely } from './wish-benchmark-ledger.js';
 
 export interface WishScanResult {
   added: number;
@@ -52,9 +53,11 @@ export function scanWishFolder({ dir, store }: { dir: string; store: CardStore }
       result.skipped++;
       continue;
     }
-    const title = /^# (.+)$/m.exec(readFileSync(path, 'utf8'))?.[1]?.trim() || basename(path, '.md');
+    const text = readFileSync(path, 'utf8');
+    const title = /^# (.+)$/m.exec(text)?.[1]?.trim() || basename(path, '.md');
     const card = old ?? store.createCard({ goalId, title });
-    const intake = { source: 'wish', path: relPath, mtime, title };
+    if (intakeSections.length === 0) recordWishBenchmarkSampleSafely({ cardId: card.id, at: card.createdAt, surface: 'wish', text });
+    const intake = { source: 'wish', path: relPath, mtime, title, text };
     store.appendSection(card.id, {
       key: `intake:wish:${intakeSections.length}`,
       owner: 'steward',

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/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[],
+    }));
+  }
+}