@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/engine/run-reconciliation.ts

@@ -0,0 +1,116 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import {
+  rebuildVisits,
+  refreshApprovedGateHistory,
+  retainedReviewedArtifact,
+} from './reconciliation-history.ts';
+import type { WorkflowRun } from './state-types.ts';
+import { withRunUpdate } from './transition-helpers.ts';
+import type { ReconcileResult } from './transition-types.ts';
+
+/**
+ * Reconciles persisted run state with a reloaded workflow configuration.
+ *
+ * The earliest changed completed step is restarted. Changes limited to the
+ * current step restart that step, while incompatible removals return an error.
+ *
+ * @param run - Persisted workflow state.
+ * @param workflow - Reloaded workflow.
+ * @param now - Reconciliation timestamp.
+ * @returns Reconciled state and restart metadata.
+ */
+export const reconcileRun = (
+  run: WorkflowRun,
+  workflow: LoadedWorkflow,
+  now: number,
+): ReconcileResult => {
+  if (run.workflowId !== workflow.definition.id) {
+    return {
+      changed: false,
+      error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`,
+    };
+  }
+  if (run.workflowDigest === workflow.digest) {
+    return { run, changed: false };
+  }
+  if (!workflow.definition.steps[run.currentStepId]) {
+    return {
+      changed: true,
+      error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`,
+    };
+  }
+
+  const reconciledRun = refreshApprovedGateHistory(run, workflow);
+  const changedHistoryIndex = reconciledRun.history.findIndex(
+    (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
+  );
+  if (changedHistoryIndex >= 0) {
+    const changedEntry = reconciledRun.history[changedHistoryIndex];
+    if (!changedEntry || !workflow.definition.steps[changedEntry.stepId]) {
+      return {
+        changed: true,
+        error:
+          'a completed step was removed; abort or restore the configuration',
+      };
+    }
+
+    const retainedHistory = reconciledRun.history.slice(0, changedHistoryIndex);
+    const restartedStep = changedEntry.stepId;
+    const stepHandoff = retainedHistory.at(-1)?.summary ?? '';
+    return {
+      changed: true,
+      restartedStep,
+      run: withRunUpdate(
+        reconciledRun,
+        {
+          workflowDigest: workflow.digest,
+          status: 'paused',
+          currentStepId: restartedStep,
+          currentStepDigest: workflow.stepDigests[restartedStep] ?? '',
+          history: retainedHistory,
+          visits: rebuildVisits(retainedHistory, restartedStep),
+          reviewedArtifact: retainedReviewedArtifact(
+            workflow,
+            reconciledRun,
+            retainedHistory,
+          ),
+          stepHandoff,
+          lastSummary: stepHandoff,
+          pendingGate: undefined,
+          pausedFrom: 'running',
+          failedStepId: undefined,
+          pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
+          gateFeedback: '',
+        },
+        now,
+      ),
+    };
+  }
+
+  const currentDigest = workflow.stepDigests[run.currentStepId] ?? '';
+  const hasCurrentStepChanged =
+    currentDigest !== reconciledRun.currentStepDigest;
+  const restartChanges: Partial<WorkflowRun> = hasCurrentStepChanged
+    ? {
+        status: 'paused',
+        pendingGate: undefined,
+        pausedFrom: 'running',
+        failedStepId: undefined,
+        pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
+        gateFeedback: '',
+      }
+    : {};
+  return {
+    changed: true,
+    ...(hasCurrentStepChanged ? { restartedStep: run.currentStepId } : {}),
+    run: withRunUpdate(
+      reconciledRun,
+      {
+        ...restartChanges,
+        workflowDigest: workflow.digest,
+        currentStepDigest: currentDigest,
+      },
+      now,
+    ),
+  };
+};

package/src/engine/run-validation.ts

@@ -0,0 +1,129 @@
+import {
+  RUN_STATE_VERSION,
+  type GateResolution,
+  type PendingGate,
+  type StepHistoryEntry,
+  type WorkflowRun,
+  type WorkflowRunStatus,
+} from './state-types.ts';
+
+type UnknownRecord = Readonly<Record<string, unknown>>;
+
+const isRecord = (value: unknown): value is UnknownRecord =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const isStepHistoryEntry = (value: unknown): value is StepHistoryEntry =>
+  isRecord(value) &&
+  typeof value.stepId === 'string' &&
+  typeof value.stepDigest === 'string' &&
+  typeof value.outcome === 'string' &&
+  typeof value.summary === 'string' &&
+  typeof value.completedAt === 'number';
+
+const isGateResolution = (value: unknown): value is GateResolution =>
+  isRecord(value) &&
+  typeof value.approved === 'boolean' &&
+  typeof value.feedback === 'string' &&
+  typeof value.resolvedAt === 'number';
+
+const isPendingGate = (value: unknown): value is PendingGate =>
+  isRecord(value) &&
+  (value.provider === 'prompt' || value.provider === 'plannotator') &&
+  typeof value.requestId === 'string' &&
+  value.requestId.length > 0 &&
+  typeof value.stepId === 'string' &&
+  typeof value.artifact === 'string' &&
+  (value.summary === undefined || typeof value.summary === 'string') &&
+  typeof value.submittedOutcome === 'string' &&
+  typeof value.requestedAt === 'number' &&
+  (value.reviewId === undefined || typeof value.reviewId === 'string') &&
+  (value.resolution === undefined || isGateResolution(value.resolution));
+
+const isVisitCounts = (value: unknown): value is Record<string, number> =>
+  isRecord(value) &&
+  Object.values(value).every(
+    (count) =>
+      typeof count === 'number' && Number.isInteger(count) && count >= 0,
+  );
+
+const isOptionalString = (value: unknown): value is string | undefined =>
+  value === undefined || typeof value === 'string';
+
+const isWorkflowRunStatus = (value: unknown): value is WorkflowRunStatus =>
+  value === 'running' ||
+  value === 'paused' ||
+  value === 'awaiting-gate' ||
+  value === 'completed' ||
+  value === 'aborted';
+
+const hasValidPauseState = (run: UnknownRecord): boolean =>
+  run.status === 'paused'
+    ? run.pausedFrom === 'running' || run.pausedFrom === 'awaiting-gate'
+    : run.pausedFrom === undefined;
+
+const hasValidFailureState = (run: UnknownRecord): boolean =>
+  run.failedStepId === undefined ||
+  (run.status === 'paused' && run.failedStepId === run.currentStepId);
+
+const hasValidGateState = (
+  run: UnknownRecord,
+  pendingGate: PendingGate | undefined,
+): boolean =>
+  pendingGate === undefined
+    ? run.status !== 'awaiting-gate' && run.pausedFrom !== 'awaiting-gate'
+    : pendingGate.stepId === run.currentStepId &&
+      (run.status === 'awaiting-gate' ||
+        (run.status === 'paused' && run.pausedFrom === 'awaiting-gate'));
+
+/**
+ * Validates an unknown value as a persisted workflow run.
+ *
+ * State invariants are checked in addition to field types so corrupt
+ * checkpoints cannot resume into an impossible gate, pause, or failure state.
+ *
+ * @param value - Persisted value to validate.
+ * @returns `true` when the value is a valid workflow run.
+ */
+export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
+  if (!isRecord(value)) return false;
+
+  const hasValidRequiredFields =
+    value.stateVersion === RUN_STATE_VERSION &&
+    typeof value.runId === 'string' &&
+    typeof value.workflowId === 'string' &&
+    typeof value.workflowDigest === 'string' &&
+    typeof value.input === 'string' &&
+    isWorkflowRunStatus(value.status) &&
+    typeof value.currentStepId === 'string' &&
+    typeof value.currentStepDigest === 'string' &&
+    Array.isArray(value.baselineTools) &&
+    value.baselineTools.every((tool) => typeof tool === 'string') &&
+    Array.isArray(value.history) &&
+    value.history.every(isStepHistoryEntry) &&
+    isVisitCounts(value.visits) &&
+    typeof value.startedAt === 'number' &&
+    typeof value.updatedAt === 'number' &&
+    typeof value.lastSummary === 'string' &&
+    typeof value.gateFeedback === 'string';
+  if (!hasValidRequiredFields) return false;
+
+  const hasValidOptionalFields =
+    isOptionalString(value.reviewedArtifact) &&
+    isOptionalString(value.reviewedFeedback) &&
+    isOptionalString(value.stepHandoff) &&
+    isOptionalString(value.pauseReason) &&
+    isOptionalString(value.failedStepId) &&
+    (value.pausedFrom === undefined ||
+      value.pausedFrom === 'running' ||
+      value.pausedFrom === 'awaiting-gate');
+  if (!hasValidOptionalFields) return false;
+
+  const pendingGate = value.pendingGate;
+  if (pendingGate !== undefined && !isPendingGate(pendingGate)) return false;
+
+  return (
+    hasValidPauseState(value) &&
+    hasValidFailureState(value) &&
+    hasValidGateState(value, pendingGate)
+  );
+};

