@auto-engineer/job-graph-processor 1.12.1

package/src/handle-job-event.specs.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+import { evolve, initialState } from './evolve';
+import { classifyJobEvent, handleJobEvent, isJobFailure, parseCorrelationId } from './handle-job-event';
+
+describe('parseCorrelationId', () => {
+  it('extracts graphId and jobId from graph correlation format', () => {
+    expect(parseCorrelationId('graph:g1:job-a')).toEqual({ graphId: 'g1', jobId: 'job-a' });
+  });
+});
+
+describe('isJobFailure', () => {
+  it('returns true when event data contains error field', () => {
+    expect(isJobFailure({ type: 'BuildFailed', data: { error: 'compile error' } })).toBe(true);
+  });
+});
+
+describe('classifyJobEvent', () => {
+  it('returns null for events without graph correlation', () => {
+    expect(classifyJobEvent({ type: 'Unrelated', data: {} })).toBe(null);
+  });
+
+  it('returns JobFailed when event has error field', () => {
+    const result = classifyJobEvent({
+      type: 'BuildFailed',
+      data: { error: 'compile error' },
+      correlationId: 'graph:g1:job-a',
+    });
+
+    expect(result).toEqual({
+      type: 'JobFailed',
+      data: { jobId: 'job-a', error: 'compile error' },
+    });
+  });
+
+  it('returns JobSucceeded when event has no error', () => {
+    const result = classifyJobEvent({
+      type: 'BuildCompleted',
+      data: { output: 'success' },
+      correlationId: 'graph:g1:job-a',
+    });
+
+    expect(result).toEqual({
+      type: 'JobSucceeded',
+      data: { jobId: 'job-a', result: { output: 'success' } },
+    });
+  });
+});
+
+describe('handleJobEvent', () => {
+  it('returns null for events without graph correlation', () => {
+    const state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+
+    const result = handleJobEvent(state, { type: 'Unrelated', data: {} });
+
+    expect(result).toBe(null);
+  });
+
+  it('emits JobSucceeded and dispatches ready dependents', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const result = handleJobEvent(state, {
+      type: 'BuildCompleted',
+      data: { output: 'ok' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(result).toEqual({
+      events: [{ type: 'JobSucceeded', data: { jobId: 'a', result: { output: 'ok' } } }],
+      readyJobs: ['b'],
+      graphComplete: false,
+    });
+  });
+
+  it('marks graph complete when last job succeeds', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const result = handleJobEvent(state, {
+      type: 'BuildCompleted',
+      data: { output: 'ok' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(result).toEqual({
+      events: [{ type: 'JobSucceeded', data: { jobId: 'a', result: { output: 'ok' } } }],
+      readyJobs: [],
+      graphComplete: true,
+    });
+  });
+
+  it('applies halt policy and marks graph complete on failure', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const result = handleJobEvent(state, {
+      type: 'BuildFailed',
+      data: { error: 'compile error' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(result).toEqual({
+      events: [
+        { type: 'JobFailed', data: { jobId: 'a', error: 'compile error' } },
+        { type: 'JobSkipped', data: { jobId: 'b', reason: 'halt policy' } },
+      ],
+      readyJobs: [],
+      graphComplete: true,
+    });
+  });
+});

package/src/handle-job-event.ts

@@ -0,0 +1,59 @@
+import type { Event } from '@auto-engineer/message-bus';
+import { applyPolicy } from './apply-policy';
+import type { GraphState, JobGraphEvent } from './evolve';
+import { evolve, getReadyJobs, isGraphComplete } from './evolve';
+
+export function parseCorrelationId(correlationId: string): { graphId: string; jobId: string } | null {
+  const match = correlationId.match(/^graph:(.+):(.+)$/);
+  if (match === null) return null;
+  return { graphId: match[1], jobId: match[2] };
+}
+
+export function isJobFailure(event: Event): boolean {
+  return 'error' in event.data && event.data.error !== undefined;
+}
+
+export function classifyJobEvent(event: Event): JobGraphEvent | null {
+  const parsed = parseCorrelationId(event.correlationId ?? '');
+  if (parsed === null) return null;
+
+  if (isJobFailure(event)) {
+    return {
+      type: 'JobFailed',
+      data: { jobId: parsed.jobId, error: String(event.data.error) },
+    };
+  }
+
+  return {
+    type: 'JobSucceeded',
+    data: { jobId: parsed.jobId, result: event.data },
+  };
+}
+
+interface HandleResult {
+  events: JobGraphEvent[];
+  readyJobs: string[];
+  graphComplete: boolean;
+}
+
+export function handleJobEvent(state: GraphState, event: Event): HandleResult | null {
+  const classified = classifyJobEvent(event);
+  if (classified === null) return null;
+
+  const events: JobGraphEvent[] = [classified];
+  let current = evolve(state, classified);
+
+  if (classified.type === 'JobFailed') {
+    const policyEvents = applyPolicy(current, classified.data.jobId);
+    for (const pe of policyEvents) {
+      events.push(pe);
+      current = evolve(current, pe);
+    }
+  }
+
+  return {
+    events,
+    readyJobs: getReadyJobs(current),
+    graphComplete: isGraphComplete(current),
+  };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+import { commandHandler as processJobGraphHandler } from './commands/process-job-graph';
+
+export const COMMANDS = [processJobGraphHandler];
+
+export { applyPolicy } from './apply-policy';
+export type { FailurePolicy, GraphState, JobGraphEvent, JobStatus } from './evolve';
+
+export { evolve, getReadyJobs, getTransitiveDependents, initialState, isGraphComplete } from './evolve';
+export { createGraphProcessor } from './graph-processor';
+export type { Job } from './graph-validator';
+export { validateGraph } from './graph-validator';
+export { classifyJobEvent, handleJobEvent, isJobFailure, parseCorrelationId } from './handle-job-event';
+export { handleProcessGraph } from './process-graph';
+export type { RetryConfig, RetryManager } from './retry-manager';
+export { createRetryManager } from './retry-manager';
+export type { TimeoutManager } from './timeout-manager';
+export { createTimeoutManager } from './timeout-manager';

package/src/integration.specs.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it, vi } from 'vitest';
+import { evolve, getReadyJobs, initialState } from './evolve';
+import { handleJobEvent } from './handle-job-event';
+import { createRetryManager } from './retry-manager';
+import { createTimeoutManager } from './timeout-manager';
+
+describe('diamond dependency graph', () => {
+  it('processes a→(b,c)→d diamond graph to completion', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          { id: 'c', dependsOn: ['a'], target: 'lint', payload: {} },
+          { id: 'd', dependsOn: ['b', 'c'], target: 'deploy', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(getReadyJobs(state)).toEqual(['a']);
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const r1 = handleJobEvent(state, {
+      type: 'BuildCompleted',
+      data: { output: 'ok' },
+      correlationId: 'graph:g1:a',
+    });
+    expect(r1).toEqual({
+      events: [{ type: 'JobSucceeded', data: { jobId: 'a', result: { output: 'ok' } } }],
+      readyJobs: ['b', 'c'],
+      graphComplete: false,
+    });
+    for (const e of r1!.events) state = evolve(state, e);
+
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'b', target: 'test', correlationId: 'graph:g1:b' },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'c', target: 'lint', correlationId: 'graph:g1:c' },
+    });
+
+    const r2 = handleJobEvent(state, {
+      type: 'TestPassed',
+      data: {},
+      correlationId: 'graph:g1:b',
+    });
+    expect(r2).toEqual({
+      events: [{ type: 'JobSucceeded', data: { jobId: 'b', result: {} } }],
+      readyJobs: [],
+      graphComplete: false,
+    });
+    for (const e of r2!.events) state = evolve(state, e);
+
+    const r3 = handleJobEvent(state, {
+      type: 'LintPassed',
+      data: {},
+      correlationId: 'graph:g1:c',
+    });
+    expect(r3).toEqual({
+      events: [{ type: 'JobSucceeded', data: { jobId: 'c', result: {} } }],
+      readyJobs: ['d'],
+      graphComplete: false,
+    });
+    for (const e of r3!.events) state = evolve(state, e);
+
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'd', target: 'deploy', correlationId: 'graph:g1:d' },
+    });
+
+    const r4 = handleJobEvent(state, {
+      type: 'Deployed',
+      data: {},
+      correlationId: 'graph:g1:d',
+    });
+    expect(r4).toEqual({
+      events: [{ type: 'JobSucceeded', data: { jobId: 'd', result: {} } }],
+      readyJobs: [],
+      graphComplete: true,
+    });
+  });
+});
+
+describe('failure policies integration', () => {
+  it('halt policy skips all pending and completes graph on failure', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          { id: 'c', dependsOn: [], target: 'lint', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const result = handleJobEvent(state, {
+      type: 'BuildFailed',
+      data: { error: 'compile error' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(result).toEqual({
+      events: [
+        { type: 'JobFailed', data: { jobId: 'a', error: 'compile error' } },
+        { type: 'JobSkipped', data: { jobId: 'b', reason: 'halt policy' } },
+        { type: 'JobSkipped', data: { jobId: 'c', reason: 'halt policy' } },
+      ],
+      readyJobs: [],
+      graphComplete: true,
+    });
+  });
+
+  it('skip-dependents policy skips only dependents and allows others to continue', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+          { id: 'c', dependsOn: [], target: 'lint', payload: {} },
+        ],
+        failurePolicy: 'skip-dependents',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const result = handleJobEvent(state, {
+      type: 'BuildFailed',
+      data: { error: 'compile error' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(result).toEqual({
+      events: [
+        { type: 'JobFailed', data: { jobId: 'a', error: 'compile error' } },
+        { type: 'JobSkipped', data: { jobId: 'b', reason: 'dependency failed' } },
+      ],
+      readyJobs: ['c'],
+      graphComplete: false,
+    });
+  });
+
+  it('continue policy unlocks dependents after failure', () => {
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: {} },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'continue',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    const result = handleJobEvent(state, {
+      type: 'BuildFailed',
+      data: { error: 'compile error' },
+      correlationId: 'graph:g1:a',
+    });
+
+    expect(result).toEqual({
+      events: [{ type: 'JobFailed', data: { jobId: 'a', error: 'compile error' } }],
+      readyJobs: ['b'],
+      graphComplete: false,
+    });
+  });
+});
+
+describe('timeout integration', () => {
+  it('fires timeout callback after elapsed time and evolve treats it as terminal', () => {
+    vi.useFakeTimers();
+    const timedOut: string[] = [];
+    const manager = createTimeoutManager((jobId) => timedOut.push(jobId));
+
+    let state = evolve(initialState(), {
+      type: 'GraphSubmitted',
+      data: {
+        graphId: 'g1',
+        jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+        failurePolicy: 'halt',
+      },
+    });
+    state = evolve(state, {
+      type: 'JobDispatched',
+      data: { jobId: 'a', target: 'build', correlationId: 'graph:g1:a' },
+    });
+
+    manager.start('a', 5000);
+    vi.advanceTimersByTime(5000);
+
+    expect(timedOut).toEqual(['a']);
+
+    state = evolve(state, { type: 'JobTimedOut', data: { jobId: 'a', timeoutMs: 5000 } });
+    expect(getReadyJobs(state)).toEqual([]);
+
+    vi.useRealTimers();
+  });
+});
+
+describe('retry integration', () => {
+  it('retries with backoff then exhausts max retries', () => {
+    vi.useFakeTimers();
+    const retries: Array<{ jobId: string; attempt: number }> = [];
+    const manager = createRetryManager((jobId, attempt) => retries.push({ jobId, attempt }));
+    const config = { maxRetries: 2, backoffMs: 100, maxBackoffMs: 5000 };
+
+    const exhausted1 = manager.recordFailure('a', config);
+    expect(exhausted1).toBe(false);
+    vi.advanceTimersByTime(100);
+    expect(retries).toEqual([{ jobId: 'a', attempt: 1 }]);
+
+    const exhausted2 = manager.recordFailure('a', config);
+    expect(exhausted2).toBe(false);
+    vi.advanceTimersByTime(200);
+    expect(retries).toEqual([
+      { jobId: 'a', attempt: 1 },
+      { jobId: 'a', attempt: 2 },
+    ]);
+
+    const exhausted3 = manager.recordFailure('a', config);
+    expect(exhausted3).toBe(true);
+
+    vi.useRealTimers();
+  });
+});

package/src/process-graph.specs.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { handleProcessGraph } from './process-graph';
+
+describe('handleProcessGraph', () => {
+  it('returns graph.failed when graph validation fails', async () => {
+    const result = await handleProcessGraph({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(result).toEqual({
+      type: 'graph.failed',
+      data: {
+        graphId: 'g1',
+        reason: 'Graph must contain at least one job',
+      },
+    });
+  });
+
+  it('dispatches ready jobs for a valid graph', async () => {
+    const result = await handleProcessGraph({
+      type: 'ProcessGraph',
+      data: {
+        graphId: 'g1',
+        jobs: [
+          { id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } },
+          { id: 'b', dependsOn: ['a'], target: 'test', payload: {} },
+        ],
+        failurePolicy: 'halt',
+      },
+    });
+
+    expect(result).toEqual([
+      {
+        type: 'job.dispatched',
+        data: { graphId: 'g1', jobId: 'a', target: 'build', payload: { src: './app' } },
+      },
+    ]);
+  });
+});

package/src/process-graph.ts

@@ -0,0 +1,42 @@
+import type { Event } from '@auto-engineer/message-bus';
+import type { FailurePolicy } from './evolve';
+import { evolve, getReadyJobs, initialState } from './evolve';
+import type { Job } from './graph-validator';
+import { validateGraph } from './graph-validator';
+
+interface ProcessGraphCommand {
+  type: 'ProcessGraph';
+  data: {
+    graphId: string;
+    jobs: readonly Job[];
+    failurePolicy: FailurePolicy;
+  };
+}
+
+export async function handleProcessGraph(command: ProcessGraphCommand): Promise<Event | Event[]> {
+  const { graphId, jobs, failurePolicy } = command.data;
+
+  const validation = validateGraph(jobs);
+  if (!validation.valid) {
+    return {
+      type: 'graph.failed',
+      data: { graphId, reason: validation.error },
+    };
+  }
+
+  const state = evolve(initialState(), {
+    type: 'GraphSubmitted',
+    data: { graphId, jobs, failurePolicy },
+  });
+
+  const jobById: Record<string, Job> = {};
+  for (const job of jobs) {
+    jobById[job.id] = job;
+  }
+
+  const ready = getReadyJobs(state);
+  return ready.map((jobId) => ({
+    type: 'job.dispatched',
+    data: { graphId, jobId, target: jobById[jobId].target, payload: jobById[jobId].payload },
+  }));
+}

package/src/process-job-graph.e2e.specs.ts

@@ -0,0 +1,121 @@
+import { PipelineServer } from '@auto-engineer/pipeline';
+import { describe, expect, it } from 'vitest';
+import { COMMANDS } from './index';
+
+interface RegistryResponse {
+  commandHandlers: string[];
+  commandsWithMetadata: Array<{
+    name: string;
+    alias: string;
+    description: string;
+  }>;
+}
+
+interface CommandAck {
+  status: string;
+  commandId?: string;
+}
+
+interface StoredMessage {
+  message: { type: string; data?: Record<string, unknown> };
+  messageType: string;
+}
+
+async function fetchJson<T>(url: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(url, options);
+  return res.json() as Promise<T>;
+}
+
+describe('ProcessJobGraph E2E', () => {
+  it('registry shows ProcessJobGraph command handler', async () => {
+    const server = new PipelineServer({ port: 0 });
+    server.registerCommandHandlers(COMMANDS);
+    await server.start();
+
+    const registry = await fetchJson<RegistryResponse>(`http://localhost:${server.port}/registry`);
+
+    expect(registry.commandHandlers).toContain('ProcessJobGraph');
+    expect(registry.commandsWithMetadata).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: 'ProcessJobGraph',
+          alias: 'process:job-graph',
+          description: 'Process a directed acyclic graph of jobs with dependency tracking and failure policies',
+        }),
+      ]),
+    );
+
+    await server.stop();
+  });
+
+  it('command dispatch returns ack and produces graph.dispatching event', async () => {
+    const server = new PipelineServer({ port: 0 });
+    server.registerCommandHandlers(COMMANDS);
+    await server.start();
+
+    const ack = await fetchJson<CommandAck>(`http://localhost:${server.port}/command`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        type: 'ProcessJobGraph',
+        data: {
+          graphId: 'e2e-g1',
+          jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: { src: './app' } }],
+          failurePolicy: 'halt',
+        },
+      }),
+    });
+
+    expect(ack.status).toBe('ack');
+
+    await new Promise((r) => setTimeout(r, 200));
+
+    const messages = await fetchJson<StoredMessage[]>(`http://localhost:${server.port}/messages`);
+    const eventTypes = messages.filter((m) => m.messageType === 'event').map((m) => m.message.type);
+
+    expect(eventTypes).toContain('graph.dispatching');
+
+    await server.stop();
+  });
+
+  it('full lifecycle produces graph.completed via correlation', async () => {
+    const server = new PipelineServer({ port: 0 });
+    server.registerCommandHandlers(COMMANDS);
+    await server.start();
+
+    const completed: Array<{ type: string; data: Record<string, unknown> }> = [];
+    server.getMessageBus().subscribeToEvent('graph.completed', {
+      name: 'e2e-completion-tracker',
+      handle: (event) => {
+        completed.push(event);
+      },
+    });
+
+    await fetchJson<CommandAck>(`http://localhost:${server.port}/command`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        type: 'ProcessJobGraph',
+        data: {
+          graphId: 'e2e-g2',
+          jobs: [{ id: 'a', dependsOn: [], target: 'build', payload: {} }],
+          failurePolicy: 'halt',
+        },
+      }),
+    });
+
+    await new Promise((r) => setTimeout(r, 200));
+
+    await server.getMessageBus().publishEvent({
+      type: 'BuildCompleted',
+      data: { output: 'ok' },
+      correlationId: 'graph:e2e-g2:a',
+    });
+
+    await new Promise((r) => setTimeout(r, 100));
+
+    expect(completed).toEqual([{ type: 'graph.completed', data: { graphId: 'e2e-g2' } }]);
+
+    await server.stop();
+  });
+});