@relayflows/sdk 2.0.50 → 2.0.52

package/src/authored-flow-lifecycle.ts

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage, executionAsyncId } from 'node:async_hooks';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import { AuthoredPromiseGraph } from './authored-promise-graph.js';
-import { AuthoredStepGraph } from './authored-step-graph.js';
+import { AuthoredStepGraph, promiseOutcome } from './authored-step-graph.js';
 import type { AuthoredStepEdges } from './authored-step-index.js';
 
 type OperationToken = object;
@@ -10,12 +10,38 @@ interface PromiseAllGroup {
   aggregate: number;
   members: ReadonlySet<number>;
 }
+interface AllSettlementGuard {
+  readonly aggregate: Promise<unknown>;
+  readonly aggregateId: number;
+  readonly combinator: 'all' | 'allSettled';
+  readonly members: readonly number[];
+}
 export interface AuthoredOperationInvocation {
   readonly asyncId: number;
   bound: boolean;
 }
 
+const nativePromiseConstructor = Promise;
+const nativePromisePrototype = Promise.prototype;
 const nativePromiseThen = Promise.prototype.then;
+const nativePromiseCatch = Promise.prototype.catch;
+const nativePromiseFinally = Promise.prototype.finally;
+const nativePromiseResolve = Promise.resolve;
+const nativePromiseReject = Promise.reject;
+const nativePromisePrototypeConstructorDescriptor = Object.getOwnPropertyDescriptor(Promise.prototype, 'constructor');
+const nativePromisePrototypeConstructor = Promise.prototype.constructor;
+const nativePromiseSpeciesDescriptor = Object.getOwnPropertyDescriptor(Promise, Symbol.species);
+const nativePromiseSpeciesGetter = nativePromiseSpeciesDescriptor?.get;
+const nativeFunctionToString = Function.prototype.toString;
+/** Use the startup snapshot even when a source parser is loaded on demand. */
+export function authoredFunctionSource(value: Function): string {
+  return nativeFunctionToString.call(value);
+}
+const nativeArrayIteratorDescriptor = Object.getOwnPropertyDescriptor(Array.prototype, Symbol.iterator);
+const nativeArrayIterator = Array.prototype[Symbol.iterator];
+const nativeArrayIteratorPrototype = Object.getPrototypeOf(nativeArrayIterator.call([])) as Iterator<unknown>;
+const nativeArrayIteratorNextDescriptor = Object.getOwnPropertyDescriptor(nativeArrayIteratorPrototype, 'next');
+const nativeArrayIteratorNext = nativeArrayIteratorPrototype.next;
 const activeLifecycle = new AsyncLocalStorage<AuthoredFlowLifecycle>();
 const stepOwners = new WeakMap<object, {
   lifecycle: AuthoredFlowLifecycle;
@@ -42,7 +68,8 @@ const stepOwners = new WeakMap<object, {
  * claim was wrong: it covered whichever member happened to resolve the
  * aggregate. What is true is narrower and is what the code now implements —
  * these four are exact, and `adoptFromResolvingContext` in the promise graph is
- * a best-effort fallback for aggregates built by hand.
+ * a fallback for aggregates built by hand. Parallel f.run admission additionally
+ * rejects unregistered join shapes on its causal path and checks observer identity.
  *
  * The interception is disclosed to authors in `docs/SURFACE.md`. It is spec
  * transparent: `Symbol.iterator` is read exactly once (as the intrinsic does),
@@ -58,6 +85,51 @@ const nativeCombinators = Object.freeze(
   Object.fromEntries(COMBINATORS.map((name) => [name, Promise[name] as unknown as Combinator])),
 ) as Readonly<Record<CombinatorName, Combinator>>;
 
+const originallyNative = (value: unknown): boolean => typeof value === 'function'
+  && /\{\s*\[native code\]\s*\}/u.test(nativeFunctionToString.call(value));
+const nativeAtModuleLoad = [
+  nativePromiseConstructor, nativePromiseThen, nativePromiseCatch, nativePromiseFinally,
+  nativePromiseResolve, nativePromiseReject, nativePromisePrototypeConstructor,
+  nativePromiseSpeciesGetter, nativeFunctionToString, nativeArrayIterator,
+  nativeArrayIteratorNext, ...Object.values(nativeCombinators),
+].every(originallyNative);
+
+function sameDescriptor(actual: PropertyDescriptor | undefined, original: PropertyDescriptor | undefined): boolean {
+  return actual !== undefined && original !== undefined
+    && actual.configurable === original.configurable && actual.enumerable === original.enumerable
+    && actual.writable === original.writable && actual.value === original.value
+    && actual.get === original.get && actual.set === original.set;
+}
+
+/** Preloaded code can replace an intrinsic before this module takes its snapshot. */
+function authoredProcessHasPreload(): boolean {
+  const preload = (arg: string): boolean => arg === '-r' || arg.startsWith('-r')
+    || ['--import', '--require', '--loader', '--experimental-loader']
+      .some(flag => arg === flag || arg.startsWith(`${flag}=`));
+  return process.execArgv.some(preload)
+    || nodeOptionTokens(process.env['NODE_OPTIONS'] ?? '').some(preload);
+}
+
+/** NODE_OPTIONS is a command-line string, while execArgv is already tokenized. */
+function nodeOptionTokens(options: string): string[] {
+  const tokens: string[] = [];
+  let token = '';
+  let quote: '"' | "'" | undefined;
+  let escaped = false;
+  for (const char of options) {
+    if (escaped) { token += char; escaped = false; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; continue; }
+    if (char === quote) { quote = undefined; continue; }
+    if ((char === '"' || char === "'") && quote === undefined) { quote = char; continue; }
+    if (/\s/u.test(char) && quote === undefined) {
+      if (token.length > 0) tokens.push(token);
+      token = '';
+    } else token += char;
+  }
+  if (token.length > 0) tokens.push(token);
+  return tokens;
+}
+
 const observedCombinators: Record<CombinatorName, Combinator> = Object.fromEntries(
   COMBINATORS.map((name) => {
     const native = nativeCombinators[name];
@@ -65,11 +137,16 @@ const observedCombinators: Record<CombinatorName, Combinator> = Object.fromEntri
       this: PromiseConstructor,
       values: Iterable<unknown>,
     ): Promise<unknown> {
+      const lifecycle = activeLifecycle.getStore();
+      const declared = lifecycle?.captureParallelArrayMembers(values);
       const members = collectMembers(values);
-      if (members === undefined) return native.call(this, values);
-      const aggregate = native.call(this, members);
-      activeLifecycle.getStore()?.registerCombinator(members, aggregate, name);
-      return aggregate;
+      if (members === undefined) {
+        if (declared !== undefined) lifecycle?.refuseUnsafeCombinator(
+          `parallel Promise.${name} could not inspect its array members`);
+        return native.call(this, values);
+      }
+      if (lifecycle === undefined) return native.call(this, members);
+      return lifecycle.observeCombinator(native, this, members, name, declared);
     };
     Object.defineProperty(observed, 'name', { value: name, configurable: true });
     Object.defineProperty(observed, 'length', { value: 1, configurable: true });
@@ -79,6 +156,30 @@ const observedCombinators: Record<CombinatorName, Combinator> = Object.fromEntri
 
 let combinatorObservers = 0;
 
+/** An imported module must not substitute any primitive used to construct joins. */
+export function parallelPromiseIntrinsicsIntact(): boolean {
+  if (!nativeAtModuleLoad || authoredProcessHasPreload()
+    || Function.prototype.toString !== nativeFunctionToString
+    || !sameDescriptor(Object.getOwnPropertyDescriptor(Array.prototype, Symbol.iterator),
+      nativeArrayIteratorDescriptor)
+    || Array.prototype[Symbol.iterator] !== nativeArrayIterator
+    || !sameDescriptor(Object.getOwnPropertyDescriptor(nativeArrayIteratorPrototype, 'next'),
+      nativeArrayIteratorNextDescriptor)
+    || nativeArrayIteratorPrototype.next !== nativeArrayIteratorNext
+    || Promise !== nativePromiseConstructor || Promise.prototype !== nativePromisePrototype
+    || !sameDescriptor(Object.getOwnPropertyDescriptor(Promise.prototype, 'constructor'),
+      nativePromisePrototypeConstructorDescriptor)
+    || Promise.prototype.constructor !== nativePromisePrototypeConstructor
+    || !sameDescriptor(Object.getOwnPropertyDescriptor(Promise, Symbol.species), nativePromiseSpeciesDescriptor)
+    || Object.getOwnPropertyDescriptor(Promise, Symbol.species)?.get !== nativePromiseSpeciesGetter
+    || Promise.prototype.then !== nativePromiseThen
+    || Promise.prototype.catch !== nativePromiseCatch
+    || Promise.prototype.finally !== nativePromiseFinally
+    || Promise.resolve !== nativePromiseResolve || Promise.reject !== nativePromiseReject) return false;
+  return COMBINATORS.every(name => Promise[name] === (combinatorObservers > 0
+    ? observedCombinators[name] : nativeCombinators[name]) as unknown);
+}
+
 /**
  * Drain an iterable into an array, reading `Symbol.iterator` exactly once.
  *
@@ -125,6 +226,8 @@ export class AuthoredFlowLifecycle {
   private readonly invocations = new Map<OperationToken, AuthoredOperationInvocation[]>();
   private readonly promiseAllAggregates = new Map<OperationToken, Set<number>>();
   private readonly promiseAllGroups: PromiseAllGroup[] = [];
+  private readonly allSettlementGuards: AllSettlementGuard[] = [];
+  private invalidAllSettlement = false;
   private readonly callbackFailures = new Map<OperationToken, unknown>();
   private completionAsyncId: number | undefined;
   private closed = false;
@@ -132,14 +235,19 @@ export class AuthoredFlowLifecycle {
   private registrations = 0;
   private groupsByInvocation: { readonly key: string; readonly groups: Map<number, ReadonlySet<number>> } | undefined;
 
-  constructor() {
+  constructor(private readonly refuseUnknownThenable?: (message: string) => void) {
     this.graph = new AuthoredPromiseGraph(
       () => activeLifecycle.getStore() === this,
       (asyncId) => {
         for (const probe of this.activeResolverProbes) probe.add(asyncId);
       },
     );
-    this.stepGraph = new AuthoredStepGraph((asyncId) => this.graph.causesOf(asyncId));
+    this.stepGraph = new AuthoredStepGraph(
+      (asyncId) => this.graph.causesOf(asyncId),
+      undefined,
+      (asyncId) => this.graph.wasAdoptedFromResolvingContext(asyncId)
+        || this.graph.hasUnobservedJoinShape(asyncId),
+    );
     installPromiseAllObserver();
     try {
       this.graph.enable();
@@ -153,6 +261,19 @@ export class AuthoredFlowLifecycle {
     return activeLifecycle.run(this, body);
   }
 
+  /** Compare the literal array's indexed members with its iterable view. */
+  captureParallelArrayMembers(values: Iterable<unknown>): readonly unknown[] | undefined {
+    if (this.refuseUnknownThenable === undefined || !Array.isArray(values)) return undefined;
+    const members = new Array<unknown>(values.length);
+    for (let i = 0; i < values.length; i++) members[i] = values[i];
+    return members;
+  }
+
+  refuseUnsafeCombinator(message: string): never {
+    this.refuseUnknownThenable?.(message);
+    throw new AuthoredFlowExecutionError('step_failed', message);
+  }
+
   registerStep(step: object, operation: OperationToken): void {
     stepOwners.set(step, { lifecycle: this, operation });
   }
@@ -161,6 +282,7 @@ export class AuthoredFlowLifecycle {
     values: readonly unknown[],
     aggregate: Promise<unknown>,
     combinator: CombinatorName,
+    created: ReadonlySet<number>,
   ): void {
     const aggregateId = this.graph.idOf(aggregate);
     if (aggregateId === undefined) return;
@@ -177,6 +299,7 @@ export class AuthoredFlowLifecycle {
       const awaited = owner?.lifecycle === this ? this.operationPromises.get(owner.operation) : memberId;
       if (awaited !== undefined) awaitedMembers.push(awaited);
       if (owner?.lifecycle !== this) continue;
+      if (awaited !== undefined) this.stepGraph.certifyMember(awaited);
       let operationAggregates = this.promiseAllAggregates.get(owner.operation);
       if (operationAggregates === undefined) {
         operationAggregates = new Set();
@@ -185,8 +308,53 @@ export class AuthoredFlowLifecycle {
       operationAggregates.add(aggregateId);
     }
     this.promiseAllGroups.push({ aggregate: aggregateId, members: memberIds });
+    if (this.refuseUnknownThenable !== undefined
+      && (combinator === 'all' || combinator === 'allSettled')) {
+      this.allSettlementGuards.push({ aggregate, aggregateId, combinator, members: awaitedMembers });
+    }
     this.registrations++;
-    this.stepGraph.registerAggregate(aggregateId, aggregate, combinator, awaitedMembers);
+    this.stepGraph.registerAggregate(aggregateId, aggregate, combinator, awaitedMembers, created);
+  }
+
+  observeCombinator(
+    native: Combinator,
+    constructor: PromiseConstructor,
+    values: readonly unknown[],
+    name: CombinatorName,
+    declared?: readonly unknown[],
+  ): Promise<unknown> {
+    if (declared !== undefined) {
+      if (declared.length !== values.length) this.refuseUnsafeCombinator(
+        `parallel Promise.${name} iterated a different set of array members`);
+      for (let i = 0; i < declared.length; i++) {
+        if (declared[i] !== values[i]) this.refuseUnsafeCombinator(
+          `parallel Promise.${name} iterated a different set of array members`);
+      }
+    }
+    // Check before the native combinator reads any unknown `then` getter. A
+    // member with no tracked promise id or owned step has no causal identity
+    // to expand on a later follow-up. This also covers proxy thenables whose
+    // `then` is synthesized by a get trap and has no property descriptor.
+    if (this.refuseUnknownThenable !== undefined) {
+      for (const value of values) {
+        if ((typeof value !== 'object' && typeof value !== 'function') || value === null) continue;
+        if (stepOwners.get(value)?.lifecycle === this || this.graph.idOf(value) !== undefined) continue;
+        const message = `parallel Promise.${name} contains a member with no tracked provenance`;
+        this.refuseUnsafeCombinator(message);
+      }
+    }
+    const { value, created } = this.graph.captureCombinator(() => native.call(constructor, values));
+    this.registerCombinator(values, value, name, created);
+    return value;
+  }
+
+  /** Mark the exact promise returned by a grammar-certified async branch call. */
+  certifyBranchPromise(promise: Promise<unknown>): void {
+    const id = this.graph.idOf(promise);
+    if (id === undefined) {
+      throw new AuthoredFlowExecutionError('step_failed', 'certified branch promise was not tracked');
+    }
+    this.stepGraph.certifyMember(id);
   }
 
   /**
@@ -215,6 +383,43 @@ export class AuthoredFlowLifecycle {
     return this.stepGraph.edgesOf(step);
   }
 
+  /** Predecessors for a new invocation, before it has an operation promise. */
+  invocationPredecessors(): {
+    readonly steps: readonly string[];
+    readonly truncated: boolean;
+    readonly unregisteredAggregate: boolean;
+  } {
+    const frontier = this.stepGraph.predecessorsAt(executionAsyncId());
+    return this.hasInvalidAllSettlement()
+      ? { ...frontier, unregisteredAggregate: true }
+      : frontier;
+  }
+
+  /** A fulfilled all (or settled allSettled) must have waited for every member. */
+  private hasInvalidAllSettlement(): boolean {
+    if (this.invalidAllSettlement) return true;
+    let retained = 0;
+    for (const guard of this.allSettlementGuards) {
+      if (this.graph.isPending(guard.aggregateId)) {
+        this.allSettlementGuards[retained++] = guard;
+        continue;
+      }
+      if ((guard.combinator === 'allSettled' || promiseOutcome(guard.aggregate) === 'fulfilled')
+        && guard.members.some(id => this.graph.isPending(id))) {
+        this.invalidAllSettlement = true;
+        return true;
+      }
+      // Once an honest aggregate has settled, its invariant cannot change.
+    }
+    this.allSettlementGuards.length = retained;
+    return false;
+  }
+
+  /** The observation contract must still be installed when a child is admitted. */
+  combinatorsObserved(): boolean {
+    return combinatorObservers > 0 && parallelPromiseIntrinsicsIntact();
+  }
+
   registerInvocation(
     operation: OperationToken,
     asyncId: number,
@@ -350,6 +555,7 @@ export class AuthoredFlowLifecycle {
     this.invocations.clear();
     this.promiseAllAggregates.clear();
     this.promiseAllGroups.length = 0;
+    this.allSettlementGuards.length = 0;
     this.groupsByInvocation = undefined;
     this.callbackFailures.clear();
     this.activeResolverProbes.length = 0;

package/src/authored-node-entry.ts

@@ -81,6 +81,8 @@ try {
     request.metadata.inputPresent ? request.metadata.input : undefined, {
       getDefinition: loaded.getDefinition, dataDir: request.dataDir,
       flowPath: request.metadata.flowPath, rootRunId: request.rootRunId,
+      executionMode: request.metadata.identityVersion === 2 && request.metadata.executionMode === 'parallel'
+        ? 'parallel' : 'serial',
       extensions: loaded.extensions,
       flowGraph: loaded.graph,
       localAgentStream: request.localAgentStream, signal: controller.signal,

package/src/authored-parallel-body.ts

@@ -0,0 +1,67 @@
+import ts from 'typescript';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { authoredFunctionSource } from './authored-flow-lifecycle.js';
+import { parallelBodySyntaxEligible, unwrapParallelExpression } from './authored-parallel-eligibility.js';
+
+/**
+ * Execute a certified body with its branch-call promises marked at the call
+ * site. A combinator member is not evidence that it is a safe branch: it may
+ * be a hand-built join that resolves from whichever child finishes first.
+ *
+ * The closed grammar has no module captures, so re-evaluating this function
+ * preserves its meaning. Unknown source is refused before the first effect.
+ */
+export function instrumentParallelBody<T extends Function>(
+  body: T,
+  certifyBranch: (promise: Promise<unknown>) => void,
+): T {
+  const source = authoredFunctionSource(body);
+  if (!parallelBodySyntaxEligible(body)) {
+    throw new AuthoredFlowExecutionError('step_failed', 'parallel f.run body lost its source certificate');
+  }
+  const prefix = 'const body = ';
+  const file = ts.createSourceFile('parallel-body.js', `${prefix}${source};`,
+    ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
+  const declaration = file.statements[0];
+  if (!declaration || !ts.isVariableStatement(declaration)) throw new Error('certified body parse failed');
+  const arrow = declaration.declarationList.declarations[0]?.initializer;
+  if (!arrow || !ts.isArrowFunction(arrow) || !ts.isBlock(arrow.body)) throw new Error('certified body changed');
+  const branches = new Set<string>();
+  for (const statement of arrow.body.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const item of statement.declarationList.declarations) {
+      if (ts.isIdentifier(item.name) && item.initializer && ts.isArrowFunction(item.initializer)) {
+        branches.add(item.name.text);
+      }
+    }
+  }
+  const calls: Array<{ start: number; end: number }> = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+      && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'Promise'
+      && node.expression.name.text === 'all' && node.arguments.length === 1) {
+      const members = node.arguments[0];
+      if (members && ts.isArrayLiteralExpression(members)) {
+        for (const outer of members.elements) {
+          if (!ts.isExpression(outer)) continue;
+          const member = unwrapParallelExpression(outer);
+          if (!ts.isCallExpression(member) || member.arguments.length !== 0) continue;
+          const named = ts.isIdentifier(member.expression) && branches.has(member.expression.text);
+          const inline = ts.isParenthesizedExpression(member.expression)
+            && ts.isArrowFunction(member.expression.expression);
+          if (named || inline) calls.push({ start: outer.getStart(file) - prefix.length,
+            end: outer.getEnd() - prefix.length });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(arrow);
+  let instrumented = source;
+  for (const { start, end } of calls.sort((left, right) => right.start - left.start)) {
+    instrumented = `${instrumented.slice(0, start)}__certifyParallelBranch(${instrumented.slice(start, end)})${instrumented.slice(end)}`;
+  }
+  const factory = new Function('__certifyParallelBranch', `return (${instrumented});`) as
+    (record: (promise: Promise<unknown>) => Promise<unknown>) => T;
+  return factory((promise) => { certifyBranch(promise); return promise; });
+}

package/src/authored-parallel-eligibility.ts

@@ -0,0 +1,245 @@
+import ts from 'typescript';
+import { authoredFunctionSource } from './authored-flow-lifecycle.js';
+
+const reservedCertifier = '__certifyParallelBranch';
+
+/** Keep admission and call-site instrumentation in agreement on parentheses. */
+export function unwrapParallelExpression(node: ts.Expression): ts.Expression {
+  return ts.isParenthesizedExpression(node) ? unwrapParallelExpression(node.expression) : node;
+}
+
+/** A closed grammar for deterministic Promise.all branches. Unknown bodies stay serial. */
+export function parallelRunEligible(body: Function, moduleSource: string): boolean {
+  // Promise.all is intercepted only when `Promise` resolves to the intrinsic.
+  // Function.toString cannot see a module-level lexical binding, so inspect
+  // the complete source before using the body's narrower grammar.
+  const bodySource = authoredFunctionSource(body);
+  return moduleUsesIntrinsicPromise(moduleSource, bodySource) && parallelBodySyntaxEligible(body);
+}
+
+/** Independently re-check the closed body grammar at execution time. */
+export function parallelBodySyntaxEligible(body: Function): boolean {
+  const bodySource = authoredFunctionSource(body);
+  const file = ts.createSourceFile('authored-body.js', `const body = ${bodySource};`,
+    ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
+  if (file.statements.length !== 1) return false;
+  const declaration = file.statements[0];
+  if (!declaration || !ts.isVariableStatement(declaration)) return false;
+  const expression = declaration.declarationList.declarations[0]?.initializer;
+  // Function expressions can obtain the context through `arguments[0]`.
+  if (expression === undefined || !ts.isArrowFunction(expression) || !ts.isBlock(expression.body)
+    || expression.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) !== true) return false;
+  const parameter = expression.parameters[0]?.name;
+  if (parameter === undefined || !ts.isIdentifier(parameter) || expression.parameters.length !== 1) return false;
+  const context = parameter.text;
+  if (['Promise', 'globalThis', 'global'].includes(context)) return false;
+  // The instrumented body is re-evaluated with a private callback parameter.
+  // A lexical binding or reference with that spelling could capture it.
+  let namesCertifier = false;
+  const checkCertifierName = (node: ts.Node): void => {
+    if (ts.isIdentifier(node) && node.text === reservedCertifier) namesCertifier = true;
+    ts.forEachChild(node, checkCertifierName);
+  };
+  checkCertifierName(expression);
+  if (namesCertifier) return false;
+  const branches = new Map<string, ts.ArrowFunction>();
+  const rootValues = new Set<string>();
+  let groups = 0;
+  let runs = 0;
+
+  const unwrap = unwrapParallelExpression;
+  const method = (node: ts.Expression, owner: string, name: string): node is ts.CallExpression => {
+    const value = unwrap(node);
+    return ts.isCallExpression(value) && ts.isPropertyAccessExpression(value.expression)
+      && ts.isIdentifier(value.expression.expression) && value.expression.expression.text === owner
+      && value.expression.name.text === name;
+  };
+  const pure = (node: ts.Expression, values: ReadonlySet<string>): boolean => {
+    const value = unwrap(node);
+    if (ts.isStringLiteral(value) || ts.isNumericLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+      || value.kind === ts.SyntaxKind.TrueKeyword || value.kind === ts.SyntaxKind.FalseKeyword
+      || value.kind === ts.SyntaxKind.NullKeyword) return true;
+    if (ts.isIdentifier(value)) return values.has(value.text);
+    if (ts.isTemplateExpression(value)) return value.templateSpans.every(span => pure(span.expression, values));
+    if (ts.isPrefixUnaryExpression(value)) return [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken,
+      ts.SyntaxKind.ExclamationToken].includes(value.operator) && pure(value.operand, values);
+    if (ts.isBinaryExpression(value)) return [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken,
+      ts.SyntaxKind.AsteriskToken, ts.SyntaxKind.SlashToken, ts.SyntaxKind.EqualsEqualsEqualsToken,
+      ts.SyntaxKind.ExclamationEqualsEqualsToken, ts.SyntaxKind.LessThanToken,
+      ts.SyntaxKind.GreaterThanToken].includes(value.operatorToken.kind)
+      && pure(value.left, values) && pure(value.right, values);
+    if (ts.isConditionalExpression(value)) return pure(value.condition, values)
+      && pure(value.whenTrue, values) && pure(value.whenFalse, values);
+    if (ts.isElementAccessExpression(value)) return value.argumentExpression !== undefined
+      && pure(value.expression, values) && pure(value.argumentExpression, values);
+    if (ts.isPropertyAccessExpression(value)) return pure(value.expression, values);
+    if (ts.isArrayLiteralExpression(value)) return value.elements.every(element =>
+      ts.isExpression(element) && pure(element, values));
+    if (ts.isObjectLiteralExpression(value)) return value.properties.every(property =>
+      ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
+      && pure(property.initializer, values));
+    return false;
+  };
+  const run = (node: ts.Expression, values: ReadonlySet<string>): boolean => {
+    const value = unwrap(node);
+    if (!method(value, context, 'run') || value.arguments.length < 1 || value.arguments.length > 2
+      || !value.arguments.every(argument => pure(argument, values))) return false;
+    runs++;
+    return true;
+  };
+  const group = (node: ts.Expression, values: ReadonlySet<string>, depth: number): boolean => {
+    const value = unwrap(node);
+    if (!method(value, 'Promise', 'all') || value.arguments.length !== 1 || depth > 4) return false;
+    groups++;
+    const members = value.arguments[0]!;
+    if (ts.isArrayLiteralExpression(members)) {
+      if (members.elements.length < 2) return false;
+      return members.elements.every(member => {
+        if (!ts.isExpression(member)) return false;
+        if (run(member, values)) return true;
+        const call = unwrap(member);
+        if (depth === 0 && ts.isCallExpression(call) && ts.isIdentifier(call.expression)
+          && call.arguments.length === 0 && branches.has(call.expression.text)) {
+          return branch(branches.get(call.expression.text)!, depth + 1);
+        }
+        if (depth === 0 && ts.isCallExpression(call) && call.arguments.length === 0
+          && ts.isParenthesizedExpression(call.expression) && ts.isArrowFunction(call.expression.expression)) {
+          return branch(call.expression.expression, depth + 1);
+        }
+        return false;
+      });
+    }
+    return false;
+  };
+  const awaitStep = (node: ts.Expression, values: ReadonlySet<string>, depth: number): boolean => {
+    const value = unwrap(node);
+    if (!ts.isAwaitExpression(value)) return false;
+    return run(value.expression, values) || group(value.expression, values, depth);
+  };
+  const statements = (block: ts.Block, values: Set<string>, depth: number): boolean => {
+    for (const statement of block.statements) {
+      if (ts.isExpressionStatement(statement)) {
+        if (awaitStep(statement.expression, values, depth)) continue;
+        const value = unwrap(statement.expression);
+        if (depth === 0 && method(value, context, 'done') && value.arguments.length >= 1
+          && value.arguments.every(argument => pure(argument, values))
+          && statement === block.statements[block.statements.length - 1]) continue;
+        return false;
+      }
+      if (ts.isReturnStatement(statement) && depth > 0 && statement.expression !== undefined
+        && awaitStep(statement.expression, values, depth)) continue;
+      if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0) return false;
+      for (const item of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(item.name) || item.initializer === undefined) return false;
+        if (['Promise', 'globalThis', 'global'].includes(item.name.text)) return false;
+        if (depth === 0 && ts.isArrowFunction(item.initializer)) {
+          if (branches.has(item.name.text) || item.initializer.parameters.length !== 0
+            || item.initializer.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) !== true
+            ) return false;
+          branches.set(item.name.text, item.initializer);
+          continue;
+        }
+        if (!awaitStep(item.initializer, values, depth)) return false;
+        values.add(item.name.text);
+      }
+    }
+    return true;
+  };
+  const branch = (arrow: ts.ArrowFunction, depth: number): boolean => {
+    if (arrow.parameters.length !== 0) return false;
+    const before = runs;
+    const valid = ts.isBlock(arrow.body) ? statements(arrow.body, new Set(rootValues), depth)
+      : awaitStep(arrow.body, rootValues, depth);
+    // An empty async branch creates a join with no causal step predecessor.
+    return valid && runs > before;
+  };
+
+  if (!statements(expression.body, rootValues, 0)) return false;
+  return groups > 0 && runs > 0;
+}
+
+/** Reject any source that can change what a free `Promise` identifier means. */
+function moduleUsesIntrinsicPromise(source: string, bodySource: string): boolean {
+  const file = ts.createSourceFile('authored-module.ts', source, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TS);
+  if (((file as ts.SourceFile & { parseDiagnostics?: readonly ts.Diagnostic[] }).parseDiagnostics?.length ?? 0) > 0) {
+    return false;
+  }
+  // Top-level code can alter the constructor or its methods without binding
+  // the name. Leave these modules on the established serial scheduler too.
+  const touchesPromiseOutsideDefinition = (node: ts.Node): boolean => {
+    if (ts.isIdentifier(node) && ['Promise', 'globalThis', 'global'].includes(node.text)) return true;
+    return ts.forEachChild(node, touchesPromiseOutsideDefinition) === true;
+  };
+  let definesDefaultBody = false;
+  let importsSurfaceFlow = false;
+  for (const statement of file.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      // Imports can execute code before the body starts. Only the direct,
+      // immutable Surface binding can certify the exported body's identity.
+      if (statement.moduleSpecifier.getText(file) !== "'@relayflows/surface'"
+        && statement.moduleSpecifier.getText(file) !== '"@relayflows/surface"') return false;
+      const bindings = statement.importClause?.namedBindings;
+      if (statement.importClause?.name !== undefined || bindings === undefined
+        || !ts.isNamedImports(bindings) || bindings.elements.length !== 1
+        || bindings.elements[0]?.name.text !== 'flow'
+        || bindings.elements[0]?.propertyName !== undefined || importsSurfaceFlow) return false;
+      importsSurfaceFlow = true;
+      continue;
+    }
+    if (ts.isExportAssignment(statement)) {
+      // Only the final body argument is allowed to mention Promise.all. Do
+      // not let an expression around flow() mutate Promise while we skip it.
+      const call = statement.expression;
+      if (statement.isExportEquals || !ts.isCallExpression(call)
+        || !ts.isIdentifier(call.expression) || call.expression.text !== 'flow') return false;
+      const args = call.arguments;
+      if (args.length !== 2 || !ts.isStringLiteral(args[0]!)) return false;
+      if (!ts.isArrowFunction(args[args.length - 1]!)) return false;
+      if (args[args.length - 1]!.getText(file) !== bodySource) return false;
+      if (args.slice(0, -1).some(touchesPromiseOutsideDefinition)) return false;
+      if (definesDefaultBody) return false;
+      definesDefaultBody = true;
+      continue;
+    }
+    // The certified body cannot use module captures. Other top-level code is
+    // unnecessary for it and may schedule a later mutation through an alias.
+    return false;
+  }
+  const forbidden = new Set(['Promise', 'globalThis']);
+  const bindsForbidden = (name: ts.BindingName): boolean => ts.isIdentifier(name)
+    ? forbidden.has(name.text)
+    : name.elements.some(element => ts.isBindingElement(element) && bindsForbidden(element.name));
+  const isGlobalPromise = (node: ts.Node): boolean => {
+    if (ts.isIdentifier(node)) return forbidden.has(node.text);
+    if (ts.isPropertyAccessExpression(node)) return ts.isIdentifier(node.expression)
+      && node.expression.text === 'globalThis' && node.name.text === 'Promise';
+    return ts.isElementAccessExpression(node) && ts.isIdentifier(node.expression)
+      && node.expression.text === 'globalThis' && ts.isStringLiteral(node.argumentExpression)
+      && node.argumentExpression.text === 'Promise';
+  };
+  let unsafe = false;
+  const visit = (node: ts.Node): void => {
+    if (unsafe) return;
+    if ((ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isBindingElement(node))
+      && bindsForbidden(node.name)) unsafe = true;
+    if ((ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)
+      || ts.isClassDeclaration(node) || ts.isClassExpression(node)
+      || ts.isEnumDeclaration(node) || ts.isImportEqualsDeclaration(node)
+      || ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node))
+      && node.name !== undefined && forbidden.has(node.name.text)) unsafe = true;
+    if (ts.isImportClause(node) && node.name !== undefined && forbidden.has(node.name.text)) unsafe = true;
+    if (ts.isNamespaceImport(node) && forbidden.has(node.name.text)) unsafe = true;
+    if (ts.isImportSpecifier(node) && forbidden.has(node.name.text)) unsafe = true;
+    if (ts.isBinaryExpression(node)
+      && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment
+      && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment
+      && isGlobalPromise(node.left)) unsafe = true;
+    if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node))
+      && isGlobalPromise(node.operand)) unsafe = true;
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  // The body may come from another module, where a free Promise name can be
+  // shadowed without appearing in this source. In that case use serial IDs.
+  return importsSurfaceFlow && definesDefaultBody && !unsafe;
+}