bunqueue-client 0.1.9 → 0.2.0

package/src/canonical-transport/dlq.ts

@@ -0,0 +1,12 @@
+import { embeddedDlq } from './embedded.js';
+
+type Operations = ReturnType<typeof embeddedDlq>;
+
+export const getDlqConfig: Operations['getDlqConfig'] = (...args) =>
+  embeddedDlq().getDlqConfig(...args);
+export const getDlqEntries: Operations['getDlqEntries'] = (...args) =>
+  embeddedDlq().getDlqEntries(...args);
+export const getDlqStats: Operations['getDlqStats'] = (...args) =>
+  embeddedDlq().getDlqStats(...args);
+export const retryDlqByFilter: Operations['retryDlqByFilter'] = (...args) =>
+  embeddedDlq().retryDlqByFilter(...args);

package/src/canonical-transport/embedded.ts

@@ -0,0 +1,55 @@
+/** Load the same embedded engine under Bun without loading bun:sqlite under Node. */
+import type * as Backend from '../../../../scripts/client-portable/embedded-entry.js';
+
+type EmbeddedBackend = typeof Backend;
+
+// A non-literal specifier keeps bundlers from inlining the Bun-only engine.
+const backendPath = './embedded.js';
+const REQUIRES_BUN = 'Embedded mode requires Bun; use a TCP connection in this runtime.';
+const REBUNDLED =
+  'Embedded mode could not load the bunqueue-client engine: this copy was re-bundled ' +
+  'without its ESM files. Import the published package, or use a TCP connection.';
+let backend: EmbeddedBackend | undefined;
+
+/**
+ * Bun's require() loads the ESM engine synchronously on first embedded use.
+ * The package therefore has no top-level await (CommonJS bundlers reject it),
+ * and Node, Deno and Workers never evaluate the engine or bun:sqlite.
+ */
+function loadBackend(): EmbeddedBackend {
+  if (backend) return backend;
+  const runtime = globalThis.process;
+  if (!runtime?.versions?.bun) throw new Error(REQUIRES_BUN);
+  // The published ESM file knows its own URL. CommonJS re-bundlers replace it
+  // with nothing or with a build-time location that lacks the engine file.
+  const location: unknown = import.meta.url;
+  if (typeof location !== 'string' || !location) throw new Error(REBUNDLED);
+  const { createRequire } = runtime.getBuiltinModule('node:module') as typeof import('node:module');
+  try {
+    backend = createRequire(location)(backendPath) as EmbeddedBackend;
+  } catch (error) {
+    if ((error as { code?: unknown } | null)?.code !== 'MODULE_NOT_FOUND') throw error;
+    throw new Error(REBUNDLED, { cause: error });
+  }
+  return backend;
+}
+
+export function getSharedManager(
+  dataPath?: string
+): ReturnType<EmbeddedBackend['getSharedManager']> {
+  return loadBackend().getSharedManager(dataPath);
+}
+
+// A shared manager exists only after getSharedManager() loaded the engine, so
+// shutdown and inspection never load it on behalf of TCP-only clients.
+export function shutdownManager(): void {
+  backend?.shutdownManager();
+}
+
+export function peekSharedManager(): ReturnType<EmbeddedBackend['peekSharedManager']> {
+  return backend?.peekSharedManager() ?? null;
+}
+
+export function embeddedDlq(): EmbeddedBackend['dlq'] {
+  return loadBackend().dlq;
+}

package/src/canonical-transport/runtime.ts

