@devflow-tools/database 0.16.12 → 0.16.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.12",
+  "version": "0.16.13",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,5 +13,5 @@
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   },
-  "gitHead": "d4a018f3031a3570c794c253f8edeff405956133"
+  "gitHead": "67c9dfc3709bd0ce36b7c2a9341896eedcc8a725"
 }

package/src/database.ts

@@ -13,6 +13,12 @@ import type {
   WorkQueueHealth,
   WorkState,
 } from './work-queue';
+import {
+  mapSessionObligationRow,
+  normalizeTurnId,
+  type SessionObligationRecord,
+  type SessionObligationState,
+} from './obligation-ledger';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -132,6 +138,23 @@ export interface ContextReceiptRecord {
   contextHash: string;
   issuedAt: number;
   expiresAt: number;
+  selectedFiles?: string[];
+  memoryIds?: string[];
+  canonicalNextAction?: string;
+  requestId?: string;
+}
+
+export interface ContextSelectionEventRecord {
+  id: string;
+  projectRoot: string;
+  sessionId: string;
+  executionId: string;
+  requestId?: string;
+  selectionType: 'code' | 'action';
+  candidateId: string;
+  toolName: string;
+  toolUseId?: string;
+  selectedAt: number;
 }
 
 export interface MemoryDistillCheckpointRecord {
@@ -416,12 +439,32 @@ export class DevFlowDatabase {
         context_hash TEXT NOT NULL,
         issued_at INTEGER NOT NULL,
         expires_at INTEGER NOT NULL,
+        selected_files TEXT NOT NULL DEFAULT '[]',
+        memory_ids TEXT NOT NULL DEFAULT '[]',
+        canonical_next_action TEXT,
+        request_id TEXT,
         PRIMARY KEY (project_root, session_id, execution_id)
       );
 
       CREATE INDEX IF NOT EXISTS idx_context_receipts_expiry
         ON devflow_context_receipts(expires_at);
 
+      CREATE TABLE IF NOT EXISTS devflow_context_selection_events (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT NOT NULL,
+        request_id TEXT,
+        selection_type TEXT NOT NULL CHECK(selection_type IN ('code', 'action')),
+        candidate_id TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        tool_use_id TEXT,
+        selected_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_context_selection_identity
+        ON devflow_context_selection_events(project_root, session_id, execution_id, request_id);
+
       CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -458,6 +501,32 @@ export class DevFlowDatabase {
       CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_turns_receipt
         ON devflow_memory_turns(receipt_id) WHERE receipt_id IS NOT NULL;
 
+      CREATE TABLE IF NOT EXISTS devflow_session_obligations (
+        obligation_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        turn_id TEXT,
+        kind TEXT NOT NULL
+          CHECK(kind IN ('memory_decision', 'evidence_contract', 'session_finalize')),
+        state TEXT NOT NULL DEFAULT 'open'
+          CHECK(state IN ('open', 'satisfied', 'degraded', 'cancelled')),
+        payload TEXT NOT NULL DEFAULT '{}',
+        receipt_id TEXT,
+        reason TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        resolved_at INTEGER,
+        PRIMARY KEY (project_root, session_id, obligation_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_session_obligations_state
+        ON devflow_session_obligations(project_root, session_id, state, created_at);
+      CREATE INDEX IF NOT EXISTS idx_session_obligations_turn
+        ON devflow_session_obligations(project_root, session_id, turn_id);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_session_obligations_receipt
+        ON devflow_session_obligations(receipt_id) WHERE receipt_id IS NOT NULL;
+
       CREATE TABLE IF NOT EXISTS devflow_hook_fallbacks (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -545,6 +614,10 @@ export class DevFlowDatabase {
     } catch {}
     try { this.db.exec('ALTER TABLE devflow_rules ADD COLUMN gate INTEGER NOT NULL DEFAULT 1'); } catch {}
     try { this.db.exec('ALTER TABLE devflow_rules ADD COLUMN updated_at INTEGER'); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_context_receipts ADD COLUMN selected_files TEXT NOT NULL DEFAULT '[]'"); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_context_receipts ADD COLUMN memory_ids TEXT NOT NULL DEFAULT '[]'"); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN canonical_next_action TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN request_id TEXT'); } catch {}
     this.db.exec('UPDATE devflow_rules SET updated_at = created_at WHERE updated_at IS NULL');
     this.db.exec('CREATE INDEX IF NOT EXISTS idx_devflow_rules_gate ON devflow_rules(gate, enabled)');
 
@@ -1311,7 +1384,12 @@ export class DevFlowDatabase {
     }));
   }
 
-  updateToolCallEvent(eventId: string, updates: { output?: string; error?: string; duration?: number }): boolean {
+  updateToolCallEvent(eventId: string, updates: {
+    output?: string;
+    error?: string;
+    failureCategory?: string;
+    duration?: number;
+  }): boolean {
     const sets: string[] = [];
     const values: any[] = [];
 
@@ -1323,6 +1401,10 @@ export class DevFlowDatabase {
       sets.push('error = ?');
       values.push(updates.error);
     }
+    if (updates.failureCategory !== undefined) {
+      sets.push('failure_category = ?');
+      values.push(updates.failureCategory);
+    }
     if (updates.duration !== undefined) {
       sets.push('duration = ?');
       values.push(updates.duration);
@@ -2164,14 +2246,11 @@ export class DevFlowDatabase {
     excludingWorkItemId?: string,
     closedAt = Date.now(),
   ): SessionClosureRecord {
-    const pending = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_work_items
-      WHERE project_root = ? AND session_id = ?
-        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
-        AND (? IS NULL OR id <> ?)
-    `).get(projectRoot, sessionId, excludingWorkItemId ?? null, excludingWorkItemId ?? null) as { count?: number };
-    const pendingWorkCount = Number(pending?.count ?? 0);
+    const pendingWorkCount = this.countSessionLifecyclePending(
+      projectRoot,
+      sessionId,
+      excludingWorkItemId,
+    );
     const state = pendingWorkCount > 0 ? 'closed_with_pending_work' : 'closed';
     this.db.prepare(`
       UPDATE devflow_session_closures
@@ -2408,13 +2487,7 @@ export class DevFlowDatabase {
   }
 
   private refreshClosedSessionClosure(projectRoot: string, sessionId: string, now: number): void {
-    const pending = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_work_items
-      WHERE project_root = ? AND session_id = ?
-        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
-    `).get(projectRoot, sessionId) as { count?: number };
-    const pendingWorkCount = Number(pending?.count ?? 0);
+    const pendingWorkCount = this.countSessionLifecyclePending(projectRoot, sessionId);
     this.db.prepare(`
       UPDATE devflow_session_closures
       SET state = CASE WHEN ? = 0 THEN 'closed' ELSE 'closed_with_pending_work' END,
@@ -2424,6 +2497,44 @@ export class DevFlowDatabase {
     `).run(pendingWorkCount, pendingWorkCount, now, projectRoot, sessionId);
   }
 
+  private countSessionLifecyclePending(
+    projectRoot: string,
+    sessionId: string,
+    excludingWorkItemId?: string,
+  ): number {
+    const work = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_work_items
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND (? IS NULL OR id <> ?)
+    `).get(
+      projectRoot,
+      sessionId,
+      excludingWorkItemId ?? null,
+      excludingWorkItemId ?? null,
+    ) as { count?: number };
+    const obligations = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_session_obligations
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('open', 'degraded')
+    `).get(projectRoot, sessionId) as { count?: number };
+    const legacyTurns = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_memory_turns t
+      WHERE t.project_root = ? AND t.session_id = ? AND t.status = 'pending'
+        AND NOT EXISTS (
+          SELECT 1 FROM devflow_session_obligations o
+          WHERE o.project_root = t.project_root AND o.session_id = t.session_id
+            AND o.obligation_id = 'memory:' || t.turn_id
+        )
+    `).get(projectRoot, sessionId) as { count?: number };
+    return Number(work?.count ?? 0)
+      + Number(obligations?.count ?? 0)
+      + Number(legacyTurns?.count ?? 0);
+  }
+
   // ---- Hook Lifecycle ----
 
   getHookReceipt(projectRoot: string): HookReceiptRecord | null {
@@ -2484,12 +2595,17 @@ export class DevFlowDatabase {
   upsertContextReceipt(receipt: ContextReceiptRecord): void {
     this.db.prepare(`
       INSERT INTO devflow_context_receipts
-        (project_root, session_id, execution_id, context_hash, issued_at, expires_at)
-      VALUES (?, ?, ?, ?, ?, ?)
+        (project_root, session_id, execution_id, context_hash, issued_at, expires_at,
+         selected_files, memory_ids, canonical_next_action, request_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(project_root, session_id, execution_id) DO UPDATE SET
         context_hash = excluded.context_hash,
         issued_at = excluded.issued_at,
-        expires_at = excluded.expires_at
+        expires_at = excluded.expires_at,
+        selected_files = excluded.selected_files,
+        memory_ids = excluded.memory_ids,
+        canonical_next_action = excluded.canonical_next_action,
+        request_id = excluded.request_id
     `).run(
       receipt.projectRoot,
       receipt.sessionId,
@@ -2497,6 +2613,10 @@ export class DevFlowDatabase {
       receipt.contextHash,
       receipt.issuedAt,
       receipt.expiresAt,
+      JSON.stringify(receipt.selectedFiles ?? []),
+      JSON.stringify(receipt.memoryIds ?? []),
+      receipt.canonicalNextAction ?? null,
+      receipt.requestId ?? null,
     );
   }
 
@@ -2506,7 +2626,8 @@ export class DevFlowDatabase {
     executionId: string,
   ): ContextReceiptRecord | null {
     const row = this.db.prepare(`
-      SELECT project_root, session_id, execution_id, context_hash, issued_at, expires_at
+      SELECT project_root, session_id, execution_id, context_hash, issued_at, expires_at,
+             selected_files, memory_ids, canonical_next_action, request_id
       FROM devflow_context_receipts
       WHERE project_root = ? AND session_id = ? AND execution_id = ?
     `).get(projectRoot, sessionId, executionId) as any;
@@ -2517,9 +2638,101 @@ export class DevFlowDatabase {
       contextHash: row.context_hash,
       issuedAt: row.issued_at,
       expiresAt: row.expires_at,
+      selectedFiles: parseJsonStringArray(row.selected_files),
+      memoryIds: parseJsonStringArray(row.memory_ids),
+      canonicalNextAction: row.canonical_next_action ?? undefined,
+      requestId: row.request_id ?? undefined,
     } : null;
   }
 
+  getActiveContextReceipt(
+    projectRoot: string,
+    sessionId: string,
+    executionId?: string,
+    now = Date.now(),
+  ): ContextReceiptRecord | null {
+    const executionClause = executionId ? 'AND execution_id = ?' : '';
+    const params = executionId
+      ? [projectRoot, sessionId, executionId, now]
+      : [projectRoot, sessionId, now];
+    const row = this.db.prepare(`
+      SELECT project_root, session_id, execution_id, context_hash, issued_at, expires_at,
+             selected_files, memory_ids, canonical_next_action, request_id
+      FROM devflow_context_receipts
+      WHERE project_root = ? AND session_id = ? ${executionClause} AND expires_at > ?
+      ORDER BY issued_at DESC
+      LIMIT 1
+    `).get(...params) as any;
+    return row ? {
+      projectRoot: row.project_root,
+      sessionId: row.session_id,
+      executionId: row.execution_id,
+      contextHash: row.context_hash,
+      issuedAt: row.issued_at,
+      expiresAt: row.expires_at,
+      selectedFiles: parseJsonStringArray(row.selected_files),
+      memoryIds: parseJsonStringArray(row.memory_ids),
+      canonicalNextAction: row.canonical_next_action ?? undefined,
+      requestId: row.request_id ?? undefined,
+    } : null;
+  }
+
+  recordContextSelectionEvent(event: ContextSelectionEventRecord): boolean {
+    return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_context_selection_events
+        (id, project_root, session_id, execution_id, request_id, selection_type,
+         candidate_id, tool_name, tool_use_id, selected_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      event.id,
+      event.projectRoot,
+      event.sessionId,
+      event.executionId,
+      event.requestId ?? null,
+      event.selectionType,
+      event.candidateId,
+      event.toolName,
+      event.toolUseId ?? null,
+      event.selectedAt,
+    ).changes > 0;
+  }
+
+  listContextSelectionEvents(options: {
+    projectRoot: string;
+    sessionId?: string;
+    executionId?: string;
+    requestId?: string;
+  }): ContextSelectionEventRecord[] {
+    const predicates = ['project_root = ?'];
+    const params: unknown[] = [options.projectRoot];
+    for (const [column, value] of [
+      ['session_id', options.sessionId],
+      ['execution_id', options.executionId],
+      ['request_id', options.requestId],
+    ] as const) {
+      if (!value) continue;
+      predicates.push(`${column} = ?`);
+      params.push(value);
+    }
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_context_selection_events
+      WHERE ${predicates.join(' AND ')}
+      ORDER BY selected_at ASC, id ASC
+    `).all(...params) as any[];
+    return rows.map(row => ({
+      id: row.id,
+      projectRoot: row.project_root,
+      sessionId: row.session_id,
+      executionId: row.execution_id,
+      requestId: row.request_id ?? undefined,
+      selectionType: row.selection_type,
+      candidateId: row.candidate_id,
+      toolName: row.tool_name,
+      toolUseId: row.tool_use_id ?? undefined,
+      selectedAt: row.selected_at,
+    }));
+  }
+
   deleteContextReceipt(projectRoot: string, sessionId: string, executionId?: string): number {
     return executionId
       ? this.db.prepare(`DELETE FROM devflow_context_receipts
@@ -2536,25 +2749,158 @@ export class DevFlowDatabase {
   }
 
   beginMemoryTurn(input: Omit<MemoryTurnRecord, 'status' | 'memoryIds'>): MemoryTurnRecord {
+    const turnId = normalizeTurnId(input.turnId);
     this.db.prepare(`
       INSERT OR IGNORE INTO devflow_memory_turns
         (turn_id, project_root, session_id, prompt_hash, event_id, status, memory_ids, created_at)
       VALUES (?, ?, ?, ?, ?, 'pending', '[]', ?)
     `).run(
-      input.turnId,
+      turnId,
       input.projectRoot,
       input.sessionId,
       input.promptHash,
       input.eventId,
       input.createdAt,
     );
-    return this.getMemoryTurn(input.turnId)!;
+    const turn = this.getMemoryTurn(turnId)!;
+    this.upsertSessionObligation({
+      obligationId: `memory:${turnId}`,
+      projectRoot: input.projectRoot,
+      sessionId: input.sessionId,
+      turnId,
+      kind: 'memory_decision',
+      state: turn.status === 'pending' ? 'open' : 'satisfied',
+      payload: { eventId: input.eventId, promptHash: input.promptHash },
+      receiptId: turn.receiptId,
+      createdAt: input.createdAt,
+      updatedAt: Date.now(),
+      resolvedAt: turn.decidedAt,
+    });
+    return turn;
+  }
+
+  upsertSessionObligation(record: SessionObligationRecord): SessionObligationRecord {
+    if (!record.obligationId.trim()) throw new Error('Session obligation requires an ID');
+    if (!record.projectRoot.trim()) throw new Error('Session obligation requires a project root');
+    if (!record.sessionId.trim()) throw new Error('Session obligation requires a session ID');
+    const now = record.updatedAt || Date.now();
+    this.db.prepare(`
+      INSERT INTO devflow_session_obligations (
+        obligation_id, project_root, session_id, execution_id, turn_id, kind,
+        state, payload, receipt_id, reason, created_at, updated_at, resolved_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, session_id, obligation_id) DO UPDATE SET
+        execution_id = COALESCE(excluded.execution_id, devflow_session_obligations.execution_id),
+        turn_id = COALESCE(excluded.turn_id, devflow_session_obligations.turn_id),
+        payload = excluded.payload,
+        updated_at = excluded.updated_at
+      WHERE devflow_session_obligations.state = 'open'
+    `).run(
+      record.obligationId,
+      record.projectRoot,
+      record.sessionId,
+      record.executionId ?? null,
+      record.turnId ?? null,
+      record.kind,
+      record.state,
+      JSON.stringify(record.payload ?? {}),
+      record.receiptId ?? null,
+      record.reason ?? null,
+      record.createdAt,
+      now,
+      record.resolvedAt ?? null,
+    );
+    return this.getSessionObligation(record.projectRoot, record.sessionId, record.obligationId)!;
+  }
+
+  getSessionObligation(
+    projectRoot: string,
+    sessionId: string,
+    obligationId: string,
+  ): SessionObligationRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_session_obligations
+      WHERE project_root = ? AND session_id = ? AND obligation_id = ?
+    `).get(projectRoot, sessionId, obligationId) as Record<string, unknown> | undefined;
+    return row ? mapSessionObligationRow(row) : null;
+  }
+
+  listSessionObligations(
+    projectRoot: string,
+    sessionId: string,
+    states?: SessionObligationState[],
+  ): SessionObligationRecord[] {
+    const allowed = [...new Set(states ?? [])].filter(state =>
+      state === 'open' || state === 'satisfied' || state === 'degraded' || state === 'cancelled');
+    const rows = (allowed.length > 0
+      ? this.db.prepare(`
+          SELECT * FROM devflow_session_obligations
+          WHERE project_root = ? AND session_id = ?
+            AND state IN (${allowed.map(() => '?').join(',')})
+          ORDER BY created_at ASC, obligation_id ASC
+        `).all(projectRoot, sessionId, ...allowed)
+      : this.db.prepare(`
+          SELECT * FROM devflow_session_obligations
+          WHERE project_root = ? AND session_id = ?
+          ORDER BY created_at ASC, obligation_id ASC
+        `).all(projectRoot, sessionId)) as Array<Record<string, unknown>>;
+    return rows.map(mapSessionObligationRow);
+  }
+
+  resolveSessionObligation(input: {
+    projectRoot: string;
+    sessionId: string;
+    obligationId: string;
+    state: 'satisfied' | 'degraded' | 'cancelled';
+    receiptId?: string;
+    reason?: string;
+    resolvedAt?: number;
+  }): SessionObligationRecord {
+    return this.db.transaction(() => {
+      const existing = this.getSessionObligation(
+        input.projectRoot,
+        input.sessionId,
+        input.obligationId,
+      );
+      if (!existing) throw new Error(`Session obligation ${input.obligationId} does not exist`);
+      if (existing.state !== 'open') {
+        const sameResolution = existing.state === input.state
+          && (input.receiptId === undefined || existing.receiptId === input.receiptId);
+        if (sameResolution) return existing;
+        throw new Error(`OBLIGATION_TERMINAL_CONFLICT:${input.obligationId}`);
+      }
+      const resolvedAt = input.resolvedAt ?? Date.now();
+      this.db.prepare(`
+        UPDATE devflow_session_obligations
+        SET state = ?, receipt_id = COALESCE(?, receipt_id), reason = ?,
+            resolved_at = ?, updated_at = ?
+        WHERE project_root = ? AND session_id = ? AND obligation_id = ? AND state = 'open'
+      `).run(
+        input.state,
+        input.receiptId ?? null,
+        input.reason ?? null,
+        resolvedAt,
+        resolvedAt,
+        input.projectRoot,
+        input.sessionId,
+        input.obligationId,
+      );
+      return this.getSessionObligation(input.projectRoot, input.sessionId, input.obligationId)!;
+    });
+  }
+
+  countOpenSessionObligations(projectRoot: string, sessionId: string): number {
+    const row = this.db.prepare(`
+      SELECT COUNT(*) AS count FROM devflow_session_obligations
+      WHERE project_root = ? AND session_id = ? AND state = 'open'
+    `).get(projectRoot, sessionId) as { count?: number };
+    return Number(row?.count ?? 0);
   }
 
   getMemoryTurn(turnId: string): MemoryTurnRecord | null {
     const row = this.db.prepare(
       'SELECT * FROM devflow_memory_turns WHERE turn_id = ?',
-    ).get(turnId) as any;
+    ).get(normalizeTurnId(turnId)) as any;
     return row ? this.mapMemoryTurn(row) : null;
   }
 
@@ -2575,6 +2921,7 @@ export class DevFlowDatabase {
     reason?: string;
     decidedAt?: number;
   }): MemoryTurnRecord {
+    const turnId = normalizeTurnId(input.turnId);
     this.db.prepare(`
       UPDATE devflow_memory_turns
       SET status = 'committed', receipt_id = ?, memory_ids = ?, source = ?, reason = ?, decided_at = ?
@@ -2585,12 +2932,22 @@ export class DevFlowDatabase {
       input.source,
       input.reason ?? null,
       input.decidedAt ?? Date.now(),
-      input.turnId,
+      turnId,
     );
-    const turn = this.getMemoryTurn(input.turnId);
+    const turn = this.getMemoryTurn(turnId);
     if (!turn || turn.status !== 'committed') {
-      throw new Error(`Memory turn ${input.turnId} is not pending or does not exist`);
+      throw new Error(`Memory turn ${turnId} is not pending or does not exist`);
     }
+    this.ensureMemoryObligation(turn);
+    this.resolveSessionObligation({
+      projectRoot: turn.projectRoot,
+      sessionId: turn.sessionId,
+      obligationId: `memory:${turn.turnId}`,
+      state: 'satisfied',
+      receiptId: turn.receiptId,
+      reason: turn.reason,
+      resolvedAt: turn.decidedAt,
+    });
     return turn;
   }
 
@@ -2600,6 +2957,7 @@ export class DevFlowDatabase {
     reason: string;
     decidedAt?: number;
   }): MemoryTurnRecord {
+    const turnId = normalizeTurnId(input.turnId);
     this.db.prepare(`
       UPDATE devflow_memory_turns
       SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = 'host_skip',
@@ -2609,12 +2967,22 @@ export class DevFlowDatabase {
       input.receiptId,
       input.reason,
       input.decidedAt ?? Date.now(),
-      input.turnId,
+      turnId,
     );
-    const turn = this.getMemoryTurn(input.turnId);
+    const turn = this.getMemoryTurn(turnId);
     if (!turn || turn.status !== 'skipped') {
-      throw new Error(`Memory turn ${input.turnId} is not pending or does not exist`);
+      throw new Error(`Memory turn ${turnId} is not pending or does not exist`);
     }
+    this.ensureMemoryObligation(turn);
+    this.resolveSessionObligation({
+      projectRoot: turn.projectRoot,
+      sessionId: turn.sessionId,
+      obligationId: `memory:${turn.turnId}`,
+      state: 'satisfied',
+      receiptId: turn.receiptId,
+      reason: turn.reason,
+      resolvedAt: turn.decidedAt,
+    });
     return turn;
   }
 
@@ -2622,7 +2990,23 @@ export class DevFlowDatabase {
     return this.db.prepare(`
       UPDATE devflow_memory_turns SET stop_prompted_at = ?
       WHERE turn_id = ? AND status = 'pending' AND stop_prompted_at IS NULL
-    `).run(promptedAt, turnId).changes === 1;
+    `).run(promptedAt, normalizeTurnId(turnId)).changes === 1;
+  }
+
+  private ensureMemoryObligation(turn: MemoryTurnRecord): void {
+    const obligationId = `memory:${turn.turnId}`;
+    if (this.getSessionObligation(turn.projectRoot, turn.sessionId, obligationId)) return;
+    this.upsertSessionObligation({
+      obligationId,
+      projectRoot: turn.projectRoot,
+      sessionId: turn.sessionId,
+      turnId: turn.turnId,
+      kind: 'memory_decision',
+      state: 'open',
+      payload: { eventId: turn.eventId, promptHash: turn.promptHash },
+      createdAt: turn.createdAt,
+      updatedAt: Date.now(),
+    });
   }
 
   listMemoryTurns(projectRoot: string, sessionId?: string, limit = 50): MemoryTurnRecord[] {
@@ -2785,6 +3169,13 @@ function parseJson(value: unknown): unknown {
   try { return JSON.parse(value); } catch { return value; }
 }
 
+function parseJsonStringArray(value: unknown): string[] {
+  const parsed = parseJson(value);
+  return Array.isArray(parsed)
+    ? parsed.filter((item): item is string => typeof item === 'string')
+    : [];
+}
+
 function deriveQuery(input: unknown): string | null {
   if (!input || typeof input !== 'object') return null;
   const record = input as Record<string, unknown>;

package/src/index.ts

@@ -11,6 +11,8 @@ export type {
   GovernanceRuleRecord,
   HookFallbackRecord,
   HookReceiptRecord,
+  ContextReceiptRecord,
+  ContextSelectionEventRecord,
   MemoryDistillCheckpointRecord,
   MemoryTurnRecord,
   MemoryTurnStatus,
@@ -28,3 +30,12 @@ export type {
   WorkQueueHealth,
   WorkState,
 } from './work-queue';
+export {
+  mapSessionObligationRow,
+  normalizeTurnId,
+} from './obligation-ledger';
+export type {
+  SessionObligationKind,
+  SessionObligationRecord,
+  SessionObligationState,
+} from './obligation-ledger';