@ankhorage/flow 0.0.0-stage → 0.5.0

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

@@ -0,0 +1,21 @@
+import type { FlowRetryPolicy } from '../../../types/durableExecution.js';
+
+/*** Calculate an exponential retry time from persisted attempt state without ambient time. */
+export const calculateRetryDueAt = (
+  now: Date,
+  completedAttempt: number,
+  policy: FlowRetryPolicy,
+): string => {
+  if (!Number.isSafeInteger(completedAttempt) || completedAttempt < 1)
+    throw new Error('FLOW_RETRY_ATTEMPT_INVALID');
+  if (!Number.isSafeInteger(policy.baseDelayMs) || policy.baseDelayMs < 0)
+    throw new Error('FLOW_RETRY_BASE_DELAY_INVALID');
+  if (
+    !Number.isSafeInteger(policy.maxDelayMs) ||
+    policy.maxDelayMs < policy.baseDelayMs ||
+    policy.maxDelayMs < 0
+  )
+    throw new Error('FLOW_RETRY_MAX_DELAY_INVALID');
+  const delay = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (completedAttempt - 1));
+  return new Date(now.getTime() + delay).toISOString();
+};

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

@@ -0,0 +1,97 @@
+import type { FlowDefinition, FlowEdge, FlowNode } from '@ankhorage/contracts/flow';
+
+import type { FlowCompiledGraph, FlowNodeRegistry } from '../../../types/execution.js';
+
+/*** Compile a valid acyclic graph into deterministic execution order. */
+export const compileFlowGraph = (
+  definition: FlowDefinition,
+  registry: FlowNodeRegistry,
+): FlowCompiledGraph => {
+  const nodesById = indexNodes(definition.nodes);
+  const edgesBySourceNodeId = indexEdges(definition.edges, nodesById);
+  for (const node of definition.nodes) assertNodeIsExecutable(node, registry);
+  return {
+    definition,
+    edgesBySourceNodeId,
+    topologicalNodeIds: orderNodes(
+      definition.nodes.map(({ id }) => id),
+      definition.edges,
+    ),
+  };
+};
+
+/*** Index nodes while rejecting duplicate graph identifiers. */
+const indexNodes = (nodes: readonly FlowNode[]): Readonly<Record<string, FlowNode>> => {
+  const entries = nodes.map((node) => [node.id, node] as const);
+  if (new Set(entries.map(([id]) => id)).size !== entries.length)
+    throw new Error('FLOW_GRAPH_DUPLICATE_NODE_ID');
+  return Object.fromEntries(entries);
+};
+
+/*** Validate and group graph edges by their producing node. */
+const indexEdges = (
+  edges: readonly FlowEdge[],
+  nodesById: Readonly<Record<string, FlowNode>>,
+): Readonly<Record<string, readonly FlowEdge[]>> => {
+  if (new Set(edges.map(({ id }) => id)).size !== edges.length)
+    throw new Error('FLOW_GRAPH_DUPLICATE_EDGE_ID');
+  for (const edge of edges) {
+    const source = nodesById[edge.source.nodeId];
+    const target = nodesById[edge.target.nodeId];
+    if (!source || !target) throw new Error(`FLOW_GRAPH_UNKNOWN_EDGE_NODE:${edge.id}`);
+    assertPort(source, edge.source.portId, 'output', edge.id);
+    assertPort(target, edge.target.portId, 'input', edge.id);
+  }
+  return edges.reduce<Readonly<Record<string, readonly FlowEdge[]>>>(
+    (grouped, edge) => ({
+      ...grouped,
+      [edge.source.nodeId]: [...(grouped[edge.source.nodeId] ?? []), edge],
+    }),
+    {},
+  );
+};
+
+/*** Ensure a graph port exists exactly once with the expected direction. */
+const assertPort = (
+  node: FlowNode,
+  portId: string,
+  direction: 'input' | 'output',
+  edgeId: string,
+): void => {
+  if (node.ports.filter((port) => port.id === portId && port.direction === direction).length !== 1)
+    throw new Error(`FLOW_GRAPH_INVALID_EDGE_PORT:${edgeId}`);
+};
+
+/*** Reject unknown operations and code capabilities before execution can begin. */
+const assertNodeIsExecutable = (node: FlowNode, registry: FlowNodeRegistry): void => {
+  const { capabilityId, providerId } = node.capability;
+  const operationId = `${providerId}:${capabilityId}`;
+  if (capabilityId === 'code') throw new Error('FLOW_CODE_EXECUTION_DISABLED');
+  if (!Object.hasOwn(registry, operationId))
+    throw new Error(`FLOW_OPERATION_UNREGISTERED:${operationId}`);
+  if (
+    new Set(node.ports.map(({ direction, id }) => `${direction}:${id}`)).size !== node.ports.length
+  )
+    throw new Error(`FLOW_GRAPH_DUPLICATE_PORT_ID:${node.id}`);
+};
+
+/*** Produce stable topological order and reject cycles without an explicit bounded-loop contract. */
+const orderNodes = (nodeIds: readonly string[], edges: readonly FlowEdge[]): readonly string[] => {
+  const incomingCounts = new Map(nodeIds.map((nodeId) => [nodeId, 0]));
+  for (const edge of edges)
+    incomingCounts.set(edge.target.nodeId, (incomingCounts.get(edge.target.nodeId) ?? 0) + 1);
+  const pending = nodeIds.filter((nodeId) => incomingCounts.get(nodeId) === 0);
+  const ordered: string[] = [];
+  while (pending.length > 0) {
+    const nodeId = pending.shift();
+    if (!nodeId) continue;
+    ordered.push(nodeId);
+    for (const edge of edges.filter((candidate) => candidate.source.nodeId === nodeId)) {
+      const nextCount = (incomingCounts.get(edge.target.nodeId) ?? 0) - 1;
+      incomingCounts.set(edge.target.nodeId, nextCount);
+      if (nextCount === 0) pending.push(edge.target.nodeId);
+    }
+  }
+  if (ordered.length !== nodeIds.length) throw new Error('FLOW_GRAPH_CYCLE');
+  return ordered;
+};

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

