@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/digest.ts

@@ -1,23 +1,55 @@
 import { createHash } from 'node:crypto';
 
-function canonicalize(value: unknown): unknown {
+/**
+ * Computes a deterministic digest for an unknown value.
+ */
+export type DigestFunction = (value: unknown) => string;
+
+/**
+ * Effect boundary used to hash a canonical serialized value.
+ */
+export type DigestDependencies = {
+  readonly hash: (serializedValue: string) => string;
+};
+
+const canonicalize = (value: unknown): unknown => {
   if (Array.isArray(value)) {
     return value.map(canonicalize);
   }
 
   if (value !== null && typeof value === 'object') {
     return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>)
-        .sort(([left], [right]) => left.localeCompare(right))
+      Object.entries(value)
+        .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
         .map(([key, child]) => [key, canonicalize(child)]),
     );
   }
 
   return value;
+};
+
+const sha256 = (serializedValue: string): string =>
+  createHash('sha256').update(serializedValue).digest('hex');
+
+/**
+ * Creates a deterministic value-digest function around an injected hash
+ * implementation.
+ *
+ * @param dependencies - Hash effect used after canonical serialization.
+ * @returns A deterministic digest function.
+ */
+export function createDigest({ hash }: DigestDependencies): DigestFunction {
+  return (value: unknown): string => hash(JSON.stringify(canonicalize(value)));
 }
 
+const defaultDigest = createDigest({ hash: sha256 });
+
+/**
+ * Produces a stable SHA-256 digest independent of object key insertion order.
+ *
+ * @param value - JSON-compatible value to digest.
+ * @returns Lowercase hexadecimal SHA-256 digest.
+ */
 export function digest(value: unknown): string {
-  return createHash('sha256')
-    .update(JSON.stringify(canonicalize(value)))
-    .digest('hex');
+  return defaultDigest(value);
 }

package/src/engine/checkpoint.ts

@@ -1,22 +1,26 @@
 import { isWorkflowRun, type WorkflowRun } from './state.ts';
 
 export type CheckpointResult =
-  | { status: 'none' }
-  | { status: 'invalid' }
-  | { status: 'valid'; run: WorkflowRun };
+  | { readonly status: 'none' }
+  | { readonly status: 'invalid' }
+  | { readonly status: 'valid'; readonly run: WorkflowRun };
 