package/src/engine/state-types.ts

@@ -0,0 +1,66 @@
+export const RUN_STATE_VERSION = 1 as const;
+
+export type WorkflowRunStatus =
+  'running' | 'paused' | 'awaiting-gate' | 'completed' | 'aborted';
+
+export type StepHistoryEntry = {
+  readonly stepId: string;
+  readonly stepDigest: string;
+  readonly outcome: string;
+  readonly summary: string;
+  readonly completedAt: number;
+};
+
+export type GateResolution = {
+  readonly approved: boolean;
+  readonly feedback: string;
+  readonly resolvedAt: number;
+};
+
+export type PendingGate = {
+  readonly provider: 'prompt' | 'plannotator';
+  readonly requestId: string;
+  readonly stepId: string;
+  readonly artifact: string;
+  /** Legacy v1 field. New runs use the reviewed artifact as the handoff. */
+  summary?: string | undefined;
+  readonly submittedOutcome: string;
+  readonly requestedAt: number;
+  readonly reviewId?: string | undefined;
+  readonly resolution?: GateResolution | undefined;
+};
+
+export type WorkflowRun = {
+  readonly stateVersion: typeof RUN_STATE_VERSION;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly workflowDigest: string;
+  readonly input: string;
+  readonly status: WorkflowRunStatus;
+  readonly currentStepId: string;
+  readonly currentStepDigest: string;
+  readonly baselineTools: ReadonlyArray<string>;
+  readonly visits: Readonly<Record<string, number>>;
+  readonly history: ReadonlyArray<StepHistoryEntry>;
+  readonly startedAt: number;
+  readonly updatedAt: number;
+  /**
+   * Most recent human-approved gate artifact. This is the only provenance
+   * source from which reviewed Bash capabilities may be derived.
+   */
+  readonly reviewedArtifact?: string | undefined;
+  /** Final feedback paired with the immutable approved artifact. */
+  readonly reviewedFeedback?: string | undefined;
+  /**
+   * Input inherited from the previous completed step. Unlike `lastSummary`,
+   * this survives a paused attempt of the current step.
+   */
+  readonly stepHandoff?: string | undefined;
+  readonly lastSummary: string;
+  readonly gateFeedback: string;
+  readonly pauseReason?: string | undefined;
+  readonly pausedFrom?: 'running' | 'awaiting-gate' | undefined;
+  /** Current step when execution failed and was paused for a resumable retry. */
+  readonly failedStepId?: string | undefined;
+  readonly pendingGate?: PendingGate | undefined;
+};

