@devflow-tools/database 0.16.19 → 0.16.20

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.20](https://github.com/shilongfeicool/dev-flow/compare/v0.16.19...v0.16.20) (2026-07-28)
+
+
+### Features
+
+* **retrieval:** close outcome-aware retrieval quality ([e4048a1](https://github.com/shilongfeicool/dev-flow/commit/e4048a1d921a85bd078de031b334f24cb8f4f393))
+
+
+
+
+
 ## [0.16.19](https://github.com/shilongfeicool/dev-flow/compare/v0.16.18...v0.16.19) (2026-07-28)
 
 

package/__tests__/database.retrieval-sessions.test.ts

@@ -0,0 +1,79 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/database';
+
+describe('DevFlowDatabase retrieval sessions', () => {
+  let root: string;
+  let database: DevFlowDatabase;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'devflow-retrieval-session-'));
+    database = new DevFlowDatabase(root);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const create = () => database.createRetrievalSession({
+    id: 'retrieval-1', requestId: 'request-1', projectRoot: '/project-a',
+    sessionId: 'session-1', executionId: 'execution-1', query: 'review player',
+    intent: 'performance', tokenBudget: 1000, baselineReceipt: 'baseline-1',
+    expiresAt: Date.now() + 60_000,
+  });
+
+  it('persists idempotent cycles and rejects changed evidence', () => {
+    expect(create()).toMatchObject({ id: 'retrieval-1', cycle: 0, remainingTokenBudget: 1000 });
+    expect(create()).toMatchObject({ id: 'retrieval-1' });
+    const input = {
+      retrievalSessionId: 'retrieval-1', projectRoot: '/project-a', sessionId: 'session-1',
+      baselineReceipt: 'baseline-1', cycle: 1,
+      gaps: [{ kind: 'caller' as const, reason: 'missing caller', evidence: [], resolver: 'codegraph' as const, priority: 80 }],
+      selectedIds: ['code:src/player.tsx'], rejectedIds: [], tokenCost: 200,
+      remainingTokenBudget: 800, quality: { status: 'healthy' }, receipt: 'cycle-1', evidenceHash: 'hash-1',
+    };
+    expect(database.appendRetrievalCycle(input)).toMatchObject({ cycle: 1, tokenCost: 200 });
+    expect(database.appendRetrievalCycle(input)).toMatchObject({ evidenceHash: 'hash-1' });
+    expect(() => database.appendRetrievalCycle({ ...input, evidenceHash: 'changed' }))
+      .toThrow('RETRIEVAL_CYCLE_CONFLICT:1');
+    expect(database.getRetrievalSession('/project-a', 'session-1', 'retrieval-1'))
+      .toMatchObject({ cycle: 1, remainingTokenBudget: 800 });
+  });
+
+  it('enforces ownership, sequence, terminal state, and expiration', () => {
+    create();
+    expect(database.getRetrievalSession('/project-b', 'session-1', 'retrieval-1')).toBeNull();
+    expect(() => database.appendRetrievalCycle({
+      retrievalSessionId: 'retrieval-1', projectRoot: '/project-a', sessionId: 'session-1',
+      baselineReceipt: 'baseline-1', cycle: 2, gaps: [], selectedIds: [], rejectedIds: [],
+      tokenCost: 1, remainingTokenBudget: 999, quality: {}, receipt: 'cycle-2', evidenceHash: 'hash-2',
+    })).toThrow('RETRIEVAL_CYCLE_SEQUENCE:0->2');
+    database.finalizeRetrievalSession({
+      id: 'retrieval-1', projectRoot: '/project-a', sessionId: 'session-1',
+      state: 'exhausted', finalReceipt: 'final-1',
+    });
+    expect(() => database.finalizeRetrievalSession({
+      id: 'retrieval-1', projectRoot: '/project-a', sessionId: 'session-1',
+      state: 'satisfied', finalReceipt: 'different',
+    })).toThrow('RETRIEVAL_SESSION_TERMINAL:exhausted');
+
+    database.createRetrievalSession({
+      id: 'retrieval-expire', requestId: 'request-expire', projectRoot: '/project-a',
+      sessionId: 'session-1', query: 'x', intent: 'debug', tokenBudget: 1,
+      baselineReceipt: 'baseline-expire', expiresAt: Date.now() + 10,
+    });
+    expect(database.expireRetrievalSessions(Date.now() + 20)).toBe(1);
+    expect(database.getRetrievalSession('/project-a', 'session-1', 'retrieval-expire')?.state).toBe('expired');
+  });
+
+  it('keeps retrieval rows stable across reopen', () => {
+    create();
+    database.close();
+    database = new DevFlowDatabase(root);
+    expect(database.getRetrievalSession('/project-a', 'session-1', 'retrieval-1'))
+      .toMatchObject({ requestId: 'request-1', baselineReceipt: 'baseline-1' });
+  });
+});

package/dist/database.d.ts

@@ -1,6 +1,7 @@
 import type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, WorkError, WorkItemRecord, WorkQueueHealth } from './work-queue';
 import { type SessionObligationRecord, type SessionObligationState } from './obligation-ledger';
 import { type FailHostActionInput, type HostActionRecord, type ReportHostActionInput, type RequestHostActionInput, type StartHostActionInput, type VerifyHostActionInput } from './host-actions';
