@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/openai-compatible-provider.js

@@ -0,0 +1,451 @@
+import { AiRuntimeError, isAiRuntimeError } from './ai-runtime-error.js';
+import {
+  buildErrorDebugRecord,
+  buildRequestDebugRecord,
+  buildResponseDebugRecord,
+  parseProviderErrorDescriptor,
+  writeAiRuntimeDebugRecord
+} from './ai-runtime-debug.js';
+import { projectStructuredOutputSchemaForProvider } from './structured-output-schema.js';
+
+export const DEFAULT_AI_TIMEOUT_MS = 60_000;
+export const DEFAULT_AI_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+
+const JSON_MEDIA_TYPE = /^(?:application\/(?:json|[a-z0-9.+-]+\+json))(?:\s*;|$)/i;
+const COMPLETED_FINISH_REASONS = new Set(['stop']);
+const REFUSAL_FINISH_REASONS = new Set(['content_filter', 'safety']);
+const PROVIDER_ERROR_DESCRIPTOR_MAX_CHARACTERS = 1024;
+const ALLOWED_REQUEST_EXTRA_FIELDS = new Set([
+  'temperature',
+  'top_p',
+  'max_tokens',
+  'max_completion_tokens',
+  'seed'
+]);
+
+function configurationError(message) {
+  return new AiRuntimeError('CONFIGURATION_ERROR', message);
+}
+
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw configurationError(`${name} must be a positive integer.`);
+  }
+  return value;
+}
+
+function isLoopbackHostname(hostname) {
+  const normalized = hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+  return normalized === 'localhost'
+    || normalized === '::1'
+    || /^127(?:\.\d{1,3}){3}$/.test(normalized);
+}
+
+export function validateOpenAiCompatibleEndpoint(endpoint) {
+  if (typeof endpoint !== 'string' || endpoint.length === 0) {
+    throw configurationError('OpenAI-compatible endpoint is required.');
+  }
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw configurationError('OpenAI-compatible endpoint must be a valid URL.');
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw configurationError('OpenAI-compatible endpoint must use HTTP or HTTPS.');
+  }
+  if (url.username || url.password) {
+    throw configurationError('OpenAI-compatible endpoint must not contain credentials.');
+  }
+  if (url.protocol === 'http:' && !isLoopbackHostname(url.hostname)) {
+    throw configurationError('Remote OpenAI-compatible endpoints must use HTTPS.');
+  }
+  return url;
+}
+
+function headerValue(headers, name) {
+  return headers && typeof headers.get === 'function' ? headers.get(name) : null;
+}
+
+async function discardBody(response) {
+  try {
+    await response?.body?.cancel?.();
+  } catch {
+    // Cleanup cannot change the sanitized provider result.
+  }
+}
+
+async function readFallbackText(response, maxResponseBytes) {
+  if (typeof response?.text !== 'function') {
+    await discardBody(response);
+    throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider response body is not readable.');
+  }
+  const text = String(await response.text());
+  if (Buffer.byteLength(text, 'utf8') > maxResponseBytes) {
+    throw new AiRuntimeError('RESPONSE_TOO_LARGE', 'AI provider response exceeded the configured size limit.');
+  }
+  return text;
+}
+
+async function readBoundedText(response, maxResponseBytes) {
+  const declaredLength = headerValue(response?.headers, 'content-length');
+  if (declaredLength !== null && /^\d+$/.test(declaredLength)
+    && Number(declaredLength) > maxResponseBytes) {
+    await discardBody(response);
+    throw new AiRuntimeError('RESPONSE_TOO_LARGE', 'AI provider response exceeded the configured size limit.');
+  }
+
+  const reader = response?.body?.getReader?.();
+  if (!reader) return readFallbackText(response, maxResponseBytes);
+
+  const chunks = [];
+  let byteCount = 0;
+  let complete = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        complete = true;
+        break;
+      }
+      const chunk = Buffer.from(value);
+      byteCount += chunk.length;
+      if (byteCount > maxResponseBytes) {
+        throw new AiRuntimeError('RESPONSE_TOO_LARGE', 'AI provider response exceeded the configured size limit.');
+      }
+      chunks.push(chunk);
+    }
+  } finally {
+    if (!complete) {
+      try {
+        await reader.cancel?.();
+      } catch {
+        // Cleanup cannot change the sanitized provider result.
+      }
+    }
+    try {
+      reader.releaseLock?.();
+    } catch {
+      // Cleanup cannot change the sanitized provider result.
+    }
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function httpError(status, providerError) {
+  const descriptor = Object.values(providerError)
+    .join(' ')
+    .slice(0, PROVIDER_ERROR_DESCRIPTOR_MAX_CHARACTERS)
+    .toLowerCase();
+  const mentionsSchema = /json[_ -]?schema|response[_ -]?format|structured[_ -]?output|schema/.test(descriptor);
+  const unsupported = /unsupported|not[_ -]?supported|does[_ -]?not[_ -]?support|unknown[_ -]?(?:field|parameter)|unrecognized/.test(descriptor);
+  const modelMissing = /model[_ -]?not[_ -]?found|no such model|unknown model|model does not exist/.test(descriptor);
+
+  if (status === 401) {
+    return new AiRuntimeError('AUTH_ERROR', 'AI provider rejected authentication.', { status });
+  }
+  if (status === 403) {
+    return new AiRuntimeError('ACCESS_DENIED', 'AI provider denied access to the requested resource.', { status });
+  }
+  if (status === 402) {
+    return new AiRuntimeError('INSUFFICIENT_CREDIT', 'AI provider reported insufficient credit.', { status });
+  }
+  if (status === 404 && modelMissing) {
+    return new AiRuntimeError('MODEL_NOT_FOUND', 'Configured AI model was not found.', { status });
+  }
+  if (status === 408 || status === 504) {
+    return new AiRuntimeError('TIMEOUT', 'AI provider request timed out.', { status, retryable: true });
+  }
+  if (status === 429) {
+    return new AiRuntimeError('RATE_LIMITED', 'AI provider rate limit was reached.', { status, retryable: true });
+  }
+  if (status === 502 || status === 503) {
+    return new AiRuntimeError('PROVIDER_UNAVAILABLE', 'AI provider is temporarily unavailable.', { status, retryable: true });
+  }
+  if (status === 400 || status === 422) {
+    if (mentionsSchema && unsupported) {
+      return new AiRuntimeError(
+        'STRUCTURED_OUTPUT_UNSUPPORTED',
+        'AI provider does not support the required structured output mode.',
+        { status }
+      );
+    }
+    if (mentionsSchema) {
+      return new AiRuntimeError('SCHEMA_REJECTED', 'AI provider rejected the required output schema.', { status });
+    }
+    return new AiRuntimeError('INVALID_REQUEST', 'AI provider rejected the request parameters.', { status });
+  }
+  return new AiRuntimeError('PROVIDER_ERROR', 'AI provider returned an unsuccessful response.', { status });
+}
+
+function nullableToken(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function normalizeUsage(usage) {
+  return {
+    inputTokens: nullableToken(usage?.prompt_tokens),
+    outputTokens: nullableToken(usage?.completion_tokens),
+    totalTokens: nullableToken(usage?.total_tokens)
+  };
+}
+
+function validateSuccessEnvelope(body) {
+  if (!body || typeof body !== 'object' || !Array.isArray(body.choices) || body.choices.length !== 1) {
+    throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider returned an invalid response envelope.');
+  }
+  const choice = body.choices[0];
+  const message = choice?.message;
+  const finishReason = choice?.finish_reason;
+
+  if (finishReason === 'length') {
+    throw new AiRuntimeError('OUTPUT_TRUNCATED', 'AI provider output was truncated.');
+  }
+  if (REFUSAL_FINISH_REASONS.has(finishReason) || (typeof message?.refusal === 'string' && message.refusal.length > 0)) {
+    throw new AiRuntimeError('CONTENT_REFUSED', 'AI provider refused the requested content.');
+  }
+  if (message?.tool_calls?.length > 0 || message?.function_call || ['tool_calls', 'function_call'].includes(finishReason)) {
+    throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider returned a tool call instead of final content.');
+  }
+  if (!COMPLETED_FINISH_REASONS.has(finishReason)) {
+    throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider did not return a completed response.');
+  }
+  if (!message || message.role !== 'assistant'
+    || typeof message.content !== 'string' || message.content.trim().length === 0) {
+    throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider returned no usable assistant content.');
+  }
+  return message.content;
+}
+
+function validateStructuredRequest(request) {
+  if (typeof request?.systemPrompt !== 'string' || typeof request?.userPrompt !== 'string') {
+    throw configurationError('Runtime request requires rendered systemPrompt and userPrompt.');
+  }
+  const structuredOutput = request.structuredOutput;
+  if (structuredOutput?.mode !== 'jsonSchema') {
+    throw new AiRuntimeError(
+      'STRUCTURED_OUTPUT_UNSUPPORTED',
+      'Runtime request requires JSON Schema structured output.'
+    );
+  }
+  if (!structuredOutput.schema || typeof structuredOutput.schema !== 'object' || Array.isArray(structuredOutput.schema)) {
+    throw configurationError('Runtime request requires an exact output schema.');
+  }
+  if (typeof structuredOutput.name !== 'string'
+    || !/^[A-Za-z0-9_-]{1,64}$/.test(structuredOutput.name)) {
+    throw configurationError('Runtime request requires a valid deterministic schema name.');
+  }
+  return structuredOutput;
+}
+
+function createRequestBody(request, model, requestExtras) {
+  const structuredOutput = validateStructuredRequest(request);
+  const allowedExtras = Object.fromEntries(
+    Object.entries(requestExtras).filter(([key]) => ALLOWED_REQUEST_EXTRA_FIELDS.has(key))
+  );
+  return {
+    ...structuredClone(allowedExtras),
+    model,
+    messages: [
+      { role: 'system', content: request.systemPrompt },
+      { role: 'user', content: request.userPrompt }
+    ],
+    response_format: {
+      type: 'json_schema',
+      json_schema: {
+        name: structuredOutput.name,
+        strict: true,
+        schema: projectStructuredOutputSchemaForProvider(structuredOutput.schema)
+      }
+    },
+    stream: false
+  };
+}
+
+/**
+ * Non-streaming provider for the common OpenAI-compatible Chat Completions
+ * wire protocol. It does not parse or validate the task candidate JSON.
+ */
+export function createOpenAiCompatibleProvider({
+  endpoint,
+  model,
+  authorization,
+  provider = 'openai-compatible',
+  fetchImplementation = globalThis.fetch,
+  timeoutMs = DEFAULT_AI_TIMEOUT_MS,
+  maxResponseBytes = DEFAULT_AI_MAX_RESPONSE_BYTES,
+  requestExtras = {},
+  requireExactModelIdentity = false,
+  debug = false,
+  debugWriter = process.stderr,
+  clock = Date
+} = {}) {
+  const url = validateOpenAiCompatibleEndpoint(endpoint);
+  if (typeof model !== 'string' || model.trim().length === 0) {
+    throw configurationError('OpenAI-compatible model is required.');
+  }
+  if (typeof fetchImplementation !== 'function') {
+    throw configurationError('A WHATWG-compatible fetch implementation is required.');
+  }
+  if (authorization !== undefined && typeof authorization !== 'string') {
+    throw configurationError('OpenAI-compatible authorization must be a string when provided.');
+  }
+  if (!requestExtras || typeof requestExtras !== 'object' || Array.isArray(requestExtras)) {
+    throw configurationError('OpenAI-compatible request extras must be an object.');
+  }
+  if (typeof debug !== 'boolean') {
+    throw configurationError('OpenAI-compatible debug must be a boolean.');
+  }
+  if (debug && typeof debugWriter !== 'function' && typeof debugWriter?.write !== 'function') {
+    throw configurationError('OpenAI-compatible debug writer must be a function or writable stream.');
+  }
+  positiveInteger(timeoutMs, 'timeoutMs');
+  positiveInteger(maxResponseBytes, 'maxResponseBytes');
+
+  return {
+    name: provider,
+    model,
+    async generateStructured(request) {
+      const startedAt = clock.now();
+      let requestBody;
+      let serializedBody;
+      try {
+        requestBody = createRequestBody(request, model, requestExtras);
+        serializedBody = JSON.stringify(requestBody);
+      } catch (error) {
+        if (isAiRuntimeError(error)) throw error;
+        throw configurationError('OpenAI-compatible request could not be serialized.');
+      }
+
+      if (debug) {
+        writeAiRuntimeDebugRecord(debugWriter, buildRequestDebugRecord({
+          provider,
+          endpoint: url,
+          model,
+          requestBody,
+          serializedBody,
+          structuredOutputMode: request.structuredOutput.mode,
+          requestExtraKeys: Object.keys(requestExtras).filter((key) => ALLOWED_REQUEST_EXTRA_FIELDS.has(key))
+        }));
+      }
+
+      const controller = new AbortController();
+      let timedOut = false;
+      const onCallerAbort = () => controller.abort();
+      if (request?.signal?.aborted) controller.abort();
+      else request?.signal?.addEventListener?.('abort', onCallerAbort, { once: true });
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, timeoutMs);
+
+      try {
+        let response;
+        try {
+          response = await fetchImplementation(url, {
+            method: 'POST',
+            headers: {
+              accept: 'application/json',
+              'content-type': 'application/json',
+              ...(authorization ? { authorization } : {})
+            },
+            body: serializedBody,
+            credentials: 'omit',
+            redirect: 'error',
+            signal: controller.signal
+          });
+        } catch (error) {
+          if (isAiRuntimeError(error)) throw error;
+          if (timedOut) throw new AiRuntimeError('TIMEOUT', 'AI provider request timed out.', { retryable: true });
+          if (request?.signal?.aborted || error?.name === 'AbortError') {
+            throw new AiRuntimeError('CANCELLED', 'AI provider request was cancelled.');
+          }
+          throw new AiRuntimeError('NETWORK_ERROR', 'AI provider network request failed.', { retryable: true });
+        }
+
+        if (!response || !Number.isInteger(response.status)) {
+          await discardBody(response);
+          throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider returned an invalid HTTP response.');
+        }
+        let text;
+        try {
+          text = await readBoundedText(response, maxResponseBytes);
+        } catch (error) {
+          if (timedOut && !isAiRuntimeError(error)) {
+            throw new AiRuntimeError('TIMEOUT', 'AI provider request timed out.', { retryable: true });
+          }
+          throw error;
+        }
+        if (response.status < 200 || response.status >= 300) {
+          const providerError = parseProviderErrorDescriptor(text);
+          const runtimeError = httpError(response.status, providerError);
+          if (debug) {
+            writeAiRuntimeDebugRecord(debugWriter, buildErrorDebugRecord({
+              status: response.status,
+              runtimeError,
+              providerError,
+              responseText: text,
+              latencyMs: Math.max(0, clock.now() - startedAt)
+            }));
+          }
+          throw runtimeError;
+        }
+
+        const contentType = headerValue(response.headers, 'content-type');
+        if (!contentType || !JSON_MEDIA_TYPE.test(contentType)) {
+          throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider response must use a JSON media type.');
+        }
+        let body;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          throw new AiRuntimeError('INVALID_RESPONSE', 'AI provider response is not valid JSON.');
+        }
+        const output = validateSuccessEnvelope(body);
+        const actualModel = typeof body.model === 'string' && body.model.length > 0 ? body.model : null;
+        if (requireExactModelIdentity && actualModel !== model) {
+          throw new AiRuntimeError('IDENTITY_MISMATCH', 'AI provider returned an unexpected model identity.');
+        }
+        const providerRequestId = typeof body.id === 'string' && /^[A-Za-z0-9._:-]{1,256}$/.test(body.id)
+          ? body.id
+          : null;
+        const usage = normalizeUsage(body.usage);
+        const latencyMs = Math.max(0, clock.now() - startedAt);
+        if (debug) {
+          writeAiRuntimeDebugRecord(debugWriter, buildResponseDebugRecord({
+            status: response.status,
+            contentType,
+            responseText: text,
+            body,
+            assistantContent: output,
+            requestedModel: model,
+            actualModel,
+            usage,
+            latencyMs
+          }));
+        }
+        return {
+          output,
+          provider,
+          requestedProvider: provider,
+          model,
+          requestedModel: model,
+          actualModel,
+          finishReason: 'complete',
+          usage,
+          latencyMs,
+          providerRequestId,
+          attemptCount: 1,
+          retryCount: 0,
+          fallbackCount: 0,
+          fallbackOccurred: false
+        };
+      } finally {
+        clearTimeout(timer);
+        request?.signal?.removeEventListener?.('abort', onCallerAbort);
+      }
+    }
+  };
+}

