@voyant-travel/workflows 0.107.10

package/src/events/input-mapper.ts

@@ -0,0 +1,201 @@
+// Input mapper DSL — projects a workflow input from an event envelope.
+//
+// Each `EventFilterDeclaration` carries an optional `input: InputMapper`. At
+// ingest time, after the predicate matches, the mapper builds the actual
+// input value passed to `driver.trigger(target, input, ...)`. Same path
+// roots as the predicate evaluator (`data`, `metadata`, `name`, `emittedAt`).
+//
+// Variants:
+//   * `undefined`              → pass through `envelope.data`
+//   * `{ passthrough: true }`  → explicit pass-through of `envelope.data`
+//   * `{ path: string }`       → workflow input = the resolved path value
+//   * `{ object: {...} }`      → build an object by projecting each key;
+//                                 each value is itself an InputMapper or a
+//                                 `PathOrLit` for terminal projections
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §13.2.
+
+import { type PathOrLit, type PredicateEnvelope, resolvePath } from "./predicate.js"
+
+// ---- Public types ----
+
+export type InputMapper =
+  | undefined
+  | { passthrough: true }
+  | { path: string }
+  | { object: Record<string, InputMapper | PathOrLit> }
+
+// ---- Public API ----
+
+/**
+ * Project a workflow input from an event envelope. Mirrors the predicate
+ * evaluator's no-throw contract — missing paths produce `undefined` in the
+ * output, registration-time linting catches structural errors.
+ *
+ * Throws `InputMapperError` only on unexpected shape errors (the mapper
+ * itself was constructed wrong). Drivers catch and surface this as
+ * `IngestMatch.status === "skipped"` with reason `"input_projection_error"`.
+ */
+export function projectInput(mapper: InputMapper, envelope: PredicateEnvelope): unknown {
+  if (mapper === undefined) return envelope.data
+  if (typeof mapper !== "object" || mapper === null) {
+    throw new InputMapperError(
+      `input mapper must be undefined, {passthrough}, {path}, or {object}, got ${typeof mapper}`,
+    )
+  }
+  if ("passthrough" in mapper) {
+    if (mapper.passthrough !== true) {
+      throw new InputMapperError(`{ passthrough } must be true`)
+    }
+    return envelope.data
+  }
+  if ("path" in mapper) {
+    if (typeof mapper.path !== "string" || mapper.path.length === 0) {
+      throw new InputMapperError(`{ path } must be a non-empty string`)
+    }
+    return resolvePath(mapper.path, envelope)
+  }
+  if ("object" in mapper) {
+    if (typeof mapper.object !== "object" || mapper.object === null) {
+      throw new InputMapperError(`{ object } must map keys to InputMapper | PathOrLit`)
+    }
+    const out: Record<string, unknown> = {}
+    for (const [key, child] of Object.entries(mapper.object)) {
+      out[key] = projectChild(child, envelope)
+    }
+    return out
+  }
+  throw new InputMapperError(
+    `input mapper must contain one of passthrough | path | object, got keys: ${Object.keys(mapper).join(", ")}`,
+  )
+}
+
+// ---- Static linter ----
+
+export interface InputMapperValidationResult {
+  ok: boolean
+  errors: string[]
+}
+
+export function validateInputMapper(mapper: InputMapper): InputMapperValidationResult {
+  const errors: string[] = []
+  walkValidate(mapper, errors, [])
+  return { ok: errors.length === 0, errors }
+}
+
+// ---- Internals ----
+
+class InputMapperError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "InputMapperError"
+  }
+}
+
+/**
+ * Resolve one entry inside `{ object: { ... } }`. The value is either a
+ * nested mapper (recurse) or a `PathOrLit` (terminal projection).
+ */
+function projectChild(child: InputMapper | PathOrLit, envelope: PredicateEnvelope): unknown {
+  if (child === undefined) return envelope.data
+  if (typeof child !== "object" || child === null) {
+    throw new InputMapperError(`nested mapper entry must be an object, got ${typeof child}`)
+  }
+  // Distinguish PathOrLit (`{ path }` or `{ lit }`) from nested mapper.
+  if ("lit" in child) {
+    return (child as { lit: unknown }).lit
+  }
+  // `{ path: "..." }` is shared between PathOrLit and InputMapper — resolve directly.
+  if ("path" in child) {
+    if (typeof child.path !== "string" || child.path.length === 0) {
+      throw new InputMapperError(`nested { path } must be a non-empty string`)
+    }
+    return resolvePath(child.path, envelope)
+  }
+  // Otherwise: a nested InputMapper (passthrough / object).
+  return projectInput(child as InputMapper, envelope)
+}
+
+function walkValidate(mapper: InputMapper, errors: string[], path: string[]): void {
+  if (mapper === undefined) return
+  if (typeof mapper !== "object" || mapper === null) {
+    errors.push(
+      `${pathLabel(path)}: input mapper must be undefined or an object, got ${typeof mapper}`,
+    )
+    return
+  }
+  const keys = Object.keys(mapper)
+  if (keys.length === 0) {
+    errors.push(`${pathLabel(path)}: input mapper must specify passthrough | path | object`)
+    return
+  }
+  if ("passthrough" in mapper) {
+    if (mapper.passthrough !== true) {
+      errors.push(`${pathLabel(path)}: { passthrough } must be true`)
+    }
+    return
+  }
+  if ("path" in mapper) {
+    if (typeof mapper.path !== "string" || mapper.path.length === 0) {
+      errors.push(`${pathLabel(path)}: { path } must be a non-empty string`)
+      return
+    }
+    validatePathRoot(mapper.path, errors, path)
+    return
+  }
+  if ("object" in mapper) {
+    if (typeof mapper.object !== "object" || mapper.object === null) {
+      errors.push(`${pathLabel(path)}: { object } must map keys to InputMapper | PathOrLit`)
+      return
+    }
+    for (const [k, child] of Object.entries(mapper.object)) {
+      validateChild(child, errors, [...path, k])
+    }
+    return
+  }
+  errors.push(`${pathLabel(path)}: unknown mapper variant — keys: ${keys.join(", ")}`)
+}
+
+function validateChild(child: InputMapper | PathOrLit, errors: string[], path: string[]): void {
+  if (child === undefined) return
+  if (typeof child !== "object" || child === null) {
+    errors.push(`${pathLabel(path)}: nested entry must be an object`)
+    return
+  }
+  if ("lit" in child) {
+    const t = typeof (child as { lit: unknown }).lit
+    if (
+      t !== "string" &&
+      t !== "number" &&
+      t !== "boolean" &&
+      (child as { lit: unknown }).lit !== null
+    ) {
+      errors.push(`${pathLabel(path)}: { lit } must be string | number | boolean | null`)
+    }
+    return
+  }
+  if ("path" in child) {
+    if (typeof child.path !== "string" || child.path.length === 0) {
+      errors.push(`${pathLabel(path)}: { path } must be a non-empty string`)
+      return
+    }
+    validatePathRoot(child.path, errors, path)
+    return
+  }
+  walkValidate(child as InputMapper, errors, path)
+}
+
+function validatePathRoot(path: string, errors: string[], errorPath: string[]): void {
+  // Match the predicate path roots exactly so the two DSLs stay aligned.
+  const firstSegment = path.split(".")[0] ?? ""
+  const root = firstSegment.split("[")[0] ?? ""
+  if (root !== "data" && root !== "metadata" && root !== "name" && root !== "emittedAt") {
+    errors.push(
+      `${pathLabel(errorPath)}: path root "${root}" is not one of data | metadata | name | emittedAt`,
+    )
+  }
+}
+
+function pathLabel(path: string[]): string {
+  return path.length === 0 ? "(root)" : path.join(".")
+}

