@relayflows/sdk 2.0.51 → 2.0.53

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(

package/src/authored-verdict.ts

@@ -21,6 +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';
+/** 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;
@@ -76,7 +80,9 @@ export function declaresAuthoredRoot(spawned: JournalEvent): boolean {
   if (step === null || step['id'] !== 'authored-root') return false;
   if (typeof step['instruction'] !== 'string') return false;
   try {
-    return record(JSON.parse(step['instruction']))?.['kind'] === AUTHORED_ROOT_KIND;
+    const kind = record(JSON.parse(step['instruction']))?.['kind'];
+    return kind === AUTHORED_ROOT_KIND || kind === AUTHORED_PARALLEL_ROOT_KIND
+      || kind === AUTHORED_PARALLEL_ROOT_KIND_V3;
   } catch {
     return false;
   }

package/src/authored-worker-step.ts

@@ -19,7 +19,7 @@ import { authoredChildAdmissionKey } from './authored-admission.js';
 import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { LOCAL_AGENT_WORKSPACE } from './local-agent-pins.js';
-import { authoredWorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
+import { authoredWorkerSlots, WorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
 import { validateStepSecrets } from './step-secrets.js';
 
 const AGENT_TIMEOUT = Symbol('declared agent timeout');
@@ -356,8 +356,14 @@ export function authoredWorkerRunner(
 export function authoredDeterministicRunner(
   name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
   context: AuthoredStepContext = {},
+  parallel = false,
 ) {
   const rootRunId = context.rootRunId;
+  // run.start drives a deterministic child to completion before replying. The
+  // daemon reads one connection in order, so sharing the body's connection
+  // would serialize Promise.all. Each admitted child gets its own connection;
+  // this limit bounds both daemon threads and shell commands per authored body.
+  const slots = new WorkerSlots(8);
   // One lowering, two readers. `record` changes what the child run's verdict
   // MEANS, so the reader changes with it; everything before the read — spec,
   // admission key, budget, child index — is deliberately shared, because a
@@ -386,8 +392,10 @@ export function authoredDeterministicRunner(
       });
       return read(outcome);
     };
-    if (terminal) return journal.runStart(spec, undefined, admissionKey).then(consume);
-    return budget.execute(journal, spec, consume, admissionKey);
+    const admit = async () => terminal
+      ? consume(await journal.runStart(spec, undefined, admissionKey, false, parallel))
+      : budget.execute(journal, spec, consume, admissionKey, parallel);
+    return parallel ? slots.run(admit) : admit();
   }
   const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate,
     secrets?: string[]): Promise<string> =>
@@ -398,6 +406,7 @@ export function authoredDeterministicRunner(
     secrets?: string[]): Promise<RecordedRunOutcome> =>
     lower(id, command, false, leaseMs, verification, 'record', secrets,
       outcome => readRecordedOutcome(journal, outcome, id, journalSteps, context));
+  lowerRun.stop = (reason: unknown): void => slots.close(reason);
   return lowerRun;
 }
 

package/src/cli/run.ts

@@ -415,9 +415,11 @@ export async function resumeFlow(
       return { exitCode: 2, report: { ...base, runId, socketPath,
         diagnostics: [{ severity: 'refusal', kind: 'human_influenced_run', message: error.message.replace(/^human_influenced_run: /, '') }] } };
     }
-    if (error instanceof AuthoredFlowExecutionError && error.code === 'unsupported_promise_lifecycle') {
+    if (error instanceof AuthoredFlowExecutionError
+      && (error.code === 'unsafe_parallel_runtime' || error.code === 'unsupported_promise_lifecycle')) {
       return { exitCode: 2, report: { ...base, runId, socketPath,
-        diagnostics: [{ severity: 'refusal', kind: 'invalid_spec', message: error.message }] } };
+        diagnostics: [{ severity: 'refusal',
+          kind: error.code === 'unsafe_parallel_runtime' ? error.code : 'invalid_spec', message: error.message }] } };
     }
     if (error instanceof AuthoredFlowExecutionError
       && (error.code === 'helper_slack.credential_missing' || error.code === 'helper_slack.mount_required'

package/src/failure-kinds.ts

@@ -134,6 +134,8 @@ export const RUN_FAILURE_KINDS = [
   'run_parked',
   'run_declined',
   'run_unavailable',
+  /** A pinned parallel root is still active, but this process cannot safely dispatch it. */
+  'unsafe_parallel_runtime',
   /** A predicate `.gate(fn)` judged false; the verdict is journaled as `<step>.gate`. */
   'gate_failed',
   /** `flows answer` named a wait the run is not asking: unknown, or already answered. */

package/src/journal-client.ts

@@ -135,7 +135,12 @@ export class JournalClient extends JournalConnection {
     reuseFromRunId?: string,
     admissionKey?: string,
     watch = false,
+    isolated = false,
   ): Promise<VerbContract['run.start']['result']> {
+    if (isolated) {
+      if (watch) throw new Error('an isolated run.start cannot keep a watch on its temporary session');
+      return this.runStartIsolated(spec, reuseFromRunId, admissionKey);
+    }
     for (const step of spec.steps) {
       for (const name of validateStepSecrets(step.secrets, process.env)) {
         if (this.withheld.has(name)) {
@@ -155,6 +160,20 @@ export class JournalClient extends JournalConnection {
     }, null);
   }
 
+  /** Drive a blocking deterministic child on its own socket, then close it. */
+  private async runStartIsolated(
+    spec: KernelRunSpec, reuseFromRunId?: string, admissionKey?: string,
+  ): Promise<VerbContract['run.start']['result']> {
+    const peer = this.createPeer();
+    try {
+      await peer.connect();
+      await peer.hello('flows-authored-deterministic');
+      return await peer.runStart(spec, reuseFromRunId, admissionKey);
+    } finally {
+      peer.close();
+    }
+  }
+
   /** §3 memoized resume. */
   runResume(runId: string, allowHumanInfluenced = false): Promise<VerbContract['run.resume']['result']> {
     return this.request('run.resume', {