package/src/orchestration/failure-log.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+
+import { DEFAULT_ANALYSIS_LOG_PATH, PRODUCT_NAME } from '../constants.js';
+import { writeTextArtifact } from './text-writer.js';
+
+export function renderAnalysisFailureLog(error) {
+  const message = error.cause?.message ?? error.message;
+  const lines = [
+    `${PRODUCT_NAME} analysis failure`,
+    `Stage: ${error.stage.label}`,
+    `Message: ${message}`
+  ];
+  if (error.cause?.decision) {
+    lines.push(
+      `Qualification status: ${error.cause.decision.status}`,
+      `Reason: ${error.cause.decision.reasonCode}`,
+      `Source: ${error.cause.decision.sourceKind}`,
+      `Next action: ${error.cause.decision.nextAction}`
+    );
+  } else if (typeof error.cause?.code === 'string') {
+    lines.push(`Reason: ${error.cause.code}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function writeAnalysisFailureLog(repositoryRoot, error) {
+  return writeTextArtifact(
+    path.join(repositoryRoot, DEFAULT_ANALYSIS_LOG_PATH),
+    renderAnalysisFailureLog(error)
+  );
+}

package/src/orchestration/pipeline.js

@@ -0,0 +1,200 @@
+import { createProgressEventRuntime } from './progress-events.js';
+
+export const ANALYSIS_STAGES = Object.freeze([
+  Object.freeze({ id: 'projectDiscovery', label: 'Project Discovery' }),
+  Object.freeze({ id: 'knowledgeResearch', label: 'Knowledge Research' }),
+  Object.freeze({ id: 'versionAnalysis', label: 'Version Analysis' }),
+  Object.freeze({ id: 'usageDiscovery', label: 'Repository Usage Discovery' }),
+  Object.freeze({ id: 'impactAnalysis', label: 'Repository Impact Analysis' }),
+  Object.freeze({ id: 'impactEvidence', label: 'Repository Impact Evidence' }),
+  Object.freeze({ id: 'upgradeDecision', label: 'Deterministic Upgrade Decision' }),
+  Object.freeze({ id: 'markdownReport', label: 'Markdown Report' })
+]);
+
+export const MIGRATION_CHECKLIST_ANALYSIS_STAGE = Object.freeze({
+  id: 'migrationChecklist',
+  label: 'Migration Checklist'
+});
+
+export const ANALYSIS_STAGE_INITIAL_ACTIVITIES = Object.freeze({
+  projectDiscovery: Object.freeze({
+    activityKind: 'DISCOVER_PROJECT_MANIFESTS',
+    subject: 'Discovering project manifests'
+  }),
+  knowledgeResearch: Object.freeze({
+    activityKind: 'RESEARCH_DEPENDENCY_METADATA',
+    subject: 'Researching dependency metadata'
+  }),
+  versionAnalysis: Object.freeze({
+    activityKind: 'PREPARE_DEPENDENCY_ANALYSIS',
+    subject: 'Preparing dependency analysis'
+  }),
+  usageDiscovery: Object.freeze({
+    activityKind: 'SCAN_SUPPORTED_SOURCE',
+    subject: 'Scanning supported source files'
+  }),
+  impactAnalysis: Object.freeze({
+    activityKind: 'MATCH_REPOSITORY_IMPACT',
+    subject: 'Matching repository impact'
+  }),
+  impactEvidence: Object.freeze({
+    activityKind: 'VALIDATE_IMPACT_EVIDENCE',
+    subject: 'Validating repository impact evidence'
+  }),
+  upgradeDecision: Object.freeze({
+    activityKind: 'APPLY_UPGRADE_DECISION_POLICY',
+    subject: 'Applying deterministic upgrade decision policy'
+  }),
+  migrationChecklist: Object.freeze({
+    activityKind: 'PREPARE_MIGRATION_CONTEXTS',
+    subject: 'Preparing Migration Checklist contexts'
+  }),
+  markdownReport: Object.freeze({
+    activityKind: 'RENDER_MARKDOWN_REPORT',
+    subject: 'Rendering Markdown report'
+  })
+});
+
+export function createAnalysisStages({ migrationChecklist = false } = {}) {
+  if (!migrationChecklist) return ANALYSIS_STAGES;
+  return Object.freeze([
+    ...ANALYSIS_STAGES.slice(0, -1),
+    MIGRATION_CHECKLIST_ANALYSIS_STAGE,
+    ANALYSIS_STAGES.at(-1)
+  ]);
+}
+
+export class PipelineStageError extends Error {
+  constructor(stage, cause) {
+    super(`${stage.label} failed: ${cause?.message ?? String(cause)}`, { cause });
+    this.name = 'PipelineStageError';
+    this.stage = stage;
+  }
+}
+
+export class PipelineCancellationError extends Error {
+  constructor(stage = null, cause = null) {
+    super(stage ? `${stage.label} was cancelled.` : 'Analysis was cancelled.', { cause });
+    this.name = 'PipelineCancellationError';
+    this.code = 'ANALYSIS_CANCELLED';
+    this.stage = stage;
+  }
+}
+
+function validateRunners(runners, stages) {
+  for (const stage of stages) {
+    if (typeof runners?.[stage.id] !== 'function') {
+      throw new Error(`Analysis pipeline requires a ${stage.id} stage runner.`);
+    }
+  }
+}
+
+function failureReasonCode(cause) {
+  return typeof cause?.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(cause.code)
+    ? cause.code
+    : 'STAGE_FAILED';
+}
+
+function abortError(stage, signal) {
+  return new PipelineCancellationError(stage, signal?.reason);
+}
+
+async function runWithSignal(run, signal, stage) {
+  if (!signal) return run();
+  if (signal.aborted) throw abortError(stage, signal);
+  let removeAbortListener = () => {};
+  const aborted = new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(stage, signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener('abort', onAbort);
+  });
+  try {
+    return await Promise.race([run(), aborted]);
+  } finally {
+    removeAbortListener();
+  }
+}
+
+export async function runAnalysisPipeline({
+  repositoryRoot,
+  runners,
+  progressReporter,
+  stages = ANALYSIS_STAGES,
+  signal,
+  progressListener,
+  progressOptions = {}
+}) {
+  validateRunners(runners, stages);
+  const artifacts = {};
+  const progress = createProgressEventRuntime({
+    stages,
+    listener(event) {
+      try {
+        progressReporter?.handle?.(event)?.catch?.(() => {});
+      } catch {
+        // Reporter failures are isolated from business execution.
+      }
+      try {
+        progressListener?.(event)?.catch?.(() => {});
+      } catch {
+        // Observer failures are isolated from business execution.
+      }
+    },
+    ...progressOptions
+  });
+  progress.startRun();
+
+  try {
+    if (signal?.aborted) {
+      for (const stage of stages) progress.skipStage(stage.id, 'RUN_CANCELLED');
+      progress.cancelRun();
+      throw abortError(null, signal);
+    }
+    for (let index = 0; index < stages.length; index += 1) {
+      const stage = stages[index];
+      progress.startStage(stage.id);
+      const initialActivity = ANALYSIS_STAGE_INITIAL_ACTIVITIES[stage.id];
+      if (initialActivity) progress.activity(stage.id, initialActivity);
+      const reportActivity = (activity) => {
+        try {
+          progress.activity(stage.id, activity);
+        } catch {
+          // Invalid or throwing progress instrumentation cannot affect stage output.
+        }
+      };
+      try {
+        artifacts[stage.id] = await runWithSignal(() => runners[stage.id]({
+          repositoryRoot,
+          artifacts: Object.freeze({ ...artifacts }),
+          progress: reportActivity,
+          signal
+        }), signal, stage);
+        if (signal?.aborted) throw abortError(stage, signal);
+        progress.completeStage(stage.id);
+      } catch (cause) {
+        if (cause instanceof PipelineCancellationError || signal?.aborted) {
+          progress.cancelStage(stage.id, 'USER_CANCELLED');
+          for (const remaining of stages.slice(index + 1)) {
+            progress.skipStage(remaining.id, 'RUN_CANCELLED');
+          }
+          progress.cancelRun();
+          throw cause instanceof PipelineCancellationError ? cause : abortError(stage, signal);
+        }
+        progress.failStage(stage.id, failureReasonCode(cause));
+        for (const remaining of stages.slice(index + 1)) {
+          progress.skipStage(remaining.id, 'PRIOR_STAGE_FAILED');
+        }
+        progress.failRun();
+        throw new PipelineStageError(stage, cause);
+      }
+    }
+    progress.completeRun();
+    return Object.freeze({
+      repositoryRoot,
+      artifacts: Object.freeze({ ...artifacts }),
+      progress: progress.snapshot()
+    });
+  } finally {
+    progress.dispose();
+  }
+}