-interface SessionEntryLike {
-  type?: unknown;
-  customType?: unknown;
-  data?: unknown;
-}
+type SessionEntryLike = {
+  readonly type?: unknown;
+  readonly customType?: unknown;
+  readonly data?: unknown;
+};
 
 /**
  * Only the newest entry for this checkpoint type is authoritative. Falling
  * back past corrupt or newer-version state could repeat already-finished work.
+ *
+ * @param entries - Session entries in chronological order.
+ * @param customType - Workflow checkpoint entry type.
+ * @returns The newest checkpoint state.
  */
 export function readLatestCheckpoint(
-  entries: readonly SessionEntryLike[],
+  entries: ReadonlyArray<SessionEntryLike>,
   customType: string,
 ): CheckpointResult {
   for (let index = entries.length - 1; index >= 0; index -= 1) {

package/src/engine/create-run.ts

@@ -0,0 +1,43 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import { RUN_STATE_VERSION } from './state-types.ts';
+import type { WorkflowRun } from './state-types.ts';
+
+/**
+ * Creates the immutable initial state for a workflow run.
+ *
+ * @param workflow - Loaded workflow definition and digests.
+ * @param input - User input that started the workflow.
+ * @param baselineTools - Tool names available before workflow restrictions.
+ * @param runId - Stable run identifier.
+ * @param now - Creation timestamp.
+ * @returns A new running workflow state.
+ */
+export const createRun = (
+  workflow: LoadedWorkflow,
+  input: string,
+  baselineTools: ReadonlyArray<string>,
+  runId: string,
+  now: number,
+): WorkflowRun => {
+  const startStepId = workflow.definition.start;
+  return {
+    stateVersion: RUN_STATE_VERSION,
+    runId,
+    workflowId: workflow.definition.id,
+    workflowDigest: workflow.digest,
+    input,
+    status: 'running',
+    currentStepId: startStepId,
+    currentStepDigest: workflow.stepDigests[startStepId] ?? '',
+    baselineTools: [...new Set(baselineTools)],
+    visits: { [startStepId]: 1 },
+    history: [],
+    startedAt: now,
+    updatedAt: now,
+    reviewedArtifact: '',
+    reviewedFeedback: '',
+    stepHandoff: '',
+    lastSummary: '',
+    gateFeedback: '',
+  };
+};

package/src/engine/gate-transitions.ts

@@ -0,0 +1,187 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import { advanceRun } from './run-advance.ts';
+import type { GateResolution, WorkflowRun } from './state-types.ts';
+import { currentStep, withRunUpdate } from './transition-helpers.ts';
+
+/**
+ * Begins human review for a gated workflow step.
+ *
+ * @param workflow - Loaded workflow.
+ * @param run - Current running workflow state.
+ * @param outcome - Submitted gate outcome.
+ * @param artifact - Artifact to display for review.
+ * @param requestId - Stable gate request identifier.
+ * @param now - Update timestamp.
+ * @returns A new awaiting-gate workflow state.
+ * @throws When the run or gate submission is invalid.
+ */
+export const beginGate = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  outcome: string,
+  artifact: string,
+  requestId: string,
+  now: number,
+): WorkflowRun => {
+  if (run.status !== 'running') {
+    throw new Error(
+      `workflow is ${run.status}; gate submission requires a running workflow`,
+    );
+  }
+  const step = currentStep(workflow, run);
+  if (!step?.gate) {
+    throw new Error(`step "${run.currentStepId}" has no gate`);
+  }
+  if (outcome !== step.gate.submitOutcome) {
+    throw new Error(`gate expects outcome "${step.gate.submitOutcome}"`);
+  }
+  if (!artifact.trim()) {
+    throw new Error('gate submission requires a non-empty artifact');
+  }
+  if (!requestId) throw new Error('gate submission requires a request id');
+
+  return withRunUpdate(
+    run,
+    {
+      status: 'awaiting-gate',
+      pendingGate: {
+        provider: step.gate.provider,
+        requestId,
+        stepId: run.currentStepId,
+        artifact,
+        submittedOutcome: outcome,
+        requestedAt: now,
+      },
+    },
+    now,
+  );
+};
+
+/**
+ * Attaches the provider review identifier to a pending Plannotator gate.
+ *
+ * @param run - Current workflow state.
+ * @param reviewId - Provider review identifier.
+ * @param now - Update timestamp.
+ * @returns A new workflow state with the review identifier.
+ * @throws When no Plannotator gate is pending.
+ */
+export const attachGateReviewId = (
+  run: WorkflowRun,
+  reviewId: string,
+  now: number,
+): WorkflowRun => {
+  if (!run.pendingGate) throw new Error('workflow has no pending gate');
+  if (run.pendingGate.provider !== 'plannotator') {
+    throw new Error('only a Plannotator gate can have a review id');
+  }
+  return withRunUpdate(
+    run,
+    { pendingGate: { ...run.pendingGate, reviewId } },
+    now,
+  );
+};
+
+/**
+ * Returns a failed gate request to active step execution with feedback.
+ *
+ * @param run - Current workflow state.
+ * @param reason - Gate failure feedback.
+ * @param now - Update timestamp.
+ * @returns A running state, or the original state when no gate is pending.
+ */
+export const failGate = (
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun =>
+  run.pendingGate
+    ? withRunUpdate(
+        run,
+        {
+          status: 'running',
+          pendingGate: undefined,
+          gateFeedback: reason,
+        },
+        now,
+      )
+    : run;
+
+/**
+ * Stores a gate resolution without advancing the workflow.
+ *
+ * @param run - Current workflow state.
+ * @param resolution - Human review resolution.
+ * @param now - Update timestamp.
+ * @returns Updated gate state, or the original state when no gate is pending.
+ */
+export const storeGateResolution = (
+  run: WorkflowRun,
+  resolution: GateResolution,
+  now: number,
+): WorkflowRun =>
+  run.pendingGate
+    ? withRunUpdate(
+        run,
+        { pendingGate: { ...run.pendingGate, resolution } },
+        now,
+      )
+    : run;
+
+/**
+ * Applies a human gate decision and follows its configured transition.
+ *
+ * @param workflow - Loaded workflow.
+ * @param run - Current awaiting-gate workflow state.
+ * @param resolution - Human review resolution.
+ * @param now - Update timestamp.
+ * @returns The workflow state after the configured gate transition.
+ * @throws When pending gate state no longer matches the workflow.
+ */
+export const resolveGate = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  resolution: GateResolution,
+  now: number,
+): WorkflowRun => {
+  const pendingGate = run.pendingGate;
+  if (!pendingGate) throw new Error('workflow has no pending gate');
+
+  const step = workflow.definition.steps[pendingGate.stepId];
+  if (!step?.gate) {
+    throw new Error(`gated step "${pendingGate.stepId}" no longer exists`);
+  }
+  if (run.currentStepId !== pendingGate.stepId) {
+    throw new Error('gate result does not match the current step');
+  }
+
+  const outcome = resolution.approved
+    ? step.gate.approvedOutcome
+    : step.gate.rejectedOutcome;
+  const summary = resolution.approved
+    ? pendingGate.artifact
+    : resolution.feedback
+      ? `Gate rejected: ${resolution.feedback}`
+      : 'Gate rejected';
+  const runnableRun = withRunUpdate(
+    run,
+    {
+      status: 'running',
+      pendingGate: undefined,
+      ...(resolution.approved
+        ? {
+            reviewedArtifact: pendingGate.artifact,
+            reviewedFeedback: resolution.feedback,
+          }
+        : {}),
+      pausedFrom: undefined,
+      pauseReason: undefined,
+      gateFeedback: resolution.feedback,
+    },
+    now,
+  );
+  return {
+    ...advanceRun(workflow, runnableRun, outcome, summary, now),
+    gateFeedback: resolution.feedback,
+  };
+};

package/src/engine/reconciliation-history.ts

@@ -0,0 +1,88 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
+
+/**
+ * Rebuilds step visit counts from retained history and the current step.
+ *
+ * @param history - Retained completed-step history.
+ * @param currentStepId - Step about to run.
+ * @returns Visit counts for the reconciled state.
+ */
+export const rebuildVisits = (
+  history: ReadonlyArray<StepHistoryEntry>,
+  currentStepId: string,
+): Readonly<Record<string, number>> => {
+  const visitedStepIds = [
+    ...history.map((entry) => entry.stepId),
+    currentStepId,
+  ];
+  return visitedStepIds.reduce<Record<string, number>>(
+    (visits, stepId) => ({
+      ...visits,
+      [stepId]: (visits[stepId] ?? 0) + 1,
+    }),
+    {},
+  );
+};
+
+/**
+ * Retains reviewed authority only when its approving history remains.
+ *
+ * @param workflow - Updated workflow.
+ * @param run - Existing workflow state.
+ * @param history - History retained after reconciliation.
+ * @returns The retained artifact, or an empty string when provenance was lost.
+ */
+export const retainedReviewedArtifact = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  history: ReadonlyArray<StepHistoryEntry>,
+): string => {
+  const reviewedArtifact = run.reviewedArtifact ?? '';
+  if (!reviewedArtifact) return '';
+
+  const isApprovalRetained = history.some((entry) => {
+    const gate = workflow.definition.steps[entry.stepId]?.gate;
+    return (
+      gate !== undefined &&
+      entry.outcome === gate.approvedOutcome &&
+      entry.summary === reviewedArtifact
+    );
+  });
+  return isApprovalRetained ? reviewedArtifact : '';
+};
+
+/**
+ * Refreshes the digest of retained approved-gate history.
+ *
+ * The reviewed artifact itself proves the gate output is unchanged, allowing a
+ * prompt-only configuration refresh without discarding approved authority.
+ *
+ * @param run - Existing workflow state.
+ * @param workflow - Updated workflow.
+ * @returns A run with refreshed history when needed.
+ */
+export const refreshApprovedGateHistory = (
+  run: WorkflowRun,
+  workflow: LoadedWorkflow,
+): WorkflowRun => {
+  const reviewedArtifact = run.reviewedArtifact ?? '';
+  if (!reviewedArtifact) return run;
+
+  const history = run.history.map((entry) => {
+    const gate = workflow.definition.steps[entry.stepId]?.gate;
+    const currentDigest = workflow.stepDigests[entry.stepId];
+    const shouldRefresh =
+      gate !== undefined &&
+      typeof currentDigest === 'string' &&
+      currentDigest.length > 0 &&
+      entry.outcome === gate.approvedOutcome &&
+      entry.summary === reviewedArtifact &&
+      entry.stepDigest !== currentDigest;
+    return shouldRefresh ? { ...entry, stepDigest: currentDigest } : entry;
+  });
+  const hasChanged = history.some(
+    (entry, index) => entry !== run.history[index],
+  );
+  return hasChanged ? { ...run, history } : run;
+};

