@devflow-tools/database 0.16.11 → 0.16.13

package/dist/database.js

@@ -8,6 +8,7 @@ const path_1 = require("path");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const crypto_1 = require("crypto");
+const obligation_ledger_1 = require("./obligation-ledger");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -281,12 +282,32 @@ 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,
@@ -294,6 +315,7 @@ 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
       );
 
@@ -322,6 +344,32 @@ 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,
@@ -424,6 +472,10 @@ class DevFlowDatabase {
             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');
         }
@@ -453,6 +505,22 @@ class DevFlowDatabase {
             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)');
         // Migration: tool_metrics table for per-tool metrics collection
@@ -887,6 +955,15 @@ class DevFlowDatabase {
             metadata: row.metadata ? JSON.parse(row.metadata) : null,
         };
     }
+    getLatestSkillExecutionForSession(sessionId) {
+        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);
+        return row?.execution_id ? this.getSkillExecution(row.execution_id) : null;
+    }
     updateSkillExecution(executionId, updates) {
         const sets = [];
         const values = [];
@@ -951,6 +1028,17 @@ class DevFlowDatabase {
             this.db.prepare(`UPDATE skill_executions SET ${sets.join(', ')} WHERE execution_id = ?`).run(...values);
         }
     }
+    mergeSkillExecutionMetadata(executionId, incoming) {
+        const execution = this.getSkillExecution(executionId);
+        if (!execution)
+            return null;
+        const existing = execution.metadata && typeof execution.metadata === 'object'
+            ? execution.metadata
+            : {};
+        const merged = mergeExecutionMetadata(existing, incoming);
+        this.updateSkillExecution(executionId, { metadata: merged });
+        return merged;
+    }
     listSkillExecutions(limit, skillName) {
         let query = 'SELECT * FROM skill_executions';
         const params = [];
@@ -1058,6 +1146,10 @@ 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);
@@ -1095,23 +1187,38 @@ 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).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,
+            }))
             : [];
         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) => typeof id === 'string')
