bunqueue-dashboard 0.0.34 → 0.0.36

package/agent/workflow/list.ts

@@ -0,0 +1,87 @@
+import { openWorkflowDatabase, workflowSchema } from './sqlite';
+import {
+  WORKFLOW_LIMITS,
+  type WorkflowListOptions,
+  type WorkflowPage,
+  type WorkflowRow,
+} from './types';
+import { assertWorkflowRow, validWorkflowState } from './validation';
+
+export function workflowExecutions(
+  path: string,
+  options: WorkflowListOptions = {},
+  /** @internal Deterministic seam for the SQLite snapshot regression test. */
+  afterRowsRead?: () => void
+): WorkflowPage {
+  const kind = options.kind ?? 'active';
+  const limit = options.limit ?? 50;
+  const offset = options.offset ?? 0;
+  validateListOptions(options, limit, offset);
+  const db = openWorkflowDatabase(path);
+  try {
+    const info = workflowSchema(db, kind);
+    if (!info) return { available: false, executions: [], total: 0, limit, offset };
+    const { predicate, bindings } = listPredicate(options);
+    const archiveColumn = kind === 'archive' ? ', archived_at' : '';
+    const metaColumn = info.hasMeta ? ', meta' : '';
+    db.run('BEGIN');
+    let transactionOpen = true;
+    try {
+      const rows = db
+        .query(
+          `SELECT id, workflow_name, state, current_node_index, created_at, updated_at${archiveColumn}${metaColumn}
+           FROM ${info.table}${predicate} ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?`
+        )
+        .all(...bindings, limit, offset) as WorkflowRow[];
+      afterRowsRead?.();
+      const count = db.query(`SELECT COUNT(*) AS count FROM ${info.table}${predicate}`).get(...bindings) as { count: number };
+      const executions = rows.map(assertWorkflowRow);
+      db.run('COMMIT');
+      transactionOpen = false;
+      return { available: true, executions, total: count.count, limit, offset };
+    } finally {
+      if (transactionOpen) rollbackQuietly(db);
+    }
+  } finally {
+    db.close();
+  }
+}
+
+function validateListOptions(options: WorkflowListOptions, limit: number, offset: number): void {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > WORKFLOW_LIMITS.page) {
+    throw new Error(`Workflow limit must be an integer between 1 and ${WORKFLOW_LIMITS.page}`);
+  }
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > WORKFLOW_LIMITS.offset) {
+    throw new Error(`Workflow offset must be an integer between 0 and ${WORKFLOW_LIMITS.offset}`);
+  }
+  if (options.workflowName !== undefined && (!options.workflowName || options.workflowName.length > WORKFLOW_LIMITS.filter)) {
+    throw new Error(`Workflow name must contain 1–${WORKFLOW_LIMITS.filter} characters`);
+  }
+  if (options.state !== undefined && options.state !== 'compensation' && !validWorkflowState(options.state)) {
+    throw new Error('Unknown workflow execution state');
+  }
+}
+
+function listPredicate(options: WorkflowListOptions): { predicate: string; bindings: string[] } {
+  const where: string[] = [];
+  const bindings: string[] = [];
+  if (options.workflowName) {
+    where.push('workflow_name = ?');
+    bindings.push(options.workflowName);
+  }
+  if (options.state === 'compensation') {
+    where.push("state IN ('compensating', 'compensation-stuck')");
+  } else if (options.state) {
+    where.push('state = ?');
+    bindings.push(options.state);
+  }
+  return { predicate: where.length ? ` WHERE ${where.join(' AND ')}` : '', bindings };
+}
+
+function rollbackQuietly(db: import('bun:sqlite').Database): void {
+  try {
+    db.run('ROLLBACK');
+  } catch {
+    // Preserve the original query or decoding error if SQLite already closed the transaction.
+  }
+}

package/agent/workflow/runtime.ts

