@devflow-tools/database 0.17.0 → 0.17.2

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 {
@@ -70,6 +70,20 @@ import {
   type WorkflowWorkerRecord,
 } from './workflow-workers';
 import type { RetrievalLedgerEventRecord } from './retrieval-ledger';
+import {
+  assertTaskIdentity,
+  mapChannelQueryPlanRow,
+  mapTaskIntentArtifactRow,
+  mapTerminalTransitionRow,
+  mapToolNameResolutionRow,
+  mapTranscriptCheckpointRow,
+  stableSemanticJson,
+  type ChannelQueryPlanRecord,
+  type TaskIntentArtifactRecord,
+  type TerminalTransitionRecord,
+  type ToolNameResolutionRecord,
+  type TranscriptCheckpointRecord,
+} from './task-semantic-control';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -291,35 +305,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() {
@@ -567,6 +618,119 @@ export class DevFlowDatabase {
         project_root, session_id, execution_id, request_id, context_receipt, source_type, source_id, created_at
       );
 
+      CREATE TABLE IF NOT EXISTS devflow_task_intent_artifacts (
+        artifact_hash TEXT PRIMARY KEY,
+        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,
+        version INTEGER NOT NULL CHECK(version > 0),
+        supersedes_hash TEXT,
+        raw_prompt TEXT NOT NULL,
+        normalized_prompt TEXT NOT NULL,
+        command TEXT,
+        slash_args_json TEXT NOT NULL DEFAULT '[]',
+        active_skill TEXT,
+        intent TEXT NOT NULL,
+        action TEXT NOT NULL,
+        entities_json TEXT NOT NULL DEFAULT '[]',
+        target_anchors_json TEXT NOT NULL DEFAULT '[]',
+        policy_constraints_json TEXT NOT NULL DEFAULT '[]',
+        classification_evidence_json TEXT NOT NULL DEFAULT '[]',
+        source_event_ids_json TEXT NOT NULL DEFAULT '[]',
+        source_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, version),
+        UNIQUE(project_root, session_id, request_id, version)
+      );
+      CREATE INDEX IF NOT EXISTS idx_task_intent_active
+        ON devflow_task_intent_artifacts(project_root, session_id, turn_id, version DESC);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_task_intent_source
+        ON devflow_task_intent_artifacts(project_root, session_id, source_hash, version);
+
+      CREATE TABLE IF NOT EXISTS devflow_channel_query_plans (
+        plan_hash TEXT PRIMARY KEY,
+        source_intent_hash 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,
+        code_queries_json TEXT NOT NULL DEFAULT '[]',
+        memory_queries_json TEXT NOT NULL DEFAULT '[]',
+        knowledge_queries_json TEXT NOT NULL DEFAULT '[]',
+        generated_by TEXT NOT NULL
+          CHECK(generated_by IN ('deterministic', 'host_semantic', 'hybrid')),
+        degradation_json TEXT,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, source_intent_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_channel_query_plan_request
+        ON devflow_channel_query_plans(project_root, session_id, request_id, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_tool_name_resolutions (
+        id TEXT PRIMARY KEY,
+        source_hash TEXT NOT NULL UNIQUE,
+        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,
+        requested_name TEXT NOT NULL,
+        canonical_name TEXT,
+        projected_name TEXT,
+        status TEXT NOT NULL CHECK(status IN ('canonical', 'alias', 'unsupported')),
+        attempt INTEGER NOT NULL CHECK(attempt >= 0),
+        capability_mechanism TEXT,
+        reason TEXT,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_tool_resolution_request
+        ON devflow_tool_name_resolutions(project_root, session_id, request_id, created_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_terminal_transitions (
+        receipt_id TEXT PRIMARY KEY,
+        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,
+        sequence INTEGER NOT NULL CHECK(sequence > 0),
+        from_state TEXT,
+        to_state TEXT NOT NULL,
+        source_receipt_id TEXT,
+        reason 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_terminal_transition_turn
+        ON devflow_terminal_transitions(project_root, session_id, turn_id, sequence);
+
+      CREATE TABLE IF NOT EXISTS devflow_transcript_checkpoints (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        source_path TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        byte_offset INTEGER NOT NULL CHECK(byte_offset >= 0),
+        event_count INTEGER NOT NULL CHECK(event_count >= 0),
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, host_id, session_id, source_path, source_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_transcript_checkpoint_latest
+        ON devflow_transcript_checkpoints(project_root, host_id, session_id, source_path, created_at DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_policy_verification_baselines (
         project_root TEXT NOT NULL,
         kind TEXT NOT NULL,
@@ -1423,16 +1587,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;
   }
 
@@ -2933,7 +3111,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(`
@@ -3015,6 +3194,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;
@@ -3023,9 +3203,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 {
@@ -3039,9 +3223,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;
       }>;
@@ -3251,7 +3436,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,
@@ -3259,25 +3445,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 ----
@@ -3685,6 +3853,293 @@ export class DevFlowDatabase {
     ).changes > 0;
   }
 
+  appendTaskIntentArtifact(record: TaskIntentArtifactRecord): TaskIntentArtifactRecord {
+    assertTaskIdentity(record);
+    if (!Number.isSafeInteger(record.version) || record.version <= 0) {
+      throw new Error('TASK_INTENT_INVALID_VERSION');
+    }
+    const existingByHash = this.getTaskIntentArtifact(record.artifactHash);
+    if (existingByHash) {
+      if (stableSemanticJson(existingByHash) !== stableSemanticJson(record)) {
+        throw new Error(`TASK_INTENT_HASH_CONFLICT:${record.artifactHash}`);
+      }
+      return existingByHash;
+    }
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const conflicting = this.db.prepare(`
+        SELECT * FROM devflow_task_intent_artifacts
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND version = ?
+      `).get(record.projectRoot, record.sessionId, record.turnId, record.version) as Record<string, unknown> | undefined;
+      if (conflicting) throw new Error(`TASK_INTENT_VERSION_CONFLICT:${record.turnId}:${record.version}`);
+      if (record.supersedesHash && !this.getTaskIntentArtifact(record.supersedesHash)) {
+        throw new Error(`TASK_INTENT_SUPERSEDED_NOT_FOUND:${record.supersedesHash}`);
+      }
+      this.db.prepare(`
+        INSERT INTO devflow_task_intent_artifacts (
+          artifact_hash, project_root, project_id, host_id, session_id, turn_id, request_id,
+          execution_id, version, supersedes_hash, raw_prompt, normalized_prompt, command,
+          slash_args_json, active_skill, intent, action, entities_json, target_anchors_json,
+          policy_constraints_json, classification_evidence_json, source_event_ids_json,
+          source_hash, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        record.artifactHash, record.projectRoot, record.projectId, record.hostId,
+        record.sessionId, record.turnId, record.requestId, record.executionId ?? null,
+        record.version, record.supersedesHash ?? null, record.rawPrompt, record.normalizedPrompt,
+        record.command ?? null, stableSemanticJson(record.slashArgs), record.activeSkill ?? null,
+        record.intent, record.action, stableSemanticJson(record.entities),
+        stableSemanticJson(record.targetAnchors), stableSemanticJson(record.policyConstraints),
+        stableSemanticJson(record.classificationEvidence), stableSemanticJson(record.sourceEventIds),
+        record.sourceHash, record.createdAt,
+      );
+      const created = this.getTaskIntentArtifact(record.artifactHash)!;
+      this.db.exec('COMMIT');
+      return created;
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  getTaskIntentArtifact(artifactHash: string): TaskIntentArtifactRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts WHERE artifact_hash = ?
+    `).get(artifactHash) as Record<string, unknown> | undefined;
+    return row ? mapTaskIntentArtifactRow(row) : null;
+  }
+
+  getLatestTaskIntentArtifact(input: {
+    projectRoot: string;
+    sessionId: string;
+    turnId?: string;
+    requestId?: string;
+  }): TaskIntentArtifactRecord | null {
+    if (!input.turnId && !input.requestId) throw new Error('TASK_INTENT_LOOKUP_IDENTITY_REQUIRED');
+    const predicates = ['project_root = ?', 'session_id = ?'];
+    const params: unknown[] = [input.projectRoot, input.sessionId];
+    if (input.turnId) { predicates.push('turn_id = ?'); params.push(input.turnId); }
+    if (input.requestId) { predicates.push('request_id = ?'); params.push(input.requestId); }
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts
+      WHERE ${predicates.join(' AND ')} ORDER BY version DESC, created_at DESC LIMIT 1
+    `).get(...params) as Record<string, unknown> | undefined;
+    return row ? mapTaskIntentArtifactRow(row) : null;
+  }
+
+  getTaskIntentArtifactBySource(input: {
+    projectRoot: string;
+    sessionId: string;
+    sourceHash: string;
+  }): TaskIntentArtifactRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts
+      WHERE project_root = ? AND session_id = ? AND source_hash = ?
+      ORDER BY version DESC, created_at DESC LIMIT 1
+    `).get(input.projectRoot, input.sessionId, input.sourceHash) as Record<string, unknown> | undefined;
+    return row ? mapTaskIntentArtifactRow(row) : null;
+  }
+
+  listLatestTaskIntentArtifacts(projectRoot: string, sessionId: string): TaskIntentArtifactRecord[] {
+    return (this.db.prepare(`
+      SELECT artifact.* FROM devflow_task_intent_artifacts artifact
+      JOIN (
+        SELECT turn_id, MAX(version) AS version
+        FROM devflow_task_intent_artifacts
+        WHERE project_root = ? AND session_id = ? GROUP BY turn_id
+      ) latest ON latest.turn_id = artifact.turn_id AND latest.version = artifact.version
+      WHERE artifact.project_root = ? AND artifact.session_id = ?
+      ORDER BY artifact.created_at ASC, artifact.turn_id ASC
+    `).all(projectRoot, sessionId, projectRoot, sessionId) as Array<Record<string, unknown>>)
+      .map(mapTaskIntentArtifactRow);
+  }
+
+  appendChannelQueryPlan(record: ChannelQueryPlanRecord): ChannelQueryPlanRecord {
+    assertTaskIdentity(record);
+    const source = this.getTaskIntentArtifact(record.sourceIntentHash);
+    if (!source) throw new Error(`QUERY_PLAN_INTENT_NOT_FOUND:${record.sourceIntentHash}`);
+    if (!sameTaskIdentity(source, record)) throw new Error('QUERY_PLAN_IDENTITY_MISMATCH');
+    const existing = this.getChannelQueryPlan(record.planHash);
+    if (existing) {
+      if (stableSemanticJson(existing) !== stableSemanticJson(record)) {
+        throw new Error(`QUERY_PLAN_HASH_CONFLICT:${record.planHash}`);
+      }
+      return existing;
+    }
+    try {
+      this.db.prepare(`
+        INSERT INTO devflow_channel_query_plans (
+          plan_hash, source_intent_hash, project_root, project_id, host_id, session_id,
+          turn_id, request_id, execution_id, code_queries_json, memory_queries_json,
+          knowledge_queries_json, generated_by, degradation_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        record.planHash, record.sourceIntentHash, record.projectRoot, record.projectId,
+        record.hostId, record.sessionId, record.turnId, record.requestId,
+        record.executionId ?? null, stableSemanticJson(record.code),
+        stableSemanticJson(record.memory), stableSemanticJson(record.knowledge),
+        record.generatedBy, record.degradation ? stableSemanticJson(record.degradation) : null,
+        record.createdAt,
+      );
+    } catch (error) {
+      if (String(error).includes('UNIQUE constraint failed')) {
+        throw new Error(`QUERY_PLAN_SOURCE_CONFLICT:${record.sourceIntentHash}`);
+      }
+      throw error;
+    }
+    return this.getChannelQueryPlan(record.planHash)!;
+  }
+
+  getChannelQueryPlan(planHash: string): ChannelQueryPlanRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans WHERE plan_hash = ?
+    `).get(planHash) as Record<string, unknown> | undefined;
+    return row ? mapChannelQueryPlanRow(row) : null;
+  }
+
+  getChannelQueryPlanForIntent(input: {
+    projectRoot: string;
+    sessionId: string;
+    turnId: string;
+    sourceIntentHash: string;
+  }): ChannelQueryPlanRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans
+      WHERE project_root = ? AND session_id = ? AND turn_id = ? AND source_intent_hash = ?
+      ORDER BY created_at DESC LIMIT 1
+    `).get(
+      input.projectRoot,
+      input.sessionId,
+      input.turnId,
+      input.sourceIntentHash,
+    ) as Record<string, unknown> | undefined;
+    return row ? mapChannelQueryPlanRow(row) : null;
+  }
+
+  appendToolNameResolution(record: ToolNameResolutionRecord): boolean {
+    assertTaskIdentity(record);
+    if (!Number.isSafeInteger(record.attempt) || record.attempt < 0) {
+      throw new Error('TOOL_RESOLUTION_INVALID_ATTEMPT');
+    }
+    return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_tool_name_resolutions (
+        id, source_hash, project_root, project_id, host_id, session_id, turn_id,
+        request_id, execution_id, requested_name, canonical_name, projected_name,
+        status, attempt, capability_mechanism, reason, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      record.id, record.sourceHash, record.projectRoot, record.projectId, record.hostId,
+      record.sessionId, record.turnId, record.requestId, record.executionId ?? null,
+      record.requestedName, record.canonicalName ?? null, record.projectedName ?? null,
+      record.status, record.attempt, record.capabilityMechanism ?? null,
+      record.reason ?? null, record.createdAt,
+    ).changes > 0;
+  }
+
+  listToolNameResolutions(input: {
+    projectRoot: string;
+    sessionId: string;
+    requestId?: string;
+  }): ToolNameResolutionRecord[] {
+    const predicates = ['project_root = ?', 'session_id = ?'];
+    const params: unknown[] = [input.projectRoot, input.sessionId];
+    if (input.requestId) { predicates.push('request_id = ?'); params.push(input.requestId); }
+    return (this.db.prepare(`
+      SELECT * FROM devflow_tool_name_resolutions WHERE ${predicates.join(' AND ')}
+      ORDER BY created_at ASC, attempt ASC, id ASC
+    `).all(...params) as Array<Record<string, unknown>>).map(mapToolNameResolutionRow);
+  }
+
+  appendTerminalTransition(record: TerminalTransitionRecord): TerminalTransitionRecord {
+    assertTaskIdentity(record);
+    if (!Number.isSafeInteger(record.sequence) || record.sequence <= 0) {
+      throw new Error('TERMINAL_TRANSITION_INVALID_SEQUENCE');
+    }
+    const existing = this.getTerminalTransition(record.receiptId);
+    if (existing) {
+      if (stableSemanticJson(existing) !== stableSemanticJson(record)) {
+        throw new Error(`TERMINAL_RECEIPT_CONFLICT:${record.receiptId}`);
+      }
+      return existing;
+    }
+    const latest = this.getLatestTerminalTransition(record.projectRoot, record.sessionId, record.turnId);
+    if (record.sequence !== (latest?.sequence ?? 0) + 1) {
+      throw new Error(`TERMINAL_TRANSITION_SEQUENCE:${latest?.sequence ?? 0}->${record.sequence}`);
+    }
+    if ((latest?.toState ?? undefined) !== record.fromState) {
+      throw new Error(`TERMINAL_TRANSITION_FROM_MISMATCH:${record.fromState ?? 'none'}`);
+    }
+    this.db.prepare(`
+      INSERT INTO devflow_terminal_transitions (
+        receipt_id, project_root, project_id, host_id, session_id, turn_id, request_id,
+        execution_id, sequence, from_state, to_state, source_receipt_id, reason,
+        payload_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      record.receiptId, record.projectRoot, record.projectId, record.hostId,
+      record.sessionId, record.turnId, record.requestId, record.executionId ?? null,
+      record.sequence, record.fromState ?? null, record.toState,
+      record.sourceReceiptId ?? null, record.reason, stableSemanticJson(record.payload),
+      record.createdAt,
+    );
+    return this.getTerminalTransition(record.receiptId)!;
+  }
+
+  getTerminalTransition(receiptId: string): TerminalTransitionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
+    `).get(receiptId) as Record<string, unknown> | undefined;
+    return row ? mapTerminalTransitionRow(row) : null;
+  }
+
+  getLatestTerminalTransition(
+    projectRoot: string,
+    sessionId: string,
+    turnId: string,
+  ): TerminalTransitionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY sequence DESC LIMIT 1
+    `).get(projectRoot, sessionId, turnId) as Record<string, unknown> | undefined;
+    return row ? mapTerminalTransitionRow(row) : null;
+  }
+
+  appendTranscriptCheckpoint(record: TranscriptCheckpointRecord): boolean {
+    if (!record.id || !record.projectRoot || !record.hostId || !record.sessionId
+      || !record.sourcePath || !record.sourceHash) {
+      throw new Error('TRANSCRIPT_CHECKPOINT_INVALID_IDENTITY');
+    }
+    if (!Number.isSafeInteger(record.byteOffset) || record.byteOffset < 0
+      || !Number.isSafeInteger(record.eventCount) || record.eventCount < 0) {
+      throw new Error('TRANSCRIPT_CHECKPOINT_INVALID_POSITION');
+    }
+    return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_transcript_checkpoints (
+        id, project_root, host_id, session_id, source_path, source_hash,
+        byte_offset, event_count, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      record.id, record.projectRoot, record.hostId, record.sessionId,
+      record.sourcePath, record.sourceHash, record.byteOffset, record.eventCount,
+      record.createdAt,
+    ).changes > 0;
+  }
+
+  getLatestTranscriptCheckpoint(input: {
+    projectRoot: string;
+    hostId: string;
+    sessionId: string;
+    sourcePath: string;
+  }): TranscriptCheckpointRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_transcript_checkpoints
+      WHERE project_root = ? AND host_id = ? AND session_id = ? AND source_path = ?
+      ORDER BY created_at DESC, byte_offset DESC LIMIT 1
+    `).get(input.projectRoot, input.hostId, input.sessionId, input.sourcePath) as Record<string, unknown> | undefined;
+    return row ? mapTranscriptCheckpointRow(row) : null;
+  }
+
   listRetrievalLedgerEvents(options: {
     projectRoot: string; sessionId?: string; executionId?: string; requestId?: string;
   }): RetrievalLedgerEventRecord[] {
@@ -3916,6 +4371,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;
@@ -4003,6 +4475,28 @@ 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;
@@ -4924,3 +5418,22 @@ function canonicalWorkflowProjectRoot(projectRoot: string): string {
   const resolved = resolve(projectRoot);
   try { return realpathSync(resolved); } catch { return resolved; }
 }
+
+function sameTaskIdentity(
+  left: {
+    projectRoot: string; projectId: string; hostId: string; sessionId: string;
+    turnId: string; requestId: string; executionId?: string;
+  },
+  right: {
+    projectRoot: string; projectId: string; hostId: string; sessionId: string;
+    turnId: string; requestId: string; executionId?: string;
+  },
+): boolean {
+  return left.projectRoot === right.projectRoot
+    && left.projectId === right.projectId
+    && left.hostId === right.hostId
+    && left.sessionId === right.sessionId
+    && left.turnId === right.turnId
+    && left.requestId === right.requestId
+    && left.executionId === right.executionId;
+}