package/src/engine/state.ts

@@ -1,193 +1,10 @@
-import type { LoadedWorkflow } from '../config/types.ts';
-
-export const RUN_STATE_VERSION = 1 as const;
-
-export type WorkflowRunStatus =
-  'running' | 'paused' | 'awaiting-gate' | 'completed' | 'aborted';
-
-export interface StepHistoryEntry {
-  stepId: string;
-  stepDigest: string;
-  outcome: string;
-  summary: string;
-  completedAt: number;
-}
-
-export interface GateResolution {
-  approved: boolean;
-  feedback: string;
-  resolvedAt: number;
-}
-
-export interface PendingGate {
-  provider: 'prompt' | 'plannotator';
-  requestId: string;
-  stepId: string;
-  artifact: string;
-  /** Legacy v1 field. New runs use the reviewed artifact as the handoff. */
-  summary?: string | undefined;
-  submittedOutcome: string;
-  requestedAt: number;
-  reviewId?: string | undefined;
-  resolution?: GateResolution | undefined;
-}
-
-export interface WorkflowRun {
-  stateVersion: typeof RUN_STATE_VERSION;
-  runId: string;
-  workflowId: string;
-  workflowDigest: string;
-  input: string;
-  status: WorkflowRunStatus;
-  currentStepId: string;
-  currentStepDigest: string;
-  baselineTools: string[];
-  visits: Record<string, number>;
-  history: StepHistoryEntry[];
-  startedAt: number;
-  updatedAt: number;
-  /**
-   * Most recent human-approved gate artifact. This is the only provenance
-   * source from which reviewed Bash capabilities may be derived.
-   */
-  reviewedArtifact?: string | undefined;
-  /**
-   * Input inherited from the previous completed step. Unlike `lastSummary`,
-   * this survives a paused attempt of the current step.
-   */
-  stepHandoff?: string | undefined;
-  lastSummary: string;
-  gateFeedback: string;
-  pauseReason?: string | undefined;
-  pausedFrom?: 'running' | 'awaiting-gate' | undefined;
-  /** Current step when execution failed and was paused for a resumable retry. */
-  failedStepId?: string | undefined;
-  pendingGate?: PendingGate | undefined;
-}
-
-export function createRun(
-  workflow: LoadedWorkflow,
-  input: string,
-  baselineTools: string[],
-  runId: string,
-  now: number,
-): WorkflowRun {
-  const start = workflow.definition.start;
-  return {
-    stateVersion: RUN_STATE_VERSION,
-    runId,
-    workflowId: workflow.definition.id,
-    workflowDigest: workflow.digest,
-    input,
-    status: 'running',
-    currentStepId: start,
-    currentStepDigest: workflow.stepDigests[start] ?? '',
-    baselineTools: [...new Set(baselineTools)],
-    visits: { [start]: 1 },
-    history: [],
-    startedAt: now,
-    updatedAt: now,
-    reviewedArtifact: '',
-    stepHandoff: '',
-    lastSummary: '',
-    gateFeedback: '',
-  };
-}
-
-export function isWorkflowRun(value: unknown): value is WorkflowRun {
-  if (value === null || typeof value !== 'object') return false;
-  const run = value as Partial<WorkflowRun>;
-  const historyIsValid =
-    Array.isArray(run.history) &&
-    run.history.every(
-      (entry) =>
-        entry !== null &&
-        typeof entry === 'object' &&
-        typeof entry.stepId === 'string' &&
-        typeof entry.stepDigest === 'string' &&
-        typeof entry.outcome === 'string' &&
-        typeof entry.summary === 'string' &&
-        typeof entry.completedAt === 'number',
-    );
-  const visitsAreValid =
-    run.visits !== null &&
-    typeof run.visits === 'object' &&
-    !Array.isArray(run.visits) &&
-    Object.values(run.visits).every(
-      (count) => Number.isInteger(count) && count >= 0,
-    );
-  const gateIsValid =
-    run.pendingGate === undefined ||
-    (run.pendingGate !== null &&
-      typeof run.pendingGate === 'object' &&
-      (run.pendingGate.provider === 'prompt' ||
-        run.pendingGate.provider === 'plannotator') &&
-      typeof run.pendingGate.requestId === 'string' &&
-      run.pendingGate.requestId.length > 0 &&
-      typeof run.pendingGate.stepId === 'string' &&
-      typeof run.pendingGate.artifact === 'string' &&
-      (run.pendingGate.summary === undefined ||
-        typeof run.pendingGate.summary === 'string') &&
-      typeof run.pendingGate.submittedOutcome === 'string' &&
-      typeof run.pendingGate.requestedAt === 'number' &&
-      (run.pendingGate.reviewId === undefined ||
-        typeof run.pendingGate.reviewId === 'string') &&
-      (run.pendingGate.resolution === undefined ||
-        (run.pendingGate.resolution !== null &&
-          typeof run.pendingGate.resolution === 'object' &&
-          typeof run.pendingGate.resolution.approved === 'boolean' &&
-          typeof run.pendingGate.resolution.feedback === 'string' &&
-          typeof run.pendingGate.resolution.resolvedAt === 'number')));
-  const optionalsAreValid =
-    (run.reviewedArtifact === undefined ||
-      typeof run.reviewedArtifact === 'string') &&
-    (run.stepHandoff === undefined || typeof run.stepHandoff === 'string') &&
-    (run.pauseReason === undefined || typeof run.pauseReason === 'string') &&
-    (run.failedStepId === undefined || typeof run.failedStepId === 'string') &&
-    (run.pausedFrom === undefined ||
-      run.pausedFrom === 'running' ||
-      run.pausedFrom === 'awaiting-gate');
-  const statusIsValid =
-    run.status === 'running' ||
-    run.status === 'paused' ||
-    run.status === 'awaiting-gate' ||
-    run.status === 'completed' ||
-    run.status === 'aborted';
-  const pauseStateIsValid =
-    run.status === 'paused'
-      ? run.pausedFrom === 'running' || run.pausedFrom === 'awaiting-gate'
-      : run.pausedFrom === undefined;
-  const failureStateIsValid =
-    run.failedStepId === undefined ||
-    (run.status === 'paused' && run.failedStepId === run.currentStepId);
-  const gateStateIsValid = !gateIsValid
-    ? false
-    : run.pendingGate === undefined
-      ? run.status !== 'awaiting-gate' && run.pausedFrom !== 'awaiting-gate'
-      : run.pendingGate.stepId === run.currentStepId &&
-        (run.status === 'awaiting-gate' ||
-          (run.status === 'paused' && run.pausedFrom === 'awaiting-gate'));
-  return (
-    run.stateVersion === RUN_STATE_VERSION &&
-    typeof run.runId === 'string' &&
-    typeof run.workflowId === 'string' &&
-    typeof run.workflowDigest === 'string' &&
-    typeof run.input === 'string' &&
-    typeof run.currentStepId === 'string' &&
-    typeof run.currentStepDigest === 'string' &&
-    Array.isArray(run.baselineTools) &&
-    run.baselineTools.every((tool) => typeof tool === 'string') &&
-    historyIsValid &&
-    visitsAreValid &&
-    gateIsValid &&
-    optionalsAreValid &&
-    statusIsValid &&
-    pauseStateIsValid &&
-    failureStateIsValid &&
-    gateStateIsValid &&
-    typeof run.startedAt === 'number' &&
-    typeof run.updatedAt === 'number' &&
-    typeof run.lastSummary === 'string' &&
-    typeof run.gateFeedback === 'string'
-  );
-}
+export { createRun } from './create-run.ts';
+export { isWorkflowRun } from './run-validation.ts';
+export { RUN_STATE_VERSION } from './state-types.ts';
+export type {
+  GateResolution,
+  PendingGate,
+  StepHistoryEntry,
+  WorkflowRun,
+  WorkflowRunStatus,
+} from './state-types.ts';

