@devflow-tools/database 0.17.8 → 0.18.0

package/__tests__/database.failure-category.test.ts

@@ -1,44 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { DevFlowDatabase } from "../src/database.js";
-
-describe("tool failure categories", () => {
-  let root: string;
-  let database: DevFlowDatabase;
-
-  beforeEach(() => {
-    root = mkdtempSync(join(tmpdir(), "devflow-failure-category-"));
-    database = new DevFlowDatabase(root);
-  });
-
-  afterEach(() => {
-    database.close();
-    rmSync(root, { recursive: true, force: true });
-  });
-
-  it("persists and returns failure_category", () => {
-    database.insertToolCallEvent({
-      eventId: "event-1",
-      executionId: "execution-1",
-      sessionId: "session-1",
-      timestamp: Date.now(),
-      toolName: "Bash",
-      toolType: "direct",
-      isMcpTool: false,
-      mcpEnforced: false,
-      mcpFallback: false,
-      input: { command: "false" },
-      duration: 1,
-      error: "exit 1",
-      blocked: false,
-      failureCategory: "tool_error",
-    });
-
-    expect(database.listToolCallEvents("execution-1")[0])
-      .toMatchObject({ failureCategory: "tool_error", error: "exit 1" });
-    expect(database.listToolCallEventsBySession("session-1")[0])
-      .toMatchObject({ failureCategory: "tool_error" });
-  });
-});

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

@@ -1,405 +0,0 @@
-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/__tests__/database.learning-candidates.test.ts

@@ -1,93 +0,0 @@
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
-import { DevFlowDatabase } from '../src/index.js';
-
-describe('governed learning candidates', () => {
-  const roots: string[] = [];
-
-  afterEach(() => {
-    for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
-  });
-
-  it('requires independent evidence, grader receipt, and rolls active candidates back on contradiction', () => {
-    const root = mkdtempSync(join(tmpdir(), 'devflow-learning-db-'));
-    roots.push(root);
-    const database = new DevFlowDatabase(root);
-    const candidate = database.upsertLearningCandidate({
-      id: 'candidate:install-flag',
-      projectRoot: '/project',
-      scope: 'project',
-      kind: 'tool_preference',
-      trigger: { skills: ['devflow:react'], entities: ['--legacy-peer-deps'] },
-      instruction: 'Use --legacy-peer-deps when installing dependencies.',
-      confidence: 0.95,
-    });
-    expect(candidate.state).toBe('observed');
-
-    for (let index = 1; index <= 3; index += 1) {
-      database.addLearningCandidateEvidence({
-        id: `evidence:${index}`,
-        candidateId: candidate.id,
-        projectRoot: '/project',
-        sessionId: `session:${index}`,
-        sourceType: 'tool_preference',
-        polarity: 'supporting',
-        outcome: index <= 2 ? 'positive' : 'unknown',
-        evidenceHash: `hash:${index}`,
-      });
-    }
-    expect(database.getLearningCandidate(candidate.id)).toMatchObject({
-      state: 'candidate', supportingSessions: 3, successfulOutcomes: 2,
-    });
-    database.transitionLearningCandidate(candidate.id, { target: 'shadow', reason: 'threshold' });
-    database.transitionLearningCandidate(candidate.id, {
-      target: 'evaluated', reason: 'pass^3', graderReceipt: 'grader:receipt:12345678',
-    });
-    expect(database.transitionLearningCandidate(candidate.id, {
-      target: 'active', reason: 'automatic project activation',
-    }).state).toBe('active');
-
-    expect(database.addLearningCandidateEvidence({
-      id: 'evidence:contradiction',
-      candidateId: candidate.id,
-      projectRoot: '/project',
-      sessionId: 'session:4',
-      sourceType: 'correction',
-      polarity: 'contradicting',
-      outcome: 'positive',
-      evidenceHash: 'hash:contradiction',
-    })).toMatchObject({ state: 'shadow', contradictions: 1 });
-    database.close();
-  });
-
-  it('versions changed overlays and requires manual approval for global candidates', () => {
-    const root = mkdtempSync(join(tmpdir(), 'devflow-learning-version-'));
-    roots.push(root);
-    const database = new DevFlowDatabase(root);
-    const id = 'candidate:global';
-    database.upsertLearningCandidate({
-      id, projectRoot: '/project', scope: 'global', kind: 'convention',
-      trigger: {}, instruction: 'Use the first convention.', confidence: 0.8,
-    });
-    database.upsertLearningCandidate({
-      id, projectRoot: '/project', scope: 'global', kind: 'convention',
-      trigger: {}, instruction: 'Use the corrected convention.', confidence: 0.9,
-    });
-    expect(database.listLearningCandidateVersions(id)).toHaveLength(2);
-    for (let index = 1; index <= 3; index += 1) {
-      database.addLearningCandidateEvidence({
-        id: `global:${index}`, candidateId: id, projectRoot: '/project', sessionId: `s:${index}`,
-        sourceType: 'convention', polarity: 'supporting', outcome: 'positive', evidenceHash: `g:${index}`,
-      });
-    }
-    database.transitionLearningCandidate(id, { target: 'shadow', reason: 'threshold' });
-    database.transitionLearningCandidate(id, { target: 'evaluated', reason: 'graded', graderReceipt: 'grader:global:12345678' });
-    expect(() => database.transitionLearningCandidate(id, { target: 'active', reason: 'auto' }))
-      .toThrow('manual approval');
-    expect(database.transitionLearningCandidate(id, { target: 'active', reason: 'manual', manualApproval: true }).state)
-      .toBe('active');
-    database.close();
-  });
-});