@@ -0,0 +1,274 @@
+import { realpath, stat } from 'node:fs/promises';
+import { basename, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  Engine,
+  type EngineOptions,
+  type ExecutionState,
+  type Workflow,
+} from 'bunqueue/workflow';
+import { managedAuthToken } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import {
+  configuredWorkflowModule,
+  messageOf,
+  readyRuntimeStatus,
+  stoppedRuntimeStatus,
+  WorkflowRuntimeUnavailableError,
+  workflowRuntimeOptions,
+  workflowRuntimeSignature,
+} from './runtimeConfig';
+
+export { WorkflowRuntimeUnavailableError } from './runtimeConfig';
+
+export interface WorkflowRuntimeStatus {
+  configured: boolean;
+  ready: boolean;
+  moduleName?: string;
+  workflowNames: string[];
+  queueName?: string;
+  concurrency?: number;
+  error?: string;
+}
+
+export interface WorkflowRuntimePort {
+  status(config: ServerConfig, activate?: boolean): Promise<WorkflowRuntimeStatus>;
+  reload(config: ServerConfig): Promise<WorkflowRuntimeStatus>;
+  start(config: ServerConfig, workflowName: string, input?: unknown): Promise<unknown>;
+  signal(config: ServerConfig, id: string, event: string, payload?: unknown): Promise<void>;
+  recover(config: ServerConfig): Promise<unknown>;
+  resumeCompensation(config: ServerConfig, id: string): Promise<void>;
+  abandonCompensation(config: ServerConfig, id: string): Promise<void>;
+  archive(config: ServerConfig, maxAgeMs: number, states: ExecutionState[]): Promise<number>;
+  cleanup(config: ServerConfig, maxAgeMs: number, states: ExecutionState[]): Promise<number>;
+  close(): Promise<void>;
+}
+
+interface ActiveRuntime {
+  engine: Engine;
+  signature: string;
+  moduleName: string;
+  workflowNames: string[];
+  queueName: string;
+  concurrency: number;
+  initializationFailure?: string;
+  closeFailure?: string;
+}
+
+interface RuntimeModule {
+  workflows?: Workflow[];
+  workflowNames?: string[];
+  registerWorkflowRuntime?: (engine: Engine) => unknown | Promise<unknown>;
+  default?: (engine: Engine) => unknown | Promise<unknown>;
+}
+
+export type WorkflowEngineFactory = (options: EngineOptions) => Engine;
+
+export class WorkflowRuntime implements WorkflowRuntimePort {
+  private active: ActiveRuntime | null = null;
+  private gate: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly createEngine: WorkflowEngineFactory = (options) => new Engine(options)
+  ) {}
+
+  status(config: ServerConfig, activate = true): Promise<WorkflowRuntimeStatus> {
+    return this.serial(async () => {
+      const modulePath = configuredWorkflowModule(config);
+      try {
+        if (!modulePath) {
+          await this.closeActive();
+          return { configured: false, ready: false, workflowNames: [] };
+        }
+        if (!activate) {
+          await this.closeActive();
+          return stoppedRuntimeStatus(config, modulePath);
+        }
+        const active = await this.ensure(config);
+        return readyRuntimeStatus(active);
+      } catch (error) {
+        const active = this.active;
+        return {
+          configured: Boolean(modulePath),
+          ready: false,
+          moduleName: modulePath ? basename(modulePath) : active?.moduleName,
+          workflowNames: [],
+          queueName: active?.queueName,
+          concurrency: active?.concurrency,
+          error: messageOf(error),
+        };
+      }
+    });
+  }
+
+  reload(config: ServerConfig): Promise<WorkflowRuntimeStatus> {
+    return this.serial(async () => {
+      await this.closeActive();
+      return readyRuntimeStatus(await this.ensure(config));
+    });
+  }
+
+  start(config: ServerConfig, workflowName: string, input?: unknown): Promise<unknown> {
+    return this.run(config, (engine) => engine.start(workflowName, input));
+  }
+
+  signal(config: ServerConfig, id: string, event: string, payload?: unknown): Promise<void> {
+    return this.run(config, (engine) => engine.signal(id, event, payload));
+  }
+
+  recover(config: ServerConfig): Promise<unknown> {
+    return this.run(config, (engine) => engine.recover());
+  }
+
+  resumeCompensation(config: ServerConfig, id: string): Promise<void> {
+    return this.run(config, (engine) => engine.resumeCompensation(id));
+  }
+
+  abandonCompensation(config: ServerConfig, id: string): Promise<void> {
+    return this.run(config, (engine) => engine.abandonCompensation(id));
+  }
+
+  archive(
+    config: ServerConfig,
+    maxAgeMs: number,
+    states: ExecutionState[]
+  ): Promise<number> {
+    return this.run(config, (engine) => engine.archive(maxAgeMs, states));
+  }
+
+  cleanup(
+    config: ServerConfig,
+    maxAgeMs: number,
+    states: ExecutionState[]
+  ): Promise<number> {
+    return this.run(config, (engine) => engine.cleanup(maxAgeMs, states));
+  }
+
+  close(): Promise<void> {
+    return this.serial(() => this.closeActive());
+  }
+
+  private run<T>(config: ServerConfig, operation: (engine: Engine) => Promise<T> | T): Promise<T> {
+    return this.serial(async () => operation((await this.ensure(config)).engine));
+  }
+
+  private async ensure(config: ServerConfig): Promise<ActiveRuntime> {
+    if (this.active?.closeFailure !== undefined) {
+      throw quarantinedRuntimeError(this.active);
+    }
+    const requested = configuredWorkflowModule(config);
+    if (!requested) {
+      throw new WorkflowRuntimeUnavailableError(
+        'Set BUNQUEUE_WORKFLOW_MODULE in Server extraEnv to an absolute runtime module path.'
+      );
+    }
+    if (!isAbsolute(requested)) {
+      throw new WorkflowRuntimeUnavailableError('BUNQUEUE_WORKFLOW_MODULE must be absolute.');
+    }
+    const path = await realpath(requested).catch(() => {
+      throw new WorkflowRuntimeUnavailableError(
+        'The configured workflow runtime module was not found.'
+      );
+    });
+    const modified = (await stat(path)).mtimeMs;
+    const options = workflowRuntimeOptions(config);
+    const signature = workflowRuntimeSignature(config, path, modified, options);
+    if (this.active?.signature === signature) return this.active;
+
+    await this.closeActive();
+    const imported = (await import(`${pathToFileURL(path).href}?v=${modified}`)) as RuntimeModule;
+    const definitions = Array.isArray(imported.workflows) ? imported.workflows : [];
+    const register = imported.registerWorkflowRuntime ?? imported.default;
+    if (!register && definitions.length === 0) {
+      throw new WorkflowRuntimeUnavailableError(
+        'Workflow module must export workflows[] or registerWorkflowRuntime(engine).'
+      );
+    }
+    const engine = this.createEngine({
+      dataPath: config.dataPath,
+      queueName: options.queueName,
+      concurrency: options.concurrency,
+      connection: {
+        host: '127.0.0.1',
+        port: config.tcpPort,
+        token: managedAuthToken(config),
+      },
+    });
+    const active: ActiveRuntime = {
+      engine,
+      signature,
+      moduleName: basename(path),
+      workflowNames: [],
+      ...options,
+    };
+    this.active = active;
+    try {
+      const names = new Set<string>();
+      const originalRegister = engine.register.bind(engine);
+      engine.register = ((workflow: Workflow) => {
+        const registered = originalRegister(workflow);
+        names.add(workflowName(workflow.name));
+        return registered;
+      }) as Engine['register'];
+      try {
+        for (const workflow of definitions) engine.register(workflow);
+        if (register) await register(engine);
+      } finally {
+        engine.register = originalRegister as Engine['register'];
+      }
+      if (imported.workflowNames !== undefined && !Array.isArray(imported.workflowNames)) {
+        throw new WorkflowRuntimeUnavailableError('workflowNames must be an array of strings.');
+      }
+      for (const name of imported.workflowNames ?? []) names.add(workflowName(name));
+      active.workflowNames = Array.from(names).sort();
+      return active;
+    } catch (error) {
+      try {
+        active.initializationFailure ??= messageOf(error);
+      } finally {
+        await this.closeActive();
+      }
+      throw error;
+    }
+  }
+
+  private async closeActive(): Promise<void> {
+    const previous = this.active;
+    if (!previous) return;
+    try {
+      await previous.engine.close(true);
+    } catch (error) {
+      previous.closeFailure ??= messageOf(error);
+      throw quarantinedRuntimeError(previous);
+    }
+    if (this.active === previous) this.active = null;
+  }
+
+  private serial<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.gate.then(operation, operation);
+    this.gate = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}
+
+function quarantinedRuntimeError(active: ActiveRuntime): WorkflowRuntimeUnavailableError {
+  const initialization = active.initializationFailure !== undefined
+    ? ` Initialization failed: ${active.initializationFailure}.`
+    : '';
+  return new WorkflowRuntimeUnavailableError(
+    `Workflow Engine is quarantined.${initialization} Shutdown failed: ${active.closeFailure}. ` +
+      'Restart the control agent before running or reloading workflows.'
+  );
+}
+
+function workflowName(value: unknown): string {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 256) {
+    throw new WorkflowRuntimeUnavailableError(
+      'workflowNames must contain strings between 1 and 256 characters.'
+    );
+  }
+  return value;
+}

