@relayflows/sdk 2.0.51 → 2.0.52

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

package/src/authored-promise-graph.ts

@@ -30,12 +30,15 @@ export class AuthoredPromiseGraph {
   private readonly triggers = new Map<number, number>();
   private readonly creationContexts = new Map<number, number>();
   private readonly resolutionCauses = new Map<number, number>();
+  /** Promises attributed only when another promise's reaction resolved them. */
+  private readonly adoptedFromResolvingContext = new Set<number>();
   private readonly promiseIds = new WeakMap<object, number>();
   private readonly handles = new Map<number, Promise<unknown>>();
   private readonly unattributedChildren = new Map<number, number[]>();
   private readonly attributedRoots = new Map<number, number>();
   private readonly roots = new Set<number>();
   private readonly pending = new Set<number>();
+  private readonly combinatorCaptures: Set<number>[] = [];
   private dependencyCache: { readonly start: number; readonly found: ReadonlySet<number>; readonly version: number } | undefined;
   /** Bumped by every graph change, so derived answers can be cached between changes. */
   private changes = 0;
@@ -52,6 +55,7 @@ export class AuthoredPromiseGraph {
         this.triggers.set(asyncId, triggerAsyncId);
         this.creationContexts.set(asyncId, executionAsyncId());
         this.promiseIds.set(resource, asyncId);
+        for (const capture of this.combinatorCaptures) capture.add(asyncId);
         this.handles.set(asyncId, resource as Promise<unknown>);
         this.pending.add(asyncId);
         const root = this.roots.has(triggerAsyncId)
@@ -77,6 +81,7 @@ export class AuthoredPromiseGraph {
         // success. Measured; see ops/probes/pr134-repair-0903/combinators.mjs.
         const adopted = this.attributedRoots.get(cause);
         if (adopted !== undefined) {
+          this.adoptedFromResolvingContext.add(asyncId);
           this.attribute(asyncId, adopted);
           return;
         }
@@ -100,6 +105,18 @@ export class AuthoredPromiseGraph {
     return this.promiseIds.get(value);
   }
 
+  isPending(asyncId: number): boolean {
+    return this.pending.has(asyncId);
+  }
+
+  /** The intrinsic creates per-member reaction promises as well as its aggregate. */
+  captureCombinator<T>(call: () => T): { readonly value: T; readonly created: ReadonlySet<number> } {
+    const created = new Set<number>();
+    this.combinatorCaptures.push(created);
+    try { return { value: call(), created }; }
+    finally { this.combinatorCaptures.pop(); }
+  }
+
   /** Mark a promise whose descendants belong to an authored operation. */
   registerRoot(asyncId: number): void {
     if (asyncId <= 0 || this.roots.has(asyncId)) return;
@@ -145,6 +162,22 @@ export class AuthoredPromiseGraph {
     return causes;
   }
 
+  /**
+   * A promise created directly in one async context but settled in another
+   * can be a join. Its resolution edge names only the settling member, so a
+   * frontier may use it only when a combinator registered all members.
+   */
+  hasUnobservedJoinShape(asyncId: number): boolean {
+    const trigger = this.triggers.get(asyncId);
+    const resolution = this.resolutionCauses.get(asyncId);
+    return trigger !== undefined && trigger === this.creationContexts.get(asyncId)
+      && resolution !== undefined && resolution !== trigger;
+  }
+
+  wasAdoptedFromResolvingContext(asyncId: number): boolean {
+    return this.adoptedFromResolvingContext.has(asyncId);
+  }
+
   dependsOn(descendant: number, ancestor: number): boolean {
     return this.dependenciesOf(descendant).has(ancestor);
   }
@@ -167,11 +200,13 @@ export class AuthoredPromiseGraph {
     this.triggers.clear();
     this.creationContexts.clear();
     this.resolutionCauses.clear();
+    this.adoptedFromResolvingContext.clear();
     this.handles.clear();
     this.unattributedChildren.clear();
     this.attributedRoots.clear();
     this.roots.clear();
     this.pending.clear();
+    this.combinatorCaptures.length = 0;
     this.dependencyCache = undefined;
   }
 

package/src/authored-root-readback.ts

@@ -3,7 +3,6 @@ import type { AuthoredFlowExecutionResult } from './authored-flow-executor.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 import { JournalFrameError, JournalProtocolError, type JournalClient } from './journal-client.js';
-import type { RunOutcome } from './protocol.js';
 
 /*
  * Reading an authored root back from its journal, and what a failed read
@@ -44,7 +43,7 @@ export async function rootStepIfPresent(journal: JournalClient, runId: string):
  * it back is interrupted, the outcome is still known: say so, rather than
  * recasting a finished run as resumable.
  */
-export function completedResult(journal: JournalClient, outcome: RunOutcome, rootRunId: string): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+export function completedResult(journal: JournalClient, rootRunId: string): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
   return completedRootResult(journal, rootRunId).catch(error => {
     // A bad frame or a journal with no stored result is a definite fact; any
     // other failure — interrupted, canceled, or a daemon-side read error such

package/src/authored-root.ts

@@ -6,7 +6,7 @@ import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { executeAuthoredFlow, type AuthoredFlowExecutionResult, type AuthoredFlowSuspendedResult } from './authored-flow-executor.js';
-import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
+import { AUTHORED_PARALLEL_ROOT_KIND, AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
   loadAuthoredFlow,
   type LoadedAuthoredFlow,
@@ -23,6 +23,7 @@ import { helperReceiptWaitId, releaseHelperReceiptWaits } from './helper-park.js
 import { readSubscriptionPark } from './authored-subscription-park.js';
 import { localAgentCredentialEnvironment } from './local-agent-environment.js';
 import { completedResult, rootKernelStep, rootStepIfPresent } from './authored-root-readback.js';
+import { parallelPromiseIntrinsicsIntact } from './authored-flow-lifecycle.js';
 
 export type DurableAuthoredFlowResult =
   | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
@@ -42,7 +43,7 @@ export interface AuthoredRootExtension {
 }
 
 export interface AuthoredRootMetadata {
-  readonly kind: typeof ROOT_KIND;
+  readonly kind: typeof ROOT_KIND | typeof AUTHORED_PARALLEL_ROOT_KIND;
   readonly flowName: string;
   readonly flowPath: string;
   readonly sourceSha256: string;
@@ -50,6 +51,10 @@ export interface AuthoredRootMetadata {
   readonly sources: readonly AuthoredRootSourceAuthority[];
   /** Plugin-level provenance in lock order; empty when the project declares none. */
   readonly extensions: readonly AuthoredRootExtension[];
+  /** Absent on roots admitted before causal identities existed. */
+  readonly identityVersion?: 2;
+  /** Immutable admission choice; serial uses the 2.0.50 child identity contract. */
+  readonly executionMode?: 'serial' | 'parallel';
   readonly localAgentStream?: string;
   readonly inputPresent: boolean;
   readonly input?: unknown;
@@ -89,8 +94,19 @@ export async function executeDurableAuthoredFlow(
     surface: node.surfaceAuthority,
   })));
   const definition = loaded.getDefinition(loaded.handle);
+  let parallelEligible = false;
+  if (loaded.graph.length === 1 && (loaded.extensions?.length ?? 0) === 0
+    && definition.header.budget === undefined && parallelPromiseIntrinsicsIntact()) {
+    // The parser is needed only for an authored run, never for an ordinary
+    // CLI check or watch reload. Recheck intrinsics after the async import;
+    // author code could have replaced them while it was loading.
+    const { parallelRunEligible } = await import('./authored-parallel-eligibility.js');
+    parallelEligible = parallelPromiseIntrinsicsIntact()
+      && parallelRunEligible(definition.body, source.toString('utf8'));
+  }
+  const executionMode = parallelEligible ? 'parallel' : 'serial';
   const metadata: AuthoredRootMetadata = Object.freeze({
-    kind: ROOT_KIND,
+    kind: executionMode === 'parallel' ? AUTHORED_PARALLEL_ROOT_KIND : ROOT_KIND,
     flowName: definition.name,
     flowPath: loaded.sourcePath,
     sourceSha256: sha256(source),
@@ -99,6 +115,8 @@ export async function executeDurableAuthoredFlow(
     extensions: Object.freeze((loaded.extensions ?? []).map(extension => Object.freeze({
       name: extension.name, digest: extension.digest, ref: extension.ref,
     }))),
+    identityVersion: 2,
+    executionMode,
     ...(options.localAgentStream === undefined ? {} : { localAgentStream: options.localAgentStream }),
     inputPresent: input !== undefined,
     ...(input === undefined ? {} : { input: jsonSnapshot(input, 'authored root input') }),
@@ -121,7 +139,7 @@ export async function executeDurableAuthoredFlow(
     options.lifecycle?.onRunReceipt?.({ runId: outcome.run_id, flow: definition.name });
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
-      return await completedResult(journal, outcome, outcome.run_id);
+      return await completedResult(journal, outcome.run_id);
     }
     assertRootCanDispatch(outcome);
     await releaseHelperReceiptWaits(journal, outcome.run_id);
@@ -152,11 +170,23 @@ export async function resumeDurableAuthoredFlow(
 ): Promise<DurableAuthoredFlowResult | undefined> {
   const metadata = await readAuthoredRootMetadata(journal, rootRunId);
   if (metadata === undefined) return undefined;
-  assertAuthoredRuntimeAvailable();
-  const loaded = await loadPinnedAuthoredSource(metadata);
   if (metadata.localAgentStream !== options.localAgentStream) {
     throw new Error('authored root local agent surface mismatch');
   }
+  const completed = await completedParallelRootOrAssertRuntime(metadata, rootRunId, journal);
+  if (completed !== undefined) {
+    options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
+    return completed;
+  }
+  assertAuthoredRuntimeAvailable();
+  const loaded = await loadPinnedAuthoredSource(metadata);
+  // Source loading itself can alter a process-wide intrinsic. Refuse before
+  // run.resume dispatches a pinned parallel root in that environment.
+  const completedAfterLoad = await completedParallelRootOrAssertRuntime(metadata, rootRunId, journal);
+  if (completedAfterLoad !== undefined) {
+    options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
+    return completedAfterLoad;
+  }
   const stream = rootStreamFromMetadata(await rootKernelStep(journal, rootRunId));
   const peer = journal.createPeer();
   await peer.connect();
@@ -173,7 +203,7 @@ export async function resumeDurableAuthoredFlow(
     options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
-      return await completedResult(journal, outcome, rootRunId);
+      return await completedResult(journal, rootRunId);
     }
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
@@ -189,6 +219,22 @@ export async function resumeDurableAuthoredFlow(
   }
 }
 
+async function completedParallelRootOrAssertRuntime(
+  metadata: AuthoredRootMetadata, rootRunId: string, journal: JournalClient,
+): Promise<DurableAuthoredFlowResult | undefined> {
+  if (metadata.identityVersion !== 2 || metadata.executionMode !== 'parallel'
+    || parallelPromiseIntrinsicsIntact()) return undefined;
+  // A completed root has nothing left to dispatch. A read-only snapshot avoids
+  // refusing it under a preload while preserving the pre-dispatch guard for
+  // an active root. Readback still uses the journaled authored verdict.
+  const snapshot = await journal.runGet(rootRunId);
+  if (snapshot.status === 'completed') return completedResult(journal, rootRunId);
+  const error = new AuthoredFlowExecutionError('unsafe_parallel_runtime',
+    `pinned parallel root ${rootRunId} cannot resume while a Promise or Array intrinsic is replaced or a Node preload is active. The run remains resumable in a clean process.`);
+  error.rootRunId = rootRunId;
+  throw error;
+}
+
 /**
  * A root parked on an unanswered `f.human` will not be dispatched: the
  * kernel holds it in `needs_human` until `event.emit` closes the wait. Report
@@ -353,6 +399,8 @@ async function driveRoot(
             ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
             ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
             rootRunId: dispatch.run_id,
+            executionMode: metadata.identityVersion === 2 && metadata.executionMode === 'parallel'
+              ? 'parallel' : 'serial',
             extensions: loaded.extensions,
             flowGraph: loaded.graph,
             ...options.lifecycle,
@@ -600,7 +648,10 @@ function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
   const root = value as Partial<AuthoredRootMetadata>;
   const surface = root.surface as Partial<SurfaceModuleAuthority> | undefined;
   const sources = root.sources;
-  return root.kind === ROOT_KIND && typeof root.flowName === 'string'
+  return (root.kind === ROOT_KIND || root.kind === AUTHORED_PARALLEL_ROOT_KIND)
+    && (root.kind !== AUTHORED_PARALLEL_ROOT_KIND
+      || (root.identityVersion === 2 && root.executionMode === 'parallel'))
+    && typeof root.flowName === 'string'
     && typeof root.flowPath === 'string' && /^[a-f0-9]{64}$/.test(root.sourceSha256 ?? '')
     && typeof root.inputPresent === 'boolean' && surface?.packageName === '@relayflows/surface'
     && typeof surface.version === 'string' && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
@@ -608,7 +659,9 @@ function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
     && Array.isArray(sources) && sources.length > 0 && sources.every(isRootSourceAuthority)
     && (root.extensions === undefined || (Array.isArray(root.extensions) && root.extensions.every(isRootExtension)))
     && (root.localAgentStream === undefined
-      || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream));
+      || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream))
+    && ((root.identityVersion === undefined && root.executionMode === undefined)
+      || (root.identityVersion === 2 && (root.executionMode === 'serial' || root.executionMode === 'parallel')));
 }
 
 function isRootExtension(value: unknown): value is AuthoredRootExtension {

package/src/authored-step-graph.ts

@@ -32,14 +32,16 @@ import { MAX_AFTER, displayLabel, type AuthoredStepEdges } from './authored-step
  * body walks a few nodes per step. A walk that still exceeds `walkLimit` stops
  * and says so (`afterTruncated`) rather than guessing silently.
  *
- * This is observational metadata: it never gates execution, and it changes no
- * step id, admission key or resume identity.
+ * Most consumers use this as observational metadata. Parallel f.run follow-up
+ * IDs also use the causal frontier; the executor refuses a truncated frontier
+ * rather than choosing a replay key from incomplete predecessors.
  */
 export const MAX_WALK = 10_000;
 
 interface Frontier {
   readonly steps: readonly string[];
   readonly truncated: boolean;
+  readonly unregisteredAggregate: boolean;
 }
 
 interface StepNode {
@@ -62,6 +64,7 @@ const EXPANDS_ON: Readonly<Record<Combinator, Outcome | 'always' | undefined>> =
 
 interface Aggregate {
   readonly promise: Promise<unknown>;
+  readonly combinator: Combinator;
   /** Cached once settled: a settled promise never changes state. */
   outcome?: Outcome;
   readonly expandsOn: Outcome | 'always';
@@ -71,6 +74,10 @@ interface Aggregate {
 export class AuthoredStepGraph {
   private readonly stepPromises = new Map<number, string>();
   private readonly aggregates = new Map<number, Aggregate>();
+  private readonly registeredAggregates = new Set<number>();
+  private readonly registeredCombinatorInternals = new Set<number>();
+  private readonly certifiedMembers = new Set<number>();
+  private readonly unsafeAggregates = new Set<number>();
   private readonly contexts = new Map<number, Frontier>();
   private readonly nodes = new Map<string, StepNode>();
   private readonly edges = new Map<string, AuthoredStepEdges>();
@@ -78,6 +85,7 @@ export class AuthoredStepGraph {
   constructor(
     private readonly causesOf: (asyncId: number) => readonly number[],
     private readonly walkLimit = MAX_WALK,
+    private readonly unobservedJoinShape: (asyncId: number) => boolean = () => false,
   ) {}
 
   /** A combinator's aggregate and its members, for expansion once it settles. */
@@ -86,10 +94,19 @@ export class AuthoredStepGraph {
     promise: Promise<unknown>,
     combinator: Combinator,
     members: readonly number[],
+    created: ReadonlySet<number> = new Set(),
   ): void {
+    this.registeredAggregates.add(aggregateId);
+    for (const id of created) this.registeredCombinatorInternals.add(id);
+    if (combinator === 'race' || combinator === 'any') this.unsafeAggregates.add(aggregateId);
     const expandsOn = EXPANDS_ON[combinator];
     if (expandsOn === undefined || members.length === 0) return;
-    this.aggregates.set(aggregateId, { promise, expandsOn, members });
+    this.aggregates.set(aggregateId, { promise, combinator, expandsOn, members });
+  }
+
+  /** Only direct steps and branch calls proven by the body grammar are safe members. */
+  certifyMember(asyncId: number): void {
+    this.certifiedMembers.add(asyncId);
   }
 
   /**
@@ -119,10 +136,19 @@ export class AuthoredStepGraph {
     return this.edges.get(step);
   }
 
+  /** Causal predecessors of a step being declared in the current async context. */
+  predecessorsAt(contextId: number): Frontier {
+    return this.frontierOf(contextId);
+  }
+
   /** Drop the walk state; recorded edges stay readable for late record writes. */
   release(): void {
     this.stepPromises.clear();
     this.aggregates.clear();
+    this.registeredAggregates.clear();
+    this.registeredCombinatorInternals.clear();
+    this.certifiedMembers.clear();
+    this.unsafeAggregates.clear();
     this.contexts.clear();
     this.nodes.clear();
   }
@@ -132,6 +158,7 @@ export class AuthoredStepGraph {
     if (memo !== undefined) return memo;
     const candidates = new Set<string>();
     let truncated = false;
+    let unregisteredAggregate = false;
     const visited = new Set<number>([start]);
     const queue = [start];
     // Breadth-first, so that a walk cut short by the limit has already found
@@ -143,10 +170,24 @@ export class AuthoredStepGraph {
         candidates.add(step);
         continue;
       }
+      // A join's resolution edge contains only its settling member. In
+      // parallel mode the full member list is safe only if our combinator
+      // observer registered it before the promise settled. The creation and
+      // resolution contexts also catch an unobserved join created after a
+      // previous step, where root-adoption alone cannot detect it.
+      const aggregate = this.aggregates.get(current);
+      const rejectedAll = aggregate?.combinator === 'all'
+        && promiseOutcome(aggregate.promise) === 'rejected';
+      const possibleJoin = this.unsafeAggregates.has(current) || rejectedAll
+        || (this.unobservedJoinShape(current)
+        && !this.registeredAggregates.has(current) && !this.certifiedMembers.has(current)
+        && !this.registeredCombinatorInternals.has(current));
+      unregisteredAggregate ||= possibleJoin;
       const answered = current === start ? undefined : this.contexts.get(current);
       if (answered !== undefined) {
         for (const found of answered.steps) candidates.add(found);
         truncated ||= answered.truncated;
+        unregisteredAggregate ||= answered.unregisteredAggregate;
         continue;
       }
       for (const id of [...this.waitedFor(current), ...this.causesOf(current)]) {
@@ -162,7 +203,11 @@ export class AuthoredStepGraph {
       }
     }
     const reduced = this.reduce(candidates);
-    const frontier = Object.freeze({ steps: reduced.steps, truncated: truncated || reduced.truncated });
+    const frontier = Object.freeze({
+      steps: reduced.steps,
+      truncated: truncated || reduced.truncated,
+      unregisteredAggregate,
+    });
     this.contexts.set(start, frontier);
     return frontier;
   }
@@ -184,7 +229,7 @@ export class AuthoredStepGraph {
    * reduction reads recorded `after` lists; when one it reads is incomplete,
    * a redundant ancestor can survive, and the result says so.
    */
-  private reduce(candidates: ReadonlySet<string>): Frontier {
+  private reduce(candidates: ReadonlySet<string>): Pick<Frontier, 'steps' | 'truncated'> {
     const ordered = [...candidates].sort((a, b) => this.orderOf(a) - this.orderOf(b));
     if (ordered.length <= 1) return { steps: ordered, truncated: false };
     // An ancestor is always registered before its descendant, so nothing

package/src/authored-step-index.ts

@@ -150,7 +150,8 @@ export async function alsoRecord(
  * Fold the root's stream back into one record per authored step.
  *
  * A `completed` record supersedes the `admitted` one for the same step; first
- * admission order is preserved so the index reads in the order the body ran.
+ * admission order is preserved for each step, while different children can
+ * first appear in completion order when they finish concurrently.
  * Records this version does not recognise are skipped rather than trusted.
  */
 export async function readAuthoredStepIndex(