@devflow-tools/database 0.16.18 → 0.16.19

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.19](https://github.com/shilongfeicool/dev-flow/compare/v0.16.18...v0.16.19) (2026-07-28)
+
+
+### Bug Fixes
+
+* **database:** harden host action evidence ([b74dc11](https://github.com/shilongfeicool/dev-flow/commit/b74dc110e0b96583dd741d2772c286e414928e45))
+
+
+### Features
+
+* **database:** persist workflow host actions ([6e42606](https://github.com/shilongfeicool/dev-flow/commit/6e42606ff028a591878ade9378c5277257a35961))
+
+
+
+
+
 ## [0.16.18](https://github.com/shilongfeicool/dev-flow/compare/v0.16.17...v0.16.18) (2026-07-27)
 
 **Note:** Version bump only for package @devflow-tools/database

package/__tests__/database.host-actions.test.ts

@@ -0,0 +1,405 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/database';
+import type { FailHostActionInput, VerifyHostActionInput } from '../src/host-actions';
+
+describe('DevFlowDatabase durable host actions', () => {
+  let directory: string;
+  let database: DevFlowDatabase;
+  const projectRoot = '/project-a';
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'devflow-host-actions-'));
+    database = new DevFlowDatabase(directory);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  function request(actionId: string, stepId = 'execute') {
+    return database.requestHostAction({
+      actionId,
+      runId: 'telemetry-run-1',
+      engineRunId: 'engine-run-1',
+      stepId,
+      projectRoot,
+      sessionId: 'session-1',
+      executionId: 'execution-1',
+      contextReceipt: 'context-1',
+    });
+  }
+
+  function eventCount(actionId: string): number {
+    return Number((database.get(
+      'SELECT COUNT(*) AS count FROM devflow_host_action_events WHERE action_id = ?',
+      actionId,
+    ) as { count: number }).count);
+  }
+
+  it('persists the full waiting to running to reported to verified flow', () => {
+    expect(request('action-full')).toMatchObject({
+      actionId: 'action-full',
+      runId: 'telemetry-run-1',
+      engineRunId: 'engine-run-1',
+      state: 'waiting',
+      report: {},
+      finishedAt: undefined,
+    });
+    expect(database.startHostAction({ actionId: 'action-full', projectRoot })).toMatchObject({
+      state: 'running',
+    });
+    expect(database.reportHostAction({
+      actionId: 'action-full',
+      projectRoot,
+      report: { files: ['src/index.ts'], exitCode: 0 },
+      evidenceHash: 'execution-hash',
+    })).toMatchObject({ state: 'reported', evidenceHash: 'execution-hash' });
+    const verified = database.verifyHostAction({
+      actionId: 'action-full',
+      projectRoot,
+      report: { command: 'npm test', exitCode: 0 },
+      evidenceHash: 'verification-hash',
+    });
+
+    expect(verified).toMatchObject({
+      state: 'verified',
+      report: { command: 'npm test', exitCode: 0 },
+      evidenceHash: 'verification-hash',
+    });
+    expect(verified.finishedAt).toEqual(expect.any(Number));
+    expect(eventCount('action-full')).toBe(4);
+  });
+
+  it('supports a direct waiting to reported transition for MCP reports', () => {
+    request('action-direct');
+    expect(database.reportHostAction({
+      actionId: 'action-direct',
+      projectRoot,
+      report: { toolCalls: ['write_file'] },
+      evidenceHash: 'direct-hash',
+    })).toMatchObject({ state: 'reported', finishedAt: undefined });
+    expect(eventCount('action-direct')).toBe(2);
+  });
+
+  it('rolls back invalid transitions without appending an event', () => {
+    request('action-invalid');
+    const before = eventCount('action-invalid');
+
+    expect(() => database.verifyHostAction({
+      actionId: 'action-invalid',
+      projectRoot,
+      report: { command: 'npm test', exitCode: 0 },
+      evidenceHash: 'verify-hash',
+    })).toThrow('HOST_ACTION_INVALID_TRANSITION:waiting->verified');
+    expect(database.getHostAction(projectRoot, 'action-invalid')?.state).toBe('waiting');
+    expect(eventCount('action-invalid')).toBe(before);
+  });
+
+  it('makes identical terminal reports idempotent and rejects changed duplicates', () => {
+    request('action-terminal');
+    database.reportHostAction({
+      actionId: 'action-terminal',
+      projectRoot,
+      report: { exitCode: 0 },
+      evidenceHash: 'execution-hash',
+    });
+    const input = {
+      actionId: 'action-terminal',
+      projectRoot,
+      report: { summary: 'passed', exitCode: 0 },
+      evidenceHash: 'terminal-hash',
+    };
+    const terminal = database.verifyHostAction(input);
+    const before = eventCount('action-terminal');
+
+    expect(database.verifyHostAction({
+      ...input,
+      report: { exitCode: 0, summary: 'passed' },
+    })).toEqual(terminal);
+    expect(eventCount('action-terminal')).toBe(before);
+    expect(() => database.verifyHostAction({
+      ...input,
+      evidenceHash: 'changed-hash',
+    })).toThrow('HOST_ACTION_TERMINAL_CONFLICT:action-terminal');
+    expect(() => database.verifyHostAction({
+      ...input,
+      report: { summary: 'different', exitCode: 0 },
+    })).toThrow('HOST_ACTION_TERMINAL_CONFLICT:action-terminal');
+    expect(eventCount('action-terminal')).toBe(before);
+  });
+
+  it.each(['failed', 'cancelled', 'degraded'] as const)(
+    'reaches %s with a completion timestamp',
+    outcome => {
+      const actionId = `action-${outcome}`;
+      request(actionId, outcome);
+      const terminal = database.failHostAction({
+        actionId,
+        projectRoot,
+        outcome,
+        report: { reason: `${outcome} by host` },
+        evidenceHash: `${outcome}-hash`,
+      });
+
+      expect(terminal.state).toBe(outcome);
+      expect(terminal.finishedAt).toEqual(expect.any(Number));
+      expect(eventCount(actionId)).toBe(2);
+    },
+  );
+
+  it('rejects request identity conflicts instead of merging metadata', () => {
+    request('action-identity');
+    const identical = request('action-identity');
+    expect(identical.actionId).toBe('action-identity');
+    expect(eventCount('action-identity')).toBe(1);
+
+    expect(() => database.requestHostAction({
+      actionId: 'different-action',
+      runId: 'telemetry-run-1',
+      engineRunId: 'different-engine-run',
+      stepId: 'execute',
+      projectRoot,
+      sessionId: 'different-session',
+      executionId: 'execution-1',
+      contextReceipt: 'context-1',
+    })).toThrow('HOST_ACTION_IDENTITY_CONFLICT:telemetry-run-1:execute');
+    expect(database.all('SELECT action_id FROM devflow_host_actions')).toHaveLength(1);
+  });
+
+  it('scopes action and run reads by project root', () => {
+    request('action-isolated');
+
+    expect(database.getHostAction('/project-b', 'action-isolated')).toBeNull();
+    expect(database.listHostActionsForRun('/project-b', 'telemetry-run-1')).toEqual([]);
+    expect(database.listHostActionsForRun(projectRoot, 'telemetry-run-1')).toHaveLength(1);
+    expect(() => database.startHostAction({
+      actionId: 'action-isolated',
+      projectRoot: '/project-b',
+    })).toThrow('HOST_ACTION_NOT_FOUND:action-isolated');
+  });
+
+  it('keeps rows and schema stable across close and reopen', () => {
+    request('action-durable');
+    database.reportHostAction({
+      actionId: 'action-durable',
+      projectRoot,
+      report: { result: 'observed' },
+      evidenceHash: 'durable-hash',
+    });
+    const schemaBefore = database.all(`
+      SELECT type, name, sql FROM sqlite_master
+      WHERE name LIKE '%host_action%'
+      ORDER BY type, name
+    `);
+    database.close();
+    database = new DevFlowDatabase(directory);
+
+    expect(database.getHostAction(projectRoot, 'action-durable')).toMatchObject({
+      state: 'reported',
+      report: { result: 'observed' },
+      evidenceHash: 'durable-hash',
+    });
+    expect(eventCount('action-durable')).toBe(2);
+    expect(database.all(`
+      SELECT type, name, sql FROM sqlite_master
+      WHERE name LIKE '%host_action%'
+      ORDER BY type, name
+    `)).toEqual(schemaBefore);
+  });
+
+  it('uses UUID text event IDs and enforces append-only event rows', () => {
+    request('action-events');
+    const [event] = database.all(`
+      SELECT event_id FROM devflow_host_action_events WHERE action_id = ?
+    `, 'action-events') as Array<{ event_id: string }>;
+
+    expect(event?.event_id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+    expect(() => database.all(
+      'UPDATE devflow_host_action_events SET evidence_hash = ? WHERE event_id = ?',
+      'changed',
+      event!.event_id,
+    )).toThrow('append-only');
+  });
+
+  it('rejects INSERT OR REPLACE attempts without mutating an event', () => {
+    request('action-replace');
+    const [event] = database.all(`
+      SELECT * FROM devflow_host_action_events WHERE action_id = ?
+    `, 'action-replace') as Array<Record<string, unknown>>;
+
+    expect(() => database.all(`
+      INSERT OR REPLACE 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+    event!.event_id,
+    event!.action_id,
+    event!.project_root,
+    event!.run_id,
+    event!.step_id,
+    event!.from_state,
+    event!.to_state,
+    event!.report_json,
+    'replacement-hash',
+    event!.created_at,
+    )).toThrow('append-only');
+
+    expect(database.get(
+      'SELECT evidence_hash FROM devflow_host_action_events WHERE event_id = ?',
+      event!.event_id,
+    )).toMatchObject({ evidence_hash: null });
+  });
+
+  it.each([
+    ['undefined', { value: undefined }],
+    ['NaN', { value: Number.NaN }],
+    ['Infinity', { value: Number.POSITIVE_INFINITY }],
+    ['negative zero', { value: -0 }],
+    ['function', { value: () => undefined }],
+    ['bigint', { value: 1n }],
+    ['symbol', { value: Symbol('value') }],
+    ['non-plain object', { value: new Date(0) }],
+    ['sparse array', { value: Array(1) }],
+  ])('rejects lossy %s report values', (_name, report) => {
+    request(`action-json-${_name}`);
+    expect(() => database.reportHostAction({
+      actionId: `action-json-${_name}`,
+      projectRoot,
+      report,
+      evidenceHash: 'report-hash',
+    })).toThrow('Host action report contains a non-JSON value');
+  });
+
+  it('rejects cyclic reports', () => {
+    request('action-json-cycle');
+    const report: Record<string, unknown> = {};
+    report.self = report;
+
+    expect(() => database.reportHostAction({
+      actionId: 'action-json-cycle',
+      projectRoot,
+      report,
+      evidenceHash: 'report-hash',
+    })).toThrow('Host action report contains a cycle');
+  });
+
+  it.each(['not-json', '[]'])(
+    'fails closed when persisted report JSON is corrupt: %s',
+    reportJson => {
+      request('action-corrupt');
+      database.all(
+        'UPDATE devflow_host_actions SET report_json = ? WHERE action_id = ?',
+        reportJson,
+        'action-corrupt',
+      );
+
+      expect(() => database.getHostAction(projectRoot, 'action-corrupt'))
+        .toThrow('Invalid persisted host action report_json');
+    },
+  );
+
+  it('requires non-empty verification evidence and report content', () => {
+    request('action-verification-input');
+    database.reportHostAction({
+      actionId: 'action-verification-input',
+      projectRoot,
+      report: { output: 'observed' },
+      evidenceHash: 'execution-hash',
+    });
+    const baseInput = {
+      actionId: 'action-verification-input',
+      projectRoot,
+      report: { command: 'npm test', exitCode: 0 },
+    };
+
+    expect(() => database.verifyHostAction({
+      ...baseInput,
+      evidenceHash: '   ',
+    })).toThrow('Host action verification requires a non-empty evidence hash');
+    expect(() => database.verifyHostAction(baseInput as VerifyHostActionInput))
+      .toThrow('Host action verification requires a non-empty evidence hash');
+    expect(() => database.verifyHostAction({
+      ...baseInput,
+      report: {},
+      evidenceHash: 'verification-hash',
+    })).toThrow('Host action verification requires a non-empty report');
+    expect(() => database.failHostAction({
+      ...baseInput,
+      outcome: 'verified',
+    } as unknown as FailHostActionInput)).toThrow('Invalid host action failure outcome');
+    expect(database.getHostAction(projectRoot, 'action-verification-input')?.state).toBe('reported');
+    expect(eventCount('action-verification-input')).toBe(2);
+  });
+
+  it('waits for a competing writer and resolves the committed request idempotently', async () => {
+    const worker = new Worker(`
+      const { parentPort, workerData } = require('node:worker_threads');
+      const { DatabaseSync } = require('node:sqlite');
+      const db = new DatabaseSync(workerData.dbPath);
+      db.exec('PRAGMA busy_timeout = 5000');
+      db.exec('BEGIN IMMEDIATE');
+      const now = Date.now();
+      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)",
+      ).run(
+        'action-contended', 'telemetry-run-1', 'engine-run-1', 'execute', '/project-a',
+        'session-1', 'execution-1', 'context-1', now, now,
+      );
+      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 (?, ?, ?, ?, ?, NULL, 'waiting', '{}', NULL, ?)",
+      ).run(
+        'worker-event-contended', 'action-contended', '/project-a',
+        'telemetry-run-1', 'execute', now,
+      );
+      parentPort.postMessage('locked');
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+      db.exec('COMMIT');
+      db.close();
+      parentPort.postMessage('committed');
+    `, {
+      eval: true,
+      workerData: { dbPath: join(directory, '.devflow', 'devflow.db') },
+    });
+    let duplicate: ReturnType<typeof request> | undefined;
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        worker.on('message', message => {
+          if (message === 'locked') {
+            try {
+              duplicate = request('action-contended');
+            } catch (error) {
+              reject(error);
+            }
+          }
+          if (message === 'committed') resolve();
+        });
+        worker.on('error', reject);
+        worker.on('exit', code => {
+          if (code !== 0) reject(new Error(`Host-action lock worker exited with code ${code}`));
+        });
+      });
+
+      expect(duplicate).toMatchObject({
+        actionId: 'action-contended',
+        state: 'waiting',
+      });
+      expect(eventCount('action-contended')).toBe(1);
+    } finally {
+      await worker.terminate();
+    }
+  });
+});

package/dist/database.d.ts

@@ -1,5 +1,6 @@
 import type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, WorkError, WorkItemRecord, WorkQueueHealth } from './work-queue';
 import { type SessionObligationRecord, type SessionObligationState } from './obligation-ledger';
+import { type FailHostActionInput, type HostActionRecord, type ReportHostActionInput, type RequestHostActionInput, type StartHostActionInput, type VerifyHostActionInput } from './host-actions';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -400,6 +401,19 @@ export declare class DevFlowDatabase {
     private mapMemoryTurn;
     recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void;
     listMemoryDistillCheckpoints(projectRoot: string, limit?: number): MemoryDistillCheckpointRecord[];
+    requestHostAction(input: RequestHostActionInput): HostActionRecord;
+    startHostAction(input: StartHostActionInput): HostActionRecord;
+    reportHostAction(input: ReportHostActionInput): HostActionRecord;
+    verifyHostAction(input: VerifyHostActionInput): HostActionRecord;
+    failHostAction(input: FailHostActionInput): HostActionRecord;
+    getHostAction(projectRoot: string, actionId: string): HostActionRecord | null;
+    listHostActionsForRun(projectRoot: string, runId: string): HostActionRecord[];
+    private transitionHostAction;
+    private appendHostActionEvent;
+    private validateHostActionIdentity;
+    private withImmediateTransaction;
+    private isTerminalHostActionState;
+    private isLegalHostActionTransition;
     all(sql: string, ...params: unknown[]): unknown[];
     get(sql: string, ...params: unknown[]): unknown;
     close(): void;