@devflow-tools/database 0.16.17 → 0.16.19

package/dist/database.js

@@ -9,6 +9,7 @@ const fs_1 = require("fs");
 const os_1 = require("os");
 const crypto_1 = require("crypto");
 const obligation_ledger_1 = require("./obligation-ledger");
+const host_actions_1 = require("./host-actions");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -430,6 +431,79 @@ 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)
         try {
@@ -2517,6 +2591,182 @@ class DevFlowDatabase {
             createdAt: Number(row.created_at),
         }));
     }
+    // ---- Durable Host Actions ----
+    requestHostAction(input) {
+        this.validateHostActionIdentity(input);
+        const actionId = input.actionId ?? (0, crypto_1.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);
+            if (rows.length !== 1) {
+                throw new Error(`HOST_ACTION_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+            }
+            const record = (0, host_actions_1.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) {
+        return this.transitionHostAction(input, 'running', {});
+    }
+    reportHostAction(input) {
+        return this.transitionHostAction(input, 'reported', input.report, input.evidenceHash);
+    }
+    verifyHostAction(input) {
+        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) {
+        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, actionId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_host_actions
+      WHERE project_root = ? AND action_id = ?
+    `).get(projectRoot, actionId);
+        return row ? (0, host_actions_1.mapHostActionRow)(row) : null;
+    }
+    listHostActionsForRun(projectRoot, runId) {
+        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);
+        return rows.map(host_actions_1.mapHostActionRow);
+    }
+    transitionHostAction(identity, targetState, report, evidenceHash, requireNonEmptyReport = false) {
+        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 = (0, host_actions_1.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
+                    && (0, host_actions_1.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;
+        });
+    }
+    appendHostActionEvent(record, fromState, toState, createdAt) {
+        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((0, crypto_1.randomUUID)(), record.actionId, record.projectRoot, record.runId, record.stepId, fromState, toState, (0, host_actions_1.serializeHostActionReport)(record.report), record.evidenceHash ?? null, createdAt);
+    }
+    validateHostActionIdentity(input) {
+        const fields = [
+            ['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}`);
+        }
+    }
+    withImmediateTransaction(operation) {
+        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;
+        }
+    }
+    isTerminalHostActionState(state) {
+        return state === 'verified'
+            || state === 'failed'
+            || state === 'cancelled'
+            || state === 'degraded';
+    }
+    isLegalHostActionTransition(fromState, toState) {
+        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, ...params) {
         return this.db.prepare(sql).all(...params);

package/dist/host-actions.d.ts

@@ -0,0 +1,47 @@
+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';
+}
+export declare function isHostActionState(value: unknown): value is HostActionState;
+export declare function mapHostActionRow(row: Record<string, unknown>): HostActionRecord;
+export declare function serializeHostActionReport(report: Record<string, unknown>): string;
+export declare function hostActionReportsEqual(left: Record<string, unknown>, right: Record<string, unknown>): boolean;

package/dist/host-actions.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHostActionState = isHostActionState;
+exports.mapHostActionRow = mapHostActionRow;
+exports.serializeHostActionReport = serializeHostActionReport;
+exports.hostActionReportsEqual = hostActionReportsEqual;
+const HOST_ACTION_STATES = new Set([
+    'waiting',
+    'running',
+    'reported',
+    'verified',
+    'failed',
+    'cancelled',
+    'degraded',
+]);
+function isHostActionState(value) {
+    return typeof value === 'string' && HOST_ACTION_STATES.has(value);
+}
+function mapHostActionRow(row) {
+    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),
+    };
+}
+function serializeHostActionReport(report) {
+    if (!isPlainObject(report))
+        throw new Error('Host action report must be a plain object');
+    return JSON.stringify(canonicalizeJson(report, '$', new WeakSet()));
+}
+function hostActionReportsEqual(left, right) {
+    return serializeHostActionReport(left) === serializeHostActionReport(right);
+}
+function parseReport(value) {
+    if (typeof value !== 'string') {
+        throw new Error('Invalid persisted host action report_json: expected JSON text');
+    }
+    try {
+        const parsed = 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, path, ancestors) {
+    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 = Object.create(null);
+        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.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, path, ancestors) {
+    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, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function nonJsonValueError(path) {
+    return new Error(`Host action report contains a non-JSON value at ${path}`);
+}
+function isPlainObject(value) {
+    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, column) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid persisted host action ${column}`);
+    }
+    return value;
+}
+function asOptionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asFiniteNumber(value, column) {
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        throw new Error(`Invalid persisted host action ${column}`);
+    return number;
+}
+function asOptionalFiniteNumber(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
 export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, ContextReceiptRecord, ContextSelectionEventRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
 export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, 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, } from './obligation-ledger';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';

package/dist/index.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeTurnId = exports.mapSessionObligationRow = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.normalizeTurnId = exports.mapSessionObligationRow = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
 var database_1 = require("./database");
 Object.defineProperty(exports, "DevFlowDatabase", { enumerable: true, get: function () { return database_1.DevFlowDatabase; } });
 Object.defineProperty(exports, "getGlobalDevFlowDbPath", { enumerable: true, get: function () { return database_1.getGlobalDevFlowDbPath; } });
 Object.defineProperty(exports, "openGlobalDevFlowDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowDatabase; } });
+var host_actions_1 = require("./host-actions");
+Object.defineProperty(exports, "hostActionReportsEqual", { enumerable: true, get: function () { return host_actions_1.hostActionReportsEqual; } });
+Object.defineProperty(exports, "isHostActionState", { enumerable: true, get: function () { return host_actions_1.isHostActionState; } });
+Object.defineProperty(exports, "mapHostActionRow", { enumerable: true, get: function () { return host_actions_1.mapHostActionRow; } });
+Object.defineProperty(exports, "serializeHostActionReport", { enumerable: true, get: function () { return host_actions_1.serializeHostActionReport; } });
 var obligation_ledger_1 = require("./obligation-ledger");
 Object.defineProperty(exports, "mapSessionObligationRow", { enumerable: true, get: function () { return obligation_ledger_1.mapSessionObligationRow; } });
 Object.defineProperty(exports, "normalizeTurnId", { enumerable: true, get: function () { return obligation_ledger_1.normalizeTurnId; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.17",
+  "version": "0.16.19",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",