@ankhorage/flow 0.0.0-stage → 0.5.0

package/src/features/execution/application/executeFlowAsync.ts

@@ -0,0 +1,338 @@
+import type { DataContractValue } from '@ankhorage/contracts/data';
+import type {
+  FlowDataRef,
+  FlowEdge,
+  FlowError,
+  FlowNode,
+  FlowPortId,
+  FlowRunSnapshot,
+  FlowStepSnapshot,
+} from '@ankhorage/contracts/flow';
+
+import type {
+  FlowClock,
+  FlowCompiledGraph,
+  FlowExecutionResult,
+  FlowNodeRegistry,
+  FlowRunRequest,
+} from '../../../types/execution.js';
+import { assertFlowGraphSchemasSupported } from '../domain/assertFlowGraphSchemasSupported.js';
+import { validateFlowDataSchema } from '../domain/validateFlowDataSchema.js';
+
+/*** Execute a compiled graph in deterministic order within one process. */
+export const executeFlowAsync = async (
+  graph: FlowCompiledGraph,
+  registry: FlowNodeRegistry,
+  request: FlowRunRequest,
+  clock: FlowClock = { now: () => new Date() },
+): Promise<FlowExecutionResult> => {
+  const trigger = graph.definition.triggers.find(({ id }) => id === request.triggerId);
+  if (trigger?.kind !== 'manual') throw new Error('FLOW_TRIGGER_NOT_MANUAL');
+  assertFlowGraphSchemasSupported(graph.definition.nodes, request.schemaRegistry);
+  const startedAt = clock.now().toISOString();
+  const state = await executeNodesAsync(graph, registry, request, clock);
+  return {
+    run: createRun(
+      graph,
+      request,
+      state.steps,
+      startedAt,
+      clock.now().toISOString(),
+      state.status ?? 'succeeded',
+      state.error,
+    ),
+  };
+};
+
+/*** Iterate compiled nodes in deterministic order until completion or cancellation. */
+const executeNodesAsync = async (
+  graph: FlowCompiledGraph,
+  registry: FlowNodeRegistry,
+  request: FlowRunRequest,
+  clock: FlowClock,
+): Promise<ExecutionState> => {
+  const state: ExecutionState = {
+    activatedNodeIds: new Set(
+      graph.topologicalNodeIds.filter(
+        (nodeId) => !graph.definition.edges.some((edge) => edge.target.nodeId === nodeId),
+      ),
+    ),
+    inputs: {},
+    steps: [],
+  };
+  for (const nodeId of graph.topologicalNodeIds) {
+    if (request.signal?.aborted) return { ...state, status: 'cancelled' };
+    const node = graph.definition.nodes.find((candidate) => candidate.id === nodeId);
+    if (!node) throw new Error(`FLOW_GRAPH_UNKNOWN_NODE:${nodeId}`);
+    const result = await executeAvailableNodeAsync(node, state, registry, request, clock);
+    if (!result) continue;
+    state.steps.push(result.step);
+    if (result.step.status === 'cancelled') return { ...state, status: 'cancelled' };
+    propagateOutput(
+      graph.edgesBySourceNodeId[node.id] ?? [],
+      result.output,
+      result.step.status === 'failed' ? 'failure' : 'success',
+      state,
+    );
+  }
+  const failedStep = state.steps.find((step) => step.status === 'failed');
+  return { ...state, status: failedStep ? 'failed' : 'succeeded', error: failedStep?.error };
+};
+
+interface ExecutionState {
+  readonly activatedNodeIds: Set<string>;
+  readonly error?: FlowError;
+  readonly inputs: Record<string, Record<FlowPortId, FlowDataRef>>;
+  readonly status?: FlowRunSnapshot['status'];
+  readonly steps: FlowStepSnapshot[];
+}
+
+/*** Execute one node only when all of its required inputs were propagated. */
+const executeAvailableNodeAsync = async (
+  node: FlowNode,
+  state: ExecutionState,
+  registry: FlowNodeRegistry,
+  request: FlowRunRequest,
+  clock: FlowClock,
+): Promise<
+  | { readonly output: Readonly<Record<FlowPortId, FlowDataRef>>; readonly step: FlowStepSnapshot }
+  | undefined
+> => {
+  if (!state.activatedNodeIds.has(node.id)) return undefined;
+  const input = state.inputs[node.id] ?? request.input ?? {};
+  if (!hasRequiredInput(node, input)) return undefined;
+  return executeNodeAsync(node, input, registry, request.signal, clock, request.schemaRegistry);
+};
+
+/*** Determine whether every required input port has a propagated value. */
+const hasRequiredInput = (
+  node: FlowNode,
+  input: Readonly<Record<FlowPortId, FlowDataRef>>,
+): boolean =>
+  node.ports
+    .filter((port) => port.direction === 'input' && port.required)
+    .every((port) => input[port.id] !== undefined);
+
+/*** Execute one node and convert failures to redaction-safe contract errors. */
+const executeNodeAsync = async (
+  node: FlowNode,
+  input: Readonly<Record<FlowPortId, FlowDataRef>>,
+  registry: FlowNodeRegistry,
+  signal: AbortSignal | undefined,
+  clock: FlowClock,
+  schemas: FlowRunRequest['schemaRegistry'],
+): Promise<{
+  readonly output: Readonly<Record<FlowPortId, FlowDataRef>>;
+  readonly step: FlowStepSnapshot;
+}> => {
+  const startedAt = clock.now().toISOString();
+  try {
+    assertPortSchemas(node, input, 'input', schemas);
+    const operationId = `${node.capability.providerId}:${node.capability.capabilityId}`;
+    const operation = Object.entries(registry).find(([id]) => id === operationId)?.[1];
+    if (!operation) throw new Error(`FLOW_OPERATION_UNREGISTERED:${operationId}`);
+    const output =
+      (
+        await operation.executeAsync({
+          config: node.config,
+          input,
+          node,
+          signal: signal ?? new AbortController().signal,
+        })
+      ).output ?? {};
+    if (signal?.aborted)
+      return { output: {}, step: createCancelledStep(node, input, startedAt, clock) };
+    assertOutputPorts(node, output);
+    assertPortSchemas(node, output, 'output', schemas);
+    return { output, step: createSucceededStep(node, input, output, startedAt, clock) };
+  } catch (reason) {
+    const error = asFlowError(reason);
+    return {
+      output: {},
+      step: {
+        id: `${node.id}:1`,
+        nodeId: node.id,
+        status: 'failed',
+        attempt: 1,
+        startedAt,
+        completedAt: clock.now().toISOString(),
+        input,
+        error,
+      },
+    };
+  }
+};
+
+/*** Create an immutable successful step snapshot. */
+const createSucceededStep = (
+  node: FlowNode,
+  input: Readonly<Record<FlowPortId, FlowDataRef>>,
+  output: Readonly<Record<FlowPortId, FlowDataRef>>,
+  startedAt: string,
+  clock: FlowClock,
+): FlowStepSnapshot => ({
+  id: `${node.id}:1`,
+  nodeId: node.id,
+  status: 'succeeded',
+  attempt: 1,
+  startedAt,
+  completedAt: clock.now().toISOString(),
+  input,
+  output,
+});
+
+/*** Create a terminal snapshot when cancellation occurs during asynchronous node execution. */
+const createCancelledStep = (
+  node: FlowNode,
+  input: Readonly<Record<FlowPortId, FlowDataRef>>,
+  startedAt: string,
+  clock: FlowClock,
+): FlowStepSnapshot => ({
+  id: `${node.id}:1`,
+  nodeId: node.id,
+  status: 'cancelled',
+  attempt: 1,
+  startedAt,
+  completedAt: clock.now().toISOString(),
+  input,
+});
+
+/*** Reject operation outputs that do not correspond to declared output ports. */
+const assertOutputPorts = (
+  node: FlowNode,
+  output: Readonly<Record<FlowPortId, FlowDataRef>>,
+): void => {
+  const outputIds = new Set(
+    node.ports.filter((port) => port.direction === 'output').map(({ id }) => id),
+  );
+  if (Object.keys(output).some((portId) => !outputIds.has(portId)))
+    throw new Error(`FLOW_OUTPUT_UNDECLARED_PORT:${node.id}`);
+  const missingRequired = node.ports.some(
+    (port) => port.direction === 'output' && port.required && output[port.id] === undefined,
+  );
+  if (missingRequired) throw new Error(`FLOW_OUTPUT_REQUIRED_PORT_MISSING:${node.id}`);
+};
+
+/*** Validate inline port values against their declared portable schemas. */
+const assertPortSchemas = (
+  node: FlowNode,
+  values: Readonly<Record<FlowPortId, FlowDataRef>>,
+  direction: 'input' | 'output',
+  schemas: FlowRunRequest['schemaRegistry'],
+): void => {
+  for (const port of node.ports.filter((candidate) => candidate.direction === direction)) {
+    const value = values[port.id];
+    const schema =
+      port.data?.schema ?? (port.data?.schemaRef ? { ref: port.data.schemaRef } : undefined);
+    if (value?.kind === 'inline' && schema && !validateFlowDataSchema(value.value, schema, schemas))
+      throw new Error(`FLOW_PORT_SCHEMA_MISMATCH:${node.id}:${port.id}`);
+  }
+};
+
+/*** Propagate outputs only over edges whose declared condition matches the output value. */
+const propagateOutput = (
+  edges: readonly FlowEdge[],
+  output: Readonly<Record<FlowPortId, FlowDataRef>>,
+  outcome: 'failure' | 'success',
+  state: ExecutionState,
+): void => {
+  for (const edge of edges) {
+    const value = output[edge.source.portId];
+    if (!matchesEdge(edge, value, outcome)) continue;
+    state.activatedNodeIds.add(edge.target.nodeId);
+    if (value)
+      state.inputs[edge.target.nodeId] = {
+        ...state.inputs[edge.target.nodeId],
+        [edge.target.portId]: value,
+      };
+  }
+};
+
+/*** Evaluate an edge condition without executing arbitrary expressions. */
+const matchesEdge = (
+  edge: FlowEdge,
+  value: FlowDataRef | undefined,
+  outcome: 'failure' | 'success',
+): boolean => {
+  const condition = edge.condition ?? { kind: 'always' as const };
+  if (condition.kind === 'always') return outcome === 'success';
+  if (condition.kind === 'outcome') return condition.outcome === outcome;
+  if (value?.kind !== 'inline') return false;
+  const selected = resolvePointer(value.value, condition.path);
+  return selected !== undefined && structurallyEqual(selected, condition.equals);
+};
+
+/*** Resolve an RFC 6901 pointer against serializable inline data. */
+const resolvePointer = (
+  value: DataContractValue,
+  pointer: string,
+): DataContractValue | undefined => {
+  if (pointer === '') return value;
+  if (!pointer.startsWith('/')) return undefined;
+  return pointer
+    .slice(1)
+    .split('/')
+    .reduce<DataContractValue | undefined>((current, segment) => {
+      if (current === undefined || current === null || typeof current !== 'object')
+        return undefined;
+      const key = segment.replaceAll('~1', '/').replaceAll('~0', '~');
+      if (isDataArray(current)) return current.find((_item, index) => index === Number(key));
+      return isDataRecord(current)
+        ? Object.entries(current).find(([candidateKey]) => candidateKey === key)?.[1]
+        : undefined;
+    }, value);
+};
+
+/*** Compare JSON-compatible values with object-key-order independence. */
+const structurallyEqual = (left: DataContractValue, right: DataContractValue): boolean =>
+  JSON.stringify(normalizeValue(left)) === JSON.stringify(normalizeValue(right));
+
+/*** Canonicalize object member ordering for structural equality. */
+const normalizeValue = (value: DataContractValue): DataContractValue => {
+  if (Array.isArray(value)) return value.map(normalizeValue);
+  if (value !== null && typeof value === 'object')
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, normalizeValue(item)]),
+    );
+  return value;
+};
+
+/*** Narrow a serializable non-array object to an indexable data record. */
+const isDataRecord = (value: object): value is Readonly<Record<string, DataContractValue>> =>
+  !Array.isArray(value);
+
+/*** Narrow a serializable array without losing its element type. */
+const isDataArray = (value: object): value is readonly DataContractValue[] => Array.isArray(value);
+
+/*** Translate host failures to structured contract errors without exposing arbitrary objects. */
+const asFlowError = (reason: unknown): FlowError => ({
+  code:
+    reason instanceof Error && /^FLOW_[A-Z0-9_]+(?::|$)/.test(reason.message)
+      ? (reason.message.split(':')[0] ?? 'FLOW_OPERATION_FAILED')
+      : 'FLOW_OPERATION_FAILED',
+  message: 'The operation failed.',
+  retryable: false,
+});
+
+/*** Build the immutable run result emitted by the single-process executor. */
+const createRun = (
+  graph: FlowCompiledGraph,
+  request: FlowRunRequest,
+  steps: readonly FlowStepSnapshot[],
+  startedAt: string,
+  completedAt: string,
+  status: FlowRunSnapshot['status'],
+  error?: FlowError,
+): FlowRunSnapshot => ({
+  id: request.runId,
+  flow: { id: graph.definition.id, version: graph.definition.version },
+  status,
+  trigger: { triggerId: request.triggerId, kind: 'manual' },
+  createdAt: startedAt,
+  startedAt,
+  completedAt,
+  steps,
+  error,
+});