@@ -0,0 +1,26 @@
+import type { FlowDataRef, FlowNodeConfigValue } from '@ankhorage/contracts/flow';
+
+import type { FlowNodeOperation, FlowNodeRegistry } from '../../../types/execution.js';
+
+/*** Create the built-in operations that have no provider or host dependency. */
+export const createDefaultNodeRegistry = (): FlowNodeRegistry => ({
+  'flow:condition': { executeAsync: () => Promise.resolve({}) },
+  'flow:noop': { executeAsync: () => Promise.resolve({}) },
+  'flow:transform': { executeAsync: transformAsync },
+});
+
+/*** Copy configured inline or artifact values to matching output ports without evaluating code. */
+const transformAsync: FlowNodeOperation['executeAsync'] = ({ config, node }) => {
+  const outputIds = new Set(
+    node.ports.filter((port) => port.direction === 'output').map(({ id }) => id),
+  );
+  const output = Object.fromEntries(
+    Object.entries(config ?? {}).filter(
+      (entry): entry is [string, FlowDataRef] => outputIds.has(entry[0]) && isDataRef(entry[1]),
+    ),
+  );
+  return Promise.resolve({ output });
+};
+
+/*** Narrow a configuration value to data that may safely leave a node. */
+const isDataRef = (value: FlowNodeConfigValue): value is FlowDataRef => value.kind !== 'secret';

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

@@ -0,0 +1,14 @@
+import type { FlowDefinitionRef, FlowDurableRun } from '../../../types/durableExecution.js';
+
+/*** Create a revision-zero run pinned permanently to one published flow definition. */
+export const createDurableRun = (
+  input: { readonly flow: FlowDefinitionRef; readonly id: string },
+  now: Date,
+): FlowDurableRun => ({
+  createdAt: now.toISOString(),
+  flow: { ...input.flow },
+  id: input.id,
+  revision: 0,
+  status: 'queued',
+  updatedAt: now.toISOString(),
+});

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

@@ -0,0 +1,22 @@
+import type { FlowDurableWork, FlowRetryPolicy } from '../../../types/durableExecution.js';
+import { calculateRetryDueAt } from './calculateRetryDueAt.js';
+
+/*** Create the next immutable work attempt from a completed attempt and controlled clock. */
+export const createRetryWork = (
+  completed: FlowDurableWork,
+  now: Date,
+  policy: FlowRetryPolicy,
+): FlowDurableWork => ({
+  ...(completed.idempotencyKey === undefined ? {} : { idempotencyKey: completed.idempotencyKey }),
+  attempt: completed.attempt + 1,
+  dueAt: calculateRetryDueAt(now, completed.attempt, policy),
+  effectKind: completed.effectKind,
+  flow: { ...completed.flow },
+  id: `${completed.runId}:attempt:${completed.attempt + 1}`,
+  runId: completed.runId,
+  ...(completed.securityOperation === undefined
+    ? {}
+    : { securityOperation: completed.securityOperation }),
+  ...(completed.stepId === undefined ? {} : { stepId: completed.stepId }),
+  status: 'ready',
+});

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