@@ -0,0 +1,49 @@
+/** Runtime primitives only: job and scheduling logic stays in the canonical client. */
+import { access, unlink } from 'node:fs/promises';
+import { createHash, randomBytes } from 'node:crypto';
+import { availableParallelism } from 'node:os';
+export { ThreadWorker } from './thread-worker.js';
+
+export const hardwareConcurrency = (() => {
+  try {
+    // The embedded engine sizes shards from this exact runtime value. Host
+    // CPU inventory can exceed the quota visible to Bun inside a container.
+    return globalThis.navigator
+      ? globalThis.navigator.hardwareConcurrency || 4
+      : availableParallelism() || 4;
+  } catch {
+    return 4;
+  }
+})();
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Pool identities need a stable token fingerprint, never the token itself. */
+export function hash(value: string): number {
+  return createHash('sha256').update(value).digest().readUInt32BE(0);
+}
+
+/** RFC 9562 UUIDv7, retaining the canonical public ID format. */
+export function uuid(): string {
+  const bytes = randomBytes(16);
+  bytes.writeUIntBE(Date.now(), 0, 6);
+  bytes[6] = 0x70 | (bytes[6] & 0x0f);
+  bytes[8] = 0x80 | (bytes[8] & 0x3f);
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function file(path: string): { exists(): Promise<boolean>; delete(): Promise<void> } {
+  return {
+    async exists() {
+      try {
+        await access(path);
+        return true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+        throw error;
+      }
+    },
+    delete: () => unlink(path),
+  };
+}

package/src/canonical-transport/thread-worker.ts

@@ -0,0 +1,83 @@
+/** Worker-thread boundary for the canonical sandbox pool and generated wrapper. */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { Worker } from 'node:worker_threads';
+
+const BRIDGE = `
+import { parentPort as __bunqueueParentPort } from 'node:worker_threads';
+globalThis.self = globalThis;
+globalThis.postMessage = (message) => __bunqueueParentPort.postMessage(message);
+__bunqueueParentPort.on('message', (data) => {
+  Promise.resolve().then(() => globalThis.onmessage?.({ data })).catch((error) => {
+    queueMicrotask(() => { throw error; });
+  });
+});
+`;
+
+export interface ThreadError {
+  message: string;
+  error: Error;
+}
+
+export class ThreadWorker {
+  onmessage: ((event: { data: unknown }) => void) | null = null;
+  onerror: ((event: ThreadError) => void) | null = null;
+  private readonly worker: Worker;
+  private readonly directory: string;
+  private intentionalExit = false;
+  private reportedError = false;
+  private termination: Promise<number> | undefined;
+
+  constructor(wrapperPath: string, _options: { smol?: boolean } = {}) {
+    // The canonical wrapper contains JavaScript but uses a .ts filename.
+    // A private .mjs copy works on Node 20 without a TypeScript loader and
+    // retains file-based resolution for the absolute processor import.
+    const source = readFileSync(wrapperPath, 'utf8');
+    this.directory = mkdtempSync(join(tmpdir(), 'bunqueue-thread-'));
+    const entry = join(this.directory, 'wrapper.mjs');
+    try {
+      writeFileSync(entry, BRIDGE + source, { mode: 0o600 });
+      this.worker = new Worker(entry, {
+        // Parent stdin/eval module selection does not apply to a worker file.
+        execArgv: process.execArgv.filter(
+          (argument, index, arguments_) =>
+            argument !== '--input-type' &&
+            !argument.startsWith('--input-type=') &&
+            arguments_[index - 1] !== '--input-type'
+        ),
+      });
+    } catch (error) {
+      this.cleanup();
+      throw error;
+    }
+    this.worker.on('message', (data: unknown) => {
+      if (!this.intentionalExit) this.onmessage?.({ data });
+    });
+    this.worker.on('error', (error: Error) => this.reportError(error));
+    this.worker.on('exit', (code) => {
+      this.cleanup();
+      this.reportError(new Error(`Sandboxed worker exited unexpectedly with code ${code}`));
+    });
+  }
+
+  postMessage(message: unknown): void {
+    if (!this.intentionalExit) this.worker.postMessage(message);
+  }
+
+  terminate(): Promise<number> {
+    this.intentionalExit = true;
+    this.termination ??= this.worker.terminate().finally(() => this.cleanup());
+    return this.termination;
+  }
+
+  private reportError(error: Error): void {
+    if (this.intentionalExit || this.reportedError) return;
+    this.reportedError = true;
+    this.onerror?.({ message: error.message, error });
+  }
+
+  private cleanup(): void {
+    rmSync(this.directory, { recursive: true, force: true });
+  }
+}

package/src/canonical-transport/transport.ts

@@ -0,0 +1,153 @@
+/** Node socket boundary; command, health, retry and event behavior stays canonical. */
+import { readFileSync } from 'node:fs';
+import { createConnection as connectTcp, type Socket } from 'node:net';
+import { connect as connectTls } from 'node:tls';
+import {
+  FrameParser,
+  FrameSizeError,
+} from '../../../../src/infrastructure/server/protocol/frameParser.js';
+import type { ClientTlsOptions } from '../../../../src/client/tcp/types/tls.js';
+import type { SocketWrapper } from '../../../../src/client/tcp/types/socket.js';
+import type {
+  ConnectionEvents,
+  ConnectionResult,
+  ConnectionTarget,
+} from '../../../../src/client/tcp/transport.js';
+
+export type {
+  ConnectionEvents,
+  ConnectionResult,
+  ConnectionTarget,
+} from '../../../../src/client/tcp/transport.js';
+
+const MAX_WRITE_QUEUE_BYTES = 64 * 1024 * 1024;
+
+export function buildClientTls(
+  tls: boolean | ClientTlsOptions | undefined
+): true | Record<string, unknown> | undefined {
+  if (!tls) return undefined;
+  if (tls === true) return true;
+  return {
+    ...(tls.rejectUnauthorized !== undefined && { rejectUnauthorized: tls.rejectUnauthorized }),
+    ...(tls.caFile !== undefined && { ca: readFileSync(tls.caFile) }),
+  };
+}
+
+export function tlsRequiresVerification(tls: boolean | ClientTlsOptions | undefined): boolean {
+  return !!tls && (tls === true || tls.rejectUnauthorized !== false);
+}
+
+export function createConnection(
+  target: ConnectionTarget,
+  connectTimeout: number,
+  events: ConnectionEvents
+): Promise<ConnectionResult> {
+  return new Promise((resolve, reject) => {
+    const host = target.host ?? 'localhost';
+    const port = target.port ?? 6789;
+    const description = `${target.host}:${target.port}`;
+    const tls = buildClientTls(target.tls);
+    const parser = new FrameParser();
+    let settled = false;
+    // TCP reached the peer during this attempt (Bun's `open`); TLS may still fail.
+    let tcpOpened = false;
+    // The attempt resolved and the client owns the socket.
+    let opened = false;
+    let socket: Socket;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      if (timer !== undefined) clearTimeout(timer);
+      timer = undefined;
+    };
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+
+    try {
+      socket =
+        tls === undefined
+          ? connectTcp({ host, port })
+          : connectTls({ host, port, ...(tls === true ? {} : tls) });
+    } catch (error) {
+      fail(new Error(`Failed to connect to ${description}: ${String(error)}`));
+      return;
+    }
+
+    const wrapper: SocketWrapper = {
+      frameParser: parser,
+      write(data) {
+        if (socket.destroyed) return;
+        // Node buffers partial writes internally and resumes them on drain.
+        socket.write(data);
+        if (socket.writableLength > MAX_WRITE_QUEUE_BYTES) socket.destroy();
+      },
+      end() {
+        // Shutdown cancels pending requests in the canonical client first.
+        // Destroy also handles a peer that never acknowledges a TCP half-close.
+        socket.destroy();
+      },
+    };
+
+    const open = () => {
+      if (settled) {
+        // A late socket from an abandoned attempt never reaches the client.
+        socket.destroy();
+        return;
+      }
+      opened = true;
+      settled = true;
+      cleanup();
+      socket.setNoDelay(true);
+      socket.setKeepAlive(true, 15000);
+      resolve({ socket: wrapper, cleanup });
+    };
+    // TLS sockets also emit the TCP-level `connect` before `secureConnect`.
+    socket.on('connect', () => {
+      if (!settled) tcpOpened = true;
+      if (tls === undefined) open();
+    });
+    if (tls !== undefined) socket.on('secureConnect', open);
+    socket.on('data', (data: Buffer) => {
+      let frames: Uint8Array[];
+      try {
+        frames = parser.addData(data);
+      } catch (error) {
+        const reason =
+          error instanceof FrameSizeError
+            ? new Error(
+                `Frame too large: ${error.requestedSize} bytes exceeds maximum ${error.maxSize}`
+              )
+            : error instanceof Error
+              ? error
+              : new Error(String(error));
+        socket.destroy();
+        events.onError(reason);
+        return;
+      }
+      for (const frame of frames) events.onData(frame);
+    });
+    socket.on('error', (error: Error) => {
+      if (!opened) {
+        fail(new Error(`Failed to connect to ${description}: ${error.message}`));
+      } else {
+        events.onError(error);
+      }
+    });
+    socket.on('close', () => {
+      fail(new Error('Connection closed'));
+      cleanup();
+      // Like Bun, only a socket whose TCP connection opened reports a close. A
+      // refused attempt, or one abandoned before TCP opened, only fails the
+      // connect: the canonical client keeps queued commands and retries instead
+      // of running its lost-connection path.
+      if (tcpOpened) events.onClose();
+    });
+    timer = setTimeout(() => {
+      fail(new Error(`Connection timeout to ${description}`));
+      socket.destroy();
+    }, connectTimeout);
+  });
+}