package/src/engine/transition-helpers.ts

@@ -0,0 +1,28 @@
+import type { LoadedWorkflow, WorkflowStep } from '../config/types.ts';
+import type { WorkflowRun } from './state-types.ts';
+
+/**
+ * Finds the workflow definition for a run's current step.
+ *
+ * @param workflow - Loaded workflow.
+ * @param run - Current workflow state.
+ * @returns The current step, or `undefined` if configuration drift removed it.
+ */
+export const currentStep = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+): WorkflowStep | undefined => workflow.definition.steps[run.currentStepId];
+
+/**
+ * Produces a workflow state with changes and a refreshed update timestamp.
+ *
+ * @param run - Existing workflow state.
+ * @param changes - Fields to replace.
+ * @param now - Update timestamp.
+ * @returns A new workflow state.
+ */
+export const withRunUpdate = (
+  run: WorkflowRun,
+  changes: Partial<WorkflowRun>,
+  now: number,
+): WorkflowRun => ({ ...run, ...changes, updatedAt: now });

package/src/engine/transition-types.ts

@@ -0,0 +1,8 @@
+import type { WorkflowRun } from './state-types.ts';
+
+export type ReconcileResult = {
+  readonly run?: WorkflowRun;
+  readonly changed: boolean;
+  readonly restartedStep?: string;
+  readonly error?: string;
+};