@devflow-tools/database 0.17.1 → 0.17.3

package/src/database.ts

@@ -1,6 +1,6 @@
 import { NodeSqliteDatabase } from './node-sqlite';
 import { join, dirname, resolve } from 'path';
-import { existsSync, mkdirSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, realpathSync, statSync } from 'fs';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
 import type {
@@ -12,6 +12,7 @@ import type {
   WorkItemRecord,
   WorkQueueHealth,
   WorkState,
+  ProjectMutationLeaseRecord,
 } from './work-queue';
 import {
   mapSessionObligationRow,
@@ -84,6 +85,13 @@ import {
   type ToolNameResolutionRecord,
   type TranscriptCheckpointRecord,
 } from './task-semantic-control';
+import {
+  mapTaskRuntimeEventRow,
+  mapTaskRuntimeSnapshotRow,
+  stableTaskRuntimeJson,
+  type TaskRuntimeEventRecord,
+  type TaskRuntimeSnapshotRecord,
+} from './task-runtime';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -305,35 +313,72 @@ export function getGlobalDevFlowDbPath(home = homedir()): string {
 
 export function openGlobalDevFlowDatabase(
   home = homedir(),
-  options?: { busyTimeoutMs?: number },
+  options?: { busyTimeoutMs?: number; readonly?: boolean },
 ): DevFlowDatabase {
   return new DevFlowDatabase(home, {
     dbPath: getGlobalDevFlowDbPath(home),
     busyTimeoutMs: options?.busyTimeoutMs,
+    readonly: options?.readonly,
   });
 }
 
+export function openGlobalDevFlowReadOnlyDatabase(
+  home = homedir(),
+  options?: { busyTimeoutMs?: number },
+): DevFlowDatabase {
+  return openGlobalDevFlowDatabase(home, { ...options, readonly: true });
+}
+
+interface InitializedDatabaseIdentity {
+  dev: number;
+  ino: number;
+}
+
+// Schema setup is process-owned. Hook daemons open short-lived connections for
+// bounded transactions, but replaying the full idempotent DDL on every open is
+// still expensive and serializes concurrent host requests. An inode identity
+// keeps the cache safe when a test, repair, or user replaces the database file.
+const initializedDatabaseFiles = new Map<string, InitializedDatabaseIdentity>();
+
+function getDatabaseIdentity(path: string): InitializedDatabaseIdentity | null {
+  try {
+    const stats = statSync(path);
+    return { dev: stats.dev, ino: stats.ino };
+  } catch {
+    return null;
+  }
+}
+
 export class DevFlowDatabase {
   private db: NodeSqliteDatabase;
 
-  constructor(projectRoot: string, opts?: { dbPath?: string; busyTimeoutMs?: number }) {
+  constructor(projectRoot: string, opts?: { dbPath?: string; busyTimeoutMs?: number; readonly?: boolean }) {
     let dbPath: string;
     if (opts?.dbPath) {
       const dir = dirname(opts.dbPath);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      if (!existsSync(dir) && !opts.readonly) mkdirSync(dir, { recursive: true });
       dbPath = opts.dbPath;
     } else {
       const devflowDir = join(projectRoot, '.devflow');
-      if (!existsSync(devflowDir)) mkdirSync(devflowDir, { recursive: true });
+      if (!existsSync(devflowDir) && !opts?.readonly) mkdirSync(devflowDir, { recursive: true });
       dbPath = join(devflowDir, 'devflow.db');
     }
-    this.db = new NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs);
+    if (opts?.readonly && !existsSync(dbPath)) throw new Error(`DEVFLOW_DATABASE_NOT_FOUND:${dbPath}`);
+    this.db = new NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs, opts?.readonly === true);
 
-    this.db.exec('PRAGMA journal_mode = WAL');
     this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts?.busyTimeoutMs ?? 5000))}`);
+    if (opts?.readonly) return;
     this.db.exec('PRAGMA foreign_keys = OFF');
-
-    this.initializeSchema();
+    const databaseIdentity = getDatabaseIdentity(dbPath);
+    const initializedIdentity = initializedDatabaseFiles.get(dbPath);
+    const schemaInitialized = databaseIdentity !== null
+      && initializedIdentity?.dev === databaseIdentity.dev
+      && initializedIdentity.ino === databaseIdentity.ino;
+    if (!schemaInitialized) {
+      this.initializeSchema();
+      const currentIdentity = getDatabaseIdentity(dbPath);
+      if (currentIdentity) initializedDatabaseFiles.set(dbPath, currentIdentity);
+    }
   }
 
   private initializeSchema() {
@@ -575,6 +620,9 @@ export class DevFlowDatabase {
         source_id TEXT NOT NULL, stage TEXT NOT NULL, rank INTEGER, raw_score REAL,
         normalized_score REAL, final_score REAL, applicability TEXT NOT NULL DEFAULT '[]',
         reason TEXT, tool_evidence TEXT NOT NULL DEFAULT '[]', verification_receipt TEXT,
+        schema_version TEXT NOT NULL DEFAULT 'retrieval-ledger-event.v1', task_spec_hash TEXT,
+        actor TEXT, source_version TEXT, source_content_hash TEXT,
+        evidence_ids TEXT NOT NULL DEFAULT '[]', reason_code TEXT,
         payload TEXT NOT NULL DEFAULT '{}', created_at INTEGER NOT NULL
       );
       CREATE INDEX IF NOT EXISTS idx_retrieval_ledger_identity ON devflow_retrieval_ledger(
@@ -679,6 +727,40 @@ export class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_terminal_transition_turn
         ON devflow_terminal_transitions(project_root, session_id, turn_id, sequence);
 
+      CREATE TABLE IF NOT EXISTS devflow_task_runtime_events (
+        event_id TEXT PRIMARY KEY,
+        schema_version TEXT NOT NULL,
+        producer TEXT NOT NULL,
+        producer_version TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        execution_id TEXT,
+        task_spec_hash TEXT NOT NULL,
+        sequence INTEGER NOT NULL CHECK(sequence > 0),
+        kind TEXT NOT NULL,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, sequence)
+      );
+      CREATE INDEX IF NOT EXISTS idx_task_runtime_event_identity
+        ON devflow_task_runtime_events(project_root, session_id, turn_id, sequence);
+
+      CREATE TABLE IF NOT EXISTS devflow_task_runtime_snapshots (
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        last_event_sequence INTEGER NOT NULL,
+        schema_version TEXT NOT NULL,
+        snapshot_json TEXT NOT NULL,
+        snapshot_hash TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY(project_root, session_id, turn_id)
+      );
+
       CREATE TABLE IF NOT EXISTS devflow_transcript_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -832,9 +914,11 @@ export class DevFlowDatabase {
         project_root TEXT NOT NULL,
         session_id TEXT,
         turn_id TEXT,
+        source_hash TEXT,
+        task_spec_hash TEXT,
         payload TEXT NOT NULL,
         state TEXT NOT NULL DEFAULT 'pending'
-          CHECK(state IN ('pending', 'leased', 'completed', 'failed', 'dead_letter')),
+          CHECK(state IN ('pending', 'leased', 'completed', 'failed', 'dead_letter', 'cancelled')),
         attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts >= 0),
         max_attempts INTEGER NOT NULL DEFAULT 5 CHECK(max_attempts > 0),
         lease_owner TEXT,
@@ -844,7 +928,11 @@ export class DevFlowDatabase {
         error_message TEXT,
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL,
-        completed_at INTEGER
+        completed_at INTEGER,
+        cancelled_at INTEGER,
+        cancellation_reason TEXT,
+        replay_of_id TEXT,
+        replay_count INTEGER NOT NULL DEFAULT 0
       );
 
       CREATE INDEX IF NOT EXISTS idx_work_items_ready
@@ -854,6 +942,16 @@ export class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_work_items_completed
         ON devflow_work_items(project_root, completed_at DESC);
 
+      CREATE TABLE IF NOT EXISTS devflow_project_mutation_leases (
+        project_root TEXT NOT NULL,
+        mutation_kind TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        lease_expires_at INTEGER NOT NULL,
+        source_hash TEXT,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY(project_root, mutation_kind)
+      );
+
       CREATE TABLE IF NOT EXISTS devflow_session_closures (
         session_id TEXT NOT NULL,
         project_root TEXT NOT NULL,
@@ -1125,6 +1223,19 @@ export class DevFlowDatabase {
     try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN action_satisfied_at INTEGER'); } catch {}
     try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN action_degradation_json TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN request_id TEXT'); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_retrieval_ledger ADD COLUMN schema_version TEXT NOT NULL DEFAULT 'retrieval-ledger-event.v1'"); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN task_spec_hash TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN actor TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN source_version TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN source_content_hash TEXT'); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_retrieval_ledger ADD COLUMN evidence_ids TEXT NOT NULL DEFAULT '[]'"); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN reason_code TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN source_hash TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN task_spec_hash TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN cancelled_at INTEGER'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN cancellation_reason TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN replay_of_id TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN replay_count INTEGER NOT NULL DEFAULT 0'); } 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)');
 
@@ -1550,16 +1661,30 @@ export class DevFlowDatabase {
     }));
   }
 
-  getToolCallEventByToolUseId(sessionId: string, toolUseId: string): { eventId: string; timestamp: number; duration: number } | null {
+  getToolCallEventByToolUseId(sessionId: string, toolUseId: string): {
+    eventId: string;
+    executionId: string;
+    timestamp: number;
+    duration: number;
+    input: Record<string, unknown>;
+  } | null {
     const row = this.db.prepare(`
-      SELECT event_id, timestamp, duration
+      SELECT event_id, execution_id, timestamp, duration, input
       FROM tool_call_events
       WHERE session_id = ? AND tool_use_id = ?
       ORDER BY timestamp DESC
       LIMIT 1
-    `).get(sessionId, toolUseId) as { event_id: string; timestamp: number; duration: number } | undefined;
+    `).get(sessionId, toolUseId) as {
+      event_id: string; execution_id: string; timestamp: number; duration: number; input: string | null;
+    } | undefined;
     return row
