@relayflows/sdk 2.0.51 → 2.0.53

package/src/authored-parallel-eligibility.ts

@@ -0,0 +1,296 @@
+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 certifiedModuleBody(moduleSource, bodySource) !== undefined && parallelBodySyntaxEligible(body);
+}
+
+/**
+ * Match the body Node actually loaded against the same type-stripped source its
+ * TypeScript loader serves. First certify the original bytes: transforming
+ * away a declaration must never make an unsafe module appear closed.
+ */
+export async function parallelLoadedBodyEligible(
+  body: Function, moduleSource: string, sourceUrl: string,
+  mode: 'strip' | 'transform',
+): Promise<boolean> {
+  if (!parallelPinnedSourceEligible(moduleSource)) return false;
+  const { stripTypeScriptTypes } = await import('node:module') as unknown as {
+    stripTypeScriptTypes?: (source: string, options: { mode: 'strip' | 'transform'; sourceUrl: string }) => string;
+  };
+  if (typeof stripTypeScriptTypes !== 'function') return false;
+  // The pinned loader suppresses this one Node warning on its own thread.
+  // Recomputing the text here happens on the main thread; suppress only this
+  // call's warning and restore the original writer before yielding again.
+  const emitWarning = process.emitWarning;
+  let transformed: string;
+  try {
+    process.emitWarning = ((warning: string | Error, ...rest: unknown[]) => {
+      if (rest[0] === 'ExperimentalWarning' && String(warning).startsWith('stripTypeScriptTypes')) return;
+      (emitWarning as (...args: unknown[]) => void).call(process, warning, ...rest);
+    }) as typeof process.emitWarning;
+    transformed = stripTypeScriptTypes(moduleSource, { mode, sourceUrl });
+  } catch {
+    // A loader mode unavailable in this Node version cannot certify a body.
+    return false;
+  } finally {
+    process.emitWarning = emitWarning;
+  }
+  return parallelRunEligible(body, transformed);
+}
+
+/**
+ * The compiled Bun CLI owns the root lease, but the pinned source is executed
+ * by its embedded Node child. Bun reformats function toString output, so its
+ * in-memory body cannot be compared byte-for-byte with the source. Certify
+ * the closed source module instead; the Node child loads those hash-pinned
+ * bytes and checks exact body/source identity and grammar before any child starts.
+ */
+export function parallelPinnedSourceEligible(moduleSource: string): boolean {
+  const bodySource = certifiedModuleBody(moduleSource);
+  return bodySource !== undefined && parallelBodySourceSyntaxEligible(bodySource);
+}
+
+/** Independently re-check the closed body grammar at execution time. */
+export function parallelBodySyntaxEligible(body: Function): boolean {
+  return parallelBodySourceSyntaxEligible(authoredFunctionSource(body));
+}
+
+function parallelBodySourceSyntaxEligible(bodySource: string): boolean {
+  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 certifiedModuleBody(source: string, bodySource?: string): string | undefined {
+  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 undefined;
+  }
+  // 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;
+  let certifiedBody: string | undefined;
+  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 undefined;
+      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 undefined;
+      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 undefined;
+      const args = call.arguments;
+      if (args.length !== 2 || !ts.isStringLiteral(args[0]!)) return undefined;
+      if (!ts.isArrowFunction(args[args.length - 1]!)) return undefined;
+      certifiedBody = args[args.length - 1]!.getText(file);
+      if (bodySource !== undefined && certifiedBody !== bodySource) return undefined;
+      if (args.slice(0, -1).some(touchesPromiseOutsideDefinition)) return undefined;
+      if (definesDefaultBody) return undefined;
+      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 undefined;
+  }
+  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 ? certifiedBody : undefined;
+}

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

@@ -3,10 +3,11 @@ import { loadPinnedAuthoredSource } from './authored-source-authority.js';
 import { assertAuthoredRuntimeAvailable, runAuthoredInNode } from './authored-node-runner.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
 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_PARALLEL_ROOT_KIND_V3, AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
   loadAuthoredFlow,
   type LoadedAuthoredFlow,
@@ -23,6 +24,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 +44,7 @@ export interface AuthoredRootExtension {
 }
 
 export interface AuthoredRootMetadata {
-  readonly kind: typeof ROOT_KIND;
+  readonly kind: typeof ROOT_KIND | typeof AUTHORED_PARALLEL_ROOT_KIND | typeof AUTHORED_PARALLEL_ROOT_KIND_V3;
   readonly flowName: string;
   readonly flowPath: string;
   readonly sourceSha256: string;
@@ -50,6 +52,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 +95,35 @@ export async function executeDurableAuthoredFlow(
     surface: node.surfaceAuthority,
   })));
   const definition = loaded.getDefinition(loaded.handle);
+  let parallelEligible = false;
+  let parallelIneligibleReason: string | undefined;
+  if (loaded.graph.length !== 1) parallelIneligibleReason = 'source_graph';
+  else if ((loaded.extensions?.length ?? 0) !== 0) parallelIneligibleReason = 'extensions';
+  else if (definition.header.budget !== undefined) parallelIneligibleReason = 'shared_budget';
+  else if (!parallelPromiseIntrinsicsIntact()) parallelIneligibleReason = 'runtime_intrinsics';
+  else {
+    // 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 { parallelLoadedBodyEligible, parallelPinnedSourceEligible } = await import('./authored-parallel-eligibility.js');
+    parallelEligible = parallelPromiseIntrinsicsIntact()
+      && (process.versions['bun'] === undefined
+        // Native imports strip by default, or transform with Node's opt-in
+        // flag. Require exact identity with one of those loader outputs.
+        ? await parallelLoadedBodyEligible(definition.body, source.toString('utf8'), pathToFileURL(loaded.sourcePath).href, 'strip')
+          || await parallelLoadedBodyEligible(definition.body, source.toString('utf8'), pathToFileURL(loaded.sourcePath).href, 'transform')
+        : parallelPinnedSourceEligible(source.toString('utf8')));
+    if (!parallelEligible) parallelIneligibleReason = parallelPromiseIntrinsicsIntact()
+      ? 'source_certificate' : 'runtime_intrinsics';
+  }
+  // Opt-in operator diagnostic only: changing root metadata would change its
+  // admission spec hash and could disrupt a 2.0.52 in-flight serial root.
+  if (parallelIneligibleReason !== undefined && process.env['FLOWS_PARALLEL_DEBUG'] === '1') {
+    process.stderr.write(`[flows] parallel f.run admission: serial (${parallelIneligibleReason})\n`);
+  }
+  const executionMode = parallelEligible ? 'parallel' : 'serial';
   const metadata: AuthoredRootMetadata = Object.freeze({
-    kind: ROOT_KIND,
+    kind: executionMode === 'parallel' ? AUTHORED_PARALLEL_ROOT_KIND_V3 : ROOT_KIND,
     flowName: definition.name,
     flowPath: loaded.sourcePath,
     sourceSha256: sha256(source),
@@ -99,6 +132,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 +156,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 +187,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 +220,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 +236,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 +416,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 +665,11 @@ 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_V3)
+    && (root.kind === 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 +677,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 {