@ankhorage/flow 0.0.0-stage → 0.4.1

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/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/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,
+    },
+  });
+};