@devflow-tools/database 0.16.21 → 0.16.23

package/dist/database.js

@@ -11,6 +11,8 @@ 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 learning_candidates_1 = require("./learning-candidates");
+const workflow_workers_1 = require("./workflow-workers");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -477,6 +479,74 @@ 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_learning_candidates (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        scope TEXT NOT NULL CHECK(scope IN ('project', 'global')),
+        state TEXT NOT NULL DEFAULT 'observed'
+          CHECK(state IN ('observed', 'candidate', 'shadow', 'evaluated', 'active', 'rejected', 'retired')),
+        kind TEXT NOT NULL CHECK(kind IN ('convention', 'workflow', 'tool_preference', 'correction')),
+        trigger_json TEXT NOT NULL,
+        instruction TEXT NOT NULL,
+        confidence REAL NOT NULL CHECK(confidence BETWEEN 0 AND 1),
+        overlay_version INTEGER NOT NULL DEFAULT 1 CHECK(overlay_version > 0),
+        supporting_sessions INTEGER NOT NULL DEFAULT 0 CHECK(supporting_sessions >= 0),
+        successful_outcomes INTEGER NOT NULL DEFAULT 0 CHECK(successful_outcomes >= 0),
+        contradictions INTEGER NOT NULL DEFAULT 0 CHECK(contradictions >= 0),
+        manual_only INTEGER NOT NULL DEFAULT 0 CHECK(manual_only IN (0, 1)),
+        risk TEXT NOT NULL DEFAULT 'low' CHECK(risk IN ('low', 'medium', 'high')),
+        grader_receipt TEXT,
+        expires_at INTEGER,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_candidates_project
+        ON devflow_learning_candidates(project_root, state, kind, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidate_versions (
+        candidate_id TEXT NOT NULL,
+        version INTEGER NOT NULL CHECK(version > 0),
+        trigger_json TEXT NOT NULL,
+        instruction TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY(candidate_id, version)
+      );
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidate_evidence (
+        id TEXT PRIMARY KEY,
+        candidate_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        memory_observation_id TEXT,
+        outcome_id TEXT,
+        source_type TEXT NOT NULL
+          CHECK(source_type IN ('memory', 'correction', 'workflow_outcome', 'tool_preference', 'convention', 'grader', 'manual')),
+        polarity TEXT NOT NULL CHECK(polarity IN ('supporting', 'contradicting')),
+        outcome TEXT NOT NULL DEFAULT 'unknown' CHECK(outcome IN ('positive', 'negative', 'unknown')),
+        evidence_hash TEXT NOT NULL,
+        receipt TEXT,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        resolved_at INTEGER,
+        UNIQUE(candidate_id, evidence_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_evidence_candidate
+        ON devflow_learning_candidate_evidence(candidate_id, polarity, resolved_at, created_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_activation_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        candidate_id TEXT NOT NULL,
+        from_state TEXT NOT NULL,
+        to_state TEXT NOT NULL,
+        reason TEXT NOT NULL,
+        grader_receipt TEXT,
+        manual_approval INTEGER NOT NULL DEFAULT 0 CHECK(manual_approval IN (0, 1)),
+        changed_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_activation_candidate
+        ON devflow_learning_activation_history(candidate_id, changed_at DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_host_actions (
         action_id TEXT PRIMARY KEY,
         run_id TEXT NOT NULL,
@@ -549,6 +619,85 @@ class DevFlowDatabase {
       BEGIN
         SELECT RAISE(ABORT, 'devflow_host_action_events is append-only');
       END;
+
+      CREATE TABLE IF NOT EXISTS devflow_workflow_workers (
+        worker_id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL,
+        step_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        branch TEXT NOT NULL,
+        worktree_path TEXT NOT NULL,
+        host TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'planned'
+          CHECK(state IN ('planned','leased','starting','running','reported','verifying','merge_ready','merged','hold','failed','cancelled')),
+        lease_owner TEXT,
+        lease_expires_at INTEGER,
+        heartbeat_at INTEGER,
+        context_receipt TEXT NOT NULL,
+        retrieval_session_id TEXT,
+        session_id TEXT,
+        execution_id TEXT,
+        base_revision TEXT NOT NULL,
+        final_revision TEXT,
+        allowed_files TEXT NOT NULL DEFAULT '[]',
+        handoff_json TEXT NOT NULL DEFAULT '{}',
+        hold_reason TEXT,
+        failure_reason TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        finished_at INTEGER,
+        UNIQUE(run_id, step_id),
+        UNIQUE(worktree_path),
+        CHECK(
+          (state IN ('merged','failed','cancelled') AND finished_at IS NOT NULL)
+          OR (state NOT IN ('merged','failed','cancelled') AND finished_at IS NULL)
+        )
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_workers_project
+        ON devflow_workflow_workers(project_root, state, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_workflow_workers_lease
+        ON devflow_workflow_workers(project_root, state, lease_expires_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_worker_events (
+        event_id TEXT PRIMARY KEY,
+        worker_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        from_state TEXT,
+        to_state TEXT NOT NULL,
+        reason TEXT,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_worker_events_worker
+        ON devflow_worker_events(worker_id, created_at, event_id);
+      CREATE TRIGGER IF NOT EXISTS prevent_worker_event_update
+      BEFORE UPDATE ON devflow_worker_events BEGIN
+        SELECT RAISE(ABORT, 'devflow_worker_events is append-only');
+      END;
+      CREATE TRIGGER IF NOT EXISTS prevent_worker_event_delete
+      BEFORE DELETE ON devflow_worker_events BEGIN
+        SELECT RAISE(ABORT, 'devflow_worker_events is append-only');
+      END;
+
+      CREATE TABLE IF NOT EXISTS devflow_merge_queue (
+        merge_id TEXT PRIMARY KEY,
+        worker_id TEXT NOT NULL UNIQUE,
+        project_root TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'waiting'
+          CHECK(state IN ('waiting','ready','conflict','merged','rejected')),
+        base_revision TEXT NOT NULL,
+        parent_revision TEXT NOT NULL,
+        candidate_revision TEXT NOT NULL,
+        grader_receipts TEXT NOT NULL DEFAULT '[]',
+        simulation_hash TEXT,
+        merge_commit TEXT,
+        reason TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        finished_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_merge_queue_project
+        ON devflow_merge_queue(project_root, state, created_at, merge_id);
     `);
         // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
         try {
@@ -1815,6 +1964,245 @@ class DevFlowDatabase {
             total: Number(count?.total ?? 0),
         };
     }
+    // ---- Governed Learning ----
+    upsertLearningCandidate(input) {
+        if (!input.id.trim())
+            throw new Error('Learning candidate requires an ID');
+        if (!input.projectRoot.trim())
+            throw new Error('Learning candidate requires a project root');
+        if (!input.instruction.trim())
+            throw new Error('Learning candidate requires an instruction');
+        if (!Number.isFinite(input.confidence) || input.confidence < 0 || input.confidence > 1) {
+            throw new Error('Learning candidate confidence must be between 0 and 1');
+        }
+        return this.db.transaction(() => {
+            const now = Date.now();
+            const existing = this.getLearningCandidate(input.id);
+            const triggerJson = (0, learning_candidates_1.stableLearningJson)(input.trigger);
+            const instruction = input.instruction.trim().slice(0, 2000);
+            if (!existing) {
+                this.db.prepare(`
+          INSERT INTO devflow_learning_candidates (
+            id, project_root, scope, state, kind, trigger_json, instruction,
+            confidence, overlay_version, supporting_sessions, successful_outcomes,
+            contradictions, manual_only, risk, expires_at, created_at, updated_at
+          ) VALUES (?, ?, ?, 'observed', ?, ?, ?, ?, 1, 0, 0, 0, ?, ?, ?, ?, ?)
+        `).run(input.id, input.projectRoot, input.scope, input.kind, triggerJson, instruction, input.confidence, input.manualOnly ? 1 : 0, input.risk ?? 'low', input.expiresAt ?? null, now, now);
+                this.insertLearningCandidateVersion(input.id, 1, triggerJson, instruction, now);
+                return this.getLearningCandidate(input.id);
+            }
+            if (existing.projectRoot !== input.projectRoot || existing.scope !== input.scope || existing.kind !== input.kind) {
+                throw new Error(`Learning candidate identity mismatch for ${input.id}`);
+            }
+            const contentChanged = (0, learning_candidates_1.stableLearningJson)(existing.trigger) !== triggerJson
+                || existing.instruction !== instruction;
+            const nextVersion = contentChanged ? existing.overlayVersion + 1 : existing.overlayVersion;
+            const nextState = contentChanged && (existing.state === 'active' || existing.state === 'evaluated')
+                ? 'shadow'
+                : existing.state;
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET trigger_json = ?, instruction = ?, confidence = ?, overlay_version = ?,
+            state = ?, manual_only = MAX(manual_only, ?),
+            risk = CASE
+              WHEN risk = 'high' OR ? = 'high' THEN 'high'
+              WHEN risk = 'medium' OR ? = 'medium' THEN 'medium'
+              ELSE 'low'
+            END,
+            expires_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(triggerJson, instruction, Math.max(existing.confidence, input.confidence), nextVersion, nextState, input.manualOnly ? 1 : 0, input.risk ?? 'low', input.risk ?? 'low', input.expiresAt ?? existing.expiresAt ?? null, now, input.id);
+            if (contentChanged) {
+                this.insertLearningCandidateVersion(input.id, nextVersion, triggerJson, instruction, now);
+                if (nextState !== existing.state) {
+                    this.insertLearningActivation(input.id, existing.state, nextState, 'candidate_content_changed', undefined, false, now);
+                }
+            }
+            return this.getLearningCandidate(input.id);
+        });
+    }
+    getLearningCandidate(id) {
+        const row = this.db.prepare('SELECT * FROM devflow_learning_candidates WHERE id = ?')
+            .get(id);
+        return row ? (0, learning_candidates_1.mapLearningCandidateRow)(row) : null;
+    }
+    listLearningCandidates(options = {}) {
+        const predicates = [];
+        const params = [];
+        if (options.projectRoot) {
+            predicates.push('(project_root = ? OR scope = \'global\')');
+            params.push(options.projectRoot);
+        }
+        const states = [...new Set(options.states ?? [])];
+        if (states.length > 0) {
+            predicates.push(`state IN (${states.map(() => '?').join(',')})`);
+            params.push(...states);
+        }
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidates
+      ${predicates.length > 0 ? `WHERE ${predicates.join(' AND ')}` : ''}
+      ORDER BY updated_at DESC, id ASC
+      LIMIT ?
+    `).all(...params, Math.max(1, Math.min(options.limit ?? 200, 2000)));
+        return rows.map(learning_candidates_1.mapLearningCandidateRow);
+    }
+    addLearningCandidateEvidence(input) {
+        if (!input.evidenceHash.trim())
+            throw new Error('Learning evidence requires a hash');
+        if (!input.sessionId.trim())
+            throw new Error('Learning evidence requires a session ID');
+        return this.db.transaction(() => {
+            const candidate = this.getLearningCandidate(input.candidateId);
+            if (!candidate)
+                throw new Error(`Learning candidate ${input.candidateId} does not exist`);
+            if (candidate.projectRoot !== input.projectRoot && candidate.scope !== 'global') {
+                throw new Error(`Learning evidence project mismatch for ${input.candidateId}`);
+            }
+            const createdAt = input.createdAt ?? Date.now();
+            const inserted = this.db.prepare(`
+        INSERT OR IGNORE INTO devflow_learning_candidate_evidence (
+          id, candidate_id, project_root, session_id, execution_id,
+          memory_observation_id, outcome_id, source_type, polarity, outcome,
+          evidence_hash, receipt, payload_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.id, input.candidateId, input.projectRoot, input.sessionId, input.executionId ?? null, input.memoryObservationId ?? null, input.outcomeId ?? null, input.sourceType, input.polarity, input.outcome ?? 'unknown', input.evidenceHash, input.receipt ?? null, (0, learning_candidates_1.stableLearningJson)(input.payload ?? {}), createdAt).changes === 1;
+            if (!inserted)
+                return candidate;
+            const previousState = candidate.state;
+            const aggregates = this.getLearningEvidenceAggregates(input.candidateId);
+            let state = previousState;
+            if (state === 'observed' && aggregates.supportingSessions > 0)
+                state = 'candidate';
+            if (aggregates.contradictions > 0 && (state === 'active' || state === 'evaluated'))
+                state = 'shadow';
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET state = ?, supporting_sessions = ?, successful_outcomes = ?,
+            contradictions = ?, updated_at = ?
+        WHERE id = ?
+      `).run(state, aggregates.supportingSessions, aggregates.successfulOutcomes, aggregates.contradictions, createdAt, input.candidateId);
+            if (state !== previousState) {
+                this.insertLearningActivation(input.candidateId, previousState, state, aggregates.contradictions > 0 ? 'unresolved_contradiction' : 'first_supporting_evidence', undefined, false, createdAt);
+            }
+            return this.getLearningCandidate(input.candidateId);
+        });
+    }
+    listLearningCandidateEvidence(candidateId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidate_evidence
+      WHERE candidate_id = ? ORDER BY created_at ASC, id ASC
+    `).all(candidateId);
+        return rows.map(learning_candidates_1.mapLearningEvidenceRow);
+    }
+    resolveLearningContradiction(candidateId, evidenceId, resolvedAt = Date.now()) {
+        return this.db.transaction(() => {
+            this.db.prepare(`
+        UPDATE devflow_learning_candidate_evidence
+        SET resolved_at = ?
+        WHERE id = ? AND candidate_id = ? AND polarity = 'contradicting' AND resolved_at IS NULL
+      `).run(resolvedAt, evidenceId, candidateId);
+            const aggregates = this.getLearningEvidenceAggregates(candidateId);
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET supporting_sessions = ?, successful_outcomes = ?, contradictions = ?, updated_at = ?
+        WHERE id = ?
+      `).run(aggregates.supportingSessions, aggregates.successfulOutcomes, aggregates.contradictions, resolvedAt, candidateId);
+            const candidate = this.getLearningCandidate(candidateId);
+            if (!candidate)
+                throw new Error(`Learning candidate ${candidateId} does not exist`);
+            return candidate;
+        });
+    }
+    transitionLearningCandidate(candidateId, input) {
+        return this.db.transaction(() => {
+            const candidate = this.getLearningCandidate(candidateId);
+            if (!candidate)
+                throw new Error(`Learning candidate ${candidateId} does not exist`);
+            if (candidate.state === input.target)
+                return candidate;
+            this.assertLearningTransition(candidate, input);
+            const changedAt = input.changedAt ?? Date.now();
+            const graderReceipt = input.graderReceipt ?? candidate.graderReceipt;
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET state = ?, grader_receipt = COALESCE(?, grader_receipt), updated_at = ?
+        WHERE id = ?
+      `).run(input.target, graderReceipt ?? null, changedAt, candidateId);
+            this.insertLearningActivation(candidateId, candidate.state, input.target, input.reason, graderReceipt, input.manualApproval === true, changedAt);
+            return this.getLearningCandidate(candidateId);
+        });
+    }
+    listLearningCandidateVersions(candidateId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidate_versions
+      WHERE candidate_id = ? ORDER BY version ASC
+    `).all(candidateId);
+        return rows.map(learning_candidates_1.mapLearningVersionRow);
+    }
+    assertLearningTransition(candidate, input) {
+        const terminal = input.target === 'rejected' || input.target === 'retired';
+        const rollback = input.target === 'shadow'
+            && (candidate.state === 'active' || candidate.state === 'evaluated');
+        const legal = {
+            observed: ['candidate', 'rejected', 'retired'],
+            candidate: ['shadow', 'rejected', 'retired'],
+            shadow: ['evaluated', 'rejected', 'retired'],
+            evaluated: ['active', 'shadow', 'rejected', 'retired'],
+            active: ['shadow', 'retired'],
+            rejected: ['retired'],
+            retired: [],
+        };
+        if (!terminal && !rollback && !legal[candidate.state].includes(input.target)) {
+            throw new Error(`Illegal learning transition ${candidate.state} -> ${input.target}`);
+        }
+        if (input.target === 'shadow') {
+            if (candidate.supportingSessions < 3 || candidate.successfulOutcomes < 2) {
+                throw new Error('Learning candidate requires three sessions and two verified outcomes before shadow');
+            }
+        }
+        if (input.target === 'evaluated' && candidate.contradictions > 0) {
+            throw new Error('Learning candidate has unresolved contradictions');
+        }
+        if (input.target === 'active') {
+            const receipt = input.graderReceipt ?? candidate.graderReceipt;
+            if (!receipt)
+                throw new Error('Learning candidate activation requires a grader receipt');
+            if (candidate.contradictions > 0)
+                throw new Error('Learning candidate has unresolved contradictions');
+            const manualRequired = candidate.scope === 'global' || candidate.manualOnly || candidate.risk === 'high';
+            if (manualRequired && input.manualApproval !== true) {
+                throw new Error('Learning candidate requires manual approval');
+            }
+        }
+    }
+    getLearningEvidenceAggregates(candidateId) {
+        const row = this.db.prepare(`
+      SELECT
+        COUNT(DISTINCT CASE WHEN polarity = 'supporting' THEN session_id END) AS supporting_sessions,
+        COUNT(DISTINCT CASE WHEN polarity = 'supporting' AND outcome = 'positive' THEN session_id END) AS successful_outcomes,
+        SUM(CASE WHEN polarity = 'contradicting' AND resolved_at IS NULL THEN 1 ELSE 0 END) AS contradictions
+      FROM devflow_learning_candidate_evidence WHERE candidate_id = ?
+    `).get(candidateId);
+        return {
+            supportingSessions: Number(row?.supporting_sessions ?? 0),
+            successfulOutcomes: Number(row?.successful_outcomes ?? 0),
+            contradictions: Number(row?.contradictions ?? 0),
+        };
+    }
+    insertLearningCandidateVersion(candidateId, version, triggerJson, instruction, createdAt) {
+        this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_learning_candidate_versions
+        (candidate_id, version, trigger_json, instruction, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(candidateId, version, triggerJson, instruction, createdAt);
+    }
+    insertLearningActivation(candidateId, fromState, toState, reason, graderReceipt, manualApproval, changedAt) {
+        this.db.prepare(`
+      INSERT INTO devflow_learning_activation_history
+        (candidate_id, from_state, to_state, reason, grader_receipt, manual_approval, changed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(candidateId, fromState, toState, reason.trim().slice(0, 500), graderReceipt ?? null, manualApproval ? 1 : 0, changedAt);
+    }
     // ---- Durable Work Queue ----
     enqueueWork(input) {
         if (!input.idempotencyKey.trim())
@@ -2032,6 +2420,15 @@ class DevFlowDatabase {
         }
         return completed;
     }
+    heartbeatWork(id, owner, leaseMs, now = Date.now()) {
+        if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0)
+            return false;
+        return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET lease_expires_at = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(now + leaseMs, now, id, owner).changes === 1;
+    }
     retryWork(id, owner, error, nextAttemptAt) {
         const updatedAt = Date.now();
         return this.db.prepare(`
@@ -2998,6 +3395,232 @@ class DevFlowDatabase {
         }
         return false;
     }
+    // ---- Isolated Workflow Workers ----
+    createWorkflowWorker(input) {
+        for (const [name, value] of [
+            ['run ID', input.runId],
+            ['step ID', input.stepId],
+            ['project root', input.projectRoot],
+            ['branch', input.branch],
+            ['worktree path', input.worktreePath],
+            ['host', input.host],
+            ['context receipt', input.contextReceipt],
+            ['base revision', input.baseRevision],
+        ]) {
+            if (!value.trim())
+                throw new Error(`Workflow worker requires a ${name}`);
+        }
+        const workerId = input.workerId ?? (0, crypto_1.randomUUID)();
+        const now = Date.now();
+        return this.withImmediateTransaction(() => {
+            this.db.prepare(`
+        INSERT INTO devflow_workflow_workers (
+          worker_id, run_id, step_id, project_root, branch, worktree_path, host,
+          state, context_receipt, retrieval_session_id, session_id, execution_id,
+          base_revision, allowed_files, handoff_json, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 'planned', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT DO NOTHING
+      `).run(workerId, input.runId, input.stepId, input.projectRoot, input.branch, input.worktreePath, input.host, input.contextReceipt, input.retrievalSessionId ?? null, input.sessionId ?? null, input.executionId ?? null, input.baseRevision, JSON.stringify([...new Set(input.allowedFiles ?? [])].sort()), JSON.stringify(input.handoff ?? {}), now, now);
+            const rows = this.db.prepare(`
+        SELECT * FROM devflow_workflow_workers
+        WHERE worker_id = ? OR (run_id = ? AND step_id = ?)
+      `).all(workerId, input.runId, input.stepId);
+            if (rows.length !== 1)
+                throw new Error(`WORKFLOW_WORKER_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+            const record = (0, workflow_workers_1.mapWorkflowWorkerRow)(rows[0]);
+            if (record.workerId !== workerId
+                || record.projectRoot !== input.projectRoot
+                || record.worktreePath !== input.worktreePath
+                || record.contextReceipt !== input.contextReceipt) {
+                throw new Error(`WORKFLOW_WORKER_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+            }
+            if (record.createdAt === now)
+                this.appendWorkflowWorkerEvent(record, undefined, 'planned', undefined, {}, now);
+            return record;
+        });
+    }
+    getWorkflowWorker(projectRoot, workerId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_workflow_workers WHERE project_root = ? AND worker_id = ?
+    `).get(projectRoot, workerId);
+        return row ? (0, workflow_workers_1.mapWorkflowWorkerRow)(row) : null;
+    }
+    listWorkflowWorkers(projectRoot, options = {}) {
+        const conditions = ['project_root = ?'];
+        const values = [projectRoot];
+        if (options.runId) {
+            conditions.push('run_id = ?');
+            values.push(options.runId);
+        }
+        if (options.states?.length) {
+            conditions.push(`state IN (${options.states.map(() => '?').join(',')})`);
+            values.push(...options.states);
+        }
+        values.push(Math.max(1, Math.min(options.limit ?? 200, 2000)));
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_workflow_workers
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY updated_at DESC, worker_id ASC LIMIT ?
+    `).all(...values);
+        return rows.map(workflow_workers_1.mapWorkflowWorkerRow);
+    }
+    listWorkflowWorkerEvents(projectRoot, workerId) {
+        return this.db.prepare(`
+      SELECT * FROM devflow_worker_events
+      WHERE project_root = ? AND worker_id = ?
+      ORDER BY created_at ASC, event_id ASC
+    `).all(projectRoot, workerId).map(workflow_workers_1.mapWorkflowWorkerEventRow);
+    }
+    leaseWorkflowWorker(projectRoot, workerId, owner, leaseMs, now = Date.now()) {
+        if (!owner.trim())
+            throw new Error('Workflow worker lease owner is required');
+        if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0)
+            throw new Error('Workflow worker lease must be positive');
+        return this.transitionWorkflowWorker({
+            projectRoot,
+            workerId,
+            target: 'leased',
+            leaseOwner: owner,
+            leaseExpiresAt: now + leaseMs,
+            heartbeatAt: now,
+            now,
+        });
+    }
+    heartbeatWorkflowWorker(projectRoot, workerId, owner, leaseMs, now = Date.now()) {
+        const result = this.db.prepare(`
+      UPDATE devflow_workflow_workers
+      SET heartbeat_at = ?, lease_expires_at = ?, updated_at = ?
+      WHERE project_root = ? AND worker_id = ? AND lease_owner = ?
+        AND state IN ('leased','starting','running','reported','verifying','merge_ready')
+    `).run(now, now + leaseMs, now, projectRoot, workerId, owner);
+        if (result.changes !== 1)
+            throw new Error(`WORKFLOW_WORKER_HEARTBEAT_REJECTED:${workerId}`);
+        return this.getWorkflowWorker(projectRoot, workerId);
+    }
+    transitionWorkflowWorker(input) {
+        return this.withImmediateTransaction(() => {
+            const existing = this.getWorkflowWorker(input.projectRoot, input.workerId);
+            if (!existing)
+                throw new Error(`WORKFLOW_WORKER_NOT_FOUND:${input.workerId}`);
+            if (workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES.has(existing.state)) {
+                if (existing.state === input.target)
+                    return existing;
+                throw new Error(`WORKFLOW_WORKER_TERMINAL_CONFLICT:${input.workerId}`);
+            }
+            if (!workflow_workers_1.LEGAL_WORKFLOW_WORKER_TRANSITIONS[existing.state].includes(input.target)) {
+                throw new Error(`WORKFLOW_WORKER_INVALID_TRANSITION:${existing.state}->${input.target}`);
+            }
+            if (existing.leaseOwner && input.leaseOwner && existing.leaseOwner !== input.leaseOwner) {
+                throw new Error(`WORKFLOW_WORKER_LEASE_CONFLICT:${input.workerId}`);
+            }
+            const now = input.now ?? Date.now();
+            const terminal = workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES.has(input.target);
+            const clearLease = terminal || input.target === 'hold';
+            const reason = input.reason?.trim().slice(0, 1000);
+            const result = this.db.prepare(`
+        UPDATE devflow_workflow_workers SET
+          state = ?,
+          lease_owner = CASE WHEN ? THEN NULL ELSE COALESCE(?, lease_owner) END,
+          lease_expires_at = CASE WHEN ? THEN NULL ELSE COALESCE(?, lease_expires_at) END,
+          heartbeat_at = COALESCE(?, heartbeat_at),
+          final_revision = COALESCE(?, final_revision),
+          handoff_json = CASE WHEN ? IS NULL THEN handoff_json ELSE ? END,
+          hold_reason = CASE WHEN ? = 'hold' THEN ? ELSE hold_reason END,
+          failure_reason = CASE WHEN ? = 'failed' THEN ? ELSE failure_reason END,
+          updated_at = ?, finished_at = ?
+        WHERE project_root = ? AND worker_id = ? AND state = ?
+      `).run(input.target, clearLease ? 1 : 0, input.leaseOwner ?? null, clearLease ? 1 : 0, input.leaseExpiresAt ?? null, input.heartbeatAt ?? null, input.finalRevision ?? null, input.handoff === undefined ? null : 1, JSON.stringify(input.handoff ?? {}), input.target, reason ?? null, input.target, reason ?? null, now, terminal ? now : null, input.projectRoot, input.workerId, existing.state);
+            if (result.changes !== 1)
+                throw new Error(`WORKFLOW_WORKER_UPDATE_CONFLICT:${input.workerId}`);
+            const updated = this.getWorkflowWorker(input.projectRoot, input.workerId);
+            this.appendWorkflowWorkerEvent(updated, existing.state, input.target, reason, input.handoff ?? {}, now);
+            return updated;
+        });
+    }
+    recoverExpiredWorkflowWorkers(projectRoot, now = Date.now()) {
+        const expired = this.listWorkflowWorkers(projectRoot, {
+            states: ['leased', 'starting', 'running', 'reported', 'verifying', 'merge_ready'],
+            limit: 2000,
+        }).filter(worker => worker.leaseExpiresAt !== undefined && worker.leaseExpiresAt <= now);
+        return expired.map(worker => this.transitionWorkflowWorker({
+            projectRoot,
+            workerId: worker.workerId,
+            target: 'hold',
+            leaseOwner: worker.leaseOwner,
+            reason: 'lease_expired_dirty_worktree_requires_inspection',
+            now,
+        }));
+    }
+    enqueueWorkflowMerge(input) {
+        const now = Date.now();
+        const mergeId = input.mergeId ?? (0, crypto_1.randomUUID)();
+        this.db.prepare(`
+      INSERT INTO devflow_merge_queue (
+        merge_id, worker_id, project_root, state, base_revision, parent_revision,
+        candidate_revision, grader_receipts, simulation_hash, created_at, updated_at
+      ) VALUES (?, ?, ?, 'waiting', ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(worker_id) DO NOTHING
+    `).run(mergeId, input.workerId, input.projectRoot, input.baseRevision, input.parentRevision, input.candidateRevision, JSON.stringify([...new Set(input.graderReceipts ?? [])].sort()), input.simulationHash ?? null, now, now);
+        const record = this.getWorkflowMergeByWorker(input.projectRoot, input.workerId);
+        if (!record
+            || record.baseRevision !== input.baseRevision
+            || record.candidateRevision !== input.candidateRevision) {
+            throw new Error(`WORKFLOW_MERGE_IDENTITY_CONFLICT:${input.workerId}`);
+        }
+        return record;
+    }
+    getWorkflowMerge(projectRoot, mergeId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ? AND merge_id = ?
+    `).get(projectRoot, mergeId);
+        return row ? (0, workflow_workers_1.mapWorkflowMergeRow)(row) : null;
+    }
+    getWorkflowMergeByWorker(projectRoot, workerId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ? AND worker_id = ?
+    `).get(projectRoot, workerId);
+        return row ? (0, workflow_workers_1.mapWorkflowMergeRow)(row) : null;
+    }
+    listWorkflowMerges(projectRoot, limit = 200) {
+        return this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ?
+      ORDER BY created_at ASC, merge_id ASC LIMIT ?
+    `).all(projectRoot, Math.max(1, Math.min(limit, 2000))).map(workflow_workers_1.mapWorkflowMergeRow);
+    }
+    transitionWorkflowMerge(projectRoot, mergeId, target, update = {}, now = Date.now()) {
+        const existing = this.getWorkflowMerge(projectRoot, mergeId);
+        if (!existing)
+            throw new Error(`WORKFLOW_MERGE_NOT_FOUND:${mergeId}`);
+        const legal = {
+            waiting: ['ready', 'conflict', 'rejected'],
+            ready: ['conflict', 'merged', 'rejected'],
+            conflict: ['waiting', 'rejected'],
+            merged: [],
+            rejected: [],
+        };
+        if (!legal[existing.state].includes(target)) {
+            if (existing.state === target)
+                return existing;
+            throw new Error(`WORKFLOW_MERGE_INVALID_TRANSITION:${existing.state}->${target}`);
+        }
+        const terminal = target === 'merged' || target === 'rejected';
+        const result = this.db.prepare(`
+      UPDATE devflow_merge_queue SET state = ?, parent_revision = COALESCE(?, parent_revision),
+        simulation_hash = COALESCE(?, simulation_hash), merge_commit = COALESCE(?, merge_commit),
+        reason = COALESCE(?, reason), updated_at = ?, finished_at = ?
+      WHERE project_root = ? AND merge_id = ? AND state = ?
+    `).run(target, update.parentRevision ?? null, update.simulationHash ?? null, update.mergeCommit ?? null, update.reason?.trim().slice(0, 1000) ?? null, now, terminal ? now : null, projectRoot, mergeId, existing.state);
+        if (result.changes !== 1)
+            throw new Error(`WORKFLOW_MERGE_UPDATE_CONFLICT:${mergeId}`);
+        return this.getWorkflowMerge(projectRoot, mergeId);
+    }
+    appendWorkflowWorkerEvent(record, fromState, toState, reason, payload, createdAt) {
+        this.db.prepare(`
+      INSERT INTO devflow_worker_events (
+        event_id, worker_id, project_root, from_state, to_state, reason, payload_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run((0, crypto_1.randomUUID)(), record.workerId, record.projectRoot, fromState ?? null, toState, reason ?? null, JSON.stringify(payload), createdAt);
+    }
     // Convenience methods for raw SQL queries (used by AutoChecker)
     all(sql, ...params) {
         return this.db.prepare(sql).all(...params);

package/dist/index.d.ts

@@ -6,4 +6,8 @@ export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessi
 export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalCycleRecord, RetrievalGapKind, RetrievalGapRecord, RetrievalSessionRecord, RetrievalSessionState, } from './retrieval-sessions';
 export type { FailHostActionInput, HostActionRecord, HostActionState, ReportHostActionInput, RequestHostActionInput, StartHostActionInput, VerifyHostActionInput, } from './host-actions';
 export { mapSessionObligationRow, normalizeTurnId, } from './obligation-ledger';
+export { LEGAL_WORKFLOW_WORKER_TRANSITIONS, TERMINAL_WORKFLOW_WORKER_STATES, mapWorkflowMergeRow, mapWorkflowWorkerEventRow, mapWorkflowWorkerRow, } from './workflow-workers';
+export type { CreateWorkflowWorkerInput, EnqueueWorkflowMergeInput, TransitionWorkflowWorkerInput, WorkflowMergeRecord, WorkflowMergeState, WorkflowWorkerEventRecord, WorkflowWorkerRecord, WorkflowWorkerState, } from './workflow-workers';
+export { mapLearningCandidateRow, mapLearningEvidenceRow, mapLearningVersionRow, stableLearningJson, } from './learning-candidates';
+export type { AddLearningCandidateEvidenceInput, LearningCandidateEvidenceRecord, LearningCandidateKind, LearningCandidateRecord, LearningCandidateState, LearningCandidateVersionRecord, LearningEvidencePolarity, LearningOutcomeState, TransitionLearningCandidateInput, UpsertLearningCandidateInput, } from './learning-candidates';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';