@devflow-tools/database 0.16.12 → 0.16.13

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.13](https://github.com/shilongfeicool/dev-flow/compare/v0.16.12...v0.16.13) (2026-07-26)
+
+
+### Features
+
+* add retrieval quality control plane ([743bd12](https://github.com/shilongfeicool/dev-flow/commit/743bd12daa18ceec611dc82674b20b015d110f0c))
+
+
+
+
+
 ## [0.16.12](https://github.com/shilongfeicool/dev-flow/compare/v0.16.11...v0.16.12) (2026-07-26)
 
 

package/dist/database.d.ts

@@ -1,4 +1,5 @@
 import type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, WorkError, WorkItemRecord, WorkQueueHealth } from './work-queue';
+import { type SessionObligationRecord, type SessionObligationState } from './obligation-ledger';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -74,6 +75,22 @@ 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 {
     id: string;
@@ -217,6 +234,7 @@ export declare class DevFlowDatabase {
     updateToolCallEvent(eventId: string, updates: {
         output?: string;
         error?: string;
+        failureCategory?: string;
         duration?: number;
     }): boolean;
     markToolCallBlocked(eventId: string, reason: string): boolean;
@@ -321,14 +339,36 @@ export declare class DevFlowDatabase {
     private mapWorkItem;
     private mapSessionClosure;
     private refreshClosedSessionClosure;
+    private countSessionLifecyclePending;
     getHookReceipt(projectRoot: string): HookReceiptRecord | null;
     updateHookReceipt(projectRoot: string, updater: (current: HookReceiptRecord | null) => Omit<HookReceiptRecord, 'projectRoot' | 'updatedAt'>): HookReceiptRecord;
     deleteHookReceipt(projectRoot: string): boolean;
     upsertContextReceipt(receipt: ContextReceiptRecord): void;
     getContextReceipt(projectRoot: string, sessionId: string, executionId: string): ContextReceiptRecord | null;
+    getActiveContextReceipt(projectRoot: string, sessionId: string, executionId?: string, now?: number): ContextReceiptRecord | null;
+    recordContextSelectionEvent(event: ContextSelectionEventRecord): boolean;
+    listContextSelectionEvents(options: {
+        projectRoot: string;
+        sessionId?: string;
+        executionId?: string;
+        requestId?: string;
+    }): ContextSelectionEventRecord[];
     deleteContextReceipt(projectRoot: string, sessionId: string, executionId?: string): number;
     purgeExpiredContextReceipts(now?: number): number;
     beginMemoryTurn(input: Omit<MemoryTurnRecord, 'status' | 'memoryIds'>): MemoryTurnRecord;
+    upsertSessionObligation(record: SessionObligationRecord): SessionObligationRecord;
+    getSessionObligation(projectRoot: string, sessionId: string, obligationId: string): SessionObligationRecord | null;
+    listSessionObligations(projectRoot: string, sessionId: string, states?: SessionObligationState[]): SessionObligationRecord[];
+    resolveSessionObligation(input: {
+        projectRoot: string;
+        sessionId: string;
+        obligationId: string;
+        state: 'satisfied' | 'degraded' | 'cancelled';
+        receiptId?: string;
+        reason?: string;
+        resolvedAt?: number;
+    }): SessionObligationRecord;
+    countOpenSessionObligations(projectRoot: string, sessionId: string): number;
     getMemoryTurn(turnId: string): MemoryTurnRecord | null;
     getPendingMemoryTurn(projectRoot: string, sessionId: string): MemoryTurnRecord | null;
     commitMemoryTurn(input: {
@@ -346,6 +386,7 @@ export declare class DevFlowDatabase {
         decidedAt?: number;
     }): MemoryTurnRecord;
     markMemoryTurnStopPrompted(turnId: string, promptedAt?: number): boolean;
+    private ensureMemoryObligation;
     listMemoryTurns(projectRoot: string, sessionId?: string, limit?: number): MemoryTurnRecord[];
     listSessionMemoryTurnsForReconciliation(projectRoot: string, sessionId: string): MemoryTurnRecord[];
     insertHookFallback(record: HookFallbackRecord): boolean;

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,
@@ -323,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,
@@ -458,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
@@ -1083,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);
@@ -1748,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
@@ -1959,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,
@@ -1974,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(`
@@ -2027,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);
@@ -2048,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
@@ -2064,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) {
@@ -2084,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
@@ -2255,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;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
-export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
+export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, ContextReceiptRecord, ContextSelectionEventRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
 export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, WorkQueueHealth, WorkState, } from './work-queue';
+export { mapSessionObligationRow, normalizeTurnId, } from './obligation-ledger';
+export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';

package/dist/index.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.normalizeTurnId = exports.mapSessionObligationRow = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
 var database_1 = require("./database");
 Object.defineProperty(exports, "DevFlowDatabase", { enumerable: true, get: function () { return database_1.DevFlowDatabase; } });
 Object.defineProperty(exports, "getGlobalDevFlowDbPath", { enumerable: true, get: function () { return database_1.getGlobalDevFlowDbPath; } });
 Object.defineProperty(exports, "openGlobalDevFlowDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowDatabase; } });
+var obligation_ledger_1 = require("./obligation-ledger");
+Object.defineProperty(exports, "mapSessionObligationRow", { enumerable: true, get: function () { return obligation_ledger_1.mapSessionObligationRow; } });
+Object.defineProperty(exports, "normalizeTurnId", { enumerable: true, get: function () { return obligation_ledger_1.normalizeTurnId; } });

package/dist/obligation-ledger.d.ts

@@ -0,0 +1,19 @@
+export type SessionObligationKind = 'memory_decision' | 'evidence_contract' | 'session_finalize';
+export type SessionObligationState = 'open' | 'satisfied' | 'degraded' | 'cancelled';
+export interface SessionObligationRecord {
+    obligationId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    turnId?: string;
+    kind: SessionObligationKind;
+    state: SessionObligationState;
+    payload: Record<string, unknown>;
+    receiptId?: string;
+    reason?: string;
+    createdAt: number;
+    updatedAt: number;
+    resolvedAt?: number;
+}
+export declare function normalizeTurnId(value: string): string;
+export declare function mapSessionObligationRow(row: Record<string, unknown>): SessionObligationRecord;

package/dist/obligation-ledger.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTurnId = normalizeTurnId;
+exports.mapSessionObligationRow = mapSessionObligationRow;
+function normalizeTurnId(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error('Memory turn ID is required');
+    return trimmed.startsWith('turn:') ? trimmed : `turn:${trimmed}`;
+}
+function mapSessionObligationRow(row) {
+    let payload = {};
+    try {
+        const parsed = JSON.parse(String(row.payload ?? '{}'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            payload = parsed;
+        }
+    }
+    catch { }
+    return {
+        obligationId: String(row.obligation_id),
+        projectRoot: String(row.project_root),
+        sessionId: String(row.session_id),
+        executionId: typeof row.execution_id === 'string' ? row.execution_id : undefined,
+        turnId: typeof row.turn_id === 'string' ? row.turn_id : undefined,
+        kind: row.kind,
+        state: row.state,
+        payload,
+        receiptId: typeof row.receipt_id === 'string' ? row.receipt_id : undefined,
+        reason: typeof row.reason === 'string' ? row.reason : undefined,
+        createdAt: Number(row.created_at),
+        updatedAt: Number(row.updated_at),
+        resolvedAt: typeof row.resolved_at === 'number' ? row.resolved_at : undefined,
+    };
+}

package/dist/work-queue.d.ts

@@ -1,4 +1,4 @@
-export type WorkKind = 'memory.explicit_commit' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
+export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
 export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter';
 export interface WorkError {
     category: string;