package/src/engine/resume.ts

@@ -1,13 +1,20 @@
 import type { WorkflowRun } from './state.ts';
 
-export interface ResumeCheckpoint {
-  sessionEpoch: number;
-  runId: string;
-  workflowId: string;
-  currentStepId: string;
-  reviewId?: string;
-}
+export type ResumeCheckpoint = {
+  readonly sessionEpoch: number;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly currentStepId: string;
+  readonly reviewId?: string;
+};
 
+/**
+ * Captures the identity fields that asynchronous resume work must preserve.
+ *
+ * @param run - Paused workflow run.
+ * @param sessionEpoch - Current session-tree epoch.
+ * @returns A checkpoint suitable for a later identity comparison.
+ */
 export function captureResumeCheckpoint(
   run: WorkflowRun,
   sessionEpoch: number,
@@ -27,6 +34,11 @@ export function captureResumeCheckpoint(
  * Async resume work may overlap an abort, a session-tree switch, or a gate
  * result. A gate result may update the same paused checkpoint and is safe to
  * merge; a different session, run, step, review, or status is not.
+ *
+ * @param run - Current workflow state.
+ * @param sessionEpoch - Current session-tree epoch.
+ * @param checkpoint - Identity captured before asynchronous work.
+ * @returns `true` when the paused run still matches the checkpoint.
  */
 export function matchesResumeCheckpoint(
   run: WorkflowRun | undefined,

package/src/engine/run-advance.ts

@@ -0,0 +1,122 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
+import { currentStep, withRunUpdate } from './transition-helpers.ts';
+
+const completedStep = (
+  run: WorkflowRun,
+  outcome: string,
+  summary: string,
+  now: number,
+): StepHistoryEntry => ({
+  stepId: run.currentStepId,
+  stepDigest: run.currentStepDigest,
+  outcome,
+  summary,
+  completedAt: now,
+});
+
+/**
+ * Advances a running workflow through a configured non-gate transition.
+ *
+ * @param workflow - Loaded workflow.
+ * @param run - Current running workflow state.
+ * @param outcome - Submitted step outcome.
+ * @param summary - Step handoff summary.
+ * @param now - Update timestamp.
+ * @returns A new paused, running, or completed workflow state.
+ * @throws When the run, outcome, current step, or transition target is invalid.
+ */
+export const advanceRun = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  outcome: string,
+  summary: string,
+  now: number,
+): WorkflowRun => {
+  if (run.status !== 'running') {
+    throw new Error(
+      `workflow is ${run.status}; only a running workflow can advance`,
+    );
+  }
+
+  const step = currentStep(workflow, run);
+  if (!step) {
+    throw new Error(`current step "${run.currentStepId}" no longer exists`);
+  }
+  if (step.gate?.submitOutcome === outcome) {
+    throw new Error(
+      `outcome "${outcome}" must be submitted through the configured gate`,
+    );
+  }
+
+  const target = step.transitions[outcome];
+  if (!target) {
+    throw new Error(
+      `outcome "${outcome}" is not valid for step "${run.currentStepId}"`,
+    );
+  }
+  if (target === '$pause') {
+    return withRunUpdate(
+      run,
+      {
+        status: 'paused',
+        pausedFrom: 'running',
+        pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
+        lastSummary: summary,
+      },
+      now,
+    );
+  }
+
+  const completed = completedStep(run, outcome, summary, now);
+  if (target === '$done') {
+    return withRunUpdate(
+      run,
+      {
+        status: 'completed',
+        history: [...run.history, completed],
+        stepHandoff: summary,
+        lastSummary: summary,
+        gateFeedback: '',
+        pausedFrom: undefined,
+        pendingGate: undefined,
+      },
+      now,
+    );
+  }
+
+  const nextStep = workflow.definition.steps[target];
+  if (!nextStep) {
+    throw new Error(`transition target "${target}" does not exist`);
+  }
+
+  const nextVisitCount = (run.visits[target] ?? 0) + 1;
+  const isOverVisitLimit = nextVisitCount > workflow.definition.maxStepVisits;
+  const visitLimitChanges: Partial<WorkflowRun> = isOverVisitLimit
+    ? {
+        status: 'paused',
+        pausedFrom: 'running',
+        pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`,
+      }
+    : {
+        status: 'running',
+        pausedFrom: undefined,
+        pauseReason: undefined,
+      };
+
+  return withRunUpdate(
+    run,
+    {
+      ...visitLimitChanges,
+      currentStepId: target,
+      currentStepDigest: workflow.stepDigests[target] ?? '',
+      visits: { ...run.visits, [target]: nextVisitCount },
+      history: [...run.history, completed],
+      stepHandoff: summary,
+      lastSummary: summary,
+      gateFeedback: '',
+      ...(nextStep.gate ? { reviewedArtifact: '', reviewedFeedback: '' } : {}),
+    },
+    now,
+  );
+};

package/src/engine/run-lifecycle.ts

@@ -0,0 +1,124 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { WorkflowRun } from './state-types.ts';
+import { currentStep, withRunUpdate } from './transition-helpers.ts';
+
+/**
+ * Lists outcomes the active step may submit directly.
+ *
+ * Gate resolution outcomes are reserved for the gate; only its submit outcome
+ * is exposed to step execution.
+ *
+ * @param workflow - Loaded workflow.
+ * @param run - Current workflow state.
+ * @returns Allowed outcome names.
+ */
+export const allowedOutcomes = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+): Array<string> => {
+  const step = currentStep(workflow, run);
+  if (!step) return [];
+
+  const gateResolutionOutcomes = step.gate
+    ? new Set([step.gate.approvedOutcome, step.gate.rejectedOutcome])
+    : undefined;
+  return [
+    ...Object.keys(step.transitions).filter(
+      (outcome) => !gateResolutionOutcomes?.has(outcome),
+    ),
+    ...(step.gate ? [step.gate.submitOutcome] : []),
+  ];
+};
+
+/**
+ * Pauses an active run while preserving its previous execution mode.
+ *
+ * @param run - Current workflow state.
+ * @param reason - User-facing pause reason.
+ * @param now - Update timestamp.
+ * @returns A new paused workflow state.
+ */
+export const pauseRun = (
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun => {
+  if (run.status !== 'running' && run.status !== 'awaiting-gate') {
+    return withRunUpdate(run, { pauseReason: reason || run.pauseReason }, now);
+  }
+  return withRunUpdate(
+    run,
+    {
+      status: 'paused',
+      pausedFrom: run.status,
+      pauseReason: reason || `Paused during step "${run.currentStepId}"`,
+      failedStepId: undefined,
+    },
+    now,
+  );
+};
+
+/**
+ * Pauses a run and marks its current step as failed for a resumable retry.
+ *
+ * @param run - Current workflow state.
+ * @param reason - Failure reason.
+ * @param now - Update timestamp.
+ * @returns A new failed-and-paused workflow state.
+ */
+export const failRun = (
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun => {
+  const pausedRun = pauseRun(run, reason, now);
+  return pausedRun.status === 'paused'
+    ? { ...pausedRun, failedStepId: pausedRun.currentStepId }
+    : pausedRun;
+};
+
+/**
+ * Resumes a paused run in the mode from which it was paused.
+ *
+ * @param run - Current workflow state.
+ * @param now - Update timestamp.
+ * @returns A resumed state, or the unchanged state when it was not paused.
+ */
+export const resumeRun = (run: WorkflowRun, now: number): WorkflowRun => {
+  if (run.status !== 'paused') return run;
+  return withRunUpdate(
+    run,
+    {
+      status: run.pausedFrom ?? (run.pendingGate ? 'awaiting-gate' : 'running'),
+      pauseReason: undefined,
+      pausedFrom: undefined,
+      failedStepId: undefined,
+    },
+    now,
+  );
+};
+
+/**
+ * Aborts a run and clears resumable gate state.
+ *
+ * @param run - Current workflow state.
+ * @param reason - User-facing abort reason.
+ * @param now - Update timestamp.
+ * @returns A new aborted workflow state.
+ */
+export const abortRun = (
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun =>
+  withRunUpdate(
+    run,
+    {
+      status: 'aborted',
+      pauseReason: reason || 'Aborted by user',
+      pausedFrom: undefined,
+      failedStepId: undefined,
+      pendingGate: undefined,
+    },
+    now,
+  );