@@ -0,0 +1,131 @@
+/** Determine whether one UTC instant matches a five-field POSIX cron expression in an IANA zone. */
+export const isCronDueAt = (input: {
+  readonly cron: string;
+  readonly now: Date;
+  readonly timezone?: string;
+}): boolean => {
+  const fields = input.cron.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error('FLOW_CRON_INVALID');
+  const local = localParts(input.now, input.timezone ?? 'Etc/UTC');
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+  if (
+    minute === undefined ||
+    hour === undefined ||
+    dayOfMonth === undefined ||
+    month === undefined ||
+    dayOfWeek === undefined
+  )
+    throw new Error('FLOW_CRON_INVALID');
+  const minuteMatches = matchesField(minute, local.minute, 0, 59);
+  const hourMatches = matchesField(hour, local.hour, 0, 23);
+  const monthMatches = matchesField(month, local.month, 1, 12);
+  const dayOfMonthMatches = matchesField(dayOfMonth, local.day, 1, 31);
+  const dayOfWeekMatches = matchesField(dayOfWeek, local.dayOfWeek, 0, 7);
+  const dayMatches =
+    dayOfMonth === '*' || dayOfWeek === '*'
+      ? dayOfMonthMatches && dayOfWeekMatches
+      : dayOfMonthMatches || dayOfWeekMatches;
+  return minuteMatches && hourMatches && monthMatches && dayMatches;
+};
+
+/** Format a UTC instant into its real local wall-clock fields; duplicate fall-back instants remain distinct instants. */
+const localParts = (
+  now: Date,
+  timezone: string,
+): {
+  readonly day: number;
+  readonly dayOfWeek: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly month: number;
+} => {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      day: 'numeric',
+      hour: 'numeric',
+      hourCycle: 'h23',
+      minute: 'numeric',
+      month: 'numeric',
+      timeZone: timezone,
+      weekday: 'short',
+    }).formatToParts(now);
+    const read = (type: Intl.DateTimeFormatPartTypes): string =>
+      parts.find((part) => part.type === type)?.value ?? invalidTimezone();
+    return {
+      day: Number(read('day')),
+      dayOfWeek: weekday(read('weekday')),
+      hour: Number(read('hour')),
+      minute: Number(read('minute')),
+      month: Number(read('month')),
+    };
+  } catch {
+    throw new Error('FLOW_CRON_TIMEZONE_INVALID');
+  }
+};
+
+/** Match one POSIX cron field including lists, ranges, and positive step values. */
+const matchesField = (field: string, value: number, minimum: number, maximum: number): boolean =>
+  field.split(',').some((part) => matchesPart(part, value, minimum, maximum));
+
+/** Match one validated cron list member. */
+const matchesPart = (part: string, value: number, minimum: number, maximum: number): boolean => {
+  const [rangePart, stepPart] = part.split('/');
+  if (part.split('/').length > 2 || rangePart === undefined) throw new Error('FLOW_CRON_INVALID');
+  const step = stepPart === undefined ? 1 : parseValue(stepPart, 1, maximum - minimum + 1);
+  const [start, end] = parseRange(rangePart, minimum, maximum);
+  return value >= start && value <= end && (value - start) % step === 0;
+};
+
+/** Parse a wildcard, number, or inclusive numeric range. */
+const parseRange = (range: string, minimum: number, maximum: number): readonly [number, number] => {
+  if (range === '*') return [minimum, maximum];
+  const values = range.split('-');
+  if (values.length === 1) {
+    const [single] = values;
+    if (single === undefined) throw new Error('FLOW_CRON_INVALID');
+    const value = parseValue(single, minimum, maximum);
+    return [value, value];
+  }
+  if (values.length !== 2 || values[0] === undefined || values[1] === undefined)
+    throw new Error('FLOW_CRON_INVALID');
+  const start = parseValue(values[0], minimum, maximum);
+  const end = parseValue(values[1], minimum, maximum);
+  if (end < start) throw new Error('FLOW_CRON_INVALID');
+  return [start, end];
+};
+
+/** Parse one strict POSIX cron integer. */
+const parseValue = (value: string, minimum: number, maximum: number): number => {
+  if (!/^\d+$/.test(value)) throw new Error('FLOW_CRON_INVALID');
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum)
+    throw new Error('FLOW_CRON_INVALID');
+  return parsed;
+};
+
+/** Map English short weekday names produced by the fixed formatter to POSIX weekday values. */
+const weekday = (value: string): number => {
+  switch (value) {
+    case 'Sun':
+      return 0;
+    case 'Mon':
+      return 1;
+    case 'Tue':
+      return 2;
+    case 'Wed':
+      return 3;
+    case 'Thu':
+      return 4;
+    case 'Fri':
+      return 5;
+    case 'Sat':
+      return 6;
+    default:
+      return invalidTimezone();
+  }
+};
+
+/** Keep an impossible formatter shape distinct from a cron syntax error. */
+const invalidTimezone = (): never => {
+  throw new Error('FLOW_CRON_TIMEZONE_INVALID');
+};

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

