@voyantjs/workflows 0.28.3 → 0.29.0

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,97 @@
+// 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,
+  WorkflowManifest,
+  WorkflowManifestEntry,
+} from "../protocol/index.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?: { defaultRuntime?: "edge" | "node"; retry?: unknown; timeout?: unknown }
+  }>
+  /** 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
+}
+
+/**
+ * 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 ?? "@voyantjs/workflows@manifest-builder/v1"
+  const projectId = args.projectId ?? "default"
+
+  const workflows: WorkflowManifestEntry[] = args.workflows
+    .map((wf) => ({
+      id: wf.id,
+      version: "v1",
+      steps: [],
+      schedules: [],
+      defaultRuntime: wf.config?.defaultRuntime ?? "edge",
+      hasCompensation: false,
+      sourceLocation: { file: "<runtime>", line: 0 },
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id))
+
+  // Sort filters by id so the canonical form is order-independent.
+  const eventFilters: EventFilterManifestEntry[] = args.eventFilters
+    .map((entry) => entry.manifest)
+    .sort((a, b) => a.id.localeCompare(b.id))
+
+  const draft: Omit<WorkflowManifest, "versionId"> & { versionId?: string } = {
+    schemaVersion: 1,
+    projectId,
+    builtAt,
+    builderVersion,
+    capabilities: ["events:v1"],
+    workflows,
+    eventFilters,
+    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,
+    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,
+  }
+}

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(
+      "@voyantjs/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
+}