@devflow-tools/database 0.16.11 → 0.16.13

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 {
@@ -141,6 +164,7 @@ export interface MemoryDistillCheckpointRecord {
   trigger: 'pre_compact' | 'session_end';
   pendingEvents: number;
   releasedLeases: number;
+  details?: Record<string, unknown>;
   createdAt: number;
 }
 
@@ -415,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,
@@ -428,6 +472,7 @@ export class DevFlowDatabase {
         trigger TEXT NOT NULL CHECK(trigger IN ('pre_compact', 'session_end')),
         pending_events INTEGER NOT NULL DEFAULT 0,
         released_leases INTEGER NOT NULL DEFAULT 0,
+        details TEXT NOT NULL DEFAULT '{}',
         created_at INTEGER NOT NULL
       );
 
@@ -456,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,
@@ -532,6 +603,7 @@ export class DevFlowDatabase {
     try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN tool_use_id TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE sessions ADD COLUMN metadata TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN metadata TEXT'); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_memory_distill_checkpoints ADD COLUMN details TEXT NOT NULL DEFAULT '{}'"); } catch {}
     try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN failed_tool_calls INTEGER DEFAULT 0'); } catch {}
     try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN blocked_tool_calls INTEGER DEFAULT 0'); } catch {}
     try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN fallback_count INTEGER DEFAULT 0'); } catch {}
@@ -542,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)');
 
@@ -1076,6 +1152,16 @@ export class DevFlowDatabase {
     };
   }
 
+  getLatestSkillExecutionForSession(sessionId: string): any | null {
+    const row = this.db.prepare(`
+      SELECT execution_id FROM skill_executions
+      WHERE session_id = ?
+      ORDER BY started_at DESC, execution_id DESC
+      LIMIT 1
+    `).get(sessionId) as { execution_id?: string } | undefined;
+    return row?.execution_id ? this.getSkillExecution(row.execution_id) : null;
+  }
+
   updateSkillExecution(executionId: string, updates: {
     status?: string;
     finishedAt?: number;
@@ -1116,6 +1202,20 @@ export class DevFlowDatabase {
     }
   }
 
+  mergeSkillExecutionMetadata(
+    executionId: string,
+    incoming: Record<string, unknown>,
+  ): Record<string, unknown> | null {
+    const execution = this.getSkillExecution(executionId);
+    if (!execution) return null;
+    const existing = execution.metadata && typeof execution.metadata === 'object'
+      ? execution.metadata as Record<string, unknown>
+      : {};
+    const merged = mergeExecutionMetadata(existing, incoming);
+    this.updateSkillExecution(executionId, { metadata: merged });
+    return merged;
+  }
+
   listSkillExecutions(limit: number, skillName?: string): any[] {
     let query = 'SELECT * FROM skill_executions';
     const params: any[] = [];
@@ -1284,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[] = [];
 
@@ -1296,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);
@@ -1343,23 +1452,38 @@ export class DevFlowDatabase {
     const blocked = events.filter(event => event.blocked);
     const directFallbacks = events.filter(event => event.mcpFallback);
     const hookFallbacks = execution?.sessionId
-      ? this.listHookFallbacks({
-          sessionId: execution.sessionId,
-          from: execution.startedAt,
-          to: finishedAt,
-        })
+      ? (this.db.prepare(`
+          SELECT * FROM devflow_hook_fallbacks
+          WHERE session_id = ? AND created_at >= ? AND created_at <= ?
+          ORDER BY created_at ASC
+        `).all(execution.sessionId, execution.startedAt, finishedAt) as any[]).map(row => ({
+          id: row.id,
+          projectRoot: row.project_root,
+          sessionId: row.session_id ?? undefined,
+          toolUseId: row.tool_use_id ?? undefined,
+          requestType: row.request_type,
+          tool: row.tool,
+          reason: row.reason,
+          durationMs: row.duration_ms,
+          attempts: row.attempts,
+          createdAt: row.created_at,
+        } satisfies HookFallbackRecord))
       : [];
     const fallbackReasons = [...new Set([
       ...directFallbacks.map(() => 'direct_tool_during_context'),
       ...hookFallbacks.map(fallback => `daemon_${fallback.reason}`),
     ])];
     const eventReceiptIds = collectCanonicalReceiptIds(events.map(event => event.output));
-    const suppliedMemoryReceiptIds = Array.isArray(metadata?.memoryReceiptIds)
-      ? metadata.memoryReceiptIds.filter((id): id is string => typeof id === 'string')
-      : [];
-    const suppliedDistillReceiptIds = Array.isArray(metadata?.distillReceiptIds)
-      ? metadata.distillReceiptIds.filter((id): id is string => typeof id === 'string')
-      : [];
+    const existingMetadata = execution?.metadata && typeof execution.metadata === 'object'
+      ? execution.metadata as Record<string, unknown>
+      : {};
+    const mergedMetadata = mergeExecutionMetadata(existingMetadata, metadata ?? {});
+    const suppliedMemoryReceiptIds = [existingMetadata.memoryReceiptIds, metadata?.memoryReceiptIds]
+      .flatMap(value => Array.isArray(value) ? value : [])
+      .filter((id): id is string => typeof id === 'string');
+    const suppliedDistillReceiptIds = [existingMetadata.distillReceiptIds, metadata?.distillReceiptIds]
+      .flatMap(value => Array.isArray(value) ? value : [])
+      .filter((id): id is string => typeof id === 'string');
     const memoryReceiptIds = [...new Set([
       ...suppliedMemoryReceiptIds,
       ...eventReceiptIds.filter(id => id.startsWith('memory-receipt:')),
@@ -1385,7 +1509,7 @@ export class DevFlowDatabase {
       fallbackCount: directFallbacks.length + hookFallbacks.length,
       fallbackReasons,
       metadata: {
-        ...(metadata ?? {}),
+        ...mergedMetadata,
         applicableObligations: obligation.applicable,
         satisfiedObligations: obligation.satisfied,
         missedTools: obligation.missedTools,
@@ -2122,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
@@ -2256,6 +2377,24 @@ export class DevFlowDatabase {
     ).changes === 1;
   }
 
+  deferWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean {
+    const updatedAt = Date.now();
+    return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = 'pending', attempts = MAX(0, attempts - 1),
+          lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?,
+          error_category = ?, error_message = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(
+      nextAttemptAt,
+      error.category,
+      error.message,
+      updatedAt,
+      id,
+      owner,
+    ).changes === 1;
+  }
+
   deadLetterWork(id: string, owner: string, error: WorkError): boolean {
     return this.db.prepare(`
       UPDATE devflow_work_items
@@ -2348,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,
@@ -2364,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 {
@@ -2424,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,
@@ -2437,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,
     );
   }
 
@@ -2446,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;
@@ -2457,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
@@ -2476,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;
   }
 
@@ -2515,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 = ?
@@ -2525,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;
   }
 
@@ -2540,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',
@@ -2549,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;
   }
 
@@ -2562,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[] {
@@ -2576,6 +3020,18 @@ export class DevFlowDatabase {
     return rows.map(row => this.mapMemoryTurn(row));
   }
 
+  listSessionMemoryTurnsForReconciliation(
+    projectRoot: string,
+    sessionId: string,
+  ): MemoryTurnRecord[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_memory_turns
+      WHERE project_root = ? AND session_id = ?
+      ORDER BY created_at ASC, turn_id ASC
+    `).all(projectRoot, sessionId) as any[];
+    return rows.map(row => this.mapMemoryTurn(row));
+  }
+
   insertHookFallback(record: HookFallbackRecord): boolean {
     return this.db.prepare(`
       INSERT OR IGNORE INTO devflow_hook_fallbacks
@@ -2655,8 +3111,13 @@ export class DevFlowDatabase {
   recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void {
     this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints
-        (id, project_root, session_id, trigger, pending_events, released_leases, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
+        (id, project_root, session_id, trigger, pending_events, released_leases, details, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        pending_events = excluded.pending_events,
+        released_leases = MAX(devflow_memory_distill_checkpoints.released_leases, excluded.released_leases),
+        details = excluded.details,
+        created_at = MIN(devflow_memory_distill_checkpoints.created_at, excluded.created_at)
     `).run(
       checkpoint.id,
       checkpoint.projectRoot,
@@ -2664,13 +3125,14 @@ export class DevFlowDatabase {
       checkpoint.trigger,
       checkpoint.pendingEvents,
       checkpoint.releasedLeases,
+      JSON.stringify(checkpoint.details ?? {}),
       checkpoint.createdAt,
     );
   }
 
   listMemoryDistillCheckpoints(projectRoot: string, limit = 50): MemoryDistillCheckpointRecord[] {
     const rows = this.db.prepare(`
-      SELECT id, project_root, session_id, trigger, pending_events, released_leases, created_at
+      SELECT id, project_root, session_id, trigger, pending_events, released_leases, details, created_at
       FROM devflow_memory_distill_checkpoints
       WHERE project_root = ?
       ORDER BY created_at DESC
@@ -2683,6 +3145,7 @@ export class DevFlowDatabase {
       trigger: row.trigger,
       pendingEvents: Number(row.pending_events),
       releasedLeases: Number(row.released_leases),
+      details: row.details ? JSON.parse(row.details) : {},
       createdAt: Number(row.created_at),
     }));
   }
@@ -2706,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>;
@@ -2770,3 +3240,40 @@ function collectCanonicalReceiptIds(values: unknown[]): string[] {
   values.forEach(value => visit(value, 0));
   return [...receiptIds];
 }
+
+function stableMetadataKey(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? String(value);
+  if (Array.isArray(value)) return `[${value.map(stableMetadataKey).join(',')}]`;
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record).sort()
+    .map(key => `${JSON.stringify(key)}:${stableMetadataKey(record[key])}`)
+    .join(',')}}`;
+}
+
+function unionMetadataArrays(existing: unknown, incoming: unknown): unknown[] | undefined {
+  const values = [
+    ...(Array.isArray(existing) ? existing : []),
+    ...(Array.isArray(incoming) ? incoming : []),
+  ];
+  if (values.length === 0 && !Array.isArray(existing) && !Array.isArray(incoming)) return undefined;
+  const unique = new Map<string, unknown>();
+  for (const value of values) unique.set(stableMetadataKey(value), value);
+  return [...unique.values()];
+}
+
+function mergeExecutionMetadata(
+  existing: Record<string, unknown>,
+  incoming: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged = { ...existing, ...incoming };
+  for (const key of [
+    'evidenceDegradations',
+    'evidenceContractOutcomes',
+    'pendingEvidenceContractIds',
+    'sessionFinalizationDegradations',
+  ]) {
+    const union = unionMetadataArrays(existing[key], incoming[key]);
+    if (union !== undefined) merged[key] = union;
+  }
+  return merged;
+}