+import { type AppendRetrievalCycleInput, type CreateRetrievalSessionInput, type RetrievalCycleRecord, type RetrievalSessionRecord, type RetrievalSessionState } from './retrieval-sessions';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -344,6 +345,21 @@ export declare class DevFlowDatabase {
     getHookReceipt(projectRoot: string): HookReceiptRecord | null;
     updateHookReceipt(projectRoot: string, updater: (current: HookReceiptRecord | null) => Omit<HookReceiptRecord, 'projectRoot' | 'updatedAt'>): HookReceiptRecord;
     deleteHookReceipt(projectRoot: string): boolean;
+    createRetrievalSession(input: CreateRetrievalSessionInput): RetrievalSessionRecord;
+    getRetrievalSession(projectRoot: string, sessionId: string, id: string): RetrievalSessionRecord | null;
+    getRetrievalSessionByRequest(requestId: string): RetrievalSessionRecord | null;
+    listRetrievalCycles(retrievalSessionId: string): RetrievalCycleRecord[];
+    appendRetrievalCycle(input: AppendRetrievalCycleInput): RetrievalCycleRecord;
+    finalizeRetrievalSession(input: {
+        id: string;
+        projectRoot: string;
+        sessionId: string;
+        state: Extract<RetrievalSessionState, 'satisfied' | 'exhausted'>;
+        finalReceipt: string;
+    }): RetrievalSessionRecord;
+    expireRetrievalSessions(now?: number, limit?: number): number;
+    private validateRetrievalSessionInput;
+    private assertRetrievalIdentity;
     upsertContextReceipt(receipt: ContextReceiptRecord): void;
     getContextReceipt(projectRoot: string, sessionId: string, executionId: string): ContextReceiptRecord | null;
     getActiveContextReceipt(projectRoot: string, sessionId: string, executionId?: string, now?: number): ContextReceiptRecord | null;
@@ -408,6 +424,7 @@ export declare class DevFlowDatabase {
     failHostAction(input: FailHostActionInput): HostActionRecord;
     getHostAction(projectRoot: string, actionId: string): HostActionRecord | null;
     listHostActionsForRun(projectRoot: string, runId: string): HostActionRecord[];
+    listHostActionsForSession(projectRoot: string, sessionId: string, executionId?: string): HostActionRecord[];
     private transitionHostAction;
     private appendHostActionEvent;
     private validateHostActionIdentity;

package/dist/database.js

@@ -10,6 +10,7 @@ const os_1 = require("os");
 const crypto_1 = require("crypto");
 const obligation_ledger_1 = require("./obligation-ledger");
 const host_actions_1 = require("./host-actions");
+const retrieval_sessions_1 = require("./retrieval-sessions");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -309,6 +310,50 @@ class DevFlowDatabase {
       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_retrieval_sessions (
+        id TEXT PRIMARY KEY,
+        request_id TEXT NOT NULL UNIQUE,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        query TEXT NOT NULL,
+        intent TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'open'
+          CHECK(state IN ('open', 'satisfied', 'exhausted', 'expired')),
+        cycle INTEGER NOT NULL DEFAULT 0 CHECK(cycle BETWEEN 0 AND 3),
+        max_cycles INTEGER NOT NULL DEFAULT 3 CHECK(max_cycles = 3),
+        initial_token_budget INTEGER NOT NULL CHECK(initial_token_budget >= 0),
+        remaining_token_budget INTEGER NOT NULL CHECK(remaining_token_budget >= 0),
+        baseline_receipt TEXT NOT NULL,
+        final_receipt TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_retrieval_sessions_owner
+        ON devflow_retrieval_sessions(project_root, session_id, state, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_retrieval_sessions_expiry
+        ON devflow_retrieval_sessions(state, expires_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_retrieval_cycles (
+        retrieval_session_id TEXT NOT NULL,
+        cycle INTEGER NOT NULL CHECK(cycle BETWEEN 1 AND 3),
+        gaps_json TEXT NOT NULL DEFAULT '[]',
+        selected_ids TEXT NOT NULL DEFAULT '[]',
+        rejected_ids TEXT NOT NULL DEFAULT '[]',
+        token_cost INTEGER NOT NULL CHECK(token_cost >= 0),
+        remaining_token_budget INTEGER NOT NULL CHECK(remaining_token_budget >= 0),
+        quality_json TEXT NOT NULL DEFAULT '{}',
+        receipt TEXT NOT NULL,
+        evidence_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (retrieval_session_id, cycle)
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_retrieval_cycles_receipt
+        ON devflow_retrieval_cycles(receipt);
+
       CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -2180,6 +2225,183 @@ class DevFlowDatabase {
         return this.db.prepare('DELETE FROM devflow_hook_receipts WHERE project_root = ?')
             .run(projectRoot).changes > 0;
     }
+    createRetrievalSession(input) {
+        this.validateRetrievalSessionInput(input);
+        const now = Date.now();
+        const id = input.id?.trim() || (0, crypto_1.randomUUID)();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const existing = this.getRetrievalSessionByRequest(input.requestId);
+            if (existing) {
+                this.assertRetrievalIdentity(existing, input);
+                this.db.exec('COMMIT');
+                return existing;
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_retrieval_sessions
+          (id, request_id, project_root, session_id, execution_id, query, intent, state,
+           cycle, max_cycles, initial_token_budget, remaining_token_budget,
+           baseline_receipt, created_at, updated_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'open', 0, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, input.requestId, input.projectRoot, input.sessionId, input.executionId ?? null, input.query, input.intent, retrieval_sessions_1.RETRIEVAL_MAX_CYCLES, input.tokenBudget, input.tokenBudget, input.baselineReceipt, now, now, input.expiresAt);
+            const created = this.getRetrievalSession(input.projectRoot, input.sessionId, id);
+            this.db.exec('COMMIT');
+            return created;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    getRetrievalSession(projectRoot, sessionId, id) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_retrieval_sessions
+      WHERE id = ? AND project_root = ? AND session_id = ?
+    `).get(id, projectRoot, sessionId);
+        return row ? (0, retrieval_sessions_1.mapRetrievalSessionRow)(row) : null;
+    }
+    getRetrievalSessionByRequest(requestId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_retrieval_sessions WHERE request_id = ?
+    `).get(requestId);
+        return row ? (0, retrieval_sessions_1.mapRetrievalSessionRow)(row) : null;
+    }
+    listRetrievalCycles(retrievalSessionId) {
+        return this.db.prepare(`
+      SELECT * FROM devflow_retrieval_cycles
+      WHERE retrieval_session_id = ? ORDER BY cycle ASC
+    `).all(retrievalSessionId).map(retrieval_sessions_1.mapRetrievalCycleRow);
+    }
+    appendRetrievalCycle(input) {
+        if (!Number.isInteger(input.cycle) || input.cycle < 1 || input.cycle > retrieval_sessions_1.RETRIEVAL_MAX_CYCLES) {
+            throw new Error(`RETRIEVAL_INVALID_CYCLE:${input.cycle}`);
+        }
+        if (!Number.isSafeInteger(input.tokenCost) || input.tokenCost < 0
+            || !Number.isSafeInteger(input.remainingTokenBudget) || input.remainingTokenBudget < 0) {
+            throw new Error('RETRIEVAL_INVALID_BUDGET');
+        }
+        const gapsJson = (0, retrieval_sessions_1.serializeRetrievalJson)(input.gaps);
+        const selectedJson = (0, retrieval_sessions_1.serializeRetrievalJson)([...new Set(input.selectedIds)]);
+        const rejectedJson = (0, retrieval_sessions_1.serializeRetrievalJson)([...new Set(input.rejectedIds)]);
+        const qualityJson = (0, retrieval_sessions_1.serializeRetrievalJson)(input.quality);
+        const now = Date.now();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const session = this.getRetrievalSession(input.projectRoot, input.sessionId, input.retrievalSessionId);
+            if (!session)
+                throw new Error(`RETRIEVAL_SESSION_NOT_FOUND:${input.retrievalSessionId}`);
+            if (session.baselineReceipt !== input.baselineReceipt)
+                throw new Error('RETRIEVAL_BASELINE_RECEIPT_MISMATCH');
+            const existing = this.db.prepare(`
+        SELECT * FROM devflow_retrieval_cycles WHERE retrieval_session_id = ? AND cycle = ?
+      `).get(input.retrievalSessionId, input.cycle);
+            if (existing) {
+                const cycle = (0, retrieval_sessions_1.mapRetrievalCycleRow)(existing);
+                if (cycle.evidenceHash !== input.evidenceHash || cycle.receipt !== input.receipt
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.gaps) !== gapsJson
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.selectedIds) !== selectedJson
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.rejectedIds) !== rejectedJson
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.quality) !== qualityJson) {
+                    throw new Error(`RETRIEVAL_CYCLE_CONFLICT:${input.cycle}`);
+                }
+                this.db.exec('COMMIT');
+                return cycle;
+            }
+            if (session.state !== 'open')
+                throw new Error(`RETRIEVAL_SESSION_TERMINAL:${session.state}`);
+            if (session.expiresAt <= now)
+                throw new Error('RETRIEVAL_SESSION_EXPIRED');
+            if (input.cycle !== session.cycle + 1)
+                throw new Error(`RETRIEVAL_CYCLE_SEQUENCE:${session.cycle}->${input.cycle}`);
+            if (input.tokenCost > session.remainingTokenBudget
+                || input.remainingTokenBudget !== session.remainingTokenBudget - input.tokenCost) {
+                throw new Error('RETRIEVAL_BUDGET_MISMATCH');
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_retrieval_cycles
+          (retrieval_session_id, cycle, gaps_json, selected_ids, rejected_ids, token_cost,
+           remaining_token_budget, quality_json, receipt, evidence_hash, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.retrievalSessionId, input.cycle, gapsJson, selectedJson, rejectedJson, input.tokenCost, input.remainingTokenBudget, qualityJson, input.receipt, input.evidenceHash, now);
+            this.db.prepare(`
+        UPDATE devflow_retrieval_sessions
+        SET cycle = ?, remaining_token_budget = ?, updated_at = ?
+        WHERE id = ? AND project_root = ? AND session_id = ?
+      `).run(input.cycle, input.remainingTokenBudget, now, input.retrievalSessionId, input.projectRoot, input.sessionId);
+            const created = (0, retrieval_sessions_1.mapRetrievalCycleRow)(this.db.prepare(`
+        SELECT * FROM devflow_retrieval_cycles WHERE retrieval_session_id = ? AND cycle = ?
+      `).get(input.retrievalSessionId, input.cycle));
+            this.db.exec('COMMIT');
+            return created;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    finalizeRetrievalSession(input) {
+        const now = Date.now();
+        const current = this.getRetrievalSession(input.projectRoot, input.sessionId, input.id);
+        if (!current)
+            throw new Error(`RETRIEVAL_SESSION_NOT_FOUND:${input.id}`);
+        if (current.state !== 'open') {
+            if (current.state === input.state && current.finalReceipt === input.finalReceipt)
+                return current;
+            throw new Error(`RETRIEVAL_SESSION_TERMINAL:${current.state}`);
+        }
+        this.db.prepare(`
+      UPDATE devflow_retrieval_sessions SET state = ?, final_receipt = ?, updated_at = ?
+      WHERE id = ? AND project_root = ? AND session_id = ? AND state = 'open'
+    `).run(input.state, input.finalReceipt, now, input.id, input.projectRoot, input.sessionId);
+        return this.getRetrievalSession(input.projectRoot, input.sessionId, input.id);
+    }
+    expireRetrievalSessions(now = Date.now(), limit = 100) {
+        const rows = this.db.prepare(`
+      SELECT id FROM devflow_retrieval_sessions
+      WHERE state = 'open' AND expires_at <= ? ORDER BY expires_at ASC LIMIT ?
+    `).all(now, Math.max(1, Math.min(1000, Math.floor(limit))));
+        if (rows.length === 0)
+            return 0;
+        const placeholders = rows.map(() => '?').join(',');
+        return this.db.prepare(`
+      UPDATE devflow_retrieval_sessions SET state = 'expired', updated_at = ?
+      WHERE state = 'open' AND id IN (${placeholders})
+    `).run(now, ...rows.map(row => row.id)).changes;
+    }
+    validateRetrievalSessionInput(input) {
+        for (const [field, value] of Object.entries({
+            requestId: input.requestId,
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            query: input.query,
+            intent: input.intent,
+            baselineReceipt: input.baselineReceipt,
+        })) {
+            if (typeof value !== 'string' || value.trim().length === 0)
+                throw new Error(`RETRIEVAL_INVALID_${field}`);
+        }
+        if (!Number.isSafeInteger(input.tokenBudget) || input.tokenBudget < 0)
+            throw new Error('RETRIEVAL_INVALID_BUDGET');
+        if (!Number.isSafeInteger(input.expiresAt) || input.expiresAt <= Date.now())
+            throw new Error('RETRIEVAL_INVALID_EXPIRY');
+    }
+    assertRetrievalIdentity(existing, input) {
+        const matches = existing.projectRoot === input.projectRoot
+            && existing.sessionId === input.sessionId
+            && existing.executionId === input.executionId
+            && existing.query === input.query
+            && existing.intent === input.intent
+            && existing.initialTokenBudget === input.tokenBudget
+            && existing.baselineReceipt === input.baselineReceipt;
+        if (!matches)
+            throw new Error(`RETRIEVAL_REQUEST_CONFLICT:${input.requestId}`);
+    }
     upsertContextReceipt(receipt) {
         this.db.prepare(`
       INSERT INTO devflow_context_receipts
@@ -2665,6 +2887,15 @@ class DevFlowDatabase {
     `).all(projectRoot, runId);
         return rows.map(host_actions_1.mapHostActionRow);
     }
+    listHostActionsForSession(projectRoot, sessionId, executionId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_host_actions
+      WHERE project_root = ? AND session_id = ?
+        AND (? IS NULL OR execution_id = ?)
+      ORDER BY created_at ASC, action_id ASC
+    `).all(projectRoot, sessionId, executionId ?? null, executionId ?? null);
+        return rows.map(host_actions_1.mapHostActionRow);
+    }
     transitionHostAction(identity, targetState, report, evidenceHash, requireNonEmptyReport = false) {
         if (!identity.actionId.trim())
             throw new Error('Host action requires an action ID');

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } f
 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 { hostActionReportsEqual, isHostActionState, mapHostActionRow, serializeHostActionReport, } from './host-actions';
+export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessions';
+export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalCycleRecord, RetrievalGapKind, RetrievalGapRecord, RetrievalSessionRecord, RetrievalSessionState, } from './retrieval-sessions';
 export type { FailHostActionInput, HostActionRecord, HostActionState, ReportHostActionInput, RequestHostActionInput, StartHostActionInput, VerifyHostActionInput, } from './host-actions';
 export { mapSessionObligationRow, normalizeTurnId, } from './obligation-ledger';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeTurnId = exports.mapSessionObligationRow = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = 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; } });
@@ -10,6 +10,9 @@ Object.defineProperty(exports, "hostActionReportsEqual", { enumerable: true, get
 Object.defineProperty(exports, "isHostActionState", { enumerable: true, get: function () { return host_actions_1.isHostActionState; } });
 Object.defineProperty(exports, "mapHostActionRow", { enumerable: true, get: function () { return host_actions_1.mapHostActionRow; } });
 Object.defineProperty(exports, "serializeHostActionReport", { enumerable: true, get: function () { return host_actions_1.serializeHostActionReport; } });
+var retrieval_sessions_1 = require("./retrieval-sessions");
+Object.defineProperty(exports, "RETRIEVAL_MAX_CYCLES", { enumerable: true, get: function () { return retrieval_sessions_1.RETRIEVAL_MAX_CYCLES; } });
+Object.defineProperty(exports, "isRetrievalSessionState", { enumerable: true, get: function () { return retrieval_sessions_1.isRetrievalSessionState; } });
 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/retrieval-sessions.d.ts

@@ -0,0 +1,74 @@
+export declare const RETRIEVAL_MAX_CYCLES: 3;
+export type RetrievalSessionState = 'open' | 'satisfied' | 'exhausted' | 'expired';
+export type RetrievalGapKind = 'target' | 'caller' | 'route' | 'resource' | 'test' | 'configuration' | 'symbol_ambiguity' | 'memory_applicability' | 'knowledge_version' | 'runtime_evidence' | 'unavailable_channel';
+export interface RetrievalGapRecord {
+    kind: RetrievalGapKind;
+    target?: string;
+    reason: string;
+    evidence: string[];
+    resolver: 'codegraph' | 'memory' | 'knowledge' | 'analyzer' | 'none';
+    priority: number;
+}
+export interface RetrievalCycleRecord {
+    retrievalSessionId: string;
+    cycle: number;
+    gaps: RetrievalGapRecord[];
+    selectedIds: string[];
+    rejectedIds: string[];
+    tokenCost: number;
+    remainingTokenBudget: number;
+    quality: Record<string, unknown>;
+    receipt: string;
+    evidenceHash: string;
+    createdAt: number;
+}
+export interface RetrievalSessionRecord {
+    id: string;
+    requestId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    query: string;
+    intent: string;
+    state: RetrievalSessionState;
+    cycle: number;
+    maxCycles: typeof RETRIEVAL_MAX_CYCLES;
+    initialTokenBudget: number;
+    remainingTokenBudget: number;
+    baselineReceipt: string;
+    finalReceipt?: string;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+}
+export interface CreateRetrievalSessionInput {
+    id?: string;
+    requestId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    query: string;
+    intent: string;
+    tokenBudget: number;
+    baselineReceipt: string;
+    expiresAt: number;
+}
+export interface AppendRetrievalCycleInput {
+    retrievalSessionId: string;
+    projectRoot: string;
+    sessionId: string;
+    baselineReceipt: string;
+    cycle: number;
+    gaps: RetrievalGapRecord[];
+    selectedIds: string[];
+    rejectedIds: string[];
+    tokenCost: number;
+    remainingTokenBudget: number;
+    quality: Record<string, unknown>;
+    receipt: string;
+    evidenceHash: string;
+}
+export declare function mapRetrievalSessionRow(row: Record<string, unknown>): RetrievalSessionRecord;
+export declare function mapRetrievalCycleRow(row: Record<string, unknown>): RetrievalCycleRecord;
+export declare function serializeRetrievalJson(value: unknown): string;
+export declare function isRetrievalSessionState(value: unknown): value is RetrievalSessionState;

package/dist/retrieval-sessions.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETRIEVAL_MAX_CYCLES = void 0;
+exports.mapRetrievalSessionRow = mapRetrievalSessionRow;
+exports.mapRetrievalCycleRow = mapRetrievalCycleRow;
+exports.serializeRetrievalJson = serializeRetrievalJson;
+exports.isRetrievalSessionState = isRetrievalSessionState;
+exports.RETRIEVAL_MAX_CYCLES = 3;
+function mapRetrievalSessionRow(row) {
+    const state = requiredString(row.state, 'state');
+    if (!isRetrievalSessionState(state)) {
+        throw new Error(`Invalid persisted retrieval session state: ${state}`);
+    }
+    const maxCycles = finiteInteger(row.max_cycles, 'max_cycles');
+    if (maxCycles !== exports.RETRIEVAL_MAX_CYCLES) {
+        throw new Error(`Invalid persisted retrieval max_cycles: ${maxCycles}`);
+    }
+    return {
+        id: requiredString(row.id, 'id'),
+        requestId: requiredString(row.request_id, 'request_id'),
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        executionId: optionalString(row.execution_id),
+        query: requiredString(row.query, 'query'),
+        intent: requiredString(row.intent, 'intent'),
+        state,
+        cycle: finiteInteger(row.cycle, 'cycle'),
+        maxCycles: exports.RETRIEVAL_MAX_CYCLES,
+        initialTokenBudget: finiteInteger(row.initial_token_budget, 'initial_token_budget'),
+        remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
+        baselineReceipt: requiredString(row.baseline_receipt, 'baseline_receipt'),
+        finalReceipt: optionalString(row.final_receipt),
+        createdAt: finiteInteger(row.created_at, 'created_at'),
+        updatedAt: finiteInteger(row.updated_at, 'updated_at'),
+        expiresAt: finiteInteger(row.expires_at, 'expires_at'),
+    };
+}
+function mapRetrievalCycleRow(row) {
+    return {
+        retrievalSessionId: requiredString(row.retrieval_session_id, 'retrieval_session_id'),
+        cycle: finiteInteger(row.cycle, 'cycle'),
+        gaps: parseJsonArray(row.gaps_json, 'gaps_json'),
+        selectedIds: parseStringArray(row.selected_ids, 'selected_ids'),
+        rejectedIds: parseStringArray(row.rejected_ids, 'rejected_ids'),
+        tokenCost: finiteInteger(row.token_cost, 'token_cost'),
+        remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
+        quality: parseJsonObject(row.quality_json, 'quality_json'),
+        receipt: requiredString(row.receipt, 'receipt'),
+        evidenceHash: requiredString(row.evidence_hash, 'evidence_hash'),
+        createdAt: finiteInteger(row.created_at, 'created_at'),
+    };
+}
+function serializeRetrievalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function isRetrievalSessionState(value) {
+    return value === 'open' || value === 'satisfied' || value === 'exhausted' || value === 'expired';
+}
+function canonicalize(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || Object.is(value, -0))
+            throw new Error('Retrieval evidence must be lossless JSON');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('Retrieval evidence must be plain JSON');
+    }
+    const record = value;
+    return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalize(record[key])]));
+}
+function parseJson(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`Invalid persisted ${field}: expected JSON text`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`Invalid persisted ${field}: malformed JSON`);
+    }
+}
+function parseJsonArray(value, field) {
+    const parsed = parseJson(value, field);
+    if (!Array.isArray(parsed))
+        throw new Error(`Invalid persisted ${field}: expected array`);
+    return parsed;
+}
+function parseStringArray(value, field) {
+    const parsed = parseJsonArray(value, field);
+    if (parsed.some(item => typeof item !== 'string'))
+        throw new Error(`Invalid persisted ${field}: expected strings`);
+    return parsed;
+}
+function parseJsonObject(value, field) {
+    const parsed = parseJson(value, field);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Invalid persisted ${field}: expected object`);
+    }
+    return parsed;
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function finiteInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.19",
+  "version": "0.16.20",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/database.ts

@@ -31,6 +31,17 @@ import {
   type StartHostActionInput,
   type VerifyHostActionInput,
 } from './host-actions';
+import {
+  RETRIEVAL_MAX_CYCLES,
+  mapRetrievalCycleRow,
+  mapRetrievalSessionRow,
+  serializeRetrievalJson,
+  type AppendRetrievalCycleInput,
+  type CreateRetrievalSessionInput,
+  type RetrievalCycleRecord,
+  type RetrievalSessionRecord,
+  type RetrievalSessionState,
+} from './retrieval-sessions';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -477,6 +488,50 @@ export class DevFlowDatabase {
       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_retrieval_sessions (
+        id TEXT PRIMARY KEY,
+        request_id TEXT NOT NULL UNIQUE,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        query TEXT NOT NULL,
+        intent TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'open'
+          CHECK(state IN ('open', 'satisfied', 'exhausted', 'expired')),
+        cycle INTEGER NOT NULL DEFAULT 0 CHECK(cycle BETWEEN 0 AND 3),
+        max_cycles INTEGER NOT NULL DEFAULT 3 CHECK(max_cycles = 3),
+        initial_token_budget INTEGER NOT NULL CHECK(initial_token_budget >= 0),
+        remaining_token_budget INTEGER NOT NULL CHECK(remaining_token_budget >= 0),
+        baseline_receipt TEXT NOT NULL,
+        final_receipt TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_retrieval_sessions_owner
+        ON devflow_retrieval_sessions(project_root, session_id, state, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_retrieval_sessions_expiry
+        ON devflow_retrieval_sessions(state, expires_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_retrieval_cycles (
+        retrieval_session_id TEXT NOT NULL,
+        cycle INTEGER NOT NULL CHECK(cycle BETWEEN 1 AND 3),
+        gaps_json TEXT NOT NULL DEFAULT '[]',
+        selected_ids TEXT NOT NULL DEFAULT '[]',
+        rejected_ids TEXT NOT NULL DEFAULT '[]',
+        token_cost INTEGER NOT NULL CHECK(token_cost >= 0),
+        remaining_token_budget INTEGER NOT NULL CHECK(remaining_token_budget >= 0),
+        quality_json TEXT NOT NULL DEFAULT '{}',
+        receipt TEXT NOT NULL,
+        evidence_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (retrieval_session_id, cycle)
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_retrieval_cycles_receipt
+        ON devflow_retrieval_cycles(receipt);
+
       CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -2677,6 +2732,207 @@ export class DevFlowDatabase {
       .run(projectRoot).changes > 0;
   }
 
+  createRetrievalSession(input: CreateRetrievalSessionInput): RetrievalSessionRecord {
+    this.validateRetrievalSessionInput(input);
+    const now = Date.now();
+    const id = input.id?.trim() || randomUUID();
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const existing = this.getRetrievalSessionByRequest(input.requestId);
+      if (existing) {
+        this.assertRetrievalIdentity(existing, input);
+        this.db.exec('COMMIT');
+        return existing;
+      }
+      this.db.prepare(`
+        INSERT INTO devflow_retrieval_sessions
+          (id, request_id, project_root, session_id, execution_id, query, intent, state,
+           cycle, max_cycles, initial_token_budget, remaining_token_budget,
+           baseline_receipt, created_at, updated_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'open', 0, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        id,
+        input.requestId,
+        input.projectRoot,
+        input.sessionId,
+        input.executionId ?? null,
+        input.query,
+        input.intent,
+        RETRIEVAL_MAX_CYCLES,
+        input.tokenBudget,
+        input.tokenBudget,
+        input.baselineReceipt,
+        now,
+        now,
+        input.expiresAt,
+      );
+      const created = this.getRetrievalSession(input.projectRoot, input.sessionId, id)!;
+      this.db.exec('COMMIT');
+      return created;
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  getRetrievalSession(projectRoot: string, sessionId: string, id: string): RetrievalSessionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_retrieval_sessions
+      WHERE id = ? AND project_root = ? AND session_id = ?
+    `).get(id, projectRoot, sessionId) as Record<string, unknown> | undefined;
+    return row ? mapRetrievalSessionRow(row) : null;
+  }
+
+  getRetrievalSessionByRequest(requestId: string): RetrievalSessionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_retrieval_sessions WHERE request_id = ?
+    `).get(requestId) as Record<string, unknown> | undefined;
+    return row ? mapRetrievalSessionRow(row) : null;
+  }
+
+  listRetrievalCycles(retrievalSessionId: string): RetrievalCycleRecord[] {
+    return (this.db.prepare(`
+      SELECT * FROM devflow_retrieval_cycles
+      WHERE retrieval_session_id = ? ORDER BY cycle ASC
+    `).all(retrievalSessionId) as Array<Record<string, unknown>>).map(mapRetrievalCycleRow);
+  }
+
+  appendRetrievalCycle(input: AppendRetrievalCycleInput): RetrievalCycleRecord {
+    if (!Number.isInteger(input.cycle) || input.cycle < 1 || input.cycle > RETRIEVAL_MAX_CYCLES) {
+      throw new Error(`RETRIEVAL_INVALID_CYCLE:${input.cycle}`);
+    }
+    if (!Number.isSafeInteger(input.tokenCost) || input.tokenCost < 0
+      || !Number.isSafeInteger(input.remainingTokenBudget) || input.remainingTokenBudget < 0) {
+      throw new Error('RETRIEVAL_INVALID_BUDGET');
+    }
+    const gapsJson = serializeRetrievalJson(input.gaps);
+    const selectedJson = serializeRetrievalJson([...new Set(input.selectedIds)]);
+    const rejectedJson = serializeRetrievalJson([...new Set(input.rejectedIds)]);
+    const qualityJson = serializeRetrievalJson(input.quality);
+    const now = Date.now();
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const session = this.getRetrievalSession(input.projectRoot, input.sessionId, input.retrievalSessionId);
+      if (!session) throw new Error(`RETRIEVAL_SESSION_NOT_FOUND:${input.retrievalSessionId}`);
+      if (session.baselineReceipt !== input.baselineReceipt) throw new Error('RETRIEVAL_BASELINE_RECEIPT_MISMATCH');
+
+      const existing = this.db.prepare(`
+        SELECT * FROM devflow_retrieval_cycles WHERE retrieval_session_id = ? AND cycle = ?
+      `).get(input.retrievalSessionId, input.cycle) as Record<string, unknown> | undefined;
+      if (existing) {
+        const cycle = mapRetrievalCycleRow(existing);
+        if (cycle.evidenceHash !== input.evidenceHash || cycle.receipt !== input.receipt
+          || serializeRetrievalJson(cycle.gaps) !== gapsJson
+          || serializeRetrievalJson(cycle.selectedIds) !== selectedJson
+          || serializeRetrievalJson(cycle.rejectedIds) !== rejectedJson
+          || serializeRetrievalJson(cycle.quality) !== qualityJson) {
+          throw new Error(`RETRIEVAL_CYCLE_CONFLICT:${input.cycle}`);
+        }
+        this.db.exec('COMMIT');
+        return cycle;
+      }
+      if (session.state !== 'open') throw new Error(`RETRIEVAL_SESSION_TERMINAL:${session.state}`);
+      if (session.expiresAt <= now) throw new Error('RETRIEVAL_SESSION_EXPIRED');
+      if (input.cycle !== session.cycle + 1) throw new Error(`RETRIEVAL_CYCLE_SEQUENCE:${session.cycle}->${input.cycle}`);
+      if (input.tokenCost > session.remainingTokenBudget
+        || input.remainingTokenBudget !== session.remainingTokenBudget - input.tokenCost) {
+        throw new Error('RETRIEVAL_BUDGET_MISMATCH');
+      }
+
+      this.db.prepare(`
+        INSERT INTO devflow_retrieval_cycles
+          (retrieval_session_id, cycle, gaps_json, selected_ids, rejected_ids, token_cost,
+           remaining_token_budget, quality_json, receipt, evidence_hash, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        input.retrievalSessionId,
+        input.cycle,
+        gapsJson,
+        selectedJson,
+        rejectedJson,
+        input.tokenCost,
+        input.remainingTokenBudget,
+        qualityJson,
+        input.receipt,
+        input.evidenceHash,
+        now,
+      );
+      this.db.prepare(`
+        UPDATE devflow_retrieval_sessions
+        SET cycle = ?, remaining_token_budget = ?, updated_at = ?
+        WHERE id = ? AND project_root = ? AND session_id = ?
+      `).run(input.cycle, input.remainingTokenBudget, now, input.retrievalSessionId, input.projectRoot, input.sessionId);
+      const created = mapRetrievalCycleRow(this.db.prepare(`
+        SELECT * FROM devflow_retrieval_cycles WHERE retrieval_session_id = ? AND cycle = ?
+      `).get(input.retrievalSessionId, input.cycle) as Record<string, unknown>);
+      this.db.exec('COMMIT');
+      return created;
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  finalizeRetrievalSession(input: {
+    id: string;
+    projectRoot: string;
+    sessionId: string;
+    state: Extract<RetrievalSessionState, 'satisfied' | 'exhausted'>;
+    finalReceipt: string;
+  }): RetrievalSessionRecord {
+    const now = Date.now();
+    const current = this.getRetrievalSession(input.projectRoot, input.sessionId, input.id);
+    if (!current) throw new Error(`RETRIEVAL_SESSION_NOT_FOUND:${input.id}`);
+    if (current.state !== 'open') {
+      if (current.state === input.state && current.finalReceipt === input.finalReceipt) return current;
+      throw new Error(`RETRIEVAL_SESSION_TERMINAL:${current.state}`);
+    }
+    this.db.prepare(`
+      UPDATE devflow_retrieval_sessions SET state = ?, final_receipt = ?, updated_at = ?
+      WHERE id = ? AND project_root = ? AND session_id = ? AND state = 'open'
+    `).run(input.state, input.finalReceipt, now, input.id, input.projectRoot, input.sessionId);
+    return this.getRetrievalSession(input.projectRoot, input.sessionId, input.id)!;
+  }
+
+  expireRetrievalSessions(now = Date.now(), limit = 100): number {
+    const rows = this.db.prepare(`
+      SELECT id FROM devflow_retrieval_sessions
+      WHERE state = 'open' AND expires_at <= ? ORDER BY expires_at ASC LIMIT ?
+    `).all(now, Math.max(1, Math.min(1000, Math.floor(limit)))) as Array<{ id: string }>;
+    if (rows.length === 0) return 0;
+    const placeholders = rows.map(() => '?').join(',');
+    return this.db.prepare(`
+      UPDATE devflow_retrieval_sessions SET state = 'expired', updated_at = ?
+      WHERE state = 'open' AND id IN (${placeholders})
+    `).run(now, ...rows.map(row => row.id)).changes;
+  }
+
+  private validateRetrievalSessionInput(input: CreateRetrievalSessionInput): void {
+    for (const [field, value] of Object.entries({
+      requestId: input.requestId,
+      projectRoot: input.projectRoot,
+      sessionId: input.sessionId,
+      query: input.query,
+      intent: input.intent,
+      baselineReceipt: input.baselineReceipt,
+    })) {
+      if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`RETRIEVAL_INVALID_${field}`);
+    }
+    if (!Number.isSafeInteger(input.tokenBudget) || input.tokenBudget < 0) throw new Error('RETRIEVAL_INVALID_BUDGET');
+    if (!Number.isSafeInteger(input.expiresAt) || input.expiresAt <= Date.now()) throw new Error('RETRIEVAL_INVALID_EXPIRY');
+  }
+
+  private assertRetrievalIdentity(existing: RetrievalSessionRecord, input: CreateRetrievalSessionInput): void {
+    const matches = existing.projectRoot === input.projectRoot
+      && existing.sessionId === input.sessionId
+      && existing.executionId === input.executionId
+      && existing.query === input.query
+      && existing.intent === input.intent
+      && existing.initialTokenBudget === input.tokenBudget
+      && existing.baselineReceipt === input.baselineReceipt;
+    if (!matches) throw new Error(`RETRIEVAL_REQUEST_CONFLICT:${input.requestId}`);
+  }
+
   upsertContextReceipt(receipt: ContextReceiptRecord): void {
     this.db.prepare(`
       INSERT INTO devflow_context_receipts
@@ -3335,6 +3591,16 @@ export class DevFlowDatabase {
     return rows.map(mapHostActionRow);
   }
 
+  listHostActionsForSession(projectRoot: string, sessionId: string, executionId?: string): HostActionRecord[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_host_actions
+      WHERE project_root = ? AND session_id = ?
+        AND (? IS NULL OR execution_id = ?)
+      ORDER BY created_at ASC, action_id ASC
+    `).all(projectRoot, sessionId, executionId ?? null, executionId ?? null) as Array<Record<string, unknown>>;
+    return rows.map(mapHostActionRow);
+  }
+
   private transitionHostAction(
     identity: StartHostActionInput,
     targetState: Exclude<HostActionState, 'waiting'>,

package/src/index.ts

@@ -36,6 +36,16 @@ export {
   mapHostActionRow,
   serializeHostActionReport,
 } from './host-actions';
+export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessions';
+export type {
+  AppendRetrievalCycleInput,
+  CreateRetrievalSessionInput,
+  RetrievalCycleRecord,
+  RetrievalGapKind,
+  RetrievalGapRecord,
+  RetrievalSessionRecord,
+  RetrievalSessionState,
+} from './retrieval-sessions';
 export type {
   FailHostActionInput,
   HostActionRecord,

package/src/retrieval-sessions.ts

@@ -0,0 +1,196 @@
+export const RETRIEVAL_MAX_CYCLES = 3 as const;
+
+export type RetrievalSessionState = 'open' | 'satisfied' | 'exhausted' | 'expired';
+
+export type RetrievalGapKind =
+  | 'target'
+  | 'caller'
+  | 'route'
+  | 'resource'
+  | 'test'
+  | 'configuration'
+  | 'symbol_ambiguity'
+  | 'memory_applicability'
+  | 'knowledge_version'
+  | 'runtime_evidence'
+  | 'unavailable_channel';
+
+export interface RetrievalGapRecord {
+  kind: RetrievalGapKind;
+  target?: string;
+  reason: string;
+  evidence: string[];
+  resolver: 'codegraph' | 'memory' | 'knowledge' | 'analyzer' | 'none';
+  priority: number;
+}
+
+export interface RetrievalCycleRecord {
+  retrievalSessionId: string;
+  cycle: number;
+  gaps: RetrievalGapRecord[];
+  selectedIds: string[];
+  rejectedIds: string[];
+  tokenCost: number;
+  remainingTokenBudget: number;
+  quality: Record<string, unknown>;
+  receipt: string;
+  evidenceHash: string;
+  createdAt: number;
+}
+
+export interface RetrievalSessionRecord {
+  id: string;
+  requestId: string;
+  projectRoot: string;
+  sessionId: string;
+  executionId?: string;
+  query: string;
+  intent: string;
+  state: RetrievalSessionState;
+  cycle: number;
+  maxCycles: typeof RETRIEVAL_MAX_CYCLES;
+  initialTokenBudget: number;
+  remainingTokenBudget: number;
+  baselineReceipt: string;
+  finalReceipt?: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+}
+
+export interface CreateRetrievalSessionInput {
+  id?: string;
+  requestId: string;
+  projectRoot: string;
+  sessionId: string;
+  executionId?: string;
+  query: string;
+  intent: string;
+  tokenBudget: number;
+  baselineReceipt: string;
+  expiresAt: number;
+}
+
+export interface AppendRetrievalCycleInput {
+  retrievalSessionId: string;
+  projectRoot: string;
+  sessionId: string;
+  baselineReceipt: string;
+  cycle: number;
+  gaps: RetrievalGapRecord[];
+  selectedIds: string[];
+  rejectedIds: string[];
+  tokenCost: number;
+  remainingTokenBudget: number;
+  quality: Record<string, unknown>;
+  receipt: string;
+  evidenceHash: string;
+}
+
+export function mapRetrievalSessionRow(row: Record<string, unknown>): RetrievalSessionRecord {
+  const state = requiredString(row.state, 'state');
+  if (!isRetrievalSessionState(state)) {
+    throw new Error(`Invalid persisted retrieval session state: ${state}`);
+  }
+  const maxCycles = finiteInteger(row.max_cycles, 'max_cycles');
+  if (maxCycles !== RETRIEVAL_MAX_CYCLES) {
+    throw new Error(`Invalid persisted retrieval max_cycles: ${maxCycles}`);
+  }
+  return {
+    id: requiredString(row.id, 'id'),
+    requestId: requiredString(row.request_id, 'request_id'),
+    projectRoot: requiredString(row.project_root, 'project_root'),
+    sessionId: requiredString(row.session_id, 'session_id'),
+    executionId: optionalString(row.execution_id),
+    query: requiredString(row.query, 'query'),
+    intent: requiredString(row.intent, 'intent'),
+    state,
+    cycle: finiteInteger(row.cycle, 'cycle'),
+    maxCycles: RETRIEVAL_MAX_CYCLES,
+    initialTokenBudget: finiteInteger(row.initial_token_budget, 'initial_token_budget'),
+    remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
+    baselineReceipt: requiredString(row.baseline_receipt, 'baseline_receipt'),
+    finalReceipt: optionalString(row.final_receipt),
+    createdAt: finiteInteger(row.created_at, 'created_at'),
+    updatedAt: finiteInteger(row.updated_at, 'updated_at'),
+    expiresAt: finiteInteger(row.expires_at, 'expires_at'),
+  };
+}
+
+export function mapRetrievalCycleRow(row: Record<string, unknown>): RetrievalCycleRecord {
+  return {
+    retrievalSessionId: requiredString(row.retrieval_session_id, 'retrieval_session_id'),
+    cycle: finiteInteger(row.cycle, 'cycle'),
+    gaps: parseJsonArray(row.gaps_json, 'gaps_json') as RetrievalGapRecord[],
+    selectedIds: parseStringArray(row.selected_ids, 'selected_ids'),
+    rejectedIds: parseStringArray(row.rejected_ids, 'rejected_ids'),
+    tokenCost: finiteInteger(row.token_cost, 'token_cost'),
+    remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
+    quality: parseJsonObject(row.quality_json, 'quality_json'),
+    receipt: requiredString(row.receipt, 'receipt'),
+    evidenceHash: requiredString(row.evidence_hash, 'evidence_hash'),
+    createdAt: finiteInteger(row.created_at, 'created_at'),
+  };
+}
+
+export function serializeRetrievalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function isRetrievalSessionState(value: unknown): value is RetrievalSessionState {
+  return value === 'open' || value === 'satisfied' || value === 'exhausted' || value === 'expired';
+}
+
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || Object.is(value, -0)) throw new Error('Retrieval evidence must be lossless JSON');
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new Error('Retrieval evidence must be plain JSON');
+  }
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalize(record[key])]));
+}
+
+function parseJson(value: unknown, field: string): unknown {
+  if (typeof value !== 'string') throw new Error(`Invalid persisted ${field}: expected JSON text`);
+  try { return JSON.parse(value) as unknown; } catch { throw new Error(`Invalid persisted ${field}: malformed JSON`); }
+}
+
+function parseJsonArray(value: unknown, field: string): unknown[] {
+  const parsed = parseJson(value, field);
+  if (!Array.isArray(parsed)) throw new Error(`Invalid persisted ${field}: expected array`);
+  return parsed;
+}
+
+function parseStringArray(value: unknown, field: string): string[] {
+  const parsed = parseJsonArray(value, field);
+  if (parsed.some(item => typeof item !== 'string')) throw new Error(`Invalid persisted ${field}: expected strings`);
+  return parsed as string[];
+}
+
+function parseJsonObject(value: unknown, field: string): Record<string, unknown> {
+  const parsed = parseJson(value, field);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Invalid persisted ${field}: expected object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`Invalid persisted ${field}`);
+  return value;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function finiteInteger(value: unknown, field: string): number {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result < 0) throw new Error(`Invalid persisted ${field}`);
+  return result;
+}