@@ -0,0 +1,218 @@
+import type { DataContractValue, DataSchema, DataSchemaRegistry } from '@ankhorage/contracts/data';
+
+const maximumSchemaDepth = 64;
+
+/*** Validate serializable data against the supported portable schema vocabulary. */
+export const validateFlowDataSchema = (
+  value: DataContractValue,
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+): boolean => {
+  assertFlowDataSchemaSupported(schema, schemas);
+  return matchesSchema(value, schema, schemas, createTraversalState());
+};
+
+/*** Reject unsupported, unresolved, cyclic, or excessively nested portable schemas before use. */
+export const assertFlowDataSchemaSupported = (
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+): void => assertSupportedSchema(schema, schemas, createTraversalState());
+
+/*** Resolve a schema reference only from the explicit execution registry. */
+const resolveSchema = (
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): DataSchema => {
+  if (!schema.ref) return schema;
+  if (state.referenceIds.has(schema.ref.id))
+    throw new Error(`FLOW_SCHEMA_REFERENCE_CYCLE:${schema.ref.id}`);
+  const resolved = schemas?.[schema.ref.id];
+  if (!resolved) throw new Error(`FLOW_SCHEMA_REFERENCE_UNRESOLVED:${schema.ref.id}`);
+  return resolved;
+};
+
+/*** Apply portable schema constraints without coercing a JSON-compatible value. */
+const matchesSchema = (
+  value: DataContractValue,
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): boolean => {
+  const resolved = resolveSchema(schema, schemas, state);
+  const nextState = advanceTraversalState(resolved, schema.ref?.id, state);
+  return (
+    matchesTypes(value, resolved) &&
+    matchesValues(value, resolved) &&
+    matchesComposition(value, resolved, schemas, nextState) &&
+    matchesStructure(value, resolved, schemas, nextState)
+  );
+};
+
+/*** Reject portable annotations that require a validator capability this engine does not own. */
+const assertSupportedSchema = (
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): void => {
+  if (schema.format !== undefined) throw new Error(`FLOW_SCHEMA_UNSUPPORTED_CONSTRAINT:format`);
+  const nextState = advanceTraversalState(schema, undefined, state);
+  visitChildSchemas(schema, schemas, nextState);
+  if (!schema.ref) return;
+  const resolved = resolveSchema(schema, schemas, state);
+  assertSupportedSchema(resolved, schemas, {
+    ...nextState,
+    referenceIds: new Set([...state.referenceIds, schema.ref.id]),
+  });
+};
+
+/*** Visit every schema child so unsupported declarations fail before value matching begins. */
+const visitChildSchemas = (
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): void => {
+  const children = [
+    ...(schema.items ? [schema.items] : []),
+    ...(typeof schema.additionalProperties === 'object' ? [schema.additionalProperties] : []),
+    ...Object.values(schema.properties ?? {}),
+    ...(schema.allOf ?? []),
+    ...(schema.anyOf ?? []),
+    ...(schema.oneOf ?? []),
+  ];
+  for (const child of children) assertSupportedSchema(child, schemas, state);
+};
+
+/*** Match the declared primitive type union and explicit nullability. */
+const matchesTypes = (value: DataContractValue, schema: DataSchema): boolean => {
+  if (value === null && schema.nullable) return true;
+  if (schema.type === undefined) return true;
+  if (typeof schema.type === 'string') return matchesType(value, schema.type);
+  return schema.type.some((type) => matchesType(value, type));
+};
+
+/*** Match one JSON primitive category without coercion. */
+const matchesType = (value: DataContractValue, type: string): boolean => {
+  if (type === 'array') return isDataArray(value);
+  if (type === 'integer') return typeof value === 'number' && Number.isInteger(value);
+  if (type === 'null') return value === null;
+  if (type === 'object') return isDataRecord(value);
+  return typeof value === type;
+};
+
+/*** Apply constant and enumeration constraints using structural JSON equality. */
+const matchesValues = (value: DataContractValue, schema: DataSchema): boolean =>
+  (schema.const === undefined || structurallyEqual(value, schema.const)) &&
+  (!schema.enum || schema.enum.some((candidate) => structurallyEqual(value, candidate)));
+
+/*** Apply logical schema composition with its standard cardinality semantics. */
+const matchesComposition = (
+  value: DataContractValue,
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): boolean =>
+  (!schema.allOf ||
+    schema.allOf.every((candidate) => matchesSchema(value, candidate, schemas, state))) &&
+  (!schema.anyOf ||
+    schema.anyOf.some((candidate) => matchesSchema(value, candidate, schemas, state))) &&
+  (!schema.oneOf ||
+    schema.oneOf.filter((candidate) => matchesSchema(value, candidate, schemas, state)).length ===
+      1);
+
+/*** Recursively apply object and array member constraints. */
+const matchesStructure = (
+  value: DataContractValue,
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): boolean =>
+  matchesItems(value, schema.items, schemas, state) &&
+  (!isDataRecord(value) || matchesProperties(value, schema, schemas, state));
+
+/*** Validate array elements only when an item schema is declared. */
+const matchesItems = (
+  value: DataContractValue,
+  items: DataSchema | undefined,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): boolean =>
+  !items ||
+  !isDataArray(value) ||
+  value.every((item) => matchesSchema(item, items, schemas, state));
+
+/*** Validate required object members and declared or additional property schemas. */
+const matchesProperties = (
+  value: Readonly<Record<string, DataContractValue>>,
+  schema: DataSchema,
+  schemas: DataSchemaRegistry | undefined,
+  state: SchemaTraversalState,
+): boolean => {
+  const properties = schema.properties ?? {};
+  return (
+    (schema.required ?? []).every((key) => Object.entries(value).some(([name]) => name === key)) &&
+    Object.entries(value).every(([key, item]) => {
+      const property = Object.entries(properties).find(([name]) => name === key)?.[1];
+      if (property) return matchesSchema(item, property, schemas, state);
+      if (schema.additionalProperties === false) return false;
+      return (
+        typeof schema.additionalProperties !== 'object' ||
+        matchesSchema(item, schema.additionalProperties, schemas, state)
+      );
+    })
+  );
+};
+
+interface SchemaTraversalState {
+  readonly depth: number;
+  readonly referenceIds: ReadonlySet<string>;
+  readonly schemas: ReadonlySet<DataSchema>;
+}
+
+/*** Start bounded schema traversal without retaining mutable validation state. */
+const createTraversalState = (): SchemaTraversalState => ({
+  depth: 0,
+  referenceIds: new Set(),
+  schemas: new Set(),
+});
+
+/*** Advance a schema traversal while rejecting direct cycles and excessive nesting deterministically. */
+const advanceTraversalState = (
+  schema: DataSchema,
+  referenceId: string | undefined,
+  state: SchemaTraversalState,
+): SchemaTraversalState => {
+  if (state.depth >= maximumSchemaDepth) throw new Error('FLOW_SCHEMA_MAX_DEPTH');
+  if (state.schemas.has(schema)) throw new Error('FLOW_SCHEMA_CYCLE');
+  return {
+    depth: state.depth + 1,
+    referenceIds: referenceId ? new Set([...state.referenceIds, referenceId]) : state.referenceIds,
+    schemas: new Set([...state.schemas, schema]),
+  };
+};
+
+/*** Compare JSON-compatible values independently of object key order. */
+const structurallyEqual = (left: DataContractValue, right: DataContractValue): boolean =>
+  JSON.stringify(normalizeValue(left)) === JSON.stringify(normalizeValue(right));
+
+/*** Canonicalize object member ordering for structural comparison. */
+const normalizeValue = (value: DataContractValue): DataContractValue => {
+  if (isDataArray(value)) return value.map(normalizeValue);
+  if (isDataRecord(value))
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, normalizeValue(item)]),
+    );
+  return value;
+};
+
+/*** Narrow a JSON-compatible object to a non-array member record. */
+const isDataRecord = (
+  value: DataContractValue,
+): value is Readonly<Record<string, DataContractValue>> =>
+  value !== null && typeof value === 'object' && !isDataArray(value);
+
+/*** Narrow a JSON-compatible array without losing its serializable member type. */
+const isDataArray = (value: DataContractValue): value is readonly DataContractValue[] =>
+  Array.isArray(value);