package/agent/workflow/runtimeConfig.ts

@@ -0,0 +1,103 @@
+import { basename } from 'node:path';
+import { safeErrorMessage } from '../errorMessage';
+import { managedAuthToken } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import type { WorkflowRuntimeStatus } from './runtime';
+
+export class WorkflowRuntimeUnavailableError extends Error {}
+
+export interface WorkflowRuntimeOptions {
+  queueName: string;
+  concurrency: number;
+}
+
+export interface RuntimeStatusSource extends WorkflowRuntimeOptions {
+  moduleName: string;
+  workflowNames: string[];
+}
+
+export function configuredWorkflowModule(config: ServerConfig): string | undefined {
+  return effectiveEnvironment(config, 'BUNQUEUE_WORKFLOW_MODULE')?.trim() || undefined;
+}
+
+export function workflowRuntimeOptions(config: ServerConfig): WorkflowRuntimeOptions {
+  const queueName = effectiveEnvironment(config, 'BUNQUEUE_WORKFLOW_QUEUE_NAME')?.trim() || '__wf:steps';
+  if (queueName.length > 256 || /[\u0000-\u001f\u007f]/.test(queueName)) {
+    throw new WorkflowRuntimeUnavailableError(
+      'BUNQUEUE_WORKFLOW_QUEUE_NAME must contain 1–256 printable characters.'
+    );
+  }
+  const rawConcurrency = effectiveEnvironment(config, 'BUNQUEUE_WORKFLOW_CONCURRENCY')?.trim();
+  const concurrency = rawConcurrency ? Number(rawConcurrency) : 5;
+  if (
+    (rawConcurrency !== undefined && !/^\d+$/.test(rawConcurrency)) ||
+    !Number.isSafeInteger(concurrency) ||
+    concurrency < 1 ||
+    concurrency > 1_000
+  ) {
+    throw new WorkflowRuntimeUnavailableError(
+      'BUNQUEUE_WORKFLOW_CONCURRENCY must be an integer between 1 and 1000.'
+    );
+  }
+  return { queueName, concurrency };
+}
+
+export function workflowRuntimeSignature(
+  config: ServerConfig,
+  path: string,
+  modified: number,
+  options: WorkflowRuntimeOptions
+): string {
+  return JSON.stringify([
+    path,
+    modified,
+    config.dataPath,
+    config.tcpPort,
+    managedAuthToken(config),
+    options.queueName,
+    options.concurrency,
+  ]);
+}
+
+export function stoppedRuntimeStatus(
+  config: ServerConfig,
+  modulePath: string
+): WorkflowRuntimeStatus {
+  try {
+    return {
+      configured: true,
+      ready: false,
+      moduleName: basename(modulePath),
+      workflowNames: [],
+      ...workflowRuntimeOptions(config),
+      error: 'Managed Bunqueue server is stopped.',
+    };
+  } catch (error) {
+    return {
+      configured: true,
+      ready: false,
+      moduleName: basename(modulePath),
+      workflowNames: [],
+      error: messageOf(error),
+    };
+  }
+}
+
+export function readyRuntimeStatus(active: RuntimeStatusSource): WorkflowRuntimeStatus {
+  return {
+    configured: true,
+    ready: true,
+    moduleName: active.moduleName,
+    workflowNames: active.workflowNames,
+    queueName: active.queueName,
+    concurrency: active.concurrency,
+  };
+}
+
+export function messageOf(error: unknown): string {
+  return safeErrorMessage(error);
+}
+
+function effectiveEnvironment(config: ServerConfig, key: string): string | undefined {
+  return Object.hasOwn(config.extraEnv, key) ? config.extraEnv[key] : process.env[key];
+}

