forge-server 0.1.0

package/src/pipeline/events.ts

@@ -0,0 +1,253 @@
+// Pipeline event factory and helpers for the event-sourced state machine.
+//
+// Pipeline events are the audit log. Every phase transition, agent action,
+// claim lifecycle change, and project status change is recorded as an immutable
+// event row in the pipeline_events SQLite table. The PipelineEngine reads these
+// rows to reconstruct cycle counts and provides the full history to callers.
+//
+// PipelineEvent here is the deserialized domain object (camelCase fields), not
+// the raw row. The storage layer handles the mapping between the two.
+
+import type {
+  PipelineEvent,
+  PipelineEventPayload,
+  EventType,
+  PipelinePhase,
+} from '../util/types.js';
+
+// ---------------------------------------------------------------------------
+// Event factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a PipelineEvent (without id — that is assigned by SQLite AUTOINCREMENT)
+ * with a generated timestamp and sensible defaults.
+ */
+export function createEvent(
+  projectId: string,
+  type: EventType,
+  data: {
+    fromPhase?: PipelinePhase | null;
+    toPhase?: PipelinePhase | null;
+    agent?: string | null;
+    payload?: PipelineEventPayload;
+  } = {},
+): Omit<PipelineEvent, 'id'> {
+  return {
+    projectId,
+    eventType: type,
+    fromPhase: data.fromPhase ?? null,
+    toPhase: data.toPhase ?? null,
+    agent: data.agent ?? null,
+    payload: data.payload ?? {},
+    createdAt: Date.now(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Convenience constructors for common event patterns
+// ---------------------------------------------------------------------------
+
+/** Emitted when the engine transitions a project to a new phase. */
+export function phaseTransitionEvent(
+  projectId: string,
+  fromPhase: PipelinePhase,
+  toPhase: PipelinePhase,
+  agent?: string | null,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'phase_transition', {
+    fromPhase,
+    toPhase,
+    agent: agent ?? null,
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when an agent begins work on a phase. */
+export function agentStartedEvent(
+  projectId: string,
+  phase: PipelinePhase,
+  agent: string,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'agent_started', {
+    fromPhase: phase,
+    toPhase: phase,
+    agent,
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when an agent successfully completes a phase. */
+export function agentCompletedEvent(
+  projectId: string,
+  phase: PipelinePhase,
+  agent: string,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'agent_completed', {
+    fromPhase: phase,
+    toPhase: phase,
+    agent,
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when an agent fails a phase. */
+export function agentFailedEvent(
+  projectId: string,
+  phase: PipelinePhase,
+  agent: string,
+  error: string,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'agent_failed', {
+    fromPhase: phase,
+    toPhase: phase,
+    agent,
+    payload: { error, ...(extra ?? {}) },
+  });
+}
+
+/** Emitted when the project is first created. */
+export function projectCreatedEvent(
+  projectId: string,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'project_created', {
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when the project is paused. */
+export function projectPausedEvent(
+  projectId: string,
+  phase: PipelinePhase,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'project_paused', {
+    fromPhase: phase,
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when the project is resumed from pause. */
+export function projectResumedEvent(
+  projectId: string,
+  phase: PipelinePhase,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'project_resumed', {
+    fromPhase: phase,
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when the project reaches completed status. */
+export function projectCompletedEvent(
+  projectId: string,
+  extra?: PipelineEventPayload,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'project_completed', {
+    toPhase: 'complete',
+    payload: extra ?? {},
+  });
+}
+
+/** Emitted when a new work claim is created for a module. */
+export function claimCreatedEvent(
+  projectId: string,
+  claimId: string,
+  moduleName: string,
+  agent: string,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'claim_created', {
+    agent,
+    payload: { claim_id: claimId, module_name: moduleName },
+  });
+}
+
+/** Emitted when a claim is successfully completed. */
+export function claimCompletedEvent(
+  projectId: string,
+  claimId: string,
+  moduleName: string,
+  agent: string,
+  result?: string,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'claim_completed', {
+    agent,
+    payload: { claim_id: claimId, module_name: moduleName, result: result ?? null },
+  });
+}
+
+/** Emitted when a claim fails. */
+export function claimFailedEvent(
+  projectId: string,
+  claimId: string,
+  moduleName: string,
+  agent: string,
+  reason: string,
+): Omit<PipelineEvent, 'id'> {
+  return createEvent(projectId, 'claim_failed', {
+    agent,
+    payload: { claim_id: claimId, module_name: moduleName, error: reason },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Row mapping helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Deserializes a raw pipeline_events row (snake_case TEXT columns) into a
+ * typed PipelineEvent domain object. Used by the engine when reading rows
+ * back from SQLite.
+ */
+export function rowToEvent(row: {
+  id: number;
+  project_id: string;
+  event_type: string;
+  from_phase: string | null;
+  to_phase: string | null;
+  agent: string | null;
+  payload: string;
+  created_at: number;
+}): PipelineEvent {
+  let payload: PipelineEventPayload;
+  try {
+    payload = JSON.parse(row.payload) as PipelineEventPayload;
+  } catch {
+    payload = {};
+  }
+
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    eventType: row.event_type as EventType,
+    fromPhase: (row.from_phase as PipelinePhase | null) ?? null,
+    toPhase: (row.to_phase as PipelinePhase | null) ?? null,
+    agent: row.agent,
+    payload,
+    createdAt: row.created_at,
+  };
+}
+
+/**
+ * Serializes a PipelineEvent domain object to the named parameter map
+ * expected by `PipelineDB.run()` for an INSERT into pipeline_events.
+ */
+export function eventToParams(
+  event: Omit<PipelineEvent, 'id'>,
+): Record<string, unknown> {
+  return {
+    project_id: event.projectId,
+    event_type: event.eventType,
+    from_phase: event.fromPhase,
+    to_phase: event.toPhase,
+    agent: event.agent,
+    payload: JSON.stringify(event.payload),
+    created_at: event.createdAt,
+  };
+}

package/src/pipeline/parallel.ts

@@ -0,0 +1,394 @@
+// ParallelDispatch — manages work claims for parallel implementation phases.
+//
+// During the implementation phase, multiple specialist agents work concurrently
+// on separate modules. ParallelDispatch creates and tracks per-module claims,
+// emits lifecycle events, and provides helpers to check overall completion so
+// the engine can auto-advance to inspection when all work is done.
+//
+// Claims are persisted in the SQLite `claims` table. All writes are
+// synchronous (better-sqlite3). Claim lifecycle events are also written to
+// `pipeline_events` for the audit log.
+
+import { randomUUID } from 'node:crypto';
+
+import type { PipelineDB } from '../storage/sqlite.js';
+import type { Claim, ClaimRow, ClaimStatus } from '../util/types.js';
+import {
+  claimCreatedEvent,
+  claimCompletedEvent,
+  claimFailedEvent,
+  eventToParams,
+} from './events.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Row deserializer
+// ---------------------------------------------------------------------------
+
+function rowToClaim(row: ClaimRow): Claim {
+  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,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// SQL helper: insert a pipeline event row using positional params.
+// eventToParams returns keys in the order the INSERT expects.
+// ---------------------------------------------------------------------------
+
+function insertEvent(
+  db: PipelineDB,
+  event: ReturnType<typeof claimCreatedEvent>,
+): void {
+  db.run(
+    `INSERT INTO pipeline_events
+       (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    Object.values(eventToParams(event)),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ParallelDispatch
+// ---------------------------------------------------------------------------
+
+export class ParallelDispatch {
+  constructor(private readonly db: PipelineDB) {}
+
+  // -------------------------------------------------------------------------
+  // Claim creation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Creates one claim per entry in `modules`. Each claim starts with status
+   * 'claimed' and is immediately usable by a specialist agent.
+   *
+   * A claim_created pipeline event is emitted for each created claim.
+   *
+   * Returns the full array of created Claim objects so callers can distribute
+   * them to agents.
+   */
+  createClaims(
+    projectId: string,
+    modules: Array<{ name: string; agent: string }>,
+  ): Claim[] {
+    const now = Date.now();
+    const created: Claim[] = [];
+
+    for (const mod of modules) {
+      const id = randomUUID();
+
+      this.db.run(
+        `INSERT INTO claims (id, project_id, module_name, agent, status, claimed_at)
+         VALUES (?, ?, ?, ?, 'claimed', ?)`,
+        [id, projectId, mod.name, mod.agent, now],
+      );
+
+      const event = claimCreatedEvent(projectId, id, mod.name, mod.agent);
+      insertEvent(this.db, event);
+
+      created.push({
+        id,
+        projectId,
+        moduleName: mod.name,
+        agent: mod.agent,
+        branch: null,
+        status: 'claimed',
+        claimedAt: now,
+        completedAt: null,
+        result: null,
+      });
+
+      logger.info('ParallelDispatch: claim created', { projectId, claimId: id, module: mod.name, agent: mod.agent });
+    }
+
+    return created;
+  }
+
+  // -------------------------------------------------------------------------
+  // Claim status updates
+  // -------------------------------------------------------------------------
+
+  /**
+   * Updates the status of a claim. Optionally sets the result text and branch
+   * name. This is a general-purpose setter; use completeClaim / failClaim for
+   * the semantic updates that also emit events.
+   *
+   * Throws when the claim does not exist.
+   */
+  updateClaim(
+    claimId: string,
+    status: ClaimStatus,
+    result?: string,
+    branch?: string,
+  ): void {
+    const row = this._requireClaim(claimId);
+    const now = Date.now();
+
+    this.db.run(
+      `UPDATE claims
+       SET status       = ?,
+           branch       = COALESCE(?, branch),
+           result       = COALESCE(?, result),
+           completed_at = CASE WHEN ? IN ('complete', 'failed') THEN ? ELSE completed_at END
+       WHERE id = ?`,
+      [
+        status,
+        branch ?? null,
+        result ?? null,
+        status,
+        now,
+        claimId,
+      ],
+    );
+
+    logger.info('ParallelDispatch: claim updated', {
+      claimId,
+      projectId: row.project_id,
+      module: row.module_name,
+      status,
+    });
+  }
+
+  /**
+   * Marks a claim as 'complete' and emits a claim_completed event.
+   * Records the optional result text (e.g., git branch name, summary).
+   *
+   * Returns { remainingCount, allComplete } so the caller can check whether
+   * to auto-advance the project to inspection.
+   *
+   * Throws when the claim does not exist.
+   */
+  completeClaim(claimId: string, result?: string): { remainingCount: number; allComplete: boolean } {
+    const row = this._requireClaim(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,
+    );
+    insertEvent(this.db, event);
+
+    logger.info('ParallelDispatch: claim completed', {
+      claimId,
+      projectId: row.project_id,
+      module: row.module_name,
+    });
+
+    const remaining = this.db.all<{ id: string }>(
+      `SELECT id FROM claims WHERE project_id = ? AND status NOT IN ('complete', 'failed')`,
+      [row.project_id],
+    );
+
+    return {
+      remainingCount: remaining.length,
+      allComplete: remaining.length === 0,
+    };
+  }
+
+  /**
+   * Marks a claim as 'failed' and emits a claim_failed event.
+   *
+   * Throws when the claim does not exist.
+   */
+  failClaim(claimId: string, reason: string): void {
+    const row = this._requireClaim(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,
+    );
+    insertEvent(this.db, event);
+
+    logger.warn('ParallelDispatch: claim failed', {
+      claimId,
+      projectId: row.project_id,
+      module: row.module_name,
+      reason,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Completion checks
+  // -------------------------------------------------------------------------
+
+  /**
+   * Returns true when every claim for the project is in a terminal state
+   * ('complete' or 'failed') — i.e., no claim remains in 'claimed' or
+   * 'stealable' status.
+   *
+   * Returns true vacuously when there are no claims at all (no modules were
+   * dispatched). Callers should check that at least one claim exists before
+   * using this to gate phase advance.
+   */
+  allClaimsComplete(projectId: string): boolean {
+    const pending = this.db.get<{ count: number }>(
+      `SELECT COUNT(*) as count FROM claims
+       WHERE project_id = ? AND status NOT IN ('complete', 'failed')`,
+      [projectId],
+    );
+    return (pending?.count ?? 0) === 0;
+  }
+
+  // -------------------------------------------------------------------------
+  // Query methods
+  // -------------------------------------------------------------------------
+
+  /**
+   * Returns claims for a project, optionally filtered by status.
+   * Ordered by claimed_at ASC.
+   */
+  getClaims(projectId: string, status?: ClaimStatus): Claim[] {
+    if (status !== undefined) {
+      return this.db.all<ClaimRow>(
+        `SELECT * FROM claims WHERE project_id = ? AND status = ? ORDER BY claimed_at ASC`,
+        [projectId, status],
+      ).map(rowToClaim);
+    }
+    return this.db.all<ClaimRow>(
+      `SELECT * FROM claims WHERE project_id = ? ORDER BY claimed_at ASC`,
+      [projectId],
+    ).map(rowToClaim);
+  }
+
+  /**
+   * Returns a single claim by id, or null if it does not exist.
+   */
+  getClaim(claimId: string): Claim | null {
+    const row = this.db.get<ClaimRow>(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+    return row ? rowToClaim(row) : null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Cycle reset
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resets failed claims when the inspection phase sends the project back to
+   * implementation. Re-creates claims for the specified modules (or all failed
+   * claims when `modules` is omitted) so specialists can retry.
+   *
+   * The failed rows are left in place for the audit trail. New 'claimed' rows
+   * are inserted with new IDs, and claim_created events are emitted for each.
+   *
+   * Returns the newly created Claim objects.
+   */
+  resetFailedClaims(projectId: string, modules?: string[]): Claim[] {
+    let failedRows: ClaimRow[];
+
+    if (modules !== undefined && modules.length > 0) {
+      // Use multiple individual queries rather than a parameterised IN clause
+      // to avoid the need for dynamic SQL placeholders.
+      failedRows = [];
+      for (const moduleName of modules) {
+        const rows = this.db.all<ClaimRow>(
+          `SELECT * FROM claims
+           WHERE project_id = ? AND module_name = ? AND status = 'failed'
+           ORDER BY claimed_at DESC`,
+          [projectId, moduleName],
+        );
+        // Take the most recent failed claim for each module.
+        if (rows.length > 0 && rows[0] !== undefined) {
+          failedRows.push(rows[0]);
+        }
+      }
+    } else {
+      // All failed claims for the project.
+      failedRows = this.db.all<ClaimRow>(
+        `SELECT * FROM claims WHERE project_id = ? AND status = 'failed' ORDER BY claimed_at ASC`,
+        [projectId],
+      );
+    }
+
+    if (failedRows.length === 0) {
+      logger.info('ParallelDispatch: resetFailedClaims — no failed claims to reset', { projectId });
+      return [];
+    }
+
+    const now = Date.now();
+    const recreated: Claim[] = [];
+
+    for (const failed of failedRows) {
+      const newId = randomUUID();
+
+      this.db.run(
+        `INSERT INTO claims (id, project_id, module_name, agent, status, claimed_at)
+         VALUES (?, ?, ?, ?, 'claimed', ?)`,
+        [newId, failed.project_id, failed.module_name, failed.agent, now],
+      );
+
+      const event = claimCreatedEvent(
+        failed.project_id,
+        newId,
+        failed.module_name,
+        failed.agent,
+      );
+      insertEvent(this.db, event);
+
+      recreated.push({
+        id: newId,
+        projectId: failed.project_id,
+        moduleName: failed.module_name,
+        agent: failed.agent,
+        branch: null,
+        status: 'claimed',
+        claimedAt: now,
+        completedAt: null,
+        result: null,
+      });
+
+      logger.info('ParallelDispatch: claim reset after inspection failure', {
+        projectId,
+        oldClaimId: failed.id,
+        newClaimId: newId,
+        module: failed.module_name,
+      });
+    }
+
+    return recreated;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Retrieves a raw ClaimRow by id and throws when not found.
+   * We return the raw row so callers can access project_id, module_name, and
+   * agent for event emission without an extra round-trip.
+   */
+  private _requireClaim(claimId: string): ClaimRow {
+    const row = this.db.get<ClaimRow>(
+      `SELECT * FROM claims WHERE id = ?`,
+      [claimId],
+    );
+    if (!row) {
+      throw new Error(`ParallelDispatch: claim '${claimId}' does not exist`);
+    }
+    return row;
+  }
+}