-      ? { eventId: row.event_id, timestamp: row.timestamp, duration: row.duration ?? 0 }
+      ? {
+          eventId: row.event_id,
+          executionId: row.execution_id,
+          timestamp: row.timestamp,
+          duration: row.duration ?? 0,
+          input: parseJsonObject(row.input) ?? {},
+        }
       : null;
   }
 
@@ -2959,7 +3084,8 @@ export class DevFlowDatabase {
   enqueueWork(input: EnqueueWorkInput): WorkItemRecord {
     if (!input.idempotencyKey.trim()) throw new Error('Work idempotency key is required');
     if (!input.projectRoot.trim()) throw new Error('Work project root is required');
-    const maxAttempts = input.maxAttempts ?? 5;
+    const maxAttempts = input.maxAttempts
+      ?? (input.kind === 'knowledge.ingest' || input.kind === 'knowledge.index_refresh' ? 3 : 5);
     if (!Number.isSafeInteger(maxAttempts) || maxAttempts <= 0) {
       throw new Error('Work maxAttempts must be a positive safe integer');
     }
@@ -2972,10 +3098,10 @@ export class DevFlowDatabase {
 
     const row = this.db.prepare(`
       INSERT INTO devflow_work_items (
-        id, idempotency_key, kind, project_root, session_id, turn_id, payload,
+        id, idempotency_key, kind, project_root, session_id, turn_id, source_hash, task_spec_hash, payload,
         state, attempts, max_attempts, lease_owner, lease_expires_at,
         next_attempt_at, error_category, error_message, created_at, updated_at, completed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL, ?, NULL, NULL, ?, ?, NULL)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL, ?, NULL, NULL, ?, ?, NULL)
       ON CONFLICT(idempotency_key) DO UPDATE SET
         state = CASE
           WHEN devflow_work_items.state = 'dead_letter'
@@ -3016,6 +3142,8 @@ export class DevFlowDatabase {
       input.projectRoot,
       input.sessionId ?? null,
       input.turnId ?? null,
+      input.sourceHash ?? null,
+      input.taskSpecHash ?? null,
       JSON.stringify(input.payload ?? null),
       maxAttempts,
       nextAttemptAt,
@@ -3033,6 +3161,53 @@ export class DevFlowDatabase {
     return row ? this.mapWorkItem(row) : null;
   }
 
+  getWorkById(id: string): WorkItemRecord | null {
+    const row = this.db.prepare('SELECT * FROM devflow_work_items WHERE id = ?').get(id) as any;
+    return row ? this.mapWorkItem(row) : null;
+  }
+
+  acquireProjectMutationLease(input: { projectRoot: string; mutationKind: string; owner: string; leaseMs: number; sourceHash?: string; now?: number }): boolean {
+    const now = input.now ?? Date.now();
+    return this.db.prepare(`
+      INSERT INTO devflow_project_mutation_leases
+        (project_root, mutation_kind, owner, lease_expires_at, source_hash, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, mutation_kind) DO UPDATE SET
+        owner = excluded.owner, lease_expires_at = excluded.lease_expires_at,
+        source_hash = excluded.source_hash, updated_at = excluded.updated_at
+      WHERE devflow_project_mutation_leases.lease_expires_at <= ? OR devflow_project_mutation_leases.owner = excluded.owner
+    `).run(input.projectRoot, input.mutationKind, input.owner, now + input.leaseMs, input.sourceHash ?? null, now, now).changes > 0;
+  }
+
+  releaseProjectMutationLease(projectRoot: string, mutationKind: string, owner: string): boolean {
+    return this.db.prepare('DELETE FROM devflow_project_mutation_leases WHERE project_root = ? AND mutation_kind = ? AND owner = ?')
+      .run(projectRoot, mutationKind, owner).changes > 0;
+  }
+
+  cancelStaleWork(input: { id: string; owner: string; sourceHash?: string; taskSpecHash?: string; reason?: string; now?: number }): boolean {
+    const current = this.getWorkById(input.id);
+    const stale = current && current.state === 'leased' && current.leaseOwner === input.owner
+      && ((input.sourceHash !== undefined && current.sourceHash !== input.sourceHash)
+        || (input.taskSpecHash !== undefined && current.taskSpecHash !== input.taskSpecHash));
+    if (!stale) return false;
+    const now = input.now ?? Date.now();
+    try {
+      return this.db.prepare(`UPDATE devflow_work_items SET state = 'cancelled', lease_owner = NULL, lease_expires_at = NULL, cancelled_at = ?, cancellation_reason = ?, updated_at = ? WHERE id = ? AND state = 'leased' AND lease_owner = ?`)
+        .run(now, input.reason ?? 'stale_source_or_task_spec', now, input.id, input.owner).changes === 1;
+    } catch {
+      return this.db.prepare(`UPDATE devflow_work_items SET state = 'completed', lease_owner = NULL, lease_expires_at = NULL, cancelled_at = ?, cancellation_reason = ?, updated_at = ? WHERE id = ? AND state = 'leased' AND lease_owner = ?`)
+        .run(now, input.reason ?? 'stale_source_or_task_spec', now, input.id, input.owner).changes === 1;
+    }
+  }
+
+  replayDeadLetterWork(id: string, input: { idempotencyKey: string; sourceHash?: string; taskSpecHash?: string; now?: number }): WorkItemRecord | null {
+    const original = this.getWorkById(id);
+    if (!original || original.state !== 'dead_letter') return null;
+    const replay = this.enqueueWork({ idempotencyKey: input.idempotencyKey, kind: original.kind, projectRoot: original.projectRoot, sessionId: original.sessionId, turnId: original.turnId, payload: original.payload, sourceHash: input.sourceHash ?? original.sourceHash, taskSpecHash: input.taskSpecHash ?? original.taskSpecHash, maxAttempts: original.maxAttempts, nextAttemptAt: input.now ?? Date.now() });
+    this.db.prepare('UPDATE devflow_work_items SET replay_of_id = ?, replay_count = replay_count + 1 WHERE id = ?').run(original.id, replay.id);
+    return this.getWorkById(replay.id);
+  }
+
   requestSessionClosure(input: RequestSessionClosureInput): SessionClosureRecord {
     if (!input.sessionId.trim()) throw new Error('Session closure requires a session ID');
     if (!input.projectRoot.trim()) throw new Error('Session closure requires a project root');
@@ -3060,7 +3235,8 @@ export class DevFlowDatabase {
         SELECT COUNT(*) AS count
         FROM devflow_work_items
         WHERE project_root = ? AND session_id = ?
-          AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+          AND state IN ('pending', 'leased', 'failed')
+          AND attempts < max_attempts
       `).get(input.projectRoot, input.sessionId) as { count?: number };
       const pendingWorkCount = Number(pending?.count ?? 0);
       this.db.prepare(`
@@ -3142,6 +3318,7 @@ export class DevFlowDatabase {
       throw new Error('Work leaseMs must be a positive safe integer');
     }
     if (input.kinds?.length === 0) return [];
+    if (input.workItemIds?.length === 0) return [];
 
     const now = input.now ?? Date.now();
     const leaseExpiresAt = now + input.leaseMs;
@@ -3150,9 +3327,13 @@ export class DevFlowDatabase {
     }
     const limit = Math.min(Math.floor(input.limit), 1_000);
     const kinds = input.kinds ? [...new Set(input.kinds)] : undefined;
+    const workItemIds = input.workItemIds ? [...new Set(input.workItemIds)] : undefined;
     const kindClause = kinds
       ? `AND kind IN (${kinds.map(() => '?').join(', ')})`
       : '';
+    const workItemClause = workItemIds
+      ? `AND id IN (${workItemIds.map(() => '?').join(', ')})`
+      : '';
 
     this.db.exec('BEGIN IMMEDIATE');
     try {
@@ -3166,9 +3347,10 @@ export class DevFlowDatabase {
           AND next_attempt_at <= ?
           AND attempts < max_attempts
           ${kindClause}
+          ${workItemClause}
         ORDER BY next_attempt_at ASC, created_at ASC, id ASC
         LIMIT ?
-      `).all(input.projectRoot, now, ...(kinds ?? []), limit) as Array<{
+      `).all(input.projectRoot, now, ...(kinds ?? []), ...(workItemIds ?? []), limit) as Array<{
         id: string;
         state: WorkState;
       }>;
@@ -3329,8 +3511,10 @@ export class DevFlowDatabase {
       projectRoot: row.project_root,
       sessionId: row.session_id ?? undefined,
       turnId: row.turn_id ?? undefined,
+      sourceHash: row.source_hash ?? undefined,
+      taskSpecHash: row.task_spec_hash ?? undefined,
       payload: parseJson(row.payload),
-      state: row.state,
+      state: row.cancelled_at != null ? 'cancelled' : row.state,
       attempts: Number(row.attempts),
       maxAttempts: Number(row.max_attempts),
       leaseOwner: row.lease_owner ?? undefined,
@@ -3341,6 +3525,10 @@ export class DevFlowDatabase {
       createdAt: Number(row.created_at),
       updatedAt: Number(row.updated_at),
       completedAt: row.completed_at == null ? undefined : Number(row.completed_at),
+      cancelledAt: row.cancelled_at == null ? undefined : Number(row.cancelled_at),
+      cancellationReason: row.cancellation_reason ?? undefined,
+      replayOfId: row.replay_of_id ?? undefined,
+      replayCount: Number(row.replay_count ?? 0),
     };
   }
 
@@ -3378,7 +3566,8 @@ export class DevFlowDatabase {
       SELECT COUNT(*) AS count
       FROM devflow_work_items
       WHERE project_root = ? AND session_id = ?
-        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND state IN ('pending', 'leased', 'failed')
+        AND attempts < max_attempts
         AND (? IS NULL OR id <> ?)
     `).get(
       projectRoot,
@@ -3386,25 +3575,7 @@ export class DevFlowDatabase {
       excludingWorkItemId ?? null,
       excludingWorkItemId ?? null,
     ) as { count?: number };
-    const obligations = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_session_obligations
-      WHERE project_root = ? AND session_id = ?
-        AND state IN ('open', 'degraded')
-    `).get(projectRoot, sessionId) as { count?: number };
-    const legacyTurns = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_memory_turns t
-      WHERE t.project_root = ? AND t.session_id = ? AND t.status = 'pending'
-        AND NOT EXISTS (
-          SELECT 1 FROM devflow_session_obligations o
-          WHERE o.project_root = t.project_root AND o.session_id = t.session_id
-            AND o.obligation_id = 'memory:' || t.turn_id
-        )
-    `).get(projectRoot, sessionId) as { count?: number };
-    return Number(work?.count ?? 0)
-      + Number(obligations?.count ?? 0)
-      + Number(legacyTurns?.count ?? 0);
+    return Number(work?.count ?? 0);
   }
 
   // ---- Hook Lifecycle ----
@@ -3769,6 +3940,38 @@ export class DevFlowDatabase {
     } : null;
   }
 
+  getContextReceiptForRequest(
+    projectRoot: string,
+    sessionId: string,
+    requestId: string,
+  ): ContextReceiptRecord | null {
+    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, canonical_action_json,
+             action_attempts, action_satisfied_at, action_degradation_json, request_id
+      FROM devflow_context_receipts
+      WHERE project_root = ? AND session_id = ? AND request_id = ?
+      ORDER BY issued_at DESC
+      LIMIT 1
+    `).get(projectRoot, sessionId, requestId) as any;
+    return row ? {
+      projectRoot: row.project_root,
+      sessionId: row.session_id,
+      executionId: row.execution_id,
+      contextHash: row.context_hash,
+      issuedAt: row.issued_at,
+      expiresAt: row.expires_at,
+      selectedFiles: parseJsonStringArray(row.selected_files),
+      memoryIds: parseJsonStringArray(row.memory_ids),
+      canonicalNextAction: row.canonical_next_action ?? undefined,
+      canonicalAction: parseJsonObject(row.canonical_action_json),
+      actionAttempts: parseJsonArray(row.action_attempts),
+      actionSatisfiedAt: row.action_satisfied_at ?? undefined,
+      actionDegradation: parseJsonObject(row.action_degradation_json),
+      requestId: row.request_id ?? undefined,
+    } : null;
+  }
+
   recordContextSelectionEvent(event: ContextSelectionEventRecord): boolean {
     return this.db.prepare(`
       INSERT OR IGNORE INTO devflow_context_selection_events
@@ -3801,7 +4004,8 @@ export class DevFlowDatabase {
         id, project_root, session_id, execution_id, turn_id, request_id, context_receipt,
         source_type, source_id, stage, rank, raw_score, normalized_score, final_score,
         applicability, reason, tool_evidence, verification_receipt, payload, created_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        , schema_version, task_spec_hash, actor, source_version, source_content_hash, evidence_ids, reason_code
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       event.id, event.projectRoot, event.sessionId, event.executionId ?? null, event.turnId ?? null,
       event.requestId, event.contextReceipt, event.sourceType, event.sourceId, event.stage,
@@ -3809,6 +4013,9 @@ export class DevFlowDatabase {
       event.finalScore ?? null, JSON.stringify(event.applicability), event.reason ?? null,
       JSON.stringify(event.toolEvidence), event.verificationReceipt ?? null,
       JSON.stringify(event.payload), event.createdAt,
+      event.schemaVersion ?? 'retrieval-ledger-event.v1', event.taskSpecHash ?? null,
+      event.actor ?? null, event.sourceVersion ?? null, event.sourceContentHash ?? null,
+      JSON.stringify(event.evidenceIds ?? []), event.reasonCode ?? null,
     ).changes > 0;
   }
 
@@ -4044,6 +4251,123 @@ export class DevFlowDatabase {
     return this.getTerminalTransition(record.receiptId)!;
   }
 
+  appendTaskRuntimeEvent(event: TaskRuntimeEventRecord): TaskRuntimeEventRecord {
+    const existing = this.getTaskRuntimeEvent(event.eventId);
+    if (existing) {
+      if (stableTaskRuntimeJson(existing) !== stableTaskRuntimeJson(event)) {
+        throw new Error(`TASK_RUNTIME_EVENT_CONFLICT:${event.eventId}`);
+      }
+      return existing;
+    }
+    const atSequence = this.db.prepare(`
+      SELECT event_id FROM devflow_task_runtime_events
+      WHERE project_root = ? AND session_id = ? AND turn_id = ? AND sequence = ?
+    `).get(event.identity.projectRoot, event.identity.sessionId, event.identity.turnId, event.sequence) as
+      { event_id?: string } | undefined;
+    if (atSequence) throw new Error(`TASK_RUNTIME_SEQUENCE_CONFLICT:${event.sequence}`);
+    try {
+      this.db.prepare(`
+        INSERT INTO devflow_task_runtime_events (
+          event_id, schema_version, producer, producer_version, project_root, project_id,
+          host_id, session_id, turn_id, request_id, execution_id, task_spec_hash,
+          sequence, kind, payload_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        event.eventId, event.schemaVersion, event.producer, event.producerVersion,
+        event.identity.projectRoot, event.identity.projectId, event.identity.hostId,
+        event.identity.sessionId, event.identity.turnId, event.identity.requestId,
+        event.identity.executionId ?? null, event.taskSpecHash, event.sequence,
+        event.kind, stableTaskRuntimeJson(event.payload), event.createdAt,
+      );
+    } catch (error) {
+      const concurrentEvent = this.getTaskRuntimeEvent(event.eventId);
+      if (concurrentEvent) {
+        if (stableTaskRuntimeJson(concurrentEvent) === stableTaskRuntimeJson(event)) return concurrentEvent;
+        throw new Error(`TASK_RUNTIME_EVENT_CONFLICT:${event.eventId}`);
+      }
+      const concurrentSequence = this.db.prepare(`
+        SELECT event_id FROM devflow_task_runtime_events
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND sequence = ?
+      `).get(event.identity.projectRoot, event.identity.sessionId, event.identity.turnId, event.sequence);
+      if (concurrentSequence) throw new Error(`TASK_RUNTIME_SEQUENCE_CONFLICT:${event.sequence}`);
+      throw error;
+    }
+    return this.getTaskRuntimeEvent(event.eventId)!;
+  }
+
+  getTaskRuntimeEvent(eventId: string): TaskRuntimeEventRecord | null {
+    const row = this.db.prepare('SELECT * FROM devflow_task_runtime_events WHERE event_id = ?')
+      .get(eventId) as Record<string, unknown> | undefined;
+    return row ? mapTaskRuntimeEventRow(row) : null;
+  }
+
+  listTaskRuntimeEvents(projectRoot: string, sessionId: string, turnId: string): TaskRuntimeEventRecord[] {
+    return (this.db.prepare(`
+      SELECT * FROM devflow_task_runtime_events
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY sequence ASC
+    `).all(projectRoot, sessionId, turnId) as Array<Record<string, unknown>>)
+      .map(mapTaskRuntimeEventRow);
+  }
+
+  putTaskRuntimeSnapshot(snapshot: TaskRuntimeSnapshotRecord): TaskRuntimeSnapshotRecord {
+    const current = this.getTaskRuntimeSnapshot(
+      snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId,
+    );
+    if (current && current.lastEventSequence > snapshot.lastEventSequence) {
+      throw new Error('TASK_RUNTIME_SNAPSHOT_REGRESSION');
+    }
+    this.db.prepare(`
+      INSERT INTO devflow_task_runtime_snapshots (
+        project_root, session_id, turn_id, last_event_sequence, schema_version,
+        snapshot_json, snapshot_hash, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, session_id, turn_id) DO UPDATE SET
+        last_event_sequence = excluded.last_event_sequence,
+        schema_version = excluded.schema_version,
+        snapshot_json = excluded.snapshot_json,
+        snapshot_hash = excluded.snapshot_hash,
+        updated_at = excluded.updated_at
+      WHERE excluded.last_event_sequence >= devflow_task_runtime_snapshots.last_event_sequence
+    `).run(
+      snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId,
+      snapshot.lastEventSequence, snapshot.schemaVersion, stableTaskRuntimeJson(snapshot),
+      snapshot.snapshotHash, snapshot.updatedAt,
+    );
+    return this.getTaskRuntimeSnapshot(
+      snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId,
+    )!;
+  }
+
+  appendTaskRuntimeEventAndSnapshot(
+    event: TaskRuntimeEventRecord,
+    snapshot: TaskRuntimeSnapshotRecord,
+  ): TaskRuntimeSnapshotRecord {
+    return this.db.transaction(() => {
+      this.appendTaskRuntimeEvent(event);
+      return this.putTaskRuntimeSnapshot(snapshot);
+    });
+  }
+
+  getTaskRuntimeSnapshot(
+    projectRoot: string,
+    sessionId: string,
+    turnId: string,
+  ): TaskRuntimeSnapshotRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_task_runtime_snapshots
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+    `).get(projectRoot, sessionId, turnId) as Record<string, unknown> | undefined;
+    return row ? mapTaskRuntimeSnapshotRow(row) : null;
+  }
+
+  deleteTaskRuntimeSnapshot(projectRoot: string, sessionId: string, turnId: string): boolean {
+    return this.db.prepare(`
+      DELETE FROM devflow_task_runtime_snapshots
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+    `).run(projectRoot, sessionId, turnId).changes > 0;
+  }
+
   getTerminalTransition(receiptId: string): TerminalTransitionRecord | null {
     const row = this.db.prepare(`
       SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
@@ -4115,7 +4439,11 @@ export class DevFlowDatabase {
         id: row.id, projectRoot: row.project_root, sessionId: row.session_id,
         executionId: row.execution_id ?? undefined, turnId: row.turn_id ?? undefined,
         requestId: row.request_id, contextReceipt: row.context_receipt,
-        sourceType: row.source_type, sourceId: row.source_id, stage: row.stage,
+        schemaVersion: row.schema_version ?? 'retrieval-ledger-event.v1',
+        sourceType: row.source_type, sourceId: row.source_id, stage: row.stage === 'adopted' ? 'consumed' : row.stage,
+        taskSpecHash: row.task_spec_hash ?? undefined, actor: row.actor ?? undefined,
+        sourceVersion: row.source_version ?? undefined, sourceContentHash: row.source_content_hash ?? undefined,
+        evidenceIds: parseJsonStringArray(row.evidence_ids), reasonCode: row.reason_code ?? undefined,
         rank: row.rank ?? undefined, rawScore: row.raw_score ?? undefined,
         normalizedScore: row.normalized_score ?? undefined, finalScore: row.final_score ?? undefined,
         applicability: parseJsonStringArray(row.applicability), reason: row.reason ?? undefined,
@@ -4330,6 +4658,23 @@ export class DevFlowDatabase {
       );
       if (!existing) throw new Error(`Session obligation ${input.obligationId} does not exist`);
       if (existing.state !== 'open') {
+        if (existing.state === 'degraded' && input.state === 'satisfied' && input.receiptId) {
+          const resolvedAt = input.resolvedAt ?? Date.now();
+          this.db.prepare(`
+            UPDATE devflow_session_obligations
+            SET state = 'satisfied', receipt_id = ?, reason = ?, resolved_at = ?, updated_at = ?
+            WHERE project_root = ? AND session_id = ? AND obligation_id = ? AND state = 'degraded'
+          `).run(
+            input.receiptId,
+            input.reason ?? 'superseded_by_corrected_evidence',
+            resolvedAt,
+            resolvedAt,
+            input.projectRoot,
+            input.sessionId,
+            input.obligationId,
+          );
+          return this.getSessionObligation(input.projectRoot, input.sessionId, input.obligationId)!;
+        }
         const sameResolution = existing.state === input.state
           && (input.receiptId === undefined || existing.receiptId === input.receiptId);
         if (sameResolution) return existing;
@@ -4417,20 +4762,44 @@ export class DevFlowDatabase {
     return turn;
   }
 
+  updateCommittedMemoryTurnProjection(input: {
+    turnId: string;
+    memoryIds: string[];
+    reason?: string;
+  }): MemoryTurnRecord {
+    const turnId = normalizeTurnId(input.turnId);
+    this.db.prepare(`
+      UPDATE devflow_memory_turns
+      SET memory_ids = ?, reason = COALESCE(?, reason)
+      WHERE turn_id = ? AND status = 'committed' AND source = 'explicit_intent'
+    `).run(
+      JSON.stringify([...new Set(input.memoryIds)]),
+      input.reason ?? null,
+      turnId,
+    );
+    const turn = this.getMemoryTurn(turnId);
+    if (!turn || turn.status !== 'committed') {
+      throw new Error(`Committed explicit memory turn ${turnId} does not exist`);
+    }
+    return turn;
+  }
+
   skipMemoryTurn(input: {
     turnId: string;
     receiptId: string;
     reason: string;
+    source?: string;
     decidedAt?: number;
   }): MemoryTurnRecord {
     const turnId = normalizeTurnId(input.turnId);
     this.db.prepare(`
       UPDATE devflow_memory_turns
-      SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = 'host_skip',
+      SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = ?,
           reason = ?, decided_at = ?
       WHERE turn_id = ? AND status = 'pending'
     `).run(
       input.receiptId,
+      input.source ?? 'host_skip',
       input.reason,
       input.decidedAt ?? Date.now(),
       turnId,