package/agent/workflow/runtimeRoutes.ts

@@ -0,0 +1,162 @@
+import type { ExecutionState } from 'bunqueue/workflow';
+import { assertManagedTarget } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import { readLimitedJsonBody } from '../server/jsonBody';
+import type {
+  ManagedRuntimeAdmission,
+  ManagedRuntimeSnapshot,
+} from '../server/managedRuntime';
+import type { WorkflowRuntimePort } from './runtime';
+
+const MAX_WORKFLOW_BODY_BYTES = 1024 * 1024;
+
+export interface WorkflowRuntimeRouteResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+const TERMINAL_STATES = new Set<ExecutionState>(['completed', 'failed']);
+
+export async function routeWorkflowRuntimeRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  config: ServerConfig,
+  runtime: WorkflowRuntimePort,
+  serverRunning: boolean,
+  admission?: ManagedRuntimeAdmission
+): Promise<WorkflowRuntimeRouteResponse | null> {
+  if (!isRuntimePath(pathname, method)) return null;
+  const query = exactTargetQuery(request.url);
+  assertManagedTarget(query, config);
+  const admitted = <T>(
+    requiresRunning: boolean,
+    operation: (snapshot: ManagedRuntimeSnapshot) => Promise<T>
+  ): Promise<T> => {
+    const execute = async (snapshot: ManagedRuntimeSnapshot) => {
+      assertManagedTarget(query, snapshot.config);
+      if (requiresRunning && !snapshot.running) {
+        throw new Error('Start the managed Bunqueue server before workflow control.');
+      }
+      return operation(snapshot);
+    };
+    return admission ? admission(execute) : execute({ config, running: serverRunning });
+  };
+  if (pathname === '/workflows/runtime' && method === 'GET') {
+    return success(
+      await admitted(false, ({ config: current, running }) => runtime.status(current, running))
+    );
+  }
+  if (!serverRunning) throw new Error('Start the managed Bunqueue server before workflow control.');
+  if (pathname === '/workflows/runtime/reload') {
+    return success(await admitted(true, ({ config: current }) => runtime.reload(current)));
+  }
+  if (pathname === '/workflows/start') {
+    const body = record(await workflowBody(request), ['workflowName', 'input']);
+    const workflowName = bounded(body.workflowName, 'workflowName', 256);
+    return success({
+      run: await admitted(true, ({ config: current }) =>
+        runtime.start(current, workflowName, body.input)
+      ),
+    });
+  }
+  if (pathname === '/workflows/recover') {
+    return success({
+      recovered: await admitted(true, ({ config: current }) => runtime.recover(current)),
+    });
+  }
+  if (pathname === '/workflows/archive' || pathname === '/workflows/cleanup') {
+    const body = record(await workflowBody(request), ['maxAgeMs', 'states']);
+    const maxAgeMs = boundedAge(body.maxAgeMs);
+    const states = terminalStates(body.states);
+    const affected = await admitted(true, ({ config: current }) =>
+      pathname === '/workflows/archive'
+        ? runtime.archive(current, maxAgeMs, states)
+        : runtime.cleanup(current, maxAgeMs, states)
+    );
+    return success({ affected });
+  }
+  const match = pathname.match(/^\/workflows\/([^/]+)\/(signal|resume-compensation|abandon-compensation)$/);
+  if (!match) return null;
+  const id = bounded(decodeURIComponent(match[1]), 'executionId', 1024);
+  if (match[2] === 'signal') {
+    const body = record(await workflowBody(request), ['event', 'payload']);
+    const event = bounded(body.event, 'event', 256);
+    await admitted(true, ({ config: current }) =>
+      runtime.signal(current, id, event, body.payload)
+    );
+  } else if (match[2] === 'resume-compensation') {
+    await admitted(true, ({ config: current }) => runtime.resumeCompensation(current, id));
+  } else {
+    await admitted(true, ({ config: current }) => runtime.abandonCompensation(current, id));
+  }
+  return success({ applied: true });
+}
+
+function isRuntimePath(pathname: string, method: string): boolean {
+  if (method === 'GET') return pathname === '/workflows/runtime';
+  if (method !== 'POST') return false;
+  return (
+    ['/workflows/runtime/reload', '/workflows/start', '/workflows/recover', '/workflows/archive', '/workflows/cleanup'].includes(pathname) ||
+    /^\/workflows\/[^/]+\/(signal|resume-compensation|abandon-compensation)$/.test(pathname)
+  );
+}
+
+function exactTargetQuery(url: string): URLSearchParams {
+  const query = new URL(url).searchParams;
+  for (const key of query.keys()) {
+    if (key !== 'target') throw new Error(`Unknown workflow control option: ${key}`);
+    if (query.getAll(key).length !== 1) throw new Error(`Duplicate workflow control option: ${key}`);
+  }
+  return query;
+}
+
+function success(value: unknown): WorkflowRuntimeRouteResponse {
+  return { status: 200, body: { ok: true, result: value } };
+}
+
+function record(value: unknown, allowed: string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Workflow control body must be an object');
+  }
+  const body = value as Record<string, unknown>;
+  const unknown = Object.keys(body).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`Unknown workflow control option: ${unknown}`);
+  return body;
+}
+
+function workflowBody(request: Request): Promise<unknown> {
+  return readLimitedJsonBody(request, {
+    scope: 'Workflow control',
+    maxBytes: MAX_WORKFLOW_BODY_BYTES,
+    limitLabel: '1 MiB',
+  });
+}
+
+function bounded(value: unknown, label: string, maximum: number): string {
+  if (typeof value !== 'string' || value.length < 1 || value.length > maximum) {
+    throw new Error(`Workflow ${label} must contain 1–${maximum} characters`);
+  }
+  return value;
+}
+
+function boundedAge(value: unknown): number {
+  const tenYears = 10 * 365 * 24 * 60 * 60 * 1_000;
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > tenYears) {
+    throw new Error('Workflow maxAgeMs must be an integer between 0 and ten years');
+  }
+  return value as number;
+}
+
+function terminalStates(value: unknown): ExecutionState[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > TERMINAL_STATES.size) {
+    throw new Error('Workflow maintenance states must contain completed and/or failed');
+  }
+  const states = value.map((state) => {
+    if (!TERMINAL_STATES.has(state as ExecutionState)) {
+      throw new Error('Workflow maintenance accepts only terminal completed/failed states');
+    }
+    return state as ExecutionState;
+  });
+  return Array.from(new Set(states));
+}