package/src/features/execution/ports/FlowPersistencePort.ts

@@ -0,0 +1,38 @@
+import type {
+  FlowDurableRun,
+  FlowDurableWork,
+  FlowOutboxRecord,
+} from '../../../types/durableExecution.js';
+
+export interface FlowPersistencePort {
+  readonly cancelRunWorkAsync: (runId: string) => Promise<readonly string[]>;
+  readonly claimDueWorkAsync: (input: {
+    readonly leaseDurationMs: number;
+    readonly limit: number;
+    readonly now: Date;
+    readonly workerId: string;
+  }) => Promise<readonly FlowDurableWork[]>;
+  readonly completeWorkAsync: (input: {
+    readonly id: string;
+    readonly leaseFencingToken: number;
+    readonly now: Date;
+    readonly workerId: string;
+  }) => Promise<boolean>;
+  readonly createOutboxAsync: (record: FlowOutboxRecord) => Promise<void>;
+  readonly createRunAsync: (run: FlowDurableRun) => Promise<void>;
+  readonly enqueueWorkAsync: (work: FlowDurableWork) => Promise<void>;
+  readonly markOutboxDeliveredAsync: (id: string) => Promise<boolean>;
+  readonly readOutboxAsync: (id: string) => Promise<FlowOutboxRecord | undefined>;
+  readonly readRunAsync: (id: string) => Promise<FlowDurableRun | undefined>;
+  readonly recoverExpiredClaimsAsync: (now: Date) => Promise<readonly string[]>;
+  readonly releaseWorkAsync: (input: {
+    readonly dueAt: string;
+    readonly id: string;
+    readonly leaseFencingToken: number;
+    readonly workerId: string;
+  }) => Promise<boolean>;
+  readonly transitionRunAsync: (input: {
+    readonly expectedRevision: number;
+    readonly run: FlowDurableRun;
+  }) => Promise<boolean>;
+}