package/src/events/manifest-builder.ts

@@ -0,0 +1,372 @@
+// Build a `WorkflowManifest` from collected workflow + event-filter entries.
+//
+// Called once at `createApp()` boot (PR4). The resulting manifest is
+// content-addressed: byte-identical inputs produce byte-identical
+// `versionId`s, so concurrent registration calls don't race meaningfully —
+// the second caller sees the same versionId the first did.
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §14.1.
+
+import type {
+  EventFilterManifestEntry,
+  ManifestConcurrencyPolicy,
+  ManifestSchedule,
+  WorkflowDefinitionCapabilities,
+  WorkflowManifest,
+  WorkflowManifestBundle,
+  WorkflowManifestDiagnostic,
+  WorkflowManifestEntry,
+  WorkflowReleaseCapabilities,
+} from "../protocol/index.js"
+import type { ConcurrencyPolicy, ScheduleDeclaration } from "../workflow.js"
+import { canonicalJson, shortHash } from "./payload-hash.js"
+import type { EventFilterRuntimeEntry } from "./registry.js"
+
+export interface BuildManifestArgs {
+  /** Project / tenant identifier. Single-tenant runtimes pass `"default"`. */
+  projectId?: string
+  /** Deployment environment. */
+  environment: "production" | "preview" | "development"
+  /** Workflow definitions collected from modules + plugins. */
+  workflows: ReadonlyArray<{
+    id: string
+    config?: {
+      description?: string
+      input?: unknown
+      output?: unknown
+      defaultRuntime?: "edge" | "node"
+      concurrency?: ConcurrencyPolicy<unknown>
+      retry?: unknown
+      timeout?: unknown
+      schedule?: ScheduleDeclaration | ScheduleDeclaration[]
+    }
+  }>
+  /** Event-filter entries from `getEventFilterRegistry()`. */
+  eventFilters: ReadonlyArray<EventFilterRuntimeEntry>
+  /** Wall-clock build time, ms-since-epoch. Defaults to `Date.now()`. */
+  builtAt?: number
+  /** Source-code version of the manifest builder. */
+  builderVersion?: string
+  /** Workflow bundle metadata, when the build tool owns the artifact. */
+  bundle?: WorkflowManifestBundle
+  /** Build/import diagnostics surfaced to Cloud during release registration. */
+  diagnostics?: ReadonlyArray<WorkflowManifestDiagnostic>
+}
+
+/**
+ * Build a deterministic `WorkflowManifest`. Same inputs always produce
+ * byte-identical output, including `versionId`.
+ *
+ * Does NOT write the manifest anywhere — that's the driver's
+ * `registerManifest(...)` responsibility. This function is pure.
+ */
+export async function buildManifest(args: BuildManifestArgs): Promise<WorkflowManifest> {
+  const builtAt = args.builtAt ?? Date.now()
+  const builderVersion = args.builderVersion ?? "@voyant-travel/workflows@manifest-builder"
+  const projectId = args.projectId ?? "default"
+
+  const eventFilters: EventFilterManifestEntry[] = args.eventFilters
+    .map((entry) => entry.manifest)
+    .sort((a, b) => a.id.localeCompare(b.id))
+  const eventTargetWorkflowIds = new Set(eventFilters.map((filter) => filter.targetWorkflowId))
+
+  const workflows: WorkflowManifestEntry[] = args.workflows
+    .map((wf) => {
+      const schedules = serializeSchedules(wf.config?.schedule)
+      return {
+        id: wf.id,
+        displayName: displayNameFromId(wf.id),
+        description: wf.config?.description,
+        capabilities: workflowCapabilities({
+          hasSchedules: schedules.length > 0,
+          supportsEvents: eventTargetWorkflowIds.has(wf.id),
+        }),
+        version: "current",
+        inputSchema: serializeSchema(wf.config?.input),
+        outputSchema: serializeSchema(wf.config?.output),
+        steps: [],
+        concurrency: serializeConcurrency(wf.config?.concurrency),
+        schedules,
+        defaultRuntime: wf.config?.defaultRuntime ?? "edge",
+        hasCompensation: false,
+        sourceLocation: { file: "<runtime>", line: 0 },
+      }
+    })
+    .sort((a, b) => a.id.localeCompare(b.id))
+
+  const draft: Omit<WorkflowManifest, "versionId"> & { versionId?: string } = {
+    schemaVersion: 1,
+    projectId,
+    builtAt,
+    builderVersion,
+    capabilities: releaseCapabilities(),
+    workflows,
+    eventFilters,
+    diagnostics: [...(args.diagnostics ?? [])],
+    bundle: args.bundle,
+    bindings: {},
+    environments: { production: {}, preview: {}, development: {} },
+  }
+
+  // versionId is the cryptographic short hash of the canonical manifest
+  // body (excluding builtAt + versionId itself, which are non-load-bearing
+  // for content identity).
+  const identityBody = {
+    schemaVersion: draft.schemaVersion,
+    projectId: draft.projectId,
+    builderVersion: draft.builderVersion,
+    capabilities: draft.capabilities,
+    workflows: draft.workflows,
+    eventFilters: draft.eventFilters,
+    diagnostics: draft.diagnostics,
+    bundle: draft.bundle,
+    bindings: draft.bindings,
+    environments: draft.environments,
+  }
+  const versionId = await shortHash(identityBody)
+  void canonicalJson // referenced via shortHash; keep the import surface stable
+
+  return {
+    ...(draft as Omit<WorkflowManifest, "versionId">),
+    versionId,
+  }
+}
+
+function releaseCapabilities(): WorkflowReleaseCapabilities {
+  return {
+    trigger: true,
+    events: true,
+    schedules: true,
+    rerun: true,
+    resume: true,
+    cancel: true,
+    humanApproval: true,
+    stepRerun: false,
+  }
+}
+
+function workflowCapabilities(args: {
+  hasSchedules: boolean
+  supportsEvents: boolean
+}): WorkflowDefinitionCapabilities {
+  return {
+    canTrigger: true,
+    canRerun: true,
+    canResume: false,
+    canCancel: true,
+    hasSchedules: args.hasSchedules,
+    supportsEvents: args.supportsEvents,
+    supportsHumanApproval: false,
+    supportsStepRerun: false,
+  }
+}
+
+function serializeSchema(schema: unknown): unknown {
+  if (schema === undefined) return undefined
+  return zodToJsonSchema(schema) ?? schema
+}
+
+function zodToJsonSchema(schema: unknown): unknown | undefined {
+  if (!isRecord(schema)) return undefined
+
+  const instanceConverter = schema.toJSONSchema
+  if (typeof instanceConverter === "function") {
+    try {
+      return instanceConverter.call(schema)
+    } catch {
+      // Fall through to the structural converter below.
+    }
+  }
+
+  const def = zodDef(schema)
+  if (!def) return undefined
+  return zodDefToJsonSchema(schema)
+}
+
+function zodDefToJsonSchema(schema: unknown): unknown {
+  const def = zodDef(schema)
+  const typeName = zodTypeName(schema)
+
+  if (typeName === "object") {
+    const shape = zodObjectShape(def)
+    const properties: Record<string, unknown> = {}
+    const required: string[] = []
+    for (const key of Object.keys(shape).sort()) {
+      const child = shape[key]
+      properties[key] = zodDefToJsonSchema(child)
+      if (!zodIsOptional(child)) required.push(key)
+    }
+
+    const out: Record<string, unknown> = { type: "object", properties }
+    if (required.length > 0) out.required = required
+    return withDescription(schema, out)
+  }
+
+  if (typeName === "string") return withDescription(schema, { type: "string" })
+  if (typeName === "number") return withDescription(schema, { type: "number" })
+  if (typeName === "bigint") return withDescription(schema, { type: "integer" })
+  if (typeName === "boolean") return withDescription(schema, { type: "boolean" })
+  if (typeName === "date") return withDescription(schema, { type: "string", format: "date-time" })
+  if (typeName === "null") return withDescription(schema, { type: "null" })
+  if (
+    typeName === "undefined" ||
+    typeName === "void" ||
+    typeName === "unknown" ||
+    typeName === "any"
+  ) {
+    return withDescription(schema, {})
+  }
+  if (typeName === "never") return withDescription(schema, false)
+
+  if (typeName === "array") {
+    return withDescription(schema, {
+      type: "array",
+      items: zodDefToJsonSchema(def?.type ?? def?.element),
+    })
+  }
+
+  if (typeName === "literal") {
+    const value = Array.isArray(def?.values) ? def.values[0] : def?.value
+    return withDescription(schema, { const: value })
+  }
+
+  if (typeName === "enum" || typeName === "nativeenum") {
+    return withDescription(schema, {
+      enum: zodEnumValues(def),
+    })
+  }
+
+  if (typeName === "union" || typeName === "discriminatedunion") {
+    const options = Array.isArray(def?.options) ? def.options : []
+    return withDescription(schema, {
+      anyOf: options.map((option) => zodDefToJsonSchema(option)),
+    })
+  }
+
+  if (typeName === "record") {
+    return withDescription(schema, {
+      type: "object",
+      additionalProperties: zodDefToJsonSchema(def?.valueType ?? def?.valueTypeDef),
+    })
+  }
+
+  if (typeName === "optional") {
+    return zodDefToJsonSchema(def?.innerType)
+  }
+
+  if (typeName === "nullable") {
+    return withDescription(schema, {
+      anyOf: [zodDefToJsonSchema(def?.innerType), { type: "null" }],
+    })
+  }
+
+  if (
+    typeName === "default" ||
+    typeName === "catch" ||
+    typeName === "branded" ||
+    typeName === "readonly" ||
+    typeName === "effects" ||
+    typeName === "pipeline"
+  ) {
+    return zodDefToJsonSchema(def?.innerType ?? def?.type ?? def?.schema ?? def?.in)
+  }
+
+  return withDescription(schema, {})
+}
+
+function zodTypeName(schema: unknown): string | undefined {
+  const def = zodDef(schema)
+  const raw = typeof def?.type === "string" ? def.type : def?.typeName
+  return typeof raw === "string" ? raw.replace(/^Zod/, "").toLowerCase() : undefined
+}
+
+function zodDef(schema: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(schema)) return undefined
+  const def = schema._def ?? schema.def
+  return isRecord(def) ? def : undefined
+}
+
+function zodObjectShape(def: Record<string, unknown> | undefined): Record<string, unknown> {
+  const shape = def?.shape
+  if (typeof shape === "function") {
+    const result = shape()
+    return isRecord(result) ? result : {}
+  }
+  return isRecord(shape) ? shape : {}
+}
+
+function zodEnumValues(def: Record<string, unknown> | undefined): unknown[] {
+  if (Array.isArray(def?.values)) return def.values
+  if (isRecord(def?.entries)) return Object.values(def.entries)
+  if (isRecord(def?.values)) return Object.values(def.values)
+  return []
+}
+
+function zodIsOptional(schema: unknown): boolean {
+  const typeName = zodTypeName(schema)
+  if (typeName === "optional" || typeName === "default") return true
+  if (isRecord(schema) && typeof schema.isOptional === "function") {
+    try {
+      return schema.isOptional() === true
+    } catch {
+      return false
+    }
+  }
+  return false
+}
+
+function withDescription(schema: unknown, jsonSchema: unknown): unknown {
+  if (!isRecord(jsonSchema) || !isRecord(schema)) return jsonSchema
+  const def = zodDef(schema)
+  const description = typeof schema.description === "string" ? schema.description : def?.description
+  if (typeof description !== "string") return jsonSchema
+  return { ...jsonSchema, description }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function displayNameFromId(id: string): string {
+  return id
+    .split(/[._:-]+/g)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ")
+}
+
+function serializeConcurrency(
+  concurrency: ConcurrencyPolicy<unknown> | undefined,
+): ManifestConcurrencyPolicy | undefined {
+  if (!concurrency) return undefined
+  const out: ManifestConcurrencyPolicy = {}
+  if (typeof concurrency.key === "string") out.key = concurrency.key
+  if (concurrency.limit !== undefined) out.limit = concurrency.limit
+  if (concurrency.strategy !== undefined) out.strategy = concurrency.strategy
+  return out
+}
+
+function serializeSchedules(
+  schedule: ScheduleDeclaration | ScheduleDeclaration[] | undefined,
+): ManifestSchedule[] {
+  if (!schedule) return []
+  const schedules = Array.isArray(schedule) ? schedule : [schedule]
+  return schedules.map(serializeSchedule)
+}
+
+function serializeSchedule(schedule: ScheduleDeclaration): ManifestSchedule {
+  const out: ManifestSchedule = {}
+  if ("cron" in schedule) out.cron = schedule.cron
+  if ("every" in schedule) out.every = schedule.every
+  if ("at" in schedule) {
+    out.at = schedule.at instanceof Date ? schedule.at.toISOString() : schedule.at
+  }
+  if (schedule.timezone !== undefined) out.timezone = schedule.timezone
+  if (schedule.input !== undefined && typeof schedule.input !== "function")
+    out.input = schedule.input
+  if (schedule.enabled !== undefined) out.enabled = schedule.enabled
+  if (schedule.overlap !== undefined) out.overlap = schedule.overlap
+  if (schedule.environments !== undefined) out.environments = schedule.environments
+  if (schedule.name !== undefined) out.name = schedule.name
+  return out
+}

package/src/events/payload-hash.ts

@@ -0,0 +1,110 @@
+// Canonical JSON + SHA-256 helpers used to derive `payloadHash` ids for
+// `EventFilterRuntimeEntry` and `WorkflowManifest.versionId`.
+//
+// Canonicalization recursively alphabetizes object keys before
+// JSON.stringify. SHA-256 uses Web Crypto (`globalThis.crypto.subtle`),
+// available on Node ≥ 19, all modern browsers, and Cloudflare Workers.
+// Async because Web Crypto's digest is async — callers `await` once
+// at registration time.
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §13.3.
+
+/**
+ * Recursively alphabetize object keys, leaving arrays and primitives intact.
+ * `undefined` is converted to `null` so canonical JSON shape is stable
+ * (JSON.stringify drops `undefined` from objects).
+ */
+export function canonicalize(value: unknown): unknown {
+  if (value === undefined) return null
+  if (value === null || typeof value !== "object") return value
+  if (Array.isArray(value)) {
+    return value.map(canonicalize)
+  }
+  const sorted: Record<string, unknown> = {}
+  const keys = Object.keys(value as Record<string, unknown>).sort()
+  for (const k of keys) {
+    sorted[k] = canonicalize((value as Record<string, unknown>)[k])
+  }
+  return sorted
+}
+
+/**
+ * Stable canonical JSON string for `value`. Two values that are deeply
+ * equal modulo key order produce identical strings; two values that
+ * differ in any way produce different strings. Used as the input to
+ * `sha256(...)` for content-derived ids.
+ */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value))
+}
+
+/**
+ * SHA-256 hex digest of an arbitrary value (canonicalized first). Async
+ * — callers await once during manifest build.
+ *
+ * @returns lowercase hex string, 64 chars long.
+ */
+export async function sha256(value: unknown): Promise<string> {
+  const text = canonicalJson(value)
+  const bytes = new TextEncoder().encode(text)
+  const digest = await getCrypto().subtle.digest("SHA-256", bytes)
+  return bytesToHex(new Uint8Array(digest))
+}
+
+/**
+ * Short content-derived id, used as `EventFilterManifestEntry.payloadHash`
+ * and `WorkflowManifest.versionId`. 16 hex chars (~64 bits) — collision
+ * space is fine for human-friendly ids in dashboards/logs; the canonical
+ * full hash is `sha256(...)` if you need it.
+ */
+export async function shortHash(value: unknown): Promise<string> {
+  const full = await sha256(value)
+  return full.slice(0, 16)
+}
+
+/**
+ * Derive a stable event id from an envelope when `metadata.eventId` is
+ * absent. Mirrors the formula from architecture doc §15.2:
+ *
+ *     `${name}:${emittedAt}:${sha256(canonical(data)).slice(0, 12)}`
+ *
+ * Same envelope content always produces the same id — concurrent retries
+ * of the same external HTTP delivery dedupe at the driver's
+ * `${filterId}:${eventId}` idempotency key derivation.
+ *
+ * Returns a fallback id of the form `evt_<name>_<emittedAt>_<hash12>`
+ * (URL-safe; no colons in case the id flows through path segments).
+ */
+export async function deriveStableEventId(envelope: {
+  name: string
+  data: unknown
+  emittedAt: string
+}): Promise<string> {
+  const dataHash = (await sha256(envelope.data)).slice(0, 12)
+  const safeName = envelope.name.replace(/[^a-zA-Z0-9._-]/g, "_")
+  const safeAt = envelope.emittedAt.replace(/[^a-zA-Z0-9.]/g, "_")
+  return `evt_${safeName}_${safeAt}_${dataHash}`
+}
+
+// ---- Internal ----
+
+function getCrypto(): Crypto {
+  // `globalThis.crypto` is available on Node 19+, Workers, browsers.
+  // Any environment older than that needs a polyfill at the consumer level.
+  const c = (globalThis as { crypto?: Crypto }).crypto
+  if (!c?.subtle) {
+    throw new Error(
+      "@voyant-travel/workflows/events: globalThis.crypto.subtle is required for payload-hash. " +
+        "Polyfill via webcrypto on legacy runtimes.",
+    )
+  }
+  return c
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let out = ""
+  for (let i = 0; i < bytes.length; i++) {
+    out += (bytes[i] ?? 0).toString(16).padStart(2, "0")
+  }
+  return out
+}