forge-server 0.1.0

package/dist/pipeline/engine.js

@@ -0,0 +1,691 @@
+// PipelineEngine — the core orchestration layer for Forge projects.
+//
+// The engine owns all project + phase lifecycle operations:
+//   - Creating projects
+//   - Phase transition validation and persistence (atomic: event + project update)
+//   - Trajectory recording (start/step/complete)
+//   - Phase output persistence
+//   - Claim lifecycle for parallel implementation dispatch
+//   - History reconstruction from event log
+//   - Cycle count computation from event log
+//
+// All database writes are synchronous (better-sqlite3). External operations
+// (embedding, Qdrant, knowledge extraction) are the responsibility of MCP tool
+// handlers — this engine knows nothing about them.
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Phase type bridge
+// ---------------------------------------------------------------------------
+// The storage layer uses PipelinePhase (agent-role names) in the TypeScript
+// interface types, but the actual DB values are Phase (workflow-stage names).
+// These cast helpers make the boundary explicit without scattering `as unknown`.
+/** Cast a workflow-stage Phase to the PipelinePhase expected by event factories. */
+function pp(phase) {
+    return phase;
+}
+/** Cast a PipelinePhase DB value back to a workflow-stage Phase. */
+function wp(phase) {
+    return phase;
+}
+// ---------------------------------------------------------------------------
+// Parallel phase pairs
+// ---------------------------------------------------------------------------
+// Phases that can run concurrently. When starting a phase whose parallel
+// sibling is (or leads to) the current phase, we allow the start without
+// advancing currentPhase, so both agents can work and submit independently.
+const PARALLEL_PAIRS = new Map([
+    ['architecture', 'design'],
+    ['design', 'architecture'],
+]);
+/**
+ * Check if `toPhase` can be started as a parallel sibling of the current phase.
+ * Returns true when:
+ *  - `toPhase` has a parallel sibling, AND
+ *  - `fromPhase` is the sibling itself, OR `fromPhase` can validly transition
+ *    to the sibling (so both can start from the same predecessor).
+ */
+function isParallelStart(fromPhase, toPhase, tier) {
+    const sibling = PARALLEL_PAIRS.get(toPhase);
+    if (!sibling)
+        return false;
+    return fromPhase === sibling || isValidTransition(fromPhase, sibling, tier);
+}
+import { isValidTransition, getAvailableTransitions, isCycleTransition, getCycleKey, canCycle, getForcedAdvancePhase, } from './state-machine.js';
+import { phaseTransitionEvent, agentStartedEvent, agentCompletedEvent, projectCreatedEvent, projectCompletedEvent, claimCreatedEvent, claimCompletedEvent, claimFailedEvent, eventToParams, rowToEvent, } from './events.js';
+import { logger } from '../util/logger.js';
+export class PipelineEngineError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'PipelineEngineError';
+        this.code = code;
+        this.details = details;
+    }
+}
+// ---------------------------------------------------------------------------
+// PipelineEngine
+// ---------------------------------------------------------------------------
+export class PipelineEngine {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ---------------------------------------------------------------------------
+    // Project lifecycle
+    // ---------------------------------------------------------------------------
+    createProject(opts) {
+        const id = randomUUID();
+        const now = Date.now();
+        const tier = opts.tier ?? 'full';
+        this.db.run(`INSERT INTO projects (id, repo_id, name, description, current_phase, tier, status, created_at, updated_at, metadata)
+       VALUES (?, ?, ?, ?, 'idle', ?, 'active', ?, ?, ?)`, [
+            id,
+            opts.repoId,
+            opts.name,
+            opts.description ?? null,
+            tier,
+            now,
+            now,
+            JSON.stringify(opts.metadata ?? {}),
+        ]);
+        // Emit project_created event
+        const event = projectCreatedEvent(id, {
+            name: opts.name,
+            tier,
+            repo_id: opts.repoId,
+        });
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(event)));
+        logger.info('PipelineEngine: project created', { id, name: opts.name, tier });
+        return this.getProject(id);
+    }
+    getProject(projectId) {
+        const row = this.db.get(`SELECT * FROM projects WHERE id = ?`, [projectId]);
+        if (!row)
+            return null;
+        return this._rowToProject(row);
+    }
+    /**
+     * Lists projects with optional repo and status filters.
+     * Ordered by updated_at DESC (most recently modified first).
+     */
+    listProjects(repoId, status) {
+        const conditions = [];
+        const params = [];
+        if (repoId !== undefined) {
+            conditions.push('repo_id = ?');
+            params.push(repoId);
+        }
+        if (status !== undefined) {
+            conditions.push('status = ?');
+            params.push(status);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const rows = this.db.all(`SELECT * FROM projects ${where} ORDER BY updated_at DESC`, params);
+        return rows.map((r) => this._rowToProject(r));
+    }
+    /**
+     * Returns the most recently updated active project for a repo, or null when
+     * there is no active project for that repo.
+     */
+    getActiveProject(repoId) {
+        const row = this.db.get(`SELECT * FROM projects WHERE repo_id = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1`, [repoId]);
+        return row ? this._rowToProject(row) : null;
+    }
+    // ---------------------------------------------------------------------------
+    // Task-spec core API
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the full current state of a project: project data, full event
+     * history, active claims, derived cycle counts, and available transitions.
+     *
+     * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+     * does not exist.
+     */
+    getState(projectId) {
+        const project = this._requireProject(projectId);
+        const history = this.getEventHistory(projectId);
+        const activeClaims = this.getActiveClaims(projectId);
+        const cycleCounts = this._getCycleCounts(projectId);
+        const currentPhase = wp(project.currentPhase);
+        const availableTransitions = getAvailableTransitions(currentPhase, project.tier);
+        return { project, history, activeClaims, cycleCounts, availableTransitions };
+    }
+    /**
+     * Atomically advances a project to `toPhase` in a single SQLite transaction:
+     *   1. Validates the transition (throws on illegal transitions).
+     *   2. Checks cycle limits (throws CYCLE_LIMIT_EXCEEDED; details include the
+     *      forced advance phase so callers can decide how to proceed).
+     *   3. Inserts a phase_transition event.
+     *   4. Updates projects.current_phase and updated_at.
+     *   5. If toPhase === 'completed', marks the project status 'complete' and
+     *      emits an additional project_completed event.
+     *
+     * Throws PipelineEngineError for invalid transitions and cycle limit exceeded.
+     * All writes are in a single better-sqlite3 transaction.
+     */
+    advancePhase(projectId, toPhase, agent, payload) {
+        const project = this._requireProject(projectId);
+        if (project.status !== 'active') {
+            throw new PipelineEngineError('PROJECT_NOT_ACTIVE', `Project '${projectId}' has status '${project.status}' and cannot be advanced`, { currentPhase: project.currentPhase, status: project.status });
+        }
+        const fromPhase = wp(project.currentPhase);
+        if (!isValidTransition(fromPhase, toPhase, project.tier)) {
+            const available = getAvailableTransitions(fromPhase, project.tier);
+            throw new PipelineEngineError('INVALID_TRANSITION', `Cannot transition from '${fromPhase}' to '${toPhase}' for tier '${project.tier}'`, { currentPhase: fromPhase, attempted: toPhase, legalTransitions: available });
+        }
+        // Cycle limit check for backward edges.
+        if (isCycleTransition(fromPhase, toPhase)) {
+            const key = getCycleKey(fromPhase, toPhase);
+            const cycleCounts = this._getCycleCounts(projectId);
+            const count = cycleCounts[key] ?? 0;
+            if (!canCycle(fromPhase, toPhase, count)) {
+                const forcedPhase = getForcedAdvancePhase(fromPhase, toPhase);
+                throw new PipelineEngineError('CYCLE_LIMIT_EXCEEDED', `Cycle '${key}' has reached the maximum of ${count} iterations. Force advance to '${forcedPhase ?? 'next'}'`, { cycleKey: key, cycleCount: count, forcedAdvanceTo: forcedPhase });
+            }
+        }
+        const now = Date.now();
+        const isTerminal = toPhase === 'completed';
+        const newStatus = isTerminal ? 'complete' : 'active';
+        const transEvent = phaseTransitionEvent(projectId, pp(fromPhase), pp(toPhase), agent ?? null, payload ?? {});
+        this.db.db.transaction(() => {
+            // 1. Insert phase_transition event
+            this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(transEvent)));
+            // 2. Update project
+            this.db.run(`UPDATE projects SET current_phase = ?, updated_at = ?, status = ? WHERE id = ?`, [toPhase, now, newStatus, projectId]);
+            // 3. Emit project_completed if terminal
+            if (isTerminal) {
+                const completedEvent = projectCompletedEvent(projectId, { agent: agent ?? null });
+                this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(completedEvent)));
+            }
+        })();
+        logger.info('PipelineEngine: advancePhase', { projectId, from: fromPhase, to: toPhase, agent });
+    }
+    /**
+     * Persists a phase output to phase_outputs. Multiple outputs per phase are
+     * allowed (e.g., vision doc, refined vision doc, etc.).
+     *
+     * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+     * does not exist.
+     */
+    recordOutput(projectId, phase, outputType, content, filePath) {
+        this._requireProject(projectId);
+        this.db.run(`INSERT INTO phase_outputs (project_id, phase, output_type, content, file_path, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`, [projectId, phase, outputType, content, filePath ?? null, Date.now()]);
+    }
+    /**
+     * Returns phase outputs for a project, optionally filtered to a specific
+     * phase. Ordered by created_at ASC.
+     */
+    getOutputs(projectId, phase) {
+        this._requireProject(projectId);
+        if (phase !== undefined) {
+            return this.db.all(`SELECT * FROM phase_outputs WHERE project_id = ? AND phase = ? ORDER BY created_at ASC`, [projectId, phase]).map((r) => this._rowToPhaseOutput(r));
+        }
+        return this.getAllPhaseOutputs(projectId);
+    }
+    /**
+     * Returns all events for a project ordered by created_at ASC.
+     * This is the raw event sourcing log used for history reconstruction.
+     */
+    getEventHistory(projectId) {
+        return this.db.all(`SELECT * FROM pipeline_events WHERE project_id = ? ORDER BY created_at ASC`, [projectId]).map(rowToEvent);
+    }
+    /**
+     * Marks a project as 'archived'. Emits a project_completed event with an
+     * 'abandoned' flag. Idempotent if already archived.
+     *
+     * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+     * does not exist.
+     */
+    abandonProject(projectId) {
+        const project = this._requireProject(projectId);
+        if (project.status === 'archived') {
+            return; // Idempotent.
+        }
+        const now = Date.now();
+        const completedEvent = projectCompletedEvent(projectId, { abandoned: true });
+        this.db.db.transaction(() => {
+            this.db.run(`UPDATE projects SET status = 'archived', updated_at = ? WHERE id = ?`, [now, projectId]);
+            this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(completedEvent)));
+        })();
+        logger.info('PipelineEngine: project abandoned', { projectId });
+    }
+    // ---------------------------------------------------------------------------
+    // Phase transitions (extended API — used by MCP tools)
+    // ---------------------------------------------------------------------------
+    /**
+     * Transition a project to a new phase.
+     * Validates the transition against the state machine, emits events,
+     * starts a trajectory, and returns the result.
+     */
+    startPhase(projectId, toPhase, agent, extra) {
+        const project = this.getProject(projectId);
+        if (!project) {
+            return { error: 'PROJECT_NOT_FOUND', current_phase: 'idle', legal_transitions: [] };
+        }
+        // Cast from PipelinePhase (domain type) to Phase (state-machine type) — the
+        // DB stores Phase values in the current_phase column; the Project interface
+        // types it as PipelinePhase for legacy compatibility.
+        const fromPhase = project.currentPhase;
+        const tier = project.tier;
+        const cycleCounts = this._getCycleCounts(projectId);
+        // Validate transition
+        const validTransition = isValidTransition(fromPhase, toPhase, tier);
+        const parallelStart = !validTransition && isParallelStart(fromPhase, toPhase, tier);
+        if (!validTransition && !parallelStart) {
+            const legal = getAvailableTransitions(fromPhase, tier);
+            return {
+                error: 'INVALID_TRANSITION',
+                current_phase: fromPhase,
+                legal_transitions: legal,
+            };
+        }
+        // For parallel siblings (architecture + design), don't change currentPhase —
+        // both agents run concurrently and the submit handlers coordinate advancement.
+        // Skip only when the current phase IS the sibling (both are running from the
+        // same starting point) or when we allowed a parallelStart.
+        const sibling = PARALLEL_PAIRS.get(toPhase);
+        const skipPhaseUpdate = parallelStart || (validTransition && sibling !== undefined && fromPhase === sibling);
+        // Check cycle limits (only for non-parallel forward transitions)
+        if (!skipPhaseUpdate && isCycleTransition(fromPhase, toPhase)) {
+            const key = getCycleKey(fromPhase, toPhase);
+            const count = cycleCounts[key] ?? 0;
+            if (!canCycle(fromPhase, toPhase, count)) {
+                const forcedPhase = getForcedAdvancePhase(fromPhase, toPhase);
+                logger.warn('PipelineEngine: cycle limit exceeded, forcing advance', {
+                    projectId,
+                    from: fromPhase,
+                    to: toPhase,
+                    forced: forcedPhase,
+                    count,
+                });
+                // Force advance to the prescribed phase instead
+                if (forcedPhase) {
+                    return this.startPhase(projectId, forcedPhase, agent, {
+                        ...extra,
+                        forced: true,
+                        reason: 'cycle_limit_exceeded',
+                    });
+                }
+            }
+            // Increment cycle counter
+            cycleCounts[key] = (cycleCounts[key] ?? 0) + 1;
+        }
+        const now = Date.now();
+        // Update project phase (skip for parallel siblings)
+        if (!skipPhaseUpdate) {
+            this.db.run(`UPDATE projects SET current_phase = ?, updated_at = ? WHERE id = ?`, [toPhase, now, projectId]);
+        }
+        // Emit transition event (bridge Phase -> PipelinePhase for event factory)
+        const transEvent = phaseTransitionEvent(projectId, pp(fromPhase), pp(toPhase), agent, extra ?? {});
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(transEvent)));
+        // Emit agent_started event
+        const startedEvent = agentStartedEvent(projectId, pp(toPhase), agent, extra ?? {});
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(startedEvent)));
+        // Start trajectory
+        const trajectoryId = randomUUID();
+        this.db.run(`INSERT INTO trajectories (id, project_id, phase, agent, status, started_at)
+       VALUES (?, ?, ?, ?, 'active', ?)`, [trajectoryId, projectId, toPhase, agent, now]);
+        logger.info('PipelineEngine: phase started', { projectId, from: fromPhase, to: toPhase, agent, parallel: skipPhaseUpdate });
+        return {
+            projectId,
+            fromPhase,
+            toPhase,
+            trajectoryId,
+            cycleCounts,
+            availableTransitions: getAvailableTransitions(toPhase, tier),
+        };
+    }
+    /**
+     * Record completion of a phase: persist output, complete the trajectory,
+     * and optionally advance the state machine.
+     */
+    completePhase(projectId, phase, outputType, content, opts) {
+        const project = this.getProject(projectId);
+        if (!project) {
+            throw new Error(`Project not found: ${projectId}`);
+        }
+        const now = Date.now();
+        // Persist phase output
+        const result = this.db.run(`INSERT INTO phase_outputs (project_id, phase, output_type, content, file_path, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`, [projectId, phase, outputType, content, opts.filePath ?? null, now]);
+        // Complete active trajectory for this phase
+        if (opts.trajectoryId) {
+            this.db.run(`UPDATE trajectories SET status = 'complete', completed_at = ?, success = 1 WHERE id = ?`, [now, opts.trajectoryId]);
+            // Record trajectory step for the output
+            this.db.run(`INSERT INTO trajectory_steps (trajectory_id, action, result, quality_score, metadata, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`, [
+                opts.trajectoryId,
+                `submit_${phase}`,
+                content.slice(0, 500),
+                opts.qualityScore ?? null,
+                JSON.stringify(opts.metadata ?? {}),
+                now,
+            ]);
+        }
+        // Emit agent_completed event
+        const completedEvent = agentCompletedEvent(projectId, pp(phase), opts.agent, {
+            output_type: outputType,
+            content_length: content.length,
+            ...opts.metadata,
+        });
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(completedEvent)));
+        // Advance state if requested
+        if (opts.advanceTo) {
+            this.db.run(`UPDATE projects SET current_phase = ?, updated_at = ? WHERE id = ?`, [opts.advanceTo, now, projectId]);
+            const transEvent = phaseTransitionEvent(projectId, pp(phase), pp(opts.advanceTo), opts.agent, {});
+            this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(transEvent)));
+            logger.info('PipelineEngine: phase completed, advanced', {
+                projectId,
+                from: phase,
+                to: opts.advanceTo,
+            });
+        }
+        return {
+            outputId: Number(result.lastInsertRowid),
+            nextPhase: opts.advanceTo ?? null,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Trajectory helpers
+    // ---------------------------------------------------------------------------
+    startTrajectory(projectId, phase, agent) {
+        const id = randomUUID();
+        this.db.run(`INSERT INTO trajectories (id, project_id, phase, agent, status, started_at)
+       VALUES (?, ?, ?, ?, 'active', ?)`, [id, projectId, phase, agent, Date.now()]);
+        return id;
+    }
+    recordTrajectoryStep(trajectoryId, action, result, qualityScore, metadata) {
+        this.db.run(`INSERT INTO trajectory_steps (trajectory_id, action, result, quality_score, metadata, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`, [
+            trajectoryId,
+            action,
+            result ?? null,
+            qualityScore ?? null,
+            JSON.stringify(metadata ?? {}),
+            Date.now(),
+        ]);
+    }
+    completeTrajectory(trajectoryId, success, feedback) {
+        this.db.run(`UPDATE trajectories SET status = ?, completed_at = ?, success = ?, feedback = ? WHERE id = ?`, [success ? 'complete' : 'failed', Date.now(), success ? 1 : 0, feedback ?? null, trajectoryId]);
+    }
+    // ---------------------------------------------------------------------------
+    // Claims (parallel implementation dispatch)
+    // ---------------------------------------------------------------------------
+    createClaim(projectId, moduleName, agent) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.run(`INSERT INTO claims (id, project_id, module_name, agent, status, claimed_at)
+       VALUES (?, ?, ?, ?, 'claimed', ?)`, [id, projectId, moduleName, agent, now]);
+        const event = claimCreatedEvent(projectId, id, moduleName, agent);
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(event)));
+        return {
+            id,
+            projectId,
+            moduleName,
+            agent,
+            branch: null,
+            status: 'claimed',
+            claimedAt: now,
+            completedAt: null,
+            result: null,
+        };
+    }
+    completeClaim(claimId, result) {
+        const row = this.db.get(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+        if (!row)
+            throw new Error(`Claim not found: ${claimId}`);
+        const now = Date.now();
+        this.db.run(`UPDATE claims SET status = 'complete', completed_at = ?, result = ? WHERE id = ?`, [now, result ?? null, claimId]);
+        const event = claimCompletedEvent(row.project_id, claimId, row.module_name, row.agent, result);
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(event)));
+        const remaining = this.db.all(`SELECT id FROM claims WHERE project_id = ? AND status NOT IN ('complete', 'failed')`, [row.project_id]);
+        return {
+            remainingCount: remaining.length,
+            allComplete: remaining.length === 0,
+        };
+    }
+    failClaim(claimId, reason) {
+        const row = this.db.get(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+        if (!row)
+            throw new Error(`Claim not found: ${claimId}`);
+        this.db.run(`UPDATE claims SET status = 'failed', completed_at = ? WHERE id = ?`, [Date.now(), claimId]);
+        const event = claimFailedEvent(row.project_id, claimId, row.module_name, row.agent, reason);
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, Object.values(eventToParams(event)));
+    }
+    getActiveClaims(projectId) {
+        const rows = this.db.all(`SELECT * FROM claims WHERE project_id = ? AND status NOT IN ('complete', 'failed')`, [projectId]);
+        return rows.map((r) => this._rowToClaim(r));
+    }
+    getClaims(projectId, status) {
+        if (status !== undefined) {
+            const rows = this.db.all(`SELECT * FROM claims WHERE project_id = ? AND status = ? ORDER BY claimed_at ASC`, [projectId, status]);
+            return rows.map((r) => this._rowToClaim(r));
+        }
+        const rows = this.db.all(`SELECT * FROM claims WHERE project_id = ? ORDER BY claimed_at ASC`, [projectId]);
+        return rows.map((r) => this._rowToClaim(r));
+    }
+    getClaim(claimId) {
+        const row = this.db.get(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+        return row ? this._rowToClaim(row) : null;
+    }
+    getClaimByModule(projectId, moduleName) {
+        const row = this.db.get(`SELECT * FROM claims WHERE project_id = ? AND module_name = ? ORDER BY claimed_at DESC LIMIT 1`, [projectId, moduleName]);
+        return row ? this._rowToClaim(row) : null;
+    }
+    // ---------------------------------------------------------------------------
+    // Phase outputs
+    // ---------------------------------------------------------------------------
+    getPhaseOutput(projectId, phase, outputType) {
+        const sql = outputType
+            ? `SELECT * FROM phase_outputs WHERE project_id = ? AND phase = ? AND output_type = ? ORDER BY created_at DESC LIMIT 1`
+            : `SELECT * FROM phase_outputs WHERE project_id = ? AND phase = ? ORDER BY created_at DESC LIMIT 1`;
+        const params = outputType ? [projectId, phase, outputType] : [projectId, phase];
+        const row = this.db.get(sql, params);
+        if (!row)
+            return null;
+        return this._rowToPhaseOutput(row);
+    }
+    /**
+     * Retrieve metadata stored in the agent_completed event for a phase.
+     * This includes flags like requires_qa, requires_designer, modules, etc.
+     * that are passed via opts.metadata in completePhase().
+     */
+    getPhaseMetadata(projectId, phase) {
+        const row = this.db.get(`SELECT payload FROM pipeline_events
+       WHERE project_id = ? AND event_type = 'agent_completed' AND from_phase = ?
+       ORDER BY created_at DESC LIMIT 1`, [projectId, phase]);
+        if (!row)
+            return null;
+        try {
+            return JSON.parse(row.payload);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Record a broadcast event in the pipeline_events table.
+     * Used by phase tools to auto-broadcast module completions for swarm coordination.
+     */
+    recordBroadcast(projectId, content, severity = 'info') {
+        this.db.run(`INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, NULL, NULL, NULL, ?, ?)`, [
+            projectId,
+            'agent_broadcast',
+            JSON.stringify({ content, severity }),
+            Date.now(),
+        ]);
+    }
+    getAllPhaseOutputs(projectId) {
+        const rows = this.db.all(`SELECT * FROM phase_outputs WHERE project_id = ? ORDER BY created_at ASC`, [projectId]);
+        return rows.map((r) => this._rowToPhaseOutput(r));
+    }
+    // ---------------------------------------------------------------------------
+    // History
+    // ---------------------------------------------------------------------------
+    getHistory(projectId) {
+        const events = this.db.all(`SELECT * FROM pipeline_events WHERE project_id = ? ORDER BY created_at ASC`, [projectId]);
+        const outputs = this.getAllPhaseOutputs(projectId);
+        // Build phase history from agent_started / agent_completed pairs.
+        // ev.fromPhase is PipelinePhase (domain type), PhaseHistory.phase is Phase.
+        const history = [];
+        const startedMap = new Map();
+        for (const row of events) {
+            const ev = rowToEvent(row);
+            if (ev.eventType === 'agent_started' && ev.fromPhase) {
+                startedMap.set(`${ev.fromPhase}-${ev.agent}`, {
+                    phase: wp(ev.fromPhase),
+                    agent: ev.agent ?? 'unknown',
+                    startedAt: ev.createdAt,
+                });
+            }
+            else if (ev.eventType === 'agent_completed' && ev.fromPhase) {
+                const key = `${ev.fromPhase}-${ev.agent}`;
+                const started = startedMap.get(key);
+                if (started) {
+                    history.push({
+                        phase: started.phase,
+                        agent: started.agent,
+                        startedAt: new Date(started.startedAt).toISOString(),
+                        completedAt: new Date(ev.createdAt).toISOString(),
+                        success: true,
+                    });
+                    startedMap.delete(key);
+                }
+            }
+        }
+        // Flush any in-progress phases
+        for (const [, started] of startedMap) {
+            history.push({
+                phase: started.phase,
+                agent: started.agent,
+                startedAt: new Date(started.startedAt).toISOString(),
+            });
+        }
+        return {
+            projectId,
+            events: events.map(rowToEvent),
+            outputs,
+            history,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Cycle tracking
+    // ---------------------------------------------------------------------------
+    getCycleCounts(projectId) {
+        return this._getCycleCounts(projectId);
+    }
+    _getCycleCounts(projectId) {
+        const rows = this.db.all(`SELECT from_phase, to_phase, COUNT(*) as count
+       FROM pipeline_events
+       WHERE project_id = ? AND event_type = 'phase_transition' AND from_phase IS NOT NULL AND to_phase IS NOT NULL
+       GROUP BY from_phase, to_phase`, [projectId]);
+        const counts = {};
+        for (const row of rows) {
+            const key = `${row.from_phase}_to_${row.to_phase}`;
+            // Only include recognised cycle keys
+            if (getCycleKey(row.from_phase, row.to_phase)) {
+                counts[key] = row.count;
+            }
+        }
+        return counts;
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Retrieves a project by id and throws a typed PipelineEngineError when not
+     * found. Used by every method that requires an existing project.
+     */
+    _requireProject(projectId) {
+        const row = this.db.get(`SELECT * FROM projects WHERE id = ?`, [projectId]);
+        if (!row) {
+            throw new PipelineEngineError('PROJECT_NOT_FOUND', `Project '${projectId}' does not exist`, { projectId });
+        }
+        return this._rowToProject(row);
+    }
+    // ---------------------------------------------------------------------------
+    // Row mappers
+    // ---------------------------------------------------------------------------
+    _rowToProject(row) {
+        let metadata;
+        try {
+            metadata = JSON.parse(row.metadata);
+        }
+        catch {
+            metadata = {};
+        }
+        return {
+            id: row.id,
+            repoId: row.repo_id,
+            name: row.name,
+            description: row.description,
+            // The DB stores Phase (workflow-stage) values in current_phase, but
+            // Project.currentPhase is typed as PipelinePhase. We bridge here so
+            // callers use wp() to get back to Phase when needed.
+            currentPhase: row.current_phase,
+            tier: row.tier,
+            status: row.status,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            metadata,
+        };
+    }
+    _rowToClaim(row) {
+        return {
+            id: row.id,
+            projectId: row.project_id,
+            moduleName: row.module_name,
+            agent: row.agent,
+            branch: row.branch,
+            status: row.status,
+            claimedAt: row.claimed_at,
+            completedAt: row.completed_at,
+            result: row.result,
+        };
+    }
+    _rowToPhaseOutput(row) {
+        return {
+            id: row.id,
+            projectId: row.project_id,
+            // Bridge: Phase values stored in DB, PhaseOutput.phase typed as PipelinePhase.
+            phase: row.phase,
+            outputType: row.output_type,
+            content: row.content,
+            filePath: row.file_path,
+            createdAt: row.created_at,
+        };
+    }
+    // Expose getTrajectory for phase tools
+    getActiveTrajectory(projectId, phase) {
+        const row = this.db.get(`SELECT * FROM trajectories WHERE project_id = ? AND phase = ? AND status = 'active' ORDER BY started_at DESC LIMIT 1`, [projectId, phase]);
+        if (!row)
+            return null;
+        return {
+            id: row.id,
+            projectId: row.project_id,
+            // Bridge: Phase stored in DB, Trajectory.phase typed as PipelinePhase.
+            phase: row.phase,
+            agent: row.agent,
+            status: row.status,
+            startedAt: row.started_at,
+            completedAt: row.completed_at,
+            success: row.success === null ? null : row.success === 1,
+            feedback: row.feedback,
+        };
+    }
+}
+//# sourceMappingURL=engine.js.map