package/src/connection.ts

@@ -1,14 +1,8 @@
-/**
- * TCP connection to a bunqueue server — cross-runtime (Node.js, Bun, Deno).
- *
- * Requests carry a `reqId` string; the server echoes it back, enabling
- * pipelining (many in-flight commands per socket). Uses only `node:`
- * builtins (net/tls), which Node, Bun and Deno all support.
- */
+/** Cross-runtime TCP connection with reqId-based request pipelining. */
 
 import { EventEmitter } from 'node:events';
 import type { Socket } from 'node:net';
-import { pack, unpack } from 'msgpackr';
+import { unpack } from 'msgpackr';
 import { Backpressure } from './backpressure.js';
 import type {
   Command,
@@ -18,18 +12,16 @@ import type {
   TlsOption,
 } from './connection-types.js';
 import { AuthError, CommandError, CommandTimeoutError, ConnectionClosedError } from './errors.js';
-import { compact, FrameParser, frame, PROTOCOL_VERSION } from './frame.js';
+import { FrameParser, PROTOCOL_VERSION } from './frame.js';
 import { nowMs, Telemetry } from './observability.js';
+import { serializeCommand } from './serialization.js';
 import { openSocket } from './socket-factory.js';
 
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection-types.js';
 
 /**
- * A single pipelined TCP connection to a bunqueue server.
- *
- * Emits typed lifecycle events for observability: `connect`, `disconnect` and
- * `reconnect_scheduled` (payloads mirror the telemetry events). Attach a
- * telemetry sink via the `onTelemetry` option for per-command latency metrics.
+ * A pipelined connection with lifecycle events and an optional structured
+ * telemetry sink.
  */
 export class Connection extends EventEmitter {
   readonly host: string;
@@ -49,8 +41,7 @@ export class Connection extends EventEmitter {
   private connectGeneration = 0;
   private failedAttempts = 0;
   private nextAttemptAt = 0;
-  // Half-open recovery (#94): after this many consecutive command timeouts the
-  // socket is presumed dead and torn down so the next call reconnects.
+  // Half-open recovery: repeated command timeouts force lazy reconnection.
   private readonly maxCommandTimeouts = 3;
   private consecutiveTimeouts = 0;
   private readonly telemetry: Telemetry;
@@ -75,11 +66,7 @@ export class Connection extends EventEmitter {
     return this.connected;
   }
 
-  /**
-   * Monotonic counter, incremented on every successful (re)connect. Consumers
-   * that hold per-connection server state (e.g. a Worker registration) compare
-   * it between operations and re-establish that state after a reconnect.
-   */
+  /** Successful-connect generation used to restore per-connection state. */
   get generation(): number {
     return this.connectGeneration;
   }
@@ -117,16 +104,21 @@ export class Connection extends EventEmitter {
 
   private async doConnect(): Promise<void> {
     const startMs = nowMs();
-    const socket = await openSocket(this.host, this.port, this.tls, this.connectTimeoutMs);
+    const socket = await this.telemetry.captureAsync(
+      'connect',
+      openSocket(this.host, this.port, this.tls, this.connectTimeoutMs)
+    );
     socket.setNoDelay(true);
-    // TCP keepalive (~15s idle) surfaces a half-open link (cloud LB/NAT idle
-    // drop with no FIN/RST) in seconds instead of ~tcp_retries2 minutes.
+    // TCP keepalive surfaces half-open cloud LB/NAT links promptly.
     socket.setKeepAlive(true, 15_000);
     this.parser.clear();
     this.socket = socket;
 
     socket.on('data', (chunk: Buffer) => this.handleData(chunk));
-    socket.on('error', () => this.teardown());
+    socket.on('error', (error) => {
+      this.telemetry.error('socket', error);
+      this.teardown();
+    });
     socket.on('close', () => this.teardown());
 
     this.connected = true;
@@ -159,6 +151,11 @@ export class Connection extends EventEmitter {
    */
   async call<R = Response>(command: Command, timeoutMs?: number): Promise<R> {
     if (!this.connected) await this.connect();
+    this.reqCounter = (this.reqCounter + 1) & 0x7fffffff;
+    const reqId = String(this.reqCounter);
+    const outbound = this.telemetry.capture('serialization', () =>
+      serializeCommand(command, reqId)
+    );
     // Backpressure: park here if too many commands are already in flight. The
     // socket may be torn down while parked, so re-check after the gate.
     const gate = this.backpressure.acquire(this.pending.size);
@@ -166,9 +163,6 @@ export class Connection extends EventEmitter {
     const socket = this.socket;
     if (!this.connected || !socket) throw new ConnectionClosedError('not connected');
 
-    this.reqCounter = (this.reqCounter + 1) & 0x7fffffff;
-    const reqId = String(this.reqCounter);
-    const payload = pack({ ...compact(command), reqId });
     const gen = this.connectGeneration; // snapshot: a timeout must not tear down a newer conn
     const startMs = nowMs();
 
@@ -199,8 +193,9 @@ export class Connection extends EventEmitter {
         timer,
       });
 
-      socket.write(frame(payload), (err) => {
+      socket.write(outbound, (err) => {
         if (err) {
+          this.telemetry.error('write', err);
           const entry = this.pending.get(reqId);
           this.pending.delete(reqId);
           this.backpressure.release();
@@ -227,7 +222,7 @@ export class Connection extends EventEmitter {
     return this.call({
       cmd: 'Hello',
       protocolVersion: PROTOCOL_VERSION,
-      capabilities: ['pipelining'],
+      capabilities: ['pipelining', 'separate-job-name'],
     });
   }
 

package/src/errors.ts

@@ -16,6 +16,9 @@ export class CommandTimeoutError extends BunqueueError {}
 /** The server answered ok=false; message carries the server error. */
 export class CommandError extends BunqueueError {}
 
+/** A command cannot be encoded within the protocol's wire constraints. */
+export class SerializationError extends BunqueueError {}
+
 /** Authentication with the server failed. */
 export class AuthError extends BunqueueError {}
 

package/src/flow-commit.ts

@@ -0,0 +1,45 @@
+import type { ConnectionLike } from './connection-types.js';
+import type { AtomicFlowJobInput } from './flow-plan.js';
+import type { JobRaw } from './job.js';
+import type { DataResponse } from './responses.js';
+
+interface PushFlowResult {
+  jobs: JobRaw[];
+}
+
+export function validateFlowSnapshots(
+  jobs: AtomicFlowJobInput[],
+  snapshots: unknown
+): Map<string, JobRaw> {
+  if (!Array.isArray(snapshots) || snapshots.length !== jobs.length) {
+    throw new Error('Invalid PUSHF response: committed job snapshots are missing');
+  }
+  const expected = new Map(jobs.map((job) => [job.id, job.queue]));
+  const byId = new Map<string, JobRaw>();
+  for (const value of snapshots) {
+    if (!value || typeof value !== 'object') {
+      throw new Error('Invalid PUSHF response: job snapshot is invalid');
+    }
+    const snapshot = value as JobRaw;
+    if (typeof snapshot.id !== 'string' || !expected.has(snapshot.id)) {
+      throw new Error('Invalid PUSHF response: committed job IDs do not match the request');
+    }
+    if (byId.has(snapshot.id) || snapshot.queue !== expected.get(snapshot.id)) {
+      throw new Error('Invalid PUSHF response: committed job IDs do not match the request');
+    }
+    byId.set(snapshot.id, snapshot);
+  }
+  return byId;
+}
+
+export async function commitFlow(
+  connection: ConnectionLike,
+  jobs: AtomicFlowJobInput[]
+): Promise<Map<string, JobRaw>> {
+  if (jobs.length === 0) return new Map();
+  const response = await connection.call<DataResponse<PushFlowResult>>({
+    cmd: 'PUSHF',
+    jobs,
+  });
+  return validateFlowSnapshots(jobs, response.data?.jobs);
+}

package/src/flow-plan-legacy.ts

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+import {
+  type AtomicFlowJobInput,
+  allocateFlowId,
+  type FlowIdFactory,
+  flowData,
+  flowInput,
+} from './flow-plan.js';
+import type { FlowStep } from './flow-types.js';
+
+const MAX_FLOW_JOBS = 10_000;
+const QUEUE_RE = /^[a-zA-Z0-9_\-.:]+$/;
+
+export interface ChainPlan {
+  jobs: AtomicFlowJobInput[];
+  ids: string[];
+}
+
+export interface FanInPlan {
+  jobs: AtomicFlowJobInput[];
+  parallelIds: string[];
+  finalId: string;
+}
+
+function allocateSteps<T>(
+  steps: FlowStep<T>[],
+  ids: Set<string>,
+  idFactory: FlowIdFactory
+): string[] {
+  if (steps.length > MAX_FLOW_JOBS) {
+    throw new Error(`flow exceeds the ${MAX_FLOW_JOBS} job limit`);
+  }
+  return steps.map((step) => {
+    if (!step || typeof step !== 'object') throw new Error('flow step must be an object');
+    if (typeof step.name !== 'string' || !step.name || step.name.length > 256) {
+      throw new Error('flow job name must be a non-empty string of at most 256 characters');
+    }
+    if (
+      typeof step.queueName !== 'string' ||
+      !step.queueName ||
+      step.queueName.length > 256 ||
+      !QUEUE_RE.test(step.queueName)
+    ) {
+      throw new Error('flow queueName is invalid');
+    }
+    const children = (step as FlowStep<T> & { children?: unknown }).children;
+    if (children !== undefined && !Array.isArray(children)) {
+      throw new Error('flow children must be an array');
+    }
+    if ((children?.length ?? 0) > 0) {
+      throw new Error('nested children are not supported by this flow method');
+    }
+    return allocateFlowId(step.opts ?? {}, ids, idFactory);
+  });
+}
+
+export function planChain<T>(
+  steps: FlowStep<T>[],
+  idFactory: FlowIdFactory = randomUUID
+): ChainPlan {
+  const ids = allocateSteps(steps, new Set(), idFactory);
+  const jobs = steps.map((step, index): AtomicFlowJobInput => {
+    const dependency = index > 0 ? ids[index - 1] : undefined;
+    const data = flowData(step.name, step.data, {
+      __flowParentId: dependency ?? null,
+    });
+    return {
+      id: ids[index],
+      queue: step.queueName,
+      input: flowInput(data, step.opts ?? {}, {
+        dependsOn: dependency ? [dependency] : undefined,
+      }),
+    };
+  });
+  return { jobs, ids };
+}
+
+export function planBulkThen<T>(
+  parallel: FlowStep<T>[],
+  final: FlowStep<T>,
+  idFactory: FlowIdFactory = randomUUID
+): FanInPlan {
+  if (parallel.length >= MAX_FLOW_JOBS) {
+    throw new Error(`flow exceeds the ${MAX_FLOW_JOBS} job limit`);
+  }
+  const ids = new Set<string>();
+  const parallelIds = allocateSteps(parallel, ids, idFactory);
+  const [finalId] = allocateSteps([final], ids, idFactory);
+  const parallelJobs = parallel.map((step, index): AtomicFlowJobInput => ({
+    id: parallelIds[index],
+    queue: step.queueName,
+    input: flowInput(
+      flowData(step.name, step.data, {
+        __parentId: finalId,
+        __parentQueue: final.queueName,
+      }),
+      step.opts ?? {},
+      { parentId: finalId }
+    ),
+  }));
+  const finalJob: AtomicFlowJobInput = {
+    id: finalId,
+    queue: final.queueName,
+    input: flowInput(
+      flowData(final.name, final.data, {
+        __flowParentIds: parallelIds,
+        __childrenIds: parallelIds,
+      }),
+      final.opts ?? {},
+      {
+        dependsOn: parallelIds.length > 0 ? parallelIds : undefined,
+        childrenIds: parallelIds.length > 0 ? parallelIds : undefined,
+      }
+    ),
+  };
+  return { jobs: [...parallelJobs, finalJob], parallelIds, finalId };
+}