@voyant-travel/workflows-orchestrator 0.107.10

package/dist/types.d.ts

@@ -0,0 +1,182 @@
+import type { RunTrigger, WaitpointKind } from "@voyant-travel/workflows";
+import type { StepHandlerError, WorkflowStepRequest, WorkflowStepResponse } from "@voyant-travel/workflows/handler";
+import type { CompensationJournalEntry, JournalSlice, StepJournalEntry, WaitpointResolutionEntry } from "@voyant-travel/workflows/protocol";
+export type { CompensationJournalEntry, JournalSlice, RunTrigger, StepJournalEntry, WaitpointKind, WaitpointResolutionEntry, WorkflowStepRequest, WorkflowStepResponse, };
+/**
+ * Terminal and non-terminal run statuses. Mirrors the wire statuses
+ * from docs/runtime-protocol.md §5 but only the states the orchestrator
+ * itself cares about.
+ */
+export type OrchestratorRunStatus = "running" | "waiting" | "completed" | "failed" | "cancelled" | "compensated" | "compensation_failed";
+export interface PendingWaitpoint {
+    clientWaitpointId: string;
+    kind: WaitpointKind;
+    meta: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export interface StreamChunk {
+    streamId: string;
+    seq: number;
+    encoding: "text" | "json" | "base64";
+    chunk: unknown;
+    final: boolean;
+    at: number;
+}
+export interface RunRecord {
+    id: string;
+    workflowId: string;
+    workflowVersion: string;
+    status: OrchestratorRunStatus;
+    input: unknown;
+    /** Output on "completed" runs. */
+    output?: unknown;
+    /** SerializedError for failed / compensation_failed. */
+    error?: {
+        category: string;
+        code: string;
+        message: string;
+    };
+    /** Journal accumulated across every tenant invocation. */
+    journal: JournalSlice;
+    /** Number of tenant invocations performed so far. */
+    invocationCount: number;
+    /**
+     * Positional dedup cursor for `metadataUpdates`. Each executor
+     * response re-emits every metadata mutation the body made (including
+     * those from prior invocations, since the body replays from the
+     * start). The orchestrator applies only the delta beyond what it's
+     * seen to avoid double-counting increments / duplicate appends.
+     */
+    metadataAppliedCount: number;
+    /**
+     * Cumulative ms spent inside tenant invocations, excluding parked
+     * time. Used to enforce workflow-level timeouts — a run that
+     * parks for a week on a waitpoint should not count that week
+     * against its compute budget.
+     */
+    computeTimeMs: number;
+    /** ms budget from WorkflowConfig.timeout. Zero / undefined = no limit. */
+    timeoutMs?: number;
+    /**
+     * Trigger-time scheduling priority. Higher numbers are claimed first
+     * by store-backed time wheels when multiple runs are due.
+     */
+    priority?: number;
+    /**
+     * Cross-run lineage. Present on child runs created by
+     * `ctx.invoke`; set by the orchestrator when the child parks so
+     * its eventual terminal transition can cascade-resume the parent.
+     */
+    parent?: {
+        runId: string;
+        waitpointId: string;
+    };
+    /** Pending waitpoints, only populated when status === "waiting". */
+    pendingWaitpoints: PendingWaitpoint[];
+    /** Stream chunks accumulated across every tenant invocation, keyed by streamId. */
+    streams: Record<string, StreamChunk[]>;
+    /** Wall-clock fields, all ms-since-epoch. */
+    startedAt: number;
+    completedAt?: number;
+    /** Trigger metadata. */
+    triggeredBy: RunTrigger;
+    tags: string[];
+    /** Optional environment metadata. */
+    environment: "production" | "preview" | "development";
+    /** Tenant identity flows through every step request. */
+    tenantMeta: {
+        tenantId: string;
+        projectId: string;
+        organizationId: string;
+        projectSlug?: string;
+        organizationSlug?: string;
+        /**
+         * Identifier the runtime adapter uses to locate the tenant's
+         * code. On Cloudflare this is the dispatch-namespace script name;
+         * on other targets it may be a container image tag or Node script
+         * path. Optional so local/in-process drivers aren't forced to set it.
+         */
+        tenantScript?: string;
+    };
+    runMeta: {
+        number: number;
+        attempt: number;
+    };
+    /**
+     * Caller-supplied idempotency token, mirrored from `TriggerArgs.idempotencyKey`.
+     * Persistent stores use this column to enforce dedup natively (e.g. unique
+     * partial index in `voyant_snapshot_runs`); in-process stores ignore it.
+     */
+    idempotencyKey?: string;
+}
+export interface RunRecordStore {
+    get(id: string): Promise<RunRecord | undefined>;
+    save(record: RunRecord): Promise<RunRecord>;
+    /**
+     * Atomically insert a new run record, OR return the existing one if
+     * a record with the same `id` already exists. Used by `trigger()` to
+     * close the get-then-save race window when an idempotency-derived
+     * runId could collide across concurrent callers.
+     *
+     * Stores must implement this with a single atomic operation:
+     *   - Postgres: `INSERT … ON CONFLICT (id) DO NOTHING RETURNING …`,
+     *               with a fallback SELECT when no row is returned.
+     *   - InMemory / FS: check-then-set in a single microtask.
+     *   - DO storage: get-then-save is naturally atomic per DO instance.
+     *
+     * The returned `created: true` means this caller's record was the
+     * winner — drive it. `created: false` means another caller raced in
+     * first; return the existing record without re-driving (per
+     * architecture doc §15.2).
+     */
+    tryInsert(record: RunRecord): Promise<{
+        record: RunRecord;
+        created: boolean;
+    }>;
+    list(filter?: {
+        workflowId?: string;
+        status?: OrchestratorRunStatus;
+        limit?: number;
+    }): Promise<RunRecord[]>;
+}
+/**
+ * The tenant-side step handler. In-process for tests / local dev via
+ * `handleStepRequest` from @voyant-travel/workflows/handler; HTTP in
+ * production (via a fetch to the tenant Worker). The optional
+ * per-invocation `signal` aborts in-flight step bodies when the run
+ * is cancelled mid-execution.
+ */
+export type StepHandler = (req: WorkflowStepRequest, opts?: {
+    signal?: AbortSignal;
+    /**
+     * Fires synchronously from `ctx.stream.*` as each chunk is
+     * produced. In-process only; HTTP transport drops it (chunks
+     * still arrive in the response body). Used by orchestrators to
+     * broadcast chunks to dashboards before the invocation returns.
+     */
+    onStreamChunk?: (chunk: StreamChunk) => void;
+}) => Promise<{
+    status: number;
+    body: WorkflowStepResponse;
+} | {
+    status: number;
+    body: StepHandlerError;
+}>;
+/**
+ * Injection delivered by an external signal (dashboard, API, inbox).
+ * Same shape used by the dashboard inject endpoints.
+ */
+export type WaitpointInjection = {
+    kind: "EVENT";
+    eventType: string;
+    payload?: unknown;
+} | {
+    kind: "SIGNAL";
+    name: string;
+    payload?: unknown;
+} | {
+    kind: "MANUAL";
+    tokenId: string;
+    payload?: unknown;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Types the orchestrator core uses. Decoupled from any transport:
+// the same RunRecord/Store shapes underpin the in-memory test store,
+// the Durable-Object-backed production store, and any future adapters.
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@voyant-travel/workflows-orchestrator",
+  "version": "0.107.10",
+  "description": "Reference orchestrator core for Voyant Workflows — drives runs through the tenant step handler over the v1 wire protocol.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/workflows-orchestrator"
+  },
+  "homepage": "https://voyant.cloud/workflows",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/driver-compliance.d.ts",
+      "import": "./dist/testing/driver-compliance.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@voyant-travel/workflows": "^0.107.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.6",
+    "@voyant-travel/voyant-typescript-config": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit",
+    "dev": "tsc -w -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/orchestrator-test-support.ts

@@ -0,0 +1,18 @@
+import { __resetRegistry } from "@voyant-travel/workflows"
+import { handleStepRequest, type WorkflowStepRequest } from "@voyant-travel/workflows/handler"
+import { beforeEach } from "vitest"
+import type { StepHandler } from "../index.js"
+
+export const handler: StepHandler = async (req: WorkflowStepRequest, opts) => {
+  return await handleStepRequest(req, {}, opts)
+}
+
+export const tenantMeta = {
+  tenantId: "tnt_test",
+  projectId: "prj_test",
+  organizationId: "org_test",
+}
+
+beforeEach(() => {
+  __resetRegistry()
+})

package/src/abort-registry.ts

@@ -0,0 +1,41 @@
+// Process-local map of runId → AbortController. The orchestrator
+// registers a controller when it starts driving a run and aborts it
+// when `cancel(runId)` lands mid-flight. Step bodies that honor
+// `ctx.signal` (fetches, delays, custom logic) observe the abort and
+// can clean up deterministically.
+//
+// Single-process scope by design: each Durable Object / Node serve
+// has its own registry. Cross-process cancellation rides through
+// the run store (see `beforeInvocation` in orchestrator.ts) and
+// catches up at the next invocation boundary.
+
+const controllers = new Map<string, AbortController>()
+
+export function registerRunAbort(runId: string): AbortController {
+  // If a controller already exists, reuse it (e.g., resume after
+  // park — the same run id).
+  let ctrl = controllers.get(runId)
+  if (!ctrl) {
+    ctrl = new AbortController()
+    controllers.set(runId, ctrl)
+  }
+  return ctrl
+}
+
+export function signalRunAbort(runId: string, reason?: string): boolean {
+  const ctrl = controllers.get(runId)
+  if (!ctrl) return false
+  // `AbortController.abort(reason)` is standard across modern runtimes;
+  // the reason surfaces to observers via `signal.reason`.
+  ctrl.abort(reason ?? "cancelled")
+  return true
+}
+
+export function unregisterRunAbort(runId: string): void {
+  controllers.delete(runId)
+}
+
+/** For tests. */
+export function __clearAbortRegistry(): void {
+  controllers.clear()
+}

package/src/concurrency.ts

@@ -0,0 +1,217 @@
+import type { ConcurrencyPolicy } from "@voyant-travel/workflows"
+
+import type { RunRecord } from "./types.js"
+
+export type RuntimeConcurrencyPolicy =
+  | ConcurrencyPolicy<unknown>
+  | {
+      key?: string
+      limit?: number
+      strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin"
+    }
+
+export interface ConcurrencyRunHooks {
+  onRunRecordCreated(record: RunRecord): void
+}
+
+export class WorkflowConcurrencyRejectedError extends Error {
+  readonly code = "WORKFLOW_CONCURRENCY_REJECTED"
+
+  constructor(readonly concurrencyKey: string) {
+    super(`workflow concurrency limit reached for key "${concurrencyKey}"`)
+    this.name = "WorkflowConcurrencyRejectedError"
+  }
+}
+
+export interface InProcessConcurrencyCoordinator {
+  run(
+    args: {
+      workflowId: string
+      input: unknown
+      policy?: RuntimeConcurrencyPolicy
+      holderId?: string
+    },
+    operation: (hooks: ConcurrencyRunHooks) => Promise<RunRecord>,
+  ): Promise<RunRecord>
+  releaseRun(recordOrRunId: RunRecord | string): void
+}
+
+interface Group {
+  active: Set<string>
+  waiters: Waiter[]
+}
+
+interface Slot {
+  key: string
+  holderId: string
+}
+
+interface Waiter {
+  holderId: string
+  resolve(slot: Slot): void
+}
+
+interface CreateInProcessConcurrencyCoordinatorOptions {
+  cancelRun?: (runId: string, reason: string) => Promise<unknown>
+}
+
+const TOKEN_PREFIX = "concurrency-slot:"
+
+export function createInProcessConcurrencyCoordinator(
+  opts: CreateInProcessConcurrencyCoordinatorOptions = {},
+): InProcessConcurrencyCoordinator {
+  const groups = new Map<string, Group>()
+  const runKeys = new Map<string, string>()
+  let nextToken = 0
+
+  function getGroup(key: string): Group {
+    let group = groups.get(key)
+    if (!group) {
+      group = { active: new Set(), waiters: [] }
+      groups.set(key, group)
+    }
+    return group
+  }
+
+  function createToken(): string {
+    nextToken += 1
+    return `${TOKEN_PREFIX}${nextToken}`
+  }
+
+  async function acquire(
+    key: string,
+    limit: number,
+    strategy: NonNullable<RuntimeConcurrencyPolicy["strategy"]>,
+    preferredHolderId?: string,
+  ): Promise<Slot> {
+    const group = getGroup(key)
+    if (preferredHolderId && group.active.has(preferredHolderId)) {
+      return { key, holderId: preferredHolderId }
+    }
+
+    const holderId = preferredHolderId ?? createToken()
+    if (group.active.size < limit) {
+      group.active.add(holderId)
+      return { key, holderId }
+    }
+
+    if (strategy === "cancel-newest") {
+      throw new WorkflowConcurrencyRejectedError(key)
+    }
+
+    if (strategy === "cancel-in-progress") {
+      const holders = [...group.active]
+      for (const holder of holders) {
+        group.active.delete(holder)
+        runKeys.delete(holder)
+        if (!holder.startsWith(TOKEN_PREFIX)) {
+          await opts.cancelRun?.(holder, "cancelled by workflow concurrency policy")
+        }
+      }
+      group.active.add(holderId)
+      return { key, holderId }
+    }
+
+    return new Promise((resolve) => {
+      group.waiters.push({
+        holderId,
+        resolve(slot) {
+          resolve(slot)
+        },
+      })
+    })
+  }
+
+  function assignRunId(slot: Slot, record: RunRecord): Slot {
+    const group = getGroup(slot.key)
+    if (group.active.delete(slot.holderId)) {
+      group.active.add(record.id)
+    }
+    runKeys.set(record.id, slot.key)
+    return { key: slot.key, holderId: record.id }
+  }
+
+  function releaseSlot(slot: Slot): void {
+    const group = groups.get(slot.key)
+    if (!group) return
+    group.active.delete(slot.holderId)
+    runKeys.delete(slot.holderId)
+    drain(slot.key, group)
+    if (group.active.size === 0 && group.waiters.length === 0) {
+      groups.delete(slot.key)
+    }
+  }
+
+  function drain(key: string, group: Group): void {
+    while (group.waiters.length > 0) {
+      const waiter = group.waiters.shift()
+      if (!waiter) return
+      group.active.add(waiter.holderId)
+      waiter.resolve({ key, holderId: waiter.holderId })
+      if (group.active.size > 0) return
+    }
+  }
+
+  return {
+    async run(args, operation) {
+      const policy = args.policy
+      if (!policy) {
+        return operation({ onRunRecordCreated() {} })
+      }
+
+      const key = resolveConcurrencyKey(args.workflowId, args.input, policy)
+      const limit = normalizeLimit(policy.limit)
+      const strategy = policy.strategy ?? "queue"
+      let slot = await acquire(key, limit, strategy, args.holderId)
+      let record: RunRecord | undefined
+
+      try {
+        record = await operation({
+          onRunRecordCreated(created) {
+            slot = assignRunId(slot, created)
+          },
+        })
+        if (!runKeys.has(record.id)) {
+          slot = assignRunId(slot, record)
+        }
+        return record
+      } finally {
+        if (!record || isTerminal(record.status)) {
+          releaseSlot(record ? { key: slot.key, holderId: record.id } : slot)
+        }
+      }
+    },
+
+    releaseRun(recordOrRunId) {
+      const runId = typeof recordOrRunId === "string" ? recordOrRunId : recordOrRunId.id
+      const key = runKeys.get(runId)
+      if (!key) return
+      releaseSlot({ key, holderId: runId })
+    },
+  }
+}
+
+export function resolveConcurrencyKey(
+  workflowId: string,
+  input: unknown,
+  policy: RuntimeConcurrencyPolicy,
+): string {
+  const rawKey = typeof policy.key === "function" ? policy.key(input) : policy.key
+  return `${workflowId}:${rawKey ?? "default"}`
+}
+
+function normalizeLimit(limit: number | undefined): number {
+  if (limit === undefined) return 1
+  if (!Number.isFinite(limit)) return 1
+  return Math.max(1, Math.floor(limit))
+}
+
+function isTerminal(status: RunRecord["status"]): boolean {
+  return (
+    status === "completed" ||
+    status === "failed" ||
+    status === "cancelled" ||
+    status === "compensated" ||
+    status === "compensation_failed"
+  )
+}