@relayflows/sdk 2.0.51 → 2.0.52

package/src/authored-flow-executor.ts

@@ -1,7 +1,7 @@
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 import { pluginHelpers } from './plugin-loader.js';
 import { runPluginEffect } from './authored-plugin-effect.js';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
 import { runHelperEffect } from './authored-helper-effect.js';
 import { checkSlackHelpers } from './slack-preflight.js';
@@ -55,7 +55,7 @@ import {
   stopAuthoredOperations,
   verifyAuthoredOperations,
 } from './authored-flow-operation.js';
-import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
+import { AuthoredFlowLifecycle, parallelPromiseIntrinsicsIntact } from './authored-flow-lifecycle.js';
 import { AuthoredActivities } from './authored-activity.js';
 import { displayLabel, type AuthoredStepEdges } from './authored-step-index.js';
 import { JournalClient } from './journal-client.js';
@@ -196,6 +196,8 @@ export interface ExecuteAuthoredFlowOptions {
   readonly workerCapacity?: number;
   /** Durable kernel root that owns this body's child admission identities. */
   readonly rootRunId?: string;
+  /** Pinned by the durable root. Legacy roots retain 2.0.50 step identities. */
+  readonly executionMode?: 'serial' | 'parallel';
   /** Installed flow-extension plugins, in lock order, so `f.hook` can AND-compose them. */
   readonly extensions?: readonly LoadedFlowExtension[];
   /**
@@ -287,7 +289,21 @@ export async function executeAuthoredFlow<Input = undefined>(
   const journalSteps: AuthoredFlowJournalStep[] = [];
   const authoredSteps: AuthoredFlowOperation<unknown>[] = [];
   const memoryWrites = new MemoryWriteTracker();
-  const lifecycle = new AuthoredFlowLifecycle();
+  let parallelViolation: AuthoredFlowExecutionError | undefined;
+  let closeParallelSlots: ((reason: unknown) => void) | undefined;
+  let signalParallelFailure: ((reason: unknown) => void) | undefined;
+  const parallelFailure = options.executionMode === 'parallel'
+    ? new Promise<never>((_resolve, reject) => { signalParallelFailure = reject; }) : undefined;
+  // A violation can occur synchronously before the body's promise is returned.
+  // Keep its rejection handled until the body is raced against it below.
+  void parallelFailure?.catch(() => {});
+  const markParallelViolation = (message: string): void => {
+    parallelViolation ??= new AuthoredFlowExecutionError('step_failed', message);
+    closeParallelSlots?.(parallelViolation);
+    signalParallelFailure?.(parallelViolation);
+  };
+  const lifecycle = new AuthoredFlowLifecycle(options.executionMode === 'parallel'
+    ? markParallelViolation : undefined);
   const activities = new AuthoredActivities(journal, options.rootRunId);
   const edgeOverrides = new Map<string, AuthoredStepEdges>();
   const stepEdges = (step: string): AuthoredStepEdges | undefined => {
@@ -301,8 +317,42 @@ export async function executeAuthoredFlow<Input = undefined>(
   let nextStep = 1;
   let requestedCompletion: LoweredCompletionReason | undefined;
   let requestedDetail: string | undefined;
+  let firstBodyTurn = true;
   const qualify = (id: string): string => `${options.stepPrefix ?? ''}${id}`;
-  const nextId = (kind: string): string => qualify(`${kind}-${nextStep++}`);
+  const branchOrdinals = new Map<string, number>();
+  const rejectParallel = (message: string): never => {
+    markParallelViolation(message);
+    throw parallelViolation;
+  };
+  const assertParallelRunOnly = (kind: string): void => {
+    if (options.executionMode === 'parallel') rejectParallel(`parallel f.run body attempted ${kind} before admission`);
+  };
+  const nextId = (kind: string): string => {
+    if (parallelViolation !== undefined) throw parallelViolation;
+    const sequence = nextStep++;
+    if (options.executionMode !== 'parallel') return qualify(`${kind}-${sequence}`);
+    if (kind !== 'run') rejectParallel(`parallel f.run body attempted ${kind} before admission`);
+    if (!lifecycle.combinatorsObserved()) rejectParallel(
+      'cannot assign a replay-stable f.run identity: a Promise intrinsic was replaced');
+    const predecessors = lifecycle.invocationPredecessors();
+    if (predecessors.unregisteredAggregate) rejectParallel(
+      'cannot assign a replay-stable f.run identity: its causal frontier passes through an unregistered aggregate');
+    if (predecessors.truncated) rejectParallel(
+      'cannot assign a replay-stable f.run identity: its causal predecessor graph is truncated');
+    const signature = JSON.stringify([...predecessors.steps].sort());
+    if (predecessors.steps.length === 0) {
+      if (!firstBodyTurn) rejectParallel('parallel f.run had no causal predecessor after the first body turn');
+      return qualify(`run-${sequence}`);
+    }
+    // Each new root pins parallel mode before executing the body. Its
+    // continuations derive their identity only from the causal frontier and
+    // declaration order within that frontier; child lifecycle and completion
+    // order never participate. Legacy roots take the branch above and retain
+    // their original kind-N identities.
+    const ordinal = (branchOrdinals.get(signature) ?? 0) + 1;
+    branchOrdinals.set(signature, ordinal);
+    return qualify(`run-after-${createHash('sha256').update(signature).digest('hex')}-${ordinal}`);
+  };
   const assertHelperAllowed = (provider: string): void => {
     if (options.allowedHelperProviders !== undefined && !options.allowedHelperProviders.has(provider)) {
       throw new AuthoredFlowExecutionError(
@@ -319,7 +369,9 @@ export async function executeAuthoredFlow<Input = undefined>(
       ...(options.signal === undefined ? {} : { signal: options.signal }),
       stepEdges,
     },
+    options.executionMode === 'parallel',
   );
+  closeParallelSlots = lowerDeterministic.stop;
 
   const worker = authoredWorkerRunner(
     definition, journal, flowPath, journalSteps, waitOptions,
@@ -505,6 +557,7 @@ export async function executeAuthoredFlow<Input = undefined>(
 
   const slackRun = options.rootRunId ?? randomUUID();
   function slackOperation<T>(call: SlackCall): Step<T> {
+    assertParallelRunOnly(`slack.${call.verb}`);
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
     assertHelperAllowed(call.provider);
     const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
@@ -535,6 +588,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   const context: Ctx = {
     ...createHelpers(<T>(call: HelperCall): Step<T> => {
       const verb = `${call.provider}.${call.verb}`;
+      assertParallelRunOnly(verb);
       assertOperationAllowed(verb, definition.name, requestedCompletion);
       assertHelperAllowed(call.provider);
       const snapshot = snapshotJsonValue(call, `f.${verb} call`) as unknown as HelperCall;
@@ -564,7 +618,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     }),
     memory: authoredMemory(
       scriptMemoryScope(flowPath, definition.name),
-      () => assertOperationAllowed('memory', definition.name, requestedCompletion),
+      () => { assertParallelRunOnly('memory'); assertOperationAllowed('memory', definition.name, requestedCompletion); },
       definition.header.memory?.script !== false,
       memoryWrites,
       options.rootRunId === undefined ? undefined : journalLearnLedger(journal, options.rootRunId),
@@ -588,6 +642,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       return trackStep(authoredSteps, agentOp);
     },
     on(source, activityOptions) {
+      assertParallelRunOnly('on');
       assertOperationAllowed('on', definition.name, requestedCompletion);
       // Activity ids are root-scoped (`activity-N`); a child's own counter would collide.
       if ((options.dispatchDepth ?? 0) > 0) {
@@ -695,6 +750,7 @@ export async function executeAuthoredFlow<Input = undefined>(
             ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
             ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
             ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
+            ...(options.executionMode === undefined ? {} : { executionMode: options.executionMode }),
             flowGraph: options.flowGraph,
             stepPrefix: `${id}--`,
             dispatchDepth: depth + 1,
@@ -797,7 +853,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       requestedDetail = detail;
     },
     cloud: unsupportedCloud(
-      () => assertOperationAllowed('cloud', definition.name, requestedCompletion),
+      () => { assertParallelRunOnly('cloud'); assertOperationAllowed('cloud', definition.name, requestedCompletion); },
     ),
   };
 
@@ -816,19 +872,34 @@ export async function executeAuthoredFlow<Input = undefined>(
   let bodyFailed = false;
   let bodyFailure: unknown;
   try {
-    const bodyPromise = lifecycle.runBody(() => definition.body(context, input as Input));
-    await bodyPromise;
+    let body = definition.body;
+    if (options.executionMode === 'parallel') {
+      const { instrumentParallelBody } = await import('./authored-parallel-body.js');
+      if (!parallelPromiseIntrinsicsIntact()) rejectParallel(
+        'parallel f.run body lost its Promise or Array intrinsic before execution');
+      body = instrumentParallelBody(body, promise => lifecycle.certifyBranchPromise(promise));
+      queueMicrotask(() => { firstBodyTurn = false; });
+    }
+    const bodyPromise = lifecycle.runBody(() => body(context, input as Input));
+    if (parallelFailure === undefined) await bodyPromise;
+    else await Promise.race([bodyPromise, parallelFailure]);
   } catch (error) {
     bodyFailed = true;
     bodyFailure = error;
   }
+  // A source certificate is a performance admission decision, never a way
+  // for authored try/catch to turn a refused effect into successful output.
+  if (parallelViolation !== undefined) { bodyFailed = true; bodyFailure = parallelViolation; }
   if (bodyFailed) {
+    // Refuse queued work immediately. A slow memory commit must not leave an
+    // admission slot open after the body has already failed.
+    lowerDeterministic.stop(bodyFailure);
+    worker.stop(bodyFailure);
     // An in-flight learn must land or fail before this attempt gives the root
     // back: a re-driven attempt reads the memory-learn stream, and must not
     // race a commit this one is still making.
     await memoryWrites.settle();
     try {
-      worker.stop(bodyFailure);
       await stopAuthoredOperations(authoredSteps, bodyFailure);
       // A durable wait hands execution back to the control plane. Its
       // subscriptions must keep receiving events while no body is running.
@@ -859,10 +930,12 @@ export async function executeAuthoredFlow<Input = undefined>(
       'missing_completion',
       `flow "${definition.name}" returned without done()`,
     );
-    // Same as a failed body: no learn may outlive the attempt that started it.
+    // Close queued admissions before waiting for a learn; the attempt still
+    // waits for every write before handing the root back.
+    lowerDeterministic.stop(missingCompletion);
+    worker.stop(missingCompletion);
     await memoryWrites.settle();
     try {
-      worker.stop(missingCompletion);
       await stopAuthoredOperations(authoredSteps, missingCompletion);
       await activities.closeAll('canceled');
     } finally {
@@ -881,6 +954,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     }
     await verifyAuthoredOperations(definition.name, authoredSteps, lifecycle);
   } catch (error) {
+    lowerDeterministic.stop(error);
     try {
       await activities.closeAll('canceled');
     } finally {

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