package/src/features/execution/application/runDurableWorkerAsync.ts

@@ -0,0 +1,337 @@
+import type {
+  FlowDurableRun,
+  FlowDurableWork,
+  FlowRetryPolicy,
+  FlowRunCheckpoint,
+} from '../../../types/durableExecution.js';
+import type { FlowClock } from '../../../types/execution.js';
+import type { FlowSecurityPort } from '../../../types/security.js';
+import { FlowSecurityError } from '../../security/FlowSecurityError.js';
+import { createRetryWork } from '../domain/createRetryWork.js';
+import type { FlowPersistencePort } from '../ports/FlowPersistencePort.js';
+
+/** Claim bounded durable work and execute it with fenced recovery, retry, and approval handling. */
+export const runDurableWorkerAsync = async (
+  input: {
+    readonly approvalPollIntervalMs: number;
+    readonly concurrency: number;
+    readonly leaseDurationMs: number;
+    readonly limit: number;
+    readonly retry: FlowRetryPolicy;
+    readonly workerId: string;
+  },
+  dependencies: {
+    readonly clock: FlowClock;
+    readonly effects: FlowDurableEffectPort;
+    readonly persistence: FlowPersistencePort;
+    readonly security?: FlowSecurityPort;
+  },
+): Promise<FlowWorkerResult> => {
+  assertWorkerInput(input);
+  const now = dependencies.clock.now();
+  const recoveredWorkIds = await dependencies.persistence.recoverExpiredClaimsAsync(now);
+  const claimed = await dependencies.persistence.claimDueWorkAsync({
+    leaseDurationMs: input.leaseDurationMs,
+    limit: Math.min(input.limit, input.concurrency),
+    now,
+    workerId: input.workerId,
+  });
+  const outcomes = await Promise.all(
+    claimed.map((work) => processWorkAsync(work, input, dependencies)),
+  );
+  return { claimedWorkIds: claimed.map((work) => work.id), outcomes, recoveredWorkIds };
+};
+
+/** Executes one effect through the durable step and security boundaries. */
+const processWorkAsync = async (
+  work: FlowDurableWork,
+  input: Parameters<typeof runDurableWorkerAsync>[0],
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<FlowWorkerOutcome> => {
+  const { lease } = work;
+  if (lease === undefined) return { status: 'lost_lease', workId: work.id };
+  const run = await dependencies.persistence.readRunAsync(work.runId);
+  if (run === undefined || run.status === 'cancelled') {
+    await completeAsync(work, input.workerId, dependencies);
+    return { status: 'cancelled', workId: work.id };
+  }
+  if (isCompleted(run.checkpoint, work.stepId)) {
+    await completeAsync(work, input.workerId, dependencies);
+    return { status: 'already_completed', workId: work.id };
+  }
+  try {
+    const outbox = await prepareOutboxAsync(work, dependencies);
+    if (outbox.status === 'delivered') {
+      const transitioned = await transitionAsync(
+        run,
+        'succeeded',
+        completedCheckpoint(run.checkpoint, work.stepId),
+        dependencies,
+      );
+      const completed = await completeAsync(work, input.workerId, dependencies);
+      return {
+        status: transitioned && completed ? 'already_completed' : 'lost_lease',
+        workId: work.id,
+      };
+    }
+    const effectStatus = await executeEffectAsync(work, run, dependencies);
+    await dependencies.persistence.markOutboxDeliveredAsync(work.id);
+    const transitioned = await transitionAsync(
+      run,
+      'succeeded',
+      completedCheckpoint(run.checkpoint, work.stepId),
+      dependencies,
+    );
+    if (!transitioned || !(await completeAsync(work, input.workerId, dependencies)))
+      return { status: 'lost_lease', workId: work.id };
+    return { status: effectStatus, workId: work.id };
+  } catch (error) {
+    if (isApprovalPending(error)) return waitForApprovalAsync(work, run, input, dependencies);
+    return retryOrFailAsync(work, run, input, dependencies, error);
+  }
+};
+
+/** Create an idempotency-keyed outbox record before delivery, or resume its pending record after a crash. */
+const prepareOutboxAsync = async (
+  work: FlowDurableWork,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+) => {
+  const existing = await dependencies.persistence.readOutboxAsync(work.id);
+  if (existing !== undefined) return existing;
+  const now = dependencies.clock.now().toISOString();
+  await dependencies.persistence.createOutboxAsync({
+    createdAt: now,
+    id: work.id,
+    idempotencyKey: work.idempotencyKey ?? work.id,
+    runId: work.runId,
+    status: 'pending',
+    workId: work.id,
+  });
+  const created = await dependencies.persistence.readOutboxAsync(work.id);
+  if (created === undefined) throw new Error('FLOW_OUTBOX_CREATE_FAILED');
+  return created;
+};
+
+/** Runs internal work directly, while protected provider work requires reconciliation and a canonical permit. */
+const executeEffectAsync = async (
+  work: FlowDurableWork,
+  run: FlowDurableRun,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<'succeeded'> => {
+  const execute = () =>
+    dependencies.effects.executeAsync({
+      idempotencyKey: work.idempotencyKey ?? work.id,
+      run,
+      work,
+    });
+  if (work.effectKind === 'internal') {
+    if (work.securityOperation !== undefined)
+      throw new Error('FLOW_INTERNAL_EFFECT_SECURITY_OPERATION');
+    await execute();
+    return 'succeeded';
+  }
+  if (work.securityOperation === undefined)
+    throw new Error('FLOW_PROTECTED_EFFECT_SECURITY_OPERATION');
+  if (dependencies.security === undefined) throw new Error('FLOW_SECURITY_PORT_REQUIRED');
+  if (dependencies.effects.reconcileAsync === undefined)
+    throw new Error('FLOW_PROTECTED_EFFECT_RECONCILIATION_REQUIRED');
+  if (
+    (await dependencies.effects.reconcileAsync({
+      idempotencyKey: work.idempotencyKey ?? work.id,
+      run,
+      work,
+    })) === 'delivered'
+  )
+    return 'succeeded';
+  const permit = await dependencies.security.authorizeAsync(work.securityOperation);
+  await permit.executeAsync(async () => execute());
+  return 'succeeded';
+};
+
+/** Persist a waiting approval and defer its at-least-once delivery without consuming the lease. */
+const waitForApprovalAsync = async (
+  work: FlowDurableWork,
+  run: FlowDurableRun,
+  input: Parameters<typeof runDurableWorkerAsync>[0],
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<FlowWorkerOutcome> => {
+  const transitioned = await transitionAsync(run, 'waiting_approval', run.checkpoint, dependencies);
+  const released = await dependencies.persistence.releaseWorkAsync({
+    dueAt: new Date(
+      dependencies.clock.now().getTime() + input.approvalPollIntervalMs,
+    ).toISOString(),
+    id: work.id,
+    leaseFencingToken: claimFencingToken(work),
+    workerId: input.workerId,
+  });
+  return { status: transitioned && released ? 'waiting_approval' : 'lost_lease', workId: work.id };
+};
+
+/** Persist a bounded retry or terminal failure before releasing the claimed delivery. */
+const retryOrFailAsync = async (
+  work: FlowDurableWork,
+  run: FlowDurableRun,
+  input: Parameters<typeof runDurableWorkerAsync>[0],
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+  error: unknown,
+): Promise<FlowWorkerOutcome> => {
+  if (work.attempt >= input.retry.maxAttempts) {
+    await dependencies.effects.compensateAsync?.({ run, work });
+    const transitioned = await transitionAsync(
+      run,
+      'failed',
+      failedCheckpoint(run.checkpoint, work.stepId),
+      dependencies,
+    );
+    const completed = await completeAsync(work, input.workerId, dependencies);
+    return {
+      error: errorMessage(error),
+      status: transitioned && completed ? 'failed' : 'lost_lease',
+      workId: work.id,
+    };
+  }
+  await dependencies.persistence.enqueueWorkAsync(
+    createRetryWork(work, dependencies.clock.now(), input.retry),
+  );
+  const completed = await completeAsync(work, input.workerId, dependencies);
+  return {
+    error: errorMessage(error),
+    status: completed ? 'retry_scheduled' : 'lost_lease',
+    workId: work.id,
+  };
+};
+
+/** Compare-and-swap a run state while preserving its immutable flow revision. */
+const transitionAsync = (
+  run: FlowDurableRun,
+  status: FlowDurableRun['status'],
+  checkpoint: FlowRunCheckpoint | undefined,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<boolean> =>
+  dependencies.persistence.transitionRunAsync({
+    expectedRevision: run.revision,
+    run: {
+      ...run,
+      ...(checkpoint === undefined ? {} : { checkpoint }),
+      revision: run.revision + 1,
+      status,
+      updatedAt: dependencies.clock.now().toISOString(),
+    },
+  });
+
+/** Complete a work lease only when its owner and fencing token still match. */
+const completeAsync = (
+  work: FlowDurableWork,
+  workerId: string,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<boolean> =>
+  dependencies.persistence.completeWorkAsync({
+    id: work.id,
+    leaseFencingToken: claimFencingToken(work),
+    now: dependencies.clock.now(),
+    workerId,
+  });
+
+/** Read the lease token only from a claimed work item. */
+const claimFencingToken = (work: FlowDurableWork): number => {
+  if (work.lease === undefined) throw new Error('FLOW_WORK_LEASE_MISSING');
+  return work.lease.fencingToken;
+};
+
+/** Add a successful step exactly once to an immutable checkpoint. */
+const completedCheckpoint = (
+  checkpoint: FlowRunCheckpoint | undefined,
+  stepId: string | undefined,
+): FlowRunCheckpoint => ({
+  completedStepIds: unique([
+    ...(checkpoint?.completedStepIds ?? []),
+    ...(stepId === undefined ? [] : [stepId]),
+  ]),
+  ...(checkpoint?.data === undefined ? {} : { data: checkpoint.data }),
+  failedStepIds: checkpoint?.failedStepIds ?? [],
+});
+
+/** Add a terminally failed step to an immutable checkpoint. */
+const failedCheckpoint = (
+  checkpoint: FlowRunCheckpoint | undefined,
+  stepId: string | undefined,
+): FlowRunCheckpoint => ({
+  completedStepIds: checkpoint?.completedStepIds ?? [],
+  ...(checkpoint?.data === undefined ? {} : { data: checkpoint.data }),
+  failedStepIds: unique([
+    ...(checkpoint?.failedStepIds ?? []),
+    ...(stepId === undefined ? [] : [stepId]),
+  ]),
+});
+
+/** Check whether a completed checkpoint makes a duplicate delivery a no-op. */
+const isCompleted = (
+  checkpoint: FlowRunCheckpoint | undefined,
+  stepId: string | undefined,
+): boolean => stepId !== undefined && checkpoint?.completedStepIds.includes(stepId) === true;
+
+/** Validate finite worker bounds before touching persistence. */
+const assertWorkerInput = (input: Parameters<typeof runDurableWorkerAsync>[0]): void => {
+  for (const value of [
+    input.approvalPollIntervalMs,
+    input.concurrency,
+    input.leaseDurationMs,
+    input.limit,
+    input.retry.maxAttempts,
+  ])
+    if (!Number.isSafeInteger(value) || value < 1) throw new Error('FLOW_WORKER_INPUT_INVALID');
+};
+
+/** Identify the canonical pending-approval error without interpreting untrusted error shapes. */
+const isApprovalPending = (error: unknown): boolean =>
+  error instanceof FlowSecurityError && error.code === 'approval_pending';
+
+/** Preserve a concise, provider-neutral failure signal in the worker result. */
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : 'FLOW_EFFECT_FAILED';
+
+/** Keep persisted checkpoint arrays deterministic. */
+const unique = (values: readonly string[]): readonly string[] => [...new Set(values)];
+
+/** Application-owned effect boundary; adapters must apply the supplied idempotency key at their side-effect boundary. */
+export interface FlowDurableEffectPort {
+  readonly compensateAsync?: (input: {
+    readonly run: FlowDurableRun;
+    readonly work: FlowDurableWork;
+  }) => Promise<void>;
+  readonly executeAsync: (input: {
+    readonly idempotencyKey: string;
+    readonly run: FlowDurableRun;
+    readonly work: FlowDurableWork;
+  }) => Promise<void>;
+  /**
+   * Query the provider's idempotency boundary before a protected replay. A provider must return
+   * `delivered` only when the stable key proves that the original effect completed.
+   */
+  readonly reconcileAsync?: (input: {
+    readonly idempotencyKey: string;
+    readonly run: FlowDurableRun;
+    readonly work: FlowDurableWork;
+  }) => Promise<'delivered' | 'unknown'>;
+}
+
+/** Observable outcome for every delivery claimed by one bounded worker tick. */
+export interface FlowWorkerOutcome {
+  readonly error?: string;
+  readonly status:
+    | 'already_completed'
+    | 'cancelled'
+    | 'failed'
+    | 'lost_lease'
+    | 'retry_scheduled'
+    | 'succeeded'
+    | 'waiting_approval';
+  readonly workId: string;
+}
+
+/** Summary of one worker tick; delivery remains at-least-once until fenced completion. */
+export interface FlowWorkerResult {
+  readonly claimedWorkIds: readonly string[];
+  readonly outcomes: readonly FlowWorkerOutcome[];
+  readonly recoveredWorkIds: readonly string[];
+}

package/src/features/execution/domain/assertFlowGraphSchemasSupported.ts

@@ -0,0 +1,17 @@
+import type { DataSchemaRegistry } from '@ankhorage/contracts/data';
+import type { FlowNode } from '@ankhorage/contracts/flow';
+
+import { assertFlowDataSchemaSupported } from './validateFlowDataSchema.js';
+
+/*** Validate every declared graph port schema before any operation can perform a side effect. */
+export const assertFlowGraphSchemasSupported = (
+  nodes: readonly FlowNode[],
+  schemas: DataSchemaRegistry | undefined,
+): void => {
+  for (const node of nodes)
+    for (const port of node.ports) {
+      const schema =
+        port.data?.schema ?? (port.data?.schemaRef ? { ref: port.data.schemaRef } : undefined);
+      if (schema) assertFlowDataSchemaSupported(schema, schemas);
+    }
+};