@devflow-tools/database 0.16.18 → 0.16.20

package/dist/database.js

@@ -9,6 +9,8 @@ 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 retrieval_sessions_1 = require("./retrieval-sessions");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -308,6 +310,50 @@ class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_context_selection_identity
         ON devflow_context_selection_events(project_root, session_id, execution_id, request_id);
 
+      CREATE TABLE IF NOT EXISTS devflow_retrieval_sessions (
+        id TEXT PRIMARY KEY,
+        request_id TEXT NOT NULL UNIQUE,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        query TEXT NOT NULL,
+        intent TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'open'
+          CHECK(state IN ('open', 'satisfied', 'exhausted', 'expired')),
+        cycle INTEGER NOT NULL DEFAULT 0 CHECK(cycle BETWEEN 0 AND 3),
+        max_cycles INTEGER NOT NULL DEFAULT 3 CHECK(max_cycles = 3),
+        initial_token_budget INTEGER NOT NULL CHECK(initial_token_budget >= 0),
+        remaining_token_budget INTEGER NOT NULL CHECK(remaining_token_budget >= 0),
+        baseline_receipt TEXT NOT NULL,
+        final_receipt TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_retrieval_sessions_owner
+        ON devflow_retrieval_sessions(project_root, session_id, state, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_retrieval_sessions_expiry
+        ON devflow_retrieval_sessions(state, expires_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_retrieval_cycles (
+        retrieval_session_id TEXT NOT NULL,
+        cycle INTEGER NOT NULL CHECK(cycle BETWEEN 1 AND 3),
+        gaps_json TEXT NOT NULL DEFAULT '[]',
+        selected_ids TEXT NOT NULL DEFAULT '[]',
+        rejected_ids TEXT NOT NULL DEFAULT '[]',
+        token_cost INTEGER NOT NULL CHECK(token_cost >= 0),
+        remaining_token_budget INTEGER NOT NULL CHECK(remaining_token_budget >= 0),
+        quality_json TEXT NOT NULL DEFAULT '{}',
+        receipt TEXT NOT NULL,
+        evidence_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (retrieval_session_id, cycle)
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_retrieval_cycles_receipt
+        ON devflow_retrieval_cycles(receipt);
+
       CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -430,6 +476,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 {
@@ -2106,6 +2225,183 @@ class DevFlowDatabase {
         return this.db.prepare('DELETE FROM devflow_hook_receipts WHERE project_root = ?')
             .run(projectRoot).changes > 0;
     }
+    createRetrievalSession(input) {
+        this.validateRetrievalSessionInput(input);
+        const now = Date.now();
+        const id = input.id?.trim() || (0, crypto_1.randomUUID)();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const existing = this.getRetrievalSessionByRequest(input.requestId);
+            if (existing) {
+                this.assertRetrievalIdentity(existing, input);
+                this.db.exec('COMMIT');
+                return existing;
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_retrieval_sessions
+          (id, request_id, project_root, session_id, execution_id, query, intent, state,
+           cycle, max_cycles, initial_token_budget, remaining_token_budget,
+           baseline_receipt, created_at, updated_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'open', 0, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, input.requestId, input.projectRoot, input.sessionId, input.executionId ?? null, input.query, input.intent, retrieval_sessions_1.RETRIEVAL_MAX_CYCLES, input.tokenBudget, input.tokenBudget, input.baselineReceipt, now, now, input.expiresAt);
+            const created = this.getRetrievalSession(input.projectRoot, input.sessionId, id);
+            this.db.exec('COMMIT');
+            return created;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    getRetrievalSession(projectRoot, sessionId, id) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_retrieval_sessions
+      WHERE id = ? AND project_root = ? AND session_id = ?
+    `).get(id, projectRoot, sessionId);
+        return row ? (0, retrieval_sessions_1.mapRetrievalSessionRow)(row) : null;
+    }
+    getRetrievalSessionByRequest(requestId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_retrieval_sessions WHERE request_id = ?
+    `).get(requestId);
+        return row ? (0, retrieval_sessions_1.mapRetrievalSessionRow)(row) : null;
+    }
+    listRetrievalCycles(retrievalSessionId) {
+        return this.db.prepare(`
+      SELECT * FROM devflow_retrieval_cycles
+      WHERE retrieval_session_id = ? ORDER BY cycle ASC
+    `).all(retrievalSessionId).map(retrieval_sessions_1.mapRetrievalCycleRow);
+    }
+    appendRetrievalCycle(input) {
+        if (!Number.isInteger(input.cycle) || input.cycle < 1 || input.cycle > retrieval_sessions_1.RETRIEVAL_MAX_CYCLES) {
+            throw new Error(`RETRIEVAL_INVALID_CYCLE:${input.cycle}`);
+        }
+        if (!Number.isSafeInteger(input.tokenCost) || input.tokenCost < 0
+            || !Number.isSafeInteger(input.remainingTokenBudget) || input.remainingTokenBudget < 0) {
+            throw new Error('RETRIEVAL_INVALID_BUDGET');
+        }
+        const gapsJson = (0, retrieval_sessions_1.serializeRetrievalJson)(input.gaps);
+        const selectedJson = (0, retrieval_sessions_1.serializeRetrievalJson)([...new Set(input.selectedIds)]);
+        const rejectedJson = (0, retrieval_sessions_1.serializeRetrievalJson)([...new Set(input.rejectedIds)]);
+        const qualityJson = (0, retrieval_sessions_1.serializeRetrievalJson)(input.quality);
+        const now = Date.now();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const session = this.getRetrievalSession(input.projectRoot, input.sessionId, input.retrievalSessionId);
+            if (!session)
+                throw new Error(`RETRIEVAL_SESSION_NOT_FOUND:${input.retrievalSessionId}`);
+            if (session.baselineReceipt !== input.baselineReceipt)
+                throw new Error('RETRIEVAL_BASELINE_RECEIPT_MISMATCH');
+            const existing = this.db.prepare(`
+        SELECT * FROM devflow_retrieval_cycles WHERE retrieval_session_id = ? AND cycle = ?
+      `).get(input.retrievalSessionId, input.cycle);
+            if (existing) {
+                const cycle = (0, retrieval_sessions_1.mapRetrievalCycleRow)(existing);
+                if (cycle.evidenceHash !== input.evidenceHash || cycle.receipt !== input.receipt
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.gaps) !== gapsJson
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.selectedIds) !== selectedJson
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.rejectedIds) !== rejectedJson
+                    || (0, retrieval_sessions_1.serializeRetrievalJson)(cycle.quality) !== qualityJson) {
+                    throw new Error(`RETRIEVAL_CYCLE_CONFLICT:${input.cycle}`);
+                }
+                this.db.exec('COMMIT');
+                return cycle;
+            }
+            if (session.state !== 'open')
+                throw new Error(`RETRIEVAL_SESSION_TERMINAL:${session.state}`);
+            if (session.expiresAt <= now)
+                throw new Error('RETRIEVAL_SESSION_EXPIRED');
+            if (input.cycle !== session.cycle + 1)
+                throw new Error(`RETRIEVAL_CYCLE_SEQUENCE:${session.cycle}->${input.cycle}`);
+            if (input.tokenCost > session.remainingTokenBudget
+                || input.remainingTokenBudget !== session.remainingTokenBudget - input.tokenCost) {
+                throw new Error('RETRIEVAL_BUDGET_MISMATCH');
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_retrieval_cycles
+          (retrieval_session_id, cycle, gaps_json, selected_ids, rejected_ids, token_cost,
+           remaining_token_budget, quality_json, receipt, evidence_hash, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.retrievalSessionId, input.cycle, gapsJson, selectedJson, rejectedJson, input.tokenCost, input.remainingTokenBudget, qualityJson, input.receipt, input.evidenceHash, now);
+            this.db.prepare(`
+        UPDATE devflow_retrieval_sessions
+        SET cycle = ?, remaining_token_budget = ?, updated_at = ?
+        WHERE id = ? AND project_root = ? AND session_id = ?
+      `).run(input.cycle, input.remainingTokenBudget, now, input.retrievalSessionId, input.projectRoot, input.sessionId);
+            const created = (0, retrieval_sessions_1.mapRetrievalCycleRow)(this.db.prepare(`
+        SELECT * FROM devflow_retrieval_cycles WHERE retrieval_session_id = ? AND cycle = ?
+      `).get(input.retrievalSessionId, input.cycle));
+            this.db.exec('COMMIT');
+            return created;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    finalizeRetrievalSession(input) {
+        const now = Date.now();
+        const current = this.getRetrievalSession(input.projectRoot, input.sessionId, input.id);
+        if (!current)
+            throw new Error(`RETRIEVAL_SESSION_NOT_FOUND:${input.id}`);
+        if (current.state !== 'open') {
+            if (current.state === input.state && current.finalReceipt === input.finalReceipt)
+                return current;
+            throw new Error(`RETRIEVAL_SESSION_TERMINAL:${current.state}`);
+        }
+        this.db.prepare(`
+      UPDATE devflow_retrieval_sessions SET state = ?, final_receipt = ?, updated_at = ?
+      WHERE id = ? AND project_root = ? AND session_id = ? AND state = 'open'
+    `).run(input.state, input.finalReceipt, now, input.id, input.projectRoot, input.sessionId);
+        return this.getRetrievalSession(input.projectRoot, input.sessionId, input.id);
+    }
+    expireRetrievalSessions(now = Date.now(), limit = 100) {
+        const rows = this.db.prepare(`
+      SELECT id FROM devflow_retrieval_sessions
+      WHERE state = 'open' AND expires_at <= ? ORDER BY expires_at ASC LIMIT ?
+    `).all(now, Math.max(1, Math.min(1000, Math.floor(limit))));
+        if (rows.length === 0)
+            return 0;
+        const placeholders = rows.map(() => '?').join(',');
+        return this.db.prepare(`
+      UPDATE devflow_retrieval_sessions SET state = 'expired', updated_at = ?
+      WHERE state = 'open' AND id IN (${placeholders})
+    `).run(now, ...rows.map(row => row.id)).changes;
+    }
+    validateRetrievalSessionInput(input) {
+        for (const [field, value] of Object.entries({
+            requestId: input.requestId,
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            query: input.query,
+            intent: input.intent,
+            baselineReceipt: input.baselineReceipt,
+        })) {
+            if (typeof value !== 'string' || value.trim().length === 0)
+                throw new Error(`RETRIEVAL_INVALID_${field}`);
+        }
+        if (!Number.isSafeInteger(input.tokenBudget) || input.tokenBudget < 0)
+            throw new Error('RETRIEVAL_INVALID_BUDGET');
+        if (!Number.isSafeInteger(input.expiresAt) || input.expiresAt <= Date.now())
+            throw new Error('RETRIEVAL_INVALID_EXPIRY');
+    }
+    assertRetrievalIdentity(existing, input) {
+        const matches = existing.projectRoot === input.projectRoot
+            && existing.sessionId === input.sessionId
+            && existing.executionId === input.executionId
+            && existing.query === input.query
+            && existing.intent === input.intent
+            && existing.initialTokenBudget === input.tokenBudget
+            && existing.baselineReceipt === input.baselineReceipt;
+        if (!matches)
+            throw new Error(`RETRIEVAL_REQUEST_CONFLICT:${input.requestId}`);
+    }
     upsertContextReceipt(receipt) {
         this.db.prepare(`
       INSERT INTO devflow_context_receipts
@@ -2517,6 +2813,191 @@ 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);
+    }
+    listHostActionsForSession(projectRoot, sessionId, executionId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_host_actions
+      WHERE project_root = ? AND session_id = ?
+        AND (? IS NULL OR execution_id = ?)
+      ORDER BY created_at ASC, action_id ASC
+    `).all(projectRoot, sessionId, executionId ?? null, executionId ?? null);
+        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;