@devflow-tools/database 0.16.18 → 0.16.19

package/src/database.ts

@@ -19,6 +19,18 @@ 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';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -587,6 +599,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)
@@ -3150,6 +3235,244 @@ 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);
+  }
+
+  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);

package/src/host-actions.ts

@@ -0,0 +1,211 @@
+export type HostActionState =
+  | 'waiting'
+  | 'running'
+  | 'reported'
+  | 'verified'
+  | 'failed'
+  | 'cancelled'
+  | 'degraded';
+
+export interface HostActionRecord {
+  actionId: string;
+  runId: string;
+  engineRunId: string;
+  stepId: string;
+  projectRoot: string;
+  sessionId?: string;
+  executionId?: string;
+  contextReceipt?: string;
+  state: HostActionState;
+  report: Record<string, unknown>;
+  evidenceHash?: string;
+  createdAt: number;
+  updatedAt: number;
+  finishedAt?: number;
+}
+
+export interface RequestHostActionInput {
+  actionId?: string;
+  runId: string;
+  engineRunId: string;
+  stepId: string;
+  projectRoot: string;
+  sessionId?: string;
+  executionId?: string;
+  contextReceipt?: string;
+}
+
+export interface StartHostActionInput {
+  actionId: string;
+  projectRoot: string;
+}
+
+export interface ReportHostActionInput {
+  actionId: string;
+  projectRoot: string;
+  report: Record<string, unknown>;
+  evidenceHash?: string;
+}
+
+export interface VerifyHostActionInput extends ReportHostActionInput {
+  evidenceHash: string;
+}
+
+export interface FailHostActionInput extends ReportHostActionInput {
+  outcome?: 'failed' | 'cancelled' | 'degraded';
+}
+
+const HOST_ACTION_STATES = new Set<HostActionState>([
+  'waiting',
+  'running',
+  'reported',
+  'verified',
+  'failed',
+  'cancelled',
+  'degraded',
+]);
+
+export function isHostActionState(value: unknown): value is HostActionState {
+  return typeof value === 'string' && HOST_ACTION_STATES.has(value as HostActionState);
+}
+
+export function mapHostActionRow(row: Record<string, unknown>): HostActionRecord {
+  if (!isHostActionState(row.state)) {
+    throw new Error(`Invalid persisted host action state: ${String(row.state)}`);
+  }
+
+  return {
+    actionId: asRequiredString(row.action_id, 'action_id'),
+    runId: asRequiredString(row.run_id, 'run_id'),
+    engineRunId: asRequiredString(row.engine_run_id, 'engine_run_id'),
+    stepId: asRequiredString(row.step_id, 'step_id'),
+    projectRoot: asRequiredString(row.project_root, 'project_root'),
+    sessionId: asOptionalString(row.session_id),
+    executionId: asOptionalString(row.execution_id),
+    contextReceipt: asOptionalString(row.context_receipt),
+    state: row.state,
+    report: parseReport(row.report_json),
+    evidenceHash: asOptionalString(row.evidence_hash),
+    createdAt: asFiniteNumber(row.created_at, 'created_at'),
+    updatedAt: asFiniteNumber(row.updated_at, 'updated_at'),
+    finishedAt: asOptionalFiniteNumber(row.finished_at),
+  };
+}
+
+export function serializeHostActionReport(report: Record<string, unknown>): string {
+  if (!isPlainObject(report)) throw new Error('Host action report must be a plain object');
+  return JSON.stringify(canonicalizeJson(report, '$', new WeakSet<object>()));
+}
+
+export function hostActionReportsEqual(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+): boolean {
+  return serializeHostActionReport(left) === serializeHostActionReport(right);
+}
+
+function parseReport(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'string') {
+    throw new Error('Invalid persisted host action report_json: expected JSON text');
+  }
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!isPlainObject(parsed)) {
+      throw new Error('expected a JSON object');
+    }
+    serializeHostActionReport(parsed);
+    return parsed;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid persisted host action report_json: ${detail}`);
+  }
+}
+
+function canonicalizeJson(value: unknown, path: string, ancestors: WeakSet<object>): 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 nonJsonValueError(path);
+    }
+    return value;
+  }
+  if (typeof value !== 'object') throw nonJsonValueError(path);
+  if (ancestors.has(value)) throw new Error(`Host action report contains a cycle at ${path}`);
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) return canonicalizeArray(value, path, ancestors);
+    if (!isPlainObject(value)) throw nonJsonValueError(path);
+
+    const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    const keys = Reflect.ownKeys(value);
+    for (const key of keys) {
+      if (typeof key !== 'string') throw nonJsonValueError(`${path}[symbol]`);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw nonJsonValueError(`${path}.${key}`);
+      }
+    }
+    for (const key of (keys as string[]).slice().sort(comparePropertyKeys)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+      result[key] = canonicalizeJson(descriptor.value, `${path}.${key}`, ancestors);
+    }
+    return result;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function canonicalizeArray(value: unknown[], path: string, ancestors: WeakSet<object>): unknown[] {
+  if (Object.getPrototypeOf(value) !== Array.prototype) throw nonJsonValueError(path);
+  const keys = Reflect.ownKeys(value);
+  const expectedKeys = new Set(['length', ...Array.from({ length: value.length }, (_, index) => String(index))]);
+  if (keys.some(key => typeof key !== 'string' || !expectedKeys.has(key))) {
+    throw nonJsonValueError(path);
+  }
+
+  return Array.from({ length: value.length }, (_, index) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      throw nonJsonValueError(`${path}[${index}]`);
+    }
+    return canonicalizeJson(descriptor.value, `${path}[${index}]`, ancestors);
+  });
+}
+
+function comparePropertyKeys(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function nonJsonValueError(path: string): Error {
+  return new Error(`Host action report contains a non-JSON value at ${path}`);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function asRequiredString(value: unknown, column: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Invalid persisted host action ${column}`);
+  }
+  return value;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function asFiniteNumber(value: unknown, column: string): number {
+  const number = Number(value);
+  if (!Number.isFinite(number)) throw new Error(`Invalid persisted host action ${column}`);
+  return number;
+}
+
+function asOptionalFiniteNumber(value: unknown): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}

package/src/index.ts

@@ -30,6 +30,21 @@ export type {
   WorkQueueHealth,
   WorkState,
 } from './work-queue';
+export {
+  hostActionReportsEqual,
+  isHostActionState,
+  mapHostActionRow,
+  serializeHostActionReport,
+} from './host-actions';
+export type {
+  FailHostActionInput,
+  HostActionRecord,
+  HostActionState,
+  ReportHostActionInput,
+  RequestHostActionInput,
+  StartHostActionInput,
+  VerifyHostActionInput,
+} from './host-actions';
 export {
   mapSessionObligationRow,
   normalizeTurnId,