package/__tests__/database.memory-turn-receipts.test.ts

@@ -1,98 +0,0 @@
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { DevFlowDatabase } from '../src/database';
-
-describe('DevFlowDatabase memory turn receipts', () => {
-  let directory: string;
-  let database: DevFlowDatabase;
-
-  beforeEach(() => {
-    directory = mkdtempSync(join(tmpdir(), 'devflow-memory-turn-'));
-    database = new DevFlowDatabase(directory);
-  });
-
-  afterEach(() => {
-    database.close();
-    rmSync(directory, { recursive: true, force: true });
-  });
-
-  it('commits a pending turn with one canonical receipt', () => {
-    database.beginMemoryTurn({
-      turnId: 'turn:1',
-      projectRoot: '/project',
-      sessionId: 'session-1',
-      promptHash: 'hash',
-      eventId: 'event-1',
-      createdAt: 100,
-    });
-
-    const committed = database.commitMemoryTurn({
-      turnId: 'turn:1',
-      receiptId: 'memory-receipt:1',
-      memoryIds: ['memory-1'],
-      source: 'explicit_intent',
-      decidedAt: 200,
-    });
-
-    expect(committed).toMatchObject({
-      status: 'committed',
-      receiptId: 'memory-receipt:1',
-      memoryIds: ['memory-1'],
-      stopPromptedAt: undefined,
-    });
-    expect(database.getPendingMemoryTurn('/project', 'session-1')).toBeNull();
-  });
-
-  it('marks a pending Stop prompt only once and supports skip receipts', () => {
-    database.beginMemoryTurn({
-      turnId: 'turn:2',
-      projectRoot: '/project',
-      sessionId: 'session-1',
-      promptHash: 'hash-2',
-      eventId: 'event-2',
-      createdAt: 300,
-    });
-
-    expect(database.markMemoryTurnStopPrompted('turn:2', 350)).toBe(true);
-    expect(database.markMemoryTurnStopPrompted('turn:2', 360)).toBe(false);
-    expect(database.skipMemoryTurn({
-      turnId: 'turn:2',
-      receiptId: 'memory-receipt:2',
-      reason: 'transient request',
-      decidedAt: 400,
-    })).toMatchObject({
-      status: 'skipped',
-      reason: 'transient request',
-      stopPromptedAt: 350,
-    });
-  });
-
-  it('lists every session turn in stable ascending order for reconciliation', () => {
-    for (let index = 0; index < 125; index += 1) {
-      database.beginMemoryTurn({
-        turnId: `turn:${String(index).padStart(3, '0')}`,
-        projectRoot: '/project',
-        sessionId: 'long-session',
-        promptHash: `hash-${index}`,
-        eventId: `event-${index}`,
-        createdAt: 1_000 + index,
-      });
-    }
-    database.beginMemoryTurn({
-      turnId: 'turn:other',
-      projectRoot: '/project',
-      sessionId: 'other-session',
-      promptHash: 'other',
-      eventId: 'event-other',
-      createdAt: 1,
-    });
-
-    const turns = database.listSessionMemoryTurnsForReconciliation('/project', 'long-session');
-    expect(turns).toHaveLength(125);
-    expect(turns[0]?.turnId).toBe('turn:000');
-    expect(turns.at(-1)?.turnId).toBe('turn:124');
-    expect(turns.every((turn, index) => turn.createdAt === 1_000 + index)).toBe(true);
-  });
-});