package/src/features/mcp/McpToolError.ts

@@ -0,0 +1,10 @@
+/*** Represents a stable, redaction-safe MCP failure. */
+export class McpToolError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'McpToolError';
+  }
+}

package/src/features/mcp/createMcpRemoteTransport.ts

@@ -0,0 +1,34 @@
+import type { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+import type { McpProviderDefinition } from '../../types/mcp.js';
+import type { FlowOutboundTransportPort } from '../../types/security.js';
+import { loadMcpSdkAsync } from './loadMcpSdkAsync.js';
+import { McpToolError } from './McpToolError.js';
+
+/*** Opens remote MCP only through the host-owned transport that controls every peer connection. */
+export const createMcpRemoteTransportAsync = async (
+  provider: Extract<McpProviderDefinition, { readonly transport: 'remote' }>,
+  outboundTransport: FlowOutboundTransportPort | undefined,
+): Promise<StreamableHTTPClientTransport> => {
+  if (!outboundTransport)
+    throw new McpToolError(
+      'remote_security_boundary_unavailable',
+      'Remote MCP requires a host-owned Flow security transport boundary.',
+    );
+  const { StreamableHTTPClientTransport } = await loadMcpSdkAsync();
+  return new StreamableHTTPClientTransport(new URL(provider.endpoint), {
+    fetch: async (url, init) =>
+      outboundTransport.fetchAsync({
+        allowedHosts: provider.allowedHosts,
+        ...(init === undefined ? {} : { init }),
+        url: url.toString(),
+      }),
+    redirectPolicy: 'same-origin',
+    reconnectionOptions: {
+      initialReconnectionDelay: 100,
+      maxReconnectionDelay: 1_000,
+      reconnectionDelayGrowFactor: 1,
+      maxRetries: 0,
+    },
+  });
+};