package/agent/workflow/sqlite.ts

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import { MissingDbError } from '../db';
+import type { WorkflowStoreKind } from './types';
+
+export interface WorkflowSchema {
+  table: string;
+  hasMeta: boolean;
+}
+
+const REQUIRED_COLUMNS = [
+  'id',
+  'workflow_name',
+  'state',
+  'input',
+  'steps',
+  'current_node_index',
+  'resolved_steps',
+  'signals',
+  'created_at',
+  'updated_at',
+];
+
+export function openWorkflowDatabase(path: string): Database {
+  if (!existsSync(path)) {
+    throw new MissingDbError(
+      `Database not found at "${path}" — configure the Workflow Engine dataPath and start it once.`
+    );
+  }
+  try {
+    return new Database(path, { readonly: true });
+  } catch (error) {
+    throw new Error(`Could not open workflow database: ${(error as Error).message}`);
+  }
+}
+
+export function workflowSchema(
+  db: Database,
+  kind: WorkflowStoreKind
+): WorkflowSchema | null {
+  const table = kind === 'archive' ? 'workflow_executions_archive' : 'workflow_executions';
+  if (!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) {
+    return null;
+  }
+  const found = new Set(
+    (db.query(`PRAGMA table_info("${table}")`).all() as { name: string }[]).map((row) => row.name)
+  );
+  const missing = REQUIRED_COLUMNS.filter((name) => !found.has(name));
+  if (kind === 'archive' && !found.has('archived_at')) missing.push('archived_at');
+  if (missing.length > 0) throw new Error(`Invalid ${table} schema: missing ${missing.join(', ')}`);
+  return { table, hasMeta: found.has('meta') };
+}