-            : [];
-        const suppliedDistillReceiptIds = Array.isArray(metadata?.distillReceiptIds)
-            ? metadata.distillReceiptIds.filter((id) => typeof id === 'string')
-            : [];
+        const existingMetadata = execution?.metadata && typeof execution.metadata === 'object'
+            ? execution.metadata
+            : {};
+        const mergedMetadata = mergeExecutionMetadata(existingMetadata, metadata ?? {});
+        const suppliedMemoryReceiptIds = [existingMetadata.memoryReceiptIds, metadata?.memoryReceiptIds]
+            .flatMap(value => Array.isArray(value) ? value : [])
+            .filter((id) => typeof id === 'string');
+        const suppliedDistillReceiptIds = [existingMetadata.distillReceiptIds, metadata?.distillReceiptIds]
+            .flatMap(value => Array.isArray(value) ? value : [])
+            .filter((id) => typeof id === 'string');
         const memoryReceiptIds = [...new Set([
                 ...suppliedMemoryReceiptIds,
                 ...eventReceiptIds.filter(id => id.startsWith('memory-receipt:')),
@@ -1137,7 +1244,7 @@ class DevFlowDatabase {
             fallbackCount: directFallbacks.length + hookFallbacks.length,
             fallbackReasons,
             metadata: {
-                ...(metadata ?? {}),
+                ...mergedMetadata,
                 applicableObligations: obligation.applicable,
                 satisfiedObligations: obligation.satisfied,
                 missedTools: obligation.missedTools,
@@ -1708,14 +1815,7 @@ class DevFlowDatabase {
         return row ? this.mapSessionClosure(row) : null;
     }
     completeSessionClosure(projectRoot, sessionId, excludingWorkItemId, closedAt = Date.now()) {
-        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);
-        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
@@ -1823,6 +1923,16 @@ class DevFlowDatabase {
       WHERE id = ? AND state = 'leased' AND lease_owner = ?
     `).run(nextAttemptAt, error.category, error.message, updatedAt, id, owner).changes === 1;
     }
+    deferWork(id, owner, error, nextAttemptAt) {
+        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, owner, error) {
         return this.db.prepare(`
       UPDATE devflow_work_items
@@ -1909,13 +2019,7 @@ class DevFlowDatabase {
         };
     }
     refreshClosedSessionClosure(projectRoot, sessionId, now) {
-        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);
-        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,
@@ -1924,6 +2028,34 @@ class DevFlowDatabase {
         AND state IN ('closed', 'closed_with_pending_work')
     `).run(pendingWorkCount, pendingWorkCount, now, projectRoot, sessionId);
     }
+    countSessionLifecyclePending(projectRoot, sessionId, excludingWorkItemId) {
+        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);
+        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);
+        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);
+        return Number(work?.count ?? 0)
+            + Number(obligations?.count ?? 0)
+            + Number(legacyTurns?.count ?? 0);
+    }
     // ---- Hook Lifecycle ----
     getHookReceipt(projectRoot) {
         const row = this.db.prepare(`
@@ -1977,17 +2109,23 @@ class DevFlowDatabase {
     upsertContextReceipt(receipt) {
         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
-    `).run(receipt.projectRoot, receipt.sessionId, receipt.executionId, receipt.contextHash, receipt.issuedAt, receipt.expiresAt);
+        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, receipt.executionId, receipt.contextHash, receipt.issuedAt, receipt.expiresAt, JSON.stringify(receipt.selectedFiles ?? []), JSON.stringify(receipt.memoryIds ?? []), receipt.canonicalNextAction ?? null, receipt.requestId ?? null);
     }
     getContextReceipt(projectRoot, sessionId, executionId) {
         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);
@@ -1998,8 +2136,77 @@ 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, sessionId, executionId, now = Date.now()) {
+        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);
+        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) {
+        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) {
+        const predicates = ['project_root = ?'];
+        const params = [options.projectRoot];
+        for (const [column, value] of [
+            ['session_id', options.sessionId],
+            ['execution_id', options.executionId],
+            ['request_id', options.requestId],
+        ]) {
+            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);
+        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, sessionId, executionId) {
         return executionId
             ? this.db.prepare(`DELETE FROM devflow_context_receipts
@@ -2014,15 +2221,104 @@ class DevFlowDatabase {
             .run(now).changes;
     }
     beginMemoryTurn(input) {
+        const turnId = (0, obligation_ledger_1.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, input.projectRoot, input.sessionId, input.promptHash, input.eventId, input.createdAt);
-        return this.getMemoryTurn(input.turnId);
+    `).run(turnId, input.projectRoot, input.sessionId, input.promptHash, input.eventId, input.createdAt);
+        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) {
+        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, sessionId, obligationId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_session_obligations
+      WHERE project_root = ? AND session_id = ? AND obligation_id = ?
+    `).get(projectRoot, sessionId, obligationId);
+        return row ? (0, obligation_ledger_1.mapSessionObligationRow)(row) : null;
+    }
+    listSessionObligations(projectRoot, sessionId, states) {
+        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));
+        return rows.map(obligation_ledger_1.mapSessionObligationRow);
+    }
+    resolveSessionObligation(input) {
+        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, sessionId) {
+        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);
+        return Number(row?.count ?? 0);
     }
     getMemoryTurn(turnId) {
-        const row = this.db.prepare('SELECT * FROM devflow_memory_turns WHERE turn_id = ?').get(turnId);
+        const row = this.db.prepare('SELECT * FROM devflow_memory_turns WHERE turn_id = ?').get((0, obligation_ledger_1.normalizeTurnId)(turnId));
         return row ? this.mapMemoryTurn(row) : null;
     }
     getPendingMemoryTurn(projectRoot, sessionId) {
@@ -2034,35 +2330,73 @@ class DevFlowDatabase {
         return row ? this.mapMemoryTurn(row) : null;
     }
     commitMemoryTurn(input) {
+        const turnId = (0, obligation_ledger_1.normalizeTurnId)(input.turnId);
         this.db.prepare(`
       UPDATE devflow_memory_turns
       SET status = 'committed', receipt_id = ?, memory_ids = ?, source = ?, reason = ?, decided_at = ?
       WHERE turn_id = ? AND status = 'pending'
-    `).run(input.receiptId, JSON.stringify([...new Set(input.memoryIds)]), input.source, input.reason ?? null, input.decidedAt ?? Date.now(), input.turnId);
-        const turn = this.getMemoryTurn(input.turnId);
+    `).run(input.receiptId, JSON.stringify([...new Set(input.memoryIds)]), input.source, input.reason ?? null, input.decidedAt ?? Date.now(), 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;
     }
     skipMemoryTurn(input) {
+        const turnId = (0, obligation_ledger_1.normalizeTurnId)(input.turnId);
         this.db.prepare(`
       UPDATE devflow_memory_turns
       SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = 'host_skip',
           reason = ?, decided_at = ?
       WHERE turn_id = ? AND status = 'pending'
-    `).run(input.receiptId, input.reason, input.decidedAt ?? Date.now(), input.turnId);
-        const turn = this.getMemoryTurn(input.turnId);
+    `).run(input.receiptId, input.reason, input.decidedAt ?? Date.now(), 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;
     }
     markMemoryTurnStopPrompted(turnId, promptedAt = Date.now()) {
         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, (0, obligation_ledger_1.normalizeTurnId)(turnId)).changes === 1;
+    }
+    ensureMemoryObligation(turn) {
+        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, sessionId, limit = 50) {
         const rows = (sessionId
@@ -2074,6 +2408,14 @@ class DevFlowDatabase {
                 .all(projectRoot, limit));
         return rows.map(row => this.mapMemoryTurn(row));
     }
+    listSessionMemoryTurnsForReconciliation(projectRoot, sessionId) {
+        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);
+        return rows.map(row => this.mapMemoryTurn(row));
+    }
     insertHookFallback(record) {
         return this.db.prepare(`
       INSERT OR IGNORE INTO devflow_hook_fallbacks
@@ -2147,13 +2489,18 @@ class DevFlowDatabase {
     recordMemoryDistillCheckpoint(checkpoint) {
         this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints
-        (id, project_root, session_id, trigger, pending_events, released_leases, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `).run(checkpoint.id, checkpoint.projectRoot, checkpoint.sessionId ?? null, checkpoint.trigger, checkpoint.pendingEvents, checkpoint.releasedLeases, checkpoint.createdAt);
+        (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, checkpoint.sessionId ?? null, checkpoint.trigger, checkpoint.pendingEvents, checkpoint.releasedLeases, JSON.stringify(checkpoint.details ?? {}), checkpoint.createdAt);
     }
     listMemoryDistillCheckpoints(projectRoot, limit = 50) {
         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
@@ -2166,6 +2513,7 @@ 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),
         }));
     }
@@ -2191,6 +2539,12 @@ function parseJson(value) {
         return value;
     }
 }
+function parseJsonStringArray(value) {
+    const parsed = parseJson(value);
+    return Array.isArray(parsed)
+        ? parsed.filter((item) => typeof item === 'string')
+        : [];
+}
 function deriveQuery(input) {
     if (!input || typeof input !== 'object')
         return null;
@@ -2266,3 +2620,39 @@ function collectCanonicalReceiptIds(values) {
     values.forEach(value => visit(value, 0));
     return [...receiptIds];
 }
+function stableMetadataKey(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? String(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableMetadataKey).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort()
+        .map(key => `${JSON.stringify(key)}:${stableMetadataKey(record[key])}`)
+        .join(',')}}`;
+}
+function unionMetadataArrays(existing, incoming) {
+    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();
+    for (const value of values)
+        unique.set(stableMetadataKey(value), value);
+    return [...unique.values()];
+}
+function mergeExecutionMetadata(existing, incoming) {
+    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;
+}