@relayflows/sdk 2.0.52 → 2.0.54

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_PARALLEL_ROOT_KIND, 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,
@@ -43,7 +44,7 @@ export interface AuthoredRootExtension {
 }
 
 export interface AuthoredRootMetadata {
-  readonly kind: typeof ROOT_KIND | typeof AUTHORED_PARALLEL_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;
@@ -95,18 +96,34 @@ export async function executeDurableAuthoredFlow(
   })));
   const definition = loaded.getDefinition(loaded.handle);
   let parallelEligible = false;
-  if (loaded.graph.length === 1 && (loaded.extensions?.length ?? 0) === 0
-    && definition.header.budget === undefined && parallelPromiseIntrinsicsIntact()) {
+  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 { parallelRunEligible } = await import('./authored-parallel-eligibility.js');
+    const { parallelLoadedBodyEligible, parallelPinnedSourceEligible } = await import('./authored-parallel-eligibility.js');
     parallelEligible = parallelPromiseIntrinsicsIntact()
-      && parallelRunEligible(definition.body, source.toString('utf8'));
+      && (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: executionMode === 'parallel' ? AUTHORED_PARALLEL_ROOT_KIND : ROOT_KIND,
+    kind: executionMode === 'parallel' ? AUTHORED_PARALLEL_ROOT_KIND_V3 : ROOT_KIND,
     flowName: definition.name,
     flowPath: loaded.sourcePath,
     sourceSha256: sha256(source),
@@ -648,8 +665,9 @@ 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 || root.kind === AUTHORED_PARALLEL_ROOT_KIND)
-    && (root.kind !== AUTHORED_PARALLEL_ROOT_KIND
+  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 ?? '')

package/src/authored-verdict.ts

@@ -21,8 +21,10 @@ import type { JournalEvent } from './journal-reader.js';
 
 /** The `instruction` discriminator `authored-root.ts` writes into the root step. */
 export const AUTHORED_ROOT_KIND = 'relayflows.authored-root.v1';
-/** Older CLIs do not recognize this root and must refuse a parallel rollback. */
+/** Parallel roots admitted before 2.0.53; the 2.0.52 CLI recognizes these. */
 export const AUTHORED_PARALLEL_ROOT_KIND = 'relayflows.authored-root.parallel.v2';
+/** Newly admitted parallel roots must be refused by the 2.0.52 CLI on rollback. */
+export const AUTHORED_PARALLEL_ROOT_KIND_V3 = 'relayflows.authored-root.parallel.v3';
 
 export interface AuthoredVerdict {
   readonly reason: LoweredCompletionReason;
@@ -79,7 +81,8 @@ export function declaresAuthoredRoot(spawned: JournalEvent): boolean {
   if (typeof step['instruction'] !== 'string') return false;
   try {
     const kind = record(JSON.parse(step['instruction']))?.['kind'];
-    return kind === AUTHORED_ROOT_KIND || kind === AUTHORED_PARALLEL_ROOT_KIND;
+    return kind === AUTHORED_ROOT_KIND || kind === AUTHORED_PARALLEL_ROOT_KIND
+      || kind === AUTHORED_PARALLEL_ROOT_KIND_V3;
   } catch {
     return false;
   }

package/src/cloud-signal.ts

@@ -1,18 +1,15 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { CloudFlowError, cloudFetch, cloudRunId, isCloudRecord, resolveCloudConnection,
-  transportError, type CloudConnectionOptions } from './cloud-http.js';
+import { HOSTED_SIGNAL_READ_TOKEN_ENV, holdSignalWait, signalPath as sharedSignalPath,
+  type SignalErrorFactory } from '@relayflows/surface/signals';
+import { CloudFlowError, cloudFetch, isCloudRecord, resolveCloudConnection,
+  type CloudConnectionOptions } from './cloud-http.js';
 
-const SIGNAL_NAME = /^[A-Za-z0-9_-]{1,80}$/u;
 const MAX_BYTES = 4 * 1024;
-const HELD_GET_MS = 25_000;
-const HOSTED_SIGNAL_READ_TOKEN_ENV = 'RELAYFLOW_V2_SIGNAL_READ_TOKEN';
+
+const cloudSignalError: SignalErrorFactory = (code, message, status) => new CloudFlowError(code, message, status);
 
 function signalPath(runId: string, name: string): string {
-  cloudRunId(runId);
-  if (!SIGNAL_NAME.test(name)) {
-    throw new CloudFlowError('invalid_input', 'Signal name must contain only letters, digits, underscores, or hyphens (1–80 characters).');
-  }
-  return `/api/v1/workflows/runs/${runId}/signals/${name}`;
+  return sharedSignalPath(runId, name, cloudSignalError);
 }
 
 /** Store a run-scoped completion. Retrying the same JSON payload is safe. */
@@ -38,73 +35,30 @@ export async function postCloudSignal(
 }
 
 /**
- * Wait on Cloud's held GET. A normally held 204 re-arms immediately. A fast
- * 204 backs off so a proxy or broken server cannot turn this into a hot loop.
+ * Wait on Cloud's held GET. The wire behaviour (validation, held GET, fast-204
+ * backoff, error classification) is `@relayflows/surface/signals`' single
+ * implementation, so the SDK and hosted flows cannot drift. The SDK keeps its
+ * own credential resolution and throws `CloudFlowError`.
  */
 export async function waitForCloudSignal(
   runId: string, name: string, options: CloudConnectionOptions = {},
 ): Promise<unknown> {
-  const path = signalPath(runId, name);
-  const requestTimeout = options.requestTimeoutMs ?? 30_000;
-  if (!Number.isSafeInteger(requestTimeout) || requestTimeout <= HELD_GET_MS) {
-    throw new CloudFlowError('invalid_input', 'Signal requestTimeoutMs must exceed 25 seconds.');
-  }
-  let fast204BackoffMs = 250;
-  for (;;) {
-    options.signal?.throwIfAborted();
-    let connection: { baseUrl: string; token: string };
-    try {
-      connection = await resolveCloudConnection(options);
-    } catch (error) {
-      // The hosted run's read-only credential is only a fallback for waits.
-      // Explicit Cloud credentials and stored logins retain precedence, and
-      // postCloudSignal never sees this token.
-      const hostedToken = process.env[HOSTED_SIGNAL_READ_TOKEN_ENV];
-      if (!(error instanceof CloudFlowError) || error.code !== 'configuration'
-        || error.reason !== 'auth_missing' || options.token !== undefined
-        || process.env['FLOWS_CLOUD_TOKEN'] !== undefined || hostedToken === undefined) throw error;
-      connection = await resolveCloudConnection({ ...options, token: hostedToken });
-    }
-    const { baseUrl, token } = connection;
-    const deadline = AbortSignal.timeout(requestTimeout);
-    const requestStartedAt = performance.now();
-    let response: Response;
-    try {
-      response = await fetch(`${baseUrl}${path}?waitMs=${HELD_GET_MS}`, {
-        method: 'GET',
-        headers: { authorization: `Bearer ${token}` },
-        signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
-        redirect: 'error',
-      });
-    } catch (error) {
-      options.signal?.throwIfAborted();
-      throw transportError(deadline.aborted ? deadline.reason : error);
-    }
-    if (response.status === 204) {
-      if (performance.now() - requestStartedAt < 1_000) {
-        try {
-          await delay(fast204BackoffMs, undefined, { signal: options.signal });
-        } catch (error) {
-          options.signal?.throwIfAborted();
-          throw error;
-        }
-        fast204BackoffMs = Math.min(fast204BackoffMs * 2, 5_000);
-      } else {
-        fast204BackoffMs = 250;
+  return holdSignalWait(runId, name, { signal: options.signal, requestTimeoutMs: options.requestTimeoutMs }, {
+    error: cloudSignalError,
+    sleep: (ms, signal) => delay(ms, undefined, { signal }),
+    connection: async () => {
+      try {
+        return await resolveCloudConnection(options);
+      } catch (error) {
+        // The hosted run's read-only credential is only a fallback for waits.
+        // Explicit Cloud credentials and stored logins retain precedence, and
+        // postCloudSignal never sees this token.
+        const hostedToken = process.env[HOSTED_SIGNAL_READ_TOKEN_ENV];
+        if (!(error instanceof CloudFlowError) || error.code !== 'configuration'
+          || error.reason !== 'auth_missing' || options.token !== undefined
+          || process.env['FLOWS_CLOUD_TOKEN'] !== undefined || hostedToken === undefined) throw error;
+        return resolveCloudConnection({ ...options, token: hostedToken });
       }
-      continue;
-    }
-    if (!response.ok) throw new CloudFlowError('http_error', `Cloud signal wait failed with HTTP ${response.status}.`, response.status);
-    let body: unknown;
-    try { body = await response.json(); }
-    catch (error) {
-      options.signal?.throwIfAborted();
-      if (!(error instanceof SyntaxError)) throw transportError(deadline.aborted ? deadline.reason : error);
-      throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal.');
-    }
-    if (!isCloudRecord(body) || !Object.hasOwn(body, 'payload') || typeof body.acceptedAt !== 'number') {
-      throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal.');
-    }
-    return body.payload;
-  }
+    },
+  });
 }