@devflow-tools/database 0.16.18 → 0.16.20

package/src/database.ts

@@ -19,6 +19,29 @@ import {
   type SessionObligationRecord,
   type SessionObligationState,
 } from './obligation-ledger';
+import {
+  hostActionReportsEqual,
+  mapHostActionRow,
+  serializeHostActionReport,
+  type FailHostActionInput,
+  type HostActionRecord,
+  type HostActionState,
+  type ReportHostActionInput,
+  type RequestHostActionInput,
+  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;
@@ -465,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,
@@ -587,6 +654,79 @@ export class DevFlowDatabase {
 
       CREATE INDEX IF NOT EXISTS idx_session_closures_state
         ON devflow_session_closures(project_root, state, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_host_actions (
+        action_id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL,
+        engine_run_id TEXT NOT NULL,
+        step_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT,
+        execution_id TEXT,
+        context_receipt TEXT,
+        state TEXT NOT NULL DEFAULT 'waiting'
+          CHECK(state IN ('waiting', 'running', 'reported', 'verified', 'failed', 'cancelled', 'degraded')),
+        report_json TEXT NOT NULL DEFAULT '{}',
+        evidence_hash TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        finished_at INTEGER,
+        UNIQUE(run_id, step_id),
+        CHECK(
+          (state IN ('verified', 'failed', 'cancelled', 'degraded') AND finished_at IS NOT NULL)
+          OR (state IN ('waiting', 'running', 'reported') AND finished_at IS NULL)
+        )
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_host_actions_project
+        ON devflow_host_actions(project_root, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_host_actions_session
+        ON devflow_host_actions(project_root, session_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_host_actions_run
+        ON devflow_host_actions(project_root, run_id, created_at, action_id);
+      CREATE INDEX IF NOT EXISTS idx_host_actions_action
+        ON devflow_host_actions(action_id);
+
+      CREATE TABLE IF NOT EXISTS devflow_host_action_events (
+        event_id TEXT PRIMARY KEY,
+        action_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        step_id TEXT NOT NULL,
+        from_state TEXT
+          CHECK(from_state IS NULL OR from_state IN ('waiting', 'running', 'reported', 'verified', 'failed', 'cancelled', 'degraded')),
+        to_state TEXT NOT NULL
+          CHECK(to_state IN ('waiting', 'running', 'reported', 'verified', 'failed', 'cancelled', 'degraded')),
+        report_json TEXT NOT NULL DEFAULT '{}',
+        evidence_hash TEXT,
+        created_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_host_action_events_action
+        ON devflow_host_action_events(action_id, created_at, event_id);
+      CREATE INDEX IF NOT EXISTS idx_host_action_events_project_run
+        ON devflow_host_action_events(project_root, run_id, created_at, event_id);
+
+      CREATE TRIGGER IF NOT EXISTS prevent_host_action_event_replace
+      BEFORE INSERT ON devflow_host_action_events
+      WHEN EXISTS (
+        SELECT 1 FROM devflow_host_action_events WHERE event_id = NEW.event_id
+      )
+      BEGIN
+        SELECT RAISE(ABORT, 'devflow_host_action_events is append-only');
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS prevent_host_action_event_update
+      BEFORE UPDATE ON devflow_host_action_events
+      BEGIN
+        SELECT RAISE(ABORT, 'devflow_host_action_events is append-only');
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS prevent_host_action_event_delete
+      BEFORE DELETE ON devflow_host_action_events
+      BEGIN
+        SELECT RAISE(ABORT, 'devflow_host_action_events is append-only');
+      END;
     `);
 
     // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
@@ -2592,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
@@ -3150,6 +3491,254 @@ export class DevFlowDatabase {
     }));
   }
 
+  // ---- Durable Host Actions ----
+
+  requestHostAction(input: RequestHostActionInput): HostActionRecord {
+    this.validateHostActionIdentity(input);
+    const actionId = input.actionId ?? randomUUID();
+    if (!actionId.trim()) throw new Error('Host action requires an action ID');
+
+    return this.withImmediateTransaction(() => {
+      const now = Date.now();
+      const result = this.db.prepare(`
+        INSERT INTO devflow_host_actions (
+          action_id, run_id, engine_run_id, step_id, project_root, session_id,
+          execution_id, context_receipt, state, report_json, evidence_hash,
+          created_at, updated_at, finished_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'waiting', '{}', NULL, ?, ?, NULL)
+        ON CONFLICT DO NOTHING
+      `).run(
+        actionId,
+        input.runId,
+        input.engineRunId,
+        input.stepId,
+        input.projectRoot,
+        input.sessionId ?? null,
+        input.executionId ?? null,
+        input.contextReceipt ?? null,
+        now,
+        now,
+      );
+
+      const rows = this.db.prepare(`
+        SELECT * FROM devflow_host_actions
+        WHERE action_id = ? OR (run_id = ? AND step_id = ?)
+      `).all(actionId, input.runId, input.stepId) as Array<Record<string, unknown>>;
+
+      if (rows.length !== 1) {
+        throw new Error(`HOST_ACTION_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+      }
+      const record = mapHostActionRow(rows[0]!);
+      const sameIdentity = (input.actionId === undefined || record.actionId === input.actionId)
+        && record.runId === input.runId
+        && record.engineRunId === input.engineRunId
+        && record.stepId === input.stepId
+        && record.projectRoot === input.projectRoot
+        && record.sessionId === input.sessionId
+        && record.executionId === input.executionId
+        && record.contextReceipt === input.contextReceipt;
+      if (!sameIdentity) {
+        throw new Error(`HOST_ACTION_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+      }
+
+      if (result.changes > 0) this.appendHostActionEvent(record, null, 'waiting', now);
+      return record;
+    });
+  }
+
+  startHostAction(input: StartHostActionInput): HostActionRecord {
+    return this.transitionHostAction(input, 'running', {});
+  }
+
+  reportHostAction(input: ReportHostActionInput): HostActionRecord {
+    return this.transitionHostAction(input, 'reported', input.report, input.evidenceHash);
+  }
+
+  verifyHostAction(input: VerifyHostActionInput): HostActionRecord {
+    if (typeof input.evidenceHash !== 'string' || !input.evidenceHash.trim()) {
+      throw new Error('Host action verification requires a non-empty evidence hash');
+    }
+    return this.transitionHostAction(input, 'verified', input.report, input.evidenceHash, true);
+  }
+
+  failHostAction(input: FailHostActionInput): HostActionRecord {
+    const outcome = input.outcome ?? 'failed';
+    if (outcome !== 'failed' && outcome !== 'cancelled' && outcome !== 'degraded') {
+      throw new Error(`Invalid host action failure outcome: ${String(outcome)}`);
+    }
+    return this.transitionHostAction(
+      input,
+      outcome,
+      input.report,
+      input.evidenceHash,
+    );
+  }
+
+  getHostAction(projectRoot: string, actionId: string): HostActionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_host_actions
+      WHERE project_root = ? AND action_id = ?
+    `).get(projectRoot, actionId) as Record<string, unknown> | undefined;
+    return row ? mapHostActionRow(row) : null;
+  }
+
+  listHostActionsForRun(projectRoot: string, runId: string): HostActionRecord[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_host_actions
+      WHERE project_root = ? AND run_id = ?
+      ORDER BY created_at ASC, action_id ASC
+    `).all(projectRoot, runId) as Array<Record<string, unknown>>;
+    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'>,
+    report: Record<string, unknown>,
+    evidenceHash?: string,
+    requireNonEmptyReport = false,
+  ): HostActionRecord {
+    if (!identity.actionId.trim()) throw new Error('Host action requires an action ID');
+    if (!identity.projectRoot.trim()) throw new Error('Host action requires a project root');
+    const reportJson = serializeHostActionReport(report);
+    if (requireNonEmptyReport && reportJson === '{}') {
+      throw new Error('Host action verification requires a non-empty report');
+    }
+
+    return this.withImmediateTransaction(() => {
+      const existing = this.getHostAction(identity.projectRoot, identity.actionId);
+      if (!existing) throw new Error(`HOST_ACTION_NOT_FOUND:${identity.actionId}`);
+
+      if (this.isTerminalHostActionState(existing.state)) {
+        const identical = existing.state === targetState
+          && existing.evidenceHash === evidenceHash
+          && hostActionReportsEqual(existing.report, report);
+        if (identical) return existing;
+        throw new Error(`HOST_ACTION_TERMINAL_CONFLICT:${identity.actionId}`);
+      }
+
+      if (!this.isLegalHostActionTransition(existing.state, targetState)) {
+        throw new Error(`HOST_ACTION_INVALID_TRANSITION:${existing.state}->${targetState}`);
+      }
+
+      const now = Date.now();
+      const finishedAt = this.isTerminalHostActionState(targetState) ? now : null;
+      const result = this.db.prepare(`
+        UPDATE devflow_host_actions
+        SET state = ?, report_json = ?, evidence_hash = ?, updated_at = ?, finished_at = ?
+        WHERE project_root = ? AND action_id = ? AND state = ?
+      `).run(
+        targetState,
+        reportJson,
+        evidenceHash ?? null,
+        now,
+        finishedAt,
+        identity.projectRoot,
+        identity.actionId,
+        existing.state,
+      );
+      if (result.changes !== 1) {
+        throw new Error(`HOST_ACTION_UPDATE_CONFLICT:${identity.actionId}`);
+      }
+
+      const updated = this.getHostAction(identity.projectRoot, identity.actionId)!;
+      this.appendHostActionEvent(updated, existing.state, targetState, now);
+      return updated;
+    });
+  }
+
+  private appendHostActionEvent(
+    record: HostActionRecord,
+    fromState: HostActionState | null,
+    toState: HostActionState,
+    createdAt: number,
+  ): void {
+    this.db.prepare(`
+      INSERT INTO devflow_host_action_events (
+        event_id, action_id, project_root, run_id, step_id, from_state,
+        to_state, report_json, evidence_hash, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      randomUUID(),
+      record.actionId,
+      record.projectRoot,
+      record.runId,
+      record.stepId,
+      fromState,
+      toState,
+      serializeHostActionReport(record.report),
+      record.evidenceHash ?? null,
+      createdAt,
+    );
+  }
+
+  private validateHostActionIdentity(input: RequestHostActionInput): void {
+    const fields: Array<[string, string]> = [
+      ['run ID', input.runId],
+      ['engine run ID', input.engineRunId],
+      ['step ID', input.stepId],
+      ['project root', input.projectRoot],
+    ];
+    for (const [name, value] of fields) {
+      if (!value.trim()) throw new Error(`Host action requires a ${name}`);
+    }
+  }
+
+  private withImmediateTransaction<T>(operation: () => T): T {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const result = operation();
+      this.db.exec('COMMIT');
+      return result;
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  private isTerminalHostActionState(state: HostActionState): boolean {
+    return state === 'verified'
+      || state === 'failed'
+      || state === 'cancelled'
+      || state === 'degraded';
+  }
+
+  private isLegalHostActionTransition(
+    fromState: HostActionState,
+    toState: HostActionState,
+  ): boolean {
+    if (fromState === 'waiting') {
+      return toState === 'running'
+        || toState === 'reported'
+        || toState === 'failed'
+        || toState === 'cancelled'
+        || toState === 'degraded';
+    }
+    if (fromState === 'running') {
+      return toState === 'reported'
+        || toState === 'failed'
+        || toState === 'cancelled'
+        || toState === 'degraded';
+    }
+    if (fromState === 'reported') {
+      return toState === 'verified'
+        || toState === 'failed'
+        || toState === 'cancelled'
+        || toState === 'degraded';
+    }
+    return false;
+  }
+
   // Convenience methods for raw SQL queries (used by AutoChecker)
   all(sql: string, ...params: unknown[]): unknown[] {
     return this.db.prepare(sql).all(...params);