@voyantjs/workflows 0.28.3 → 0.29.0

package/src/driver.ts

@@ -0,0 +1,277 @@
+// The WorkflowDriver contract.
+//
+// A driver is the runtime-side object that backs `createApp({ workflows })`:
+// it owns manifest registration, run triggering, event ingest, and (optionally)
+// admin reads. Concrete drivers live in downstream packages
+// (`@voyantjs/workflows-orchestrator` for InMemory, `-node` for Mode 2 / Postgres,
+// `-cloudflare` for Mode 1 / DO+KV).
+//
+// Drivers are constructed via *factories* — `DriverFactory` is a function the
+// framework invokes after `createApp()` has assembled its `ModuleContainer`.
+// This lets concrete factories accept their environment-specific options
+// (DO namespaces, DB pool, etc.) at user-call time and receive framework
+// deps (services, logger, …) at boot time, without a setter API.
+//
+// Authoritative architecture: docs/architecture/workflows-runtime-architecture.md §6.
+
+import type { WorkflowManifest } from "./protocol/index.js"
+import type { ListRunsOptions, Run, RunDetail, RunSummary, TriggerOptions } from "./trigger.js"
+import type { EnvironmentName, WaitpointKind } from "./types.js"
+import type { WorkflowDefinition } from "./workflow.js"
+
+// ---- Structural deps (kept local to avoid an @voyantjs/core dep here) ----
+
+/**
+ * Read-only view of a service container. Step bodies resolve services via
+ * `ctx.services.resolve(...)`. The framework's `ModuleContainer`
+ * (in `@voyantjs/core`) satisfies this shape structurally; we don't import
+ * it directly to keep `@voyantjs/workflows` a leaf package.
+ */
+export interface ServiceResolver {
+  resolve<T>(name: string): T
+  has(name: string): boolean
+}
+
+/**
+ * Structural shape of an event envelope as ingested by a driver. Matches
+ * `EventEnvelope` from `@voyantjs/core` (`name`, `data`, `metadata?`, `emittedAt`),
+ * declared structurally so the SDK package doesn't import core.
+ */
+export interface IngestEventEnvelope<TData = unknown> {
+  /** Event name in `<resource>.<pastTenseAction>` form. */
+  name: string
+  /** Business payload. */
+  data: TData
+  /** Optional metadata. `metadata.eventId` is the canonical idempotency seed
+   *  (a fresh ULID, stamped by the framework's EventBus forwarder). External
+   *  callers may supply their own. See architecture doc §15.2. */
+  metadata?: Record<string, unknown> & { eventId?: string }
+  /** ISO timestamp string. */
+  emittedAt: string
+}
+
+/**
+ * Minimal logger contract drivers can rely on. Matches the framework logger's
+ * call signature without taking a hard dependency on it.
+ */
+export type DriverLogger = (
+  level: "debug" | "info" | "warn" | "error",
+  msg: string,
+  data?: object,
+) => void
+
+// ---- Driver-factory wiring ----
+
+/**
+ * Deps the framework injects into a `DriverFactory` at boot. Driver factories
+ * close over their environment-specific options (DO bindings, DB pool, etc.)
+ * and read framework deps from this argument.
+ */
+export interface DriverFactoryDeps {
+  /** Read-only view of the framework's `ModuleContainer`. */
+  services: ServiceResolver
+  /** Framework logger. */
+  logger: DriverLogger
+  /** Injectable clock — defaults to `() => Date.now()`. */
+  now?: () => number
+}
+
+/**
+ * Concrete driver factories return this. `createApp()` calls it once, after
+ * the container is built, to obtain the `WorkflowDriver`.
+ */
+export type DriverFactory = (deps: DriverFactoryDeps) => WorkflowDriver
+
+// ---- Event ingest types ----
+
+/**
+ * Argument to `driver.ingestEvent(...)`. The framework's EventBus forwarder
+ * builds this from the core `EventEnvelope`; external HTTP callers (the
+ * optional ingest adapter, voyant-cloud) build it from a wire payload.
+ */
+export interface IngestEventArgs {
+  environment: EnvironmentName
+  envelope: IngestEventEnvelope
+  /** Optional caller-supplied idempotency override. When absent, the driver
+   *  derives a key per match from `metadata.eventId` (or a content hash
+   *  fallback). See architecture doc §15.2. */
+  idempotencyKey?: string
+}
+
+/** Per-filter outcome from a single `ingestEvent` call. */
+export type IngestMatch =
+  | {
+      filterId: string
+      targetWorkflowId: string
+      runId: string
+      idempotencyKey: string
+      status: "queued"
+    }
+  | {
+      filterId: string
+      status: "skipped"
+      reason: "where_eval_error" | "input_projection_error" | "input_schema_violation"
+      details?: string
+    }
+  | {
+      filterId: string
+      targetWorkflowId: string
+      status: "error"
+      reason: string
+    }
+
+export type IngestEventResponse =
+  | {
+      ok: true
+      eventId: string
+      matches: IngestMatch[]
+    }
+  | {
+      ok: false
+      reason:
+        | "manifest_not_registered"
+        | "environment_mismatch"
+        | "payload_too_large"
+        | "trigger_failed_for_all_matches"
+      message?: string
+    }
+
+// ---- Driver — execution contract ----
+
+/**
+ * The mandatory driver contract. Every concrete driver — InMemory, Mode 2
+ * (Postgres), Mode 1 (CF edge) — implements all five methods. The compliance
+ * test suite (`driver-compliance.test.ts`) is the contract.
+ */
+export interface WorkflowDriver {
+  /**
+   * Idempotent. Same manifest body returns the same `versionId` across calls.
+   * Failures are NOT swallowed — `createApp()`'s bootstrap surfaces rejections
+   * (see architecture doc §21.22).
+   */
+  registerManifest(args: {
+    environment: EnvironmentName
+    manifest: WorkflowManifest
+  }): Promise<{ versionId: string }>
+
+  /**
+   * Trigger a workflow run by id or definition handle. Honors
+   * `opts.idempotencyKey` for dedup (returns the existing run on conflict).
+   */
+  trigger<TIn, TOut>(
+    workflow: WorkflowDefinition<TIn, TOut> | string,
+    input: TIn,
+    opts?: TriggerOptions,
+  ): Promise<Run<TOut>>
+
+  /**
+   * Ingest one event. Synchronously (from the caller's POV) loads the
+   * registered manifest, evaluates `where`, projects `input`, and triggers
+   * one run per match. See architecture doc §15.
+   */
+  ingestEvent(args: IngestEventArgs): Promise<IngestEventResponse>
+
+  /**
+   * Read the registered manifest. Used at boot for version-mismatch detection
+   * and by the dashboard for filter inspection.
+   */
+  getManifest(args: { environment: EnvironmentName }): Promise<WorkflowManifest | null>
+
+  /**
+   * Optional. Drains in-flight steps, refuses new triggers, awaits time-wheel
+   * exit. Default `gracefulMs` is 30_000.
+   */
+  shutdown?(opts?: { gracefulMs?: number }): Promise<void>
+
+  /**
+   * Optional read-side surface. Drivers that can support listings, run detail,
+   * and journal streams declare this; consumers (the dashboard) duck-type on
+   * `driver.admin`. See architecture doc §6.2.
+   */
+  admin?: WorkflowAdmin | Partial<WorkflowAdmin>
+}
+
+// ---- Driver — admin (optional) ----
+
+/**
+ * Read-side operations. Implemented natively by the Mode 2 driver against
+ * Postgres, partially by Mode 1 (single-run reads only — `listRuns` is not
+ * implemented in self-host Mode 1; voyant-cloud provides an index layer).
+ * See architecture doc §6.2 + §8.3.
+ */
+export interface WorkflowAdmin {
+  listRuns(opts?: ListRunsOptions): Promise<{ runs: RunSummary[]; nextCursor?: string }>
+  getRun(runId: string): Promise<RunDetail | null>
+  cancelRun(runId: string, opts?: { reason?: string; compensate?: boolean }): Promise<void>
+  /**
+   * Subscribe to journal events for a run. The async-iterable shape lets
+   * dashboards stream live without polling.
+   */
+  streamRun(runId: string): AsyncIterable<AdminStreamEvent>
+}
+
+/**
+ * The admin streaming surface re-uses the protocol's `StreamEvent` for
+ * step/waitpoint/log events; this type is its alias to keep the import
+ * surface narrow.
+ */
+export type AdminStreamEvent =
+  | { kind: "run.snapshot"; at: number; status: string; metadata: Record<string, unknown> }
+  | { kind: "step.started"; at: number; stepId: string; runtime: "edge" | "node" }
+  | { kind: "step.ok"; at: number; stepId: string; durationMs: number }
+  | { kind: "step.err"; at: number; stepId: string; error: { code: string; message: string } }
+  | { kind: "waitpoint.registered"; at: number; waitpointId: string; waitpointKind: WaitpointKind }
+  | { kind: "waitpoint.resolved"; at: number; waitpointId: string }
+  | { kind: "log"; at: number; level: "info" | "warn" | "error"; message: string }
+  | { kind: "run.finished"; at: number; status: string }
+
+// ---- Errors ----
+
+/**
+ * Base class for typed driver errors. Concrete subclasses below; consumers
+ * `instanceof` to handle specific cases.
+ */
+export class WorkflowDriverError extends Error {
+  readonly code: string
+  readonly cause?: unknown
+
+  constructor(code: string, message: string, opts?: { cause?: unknown }) {
+    super(message)
+    this.name = "WorkflowDriverError"
+    this.code = code
+    this.cause = opts?.cause
+  }
+}
+
+export class ManifestNotRegisteredError extends WorkflowDriverError {
+  constructor(environment: EnvironmentName) {
+    super(
+      "manifest_not_registered",
+      `No manifest is registered for environment "${environment}". ` +
+        `createApp() must complete its bootstrap before driver.ingestEvent(...) can fire.`,
+    )
+    this.name = "ManifestNotRegisteredError"
+  }
+}
+
+export class EventTooLargeError extends WorkflowDriverError {
+  readonly bytes: number
+  readonly limit: number
+
+  constructor(bytes: number, limit = 256 * 1024) {
+    super("payload_too_large", `Event payload is ${bytes} bytes, exceeding the ${limit}-byte cap.`)
+    this.name = "EventTooLargeError"
+    this.bytes = bytes
+    this.limit = limit
+  }
+}
+
+export class EnvironmentMismatchError extends WorkflowDriverError {
+  constructor(eventEnv: EnvironmentName, manifestEnv: EnvironmentName) {
+    super(
+      "environment_mismatch",
+      `Event environment "${eventEnv}" does not match the registered manifest's environment "${manifestEnv}".`,
+    )
+    this.name = "EnvironmentMismatchError"
+  }
+}

package/src/events/compile.ts

@@ -0,0 +1,268 @@
+// Compile an `EventFilterDeclaration` (authored in user code) into an
+// `EventFilterRuntimeEntry`. Validates the predicate + mapper at
+// registration time so authoring errors fail fast; computes the
+// content-derived `id` / `payloadHash` so the manifest is deterministic.
+//
+// Called from `trigger.on(...)` in `../trigger.js`.
+
+import type { EventFilterManifestEntry } from "../protocol/index.js"
+import type { EventFilterDeclaration } from "../trigger.js"
+import { type InputMapper, validateInputMapper } from "./input-mapper.js"
+import { canonicalJson, sha256 } from "./payload-hash.js"
+import { type PredicateExpr, validatePredicate } from "./predicate.js"
+import { type EventFilterRuntimeEntry, getEventFilterRegistry } from "./registry.js"
+
+export class EventFilterCompileError extends Error {
+  readonly errors: string[]
+
+  constructor(message: string, errors: string[] = []) {
+    super(message)
+    this.name = "EventFilterCompileError"
+    this.errors = errors
+  }
+}
+
+/**
+ * Compile an authored declaration into a runtime entry. Throws
+ * `EventFilterCompileError` on shape errors so authoring problems fail
+ * at module-load time.
+ */
+export async function compileEventFilter<T>(
+  eventType: string,
+  declaration: EventFilterDeclaration<T>,
+): Promise<EventFilterRuntimeEntry> {
+  if (typeof eventType !== "string" || eventType.length === 0) {
+    throw new EventFilterCompileError(
+      `trigger.on(eventType, ...): eventType must be a non-empty string`,
+    )
+  }
+  if (typeof declaration !== "object" || declaration === null) {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}", ...): declaration must be an object`,
+    )
+  }
+  if (!declaration.target || typeof declaration.target !== "object") {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}", ...): "target" must be a workflow definition (got ${typeof declaration.target})`,
+    )
+  }
+  const targetWorkflowId =
+    typeof (declaration.target as { id?: unknown }).id === "string"
+      ? (declaration.target as { id: string }).id
+      : ""
+  if (targetWorkflowId.length === 0) {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}", ...): "target.id" must be a non-empty string`,
+    )
+  }
+
+  // Validate `where` if supplied.
+  const where = (declaration as { where?: PredicateExpr }).where
+  if (where !== undefined) {
+    const result = validatePredicate(where)
+    if (!result.ok) {
+      throw new EventFilterCompileError(
+        `trigger.on("${eventType}", target=${targetWorkflowId}): invalid where clause`,
+        result.errors,
+      )
+    }
+  }
+
+  // Validate `input` if supplied.
+  const input = (declaration as { input?: InputMapper }).input
+  if (input !== undefined) {
+    const result = validateInputMapper(input)
+    if (!result.ok) {
+      throw new EventFilterCompileError(
+        `trigger.on("${eventType}", target=${targetWorkflowId}): invalid input mapper`,
+        result.errors,
+      )
+    }
+  }
+
+  // Reject the legacy `match` callback explicitly so authoring errors are obvious.
+  if (typeof (declaration as { match?: unknown }).match === "function") {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}"): the "match" callback is no longer supported. ` +
+        `Use the structured "where" predicate instead. See architecture doc §12.`,
+    )
+  }
+
+  // Canonical content-derived id. Stable across re-deploys because the
+  // canonicalized JSON of the declaration is identical for byte-equivalent
+  // sources.
+  const canonicalDeclaration = {
+    eventType,
+    where: where ?? null,
+    input: input ?? null,
+    targetWorkflowId,
+  }
+  const fullHash = await sha256(canonicalDeclaration)
+  const payloadHash = fullHash
+  // Filter id seeds from the same hash but stays human-friendly in logs.
+  const id = `ef_${fullHash.slice(0, 16)}`
+
+  const manifest: EventFilterManifestEntry = {
+    id,
+    eventType,
+    payloadHash,
+    targetWorkflowId,
+    ...(where !== undefined ? { where } : {}),
+    ...(input !== undefined ? { input } : {}),
+  }
+
+  const entry: EventFilterRuntimeEntry = {
+    id,
+    eventType,
+    manifest,
+    declaration: declaration as EventFilterDeclaration<unknown>,
+    targetWorkflowId,
+  }
+  return entry
+}
+
+/**
+ * Compile + register in one step. The synchronous wrapper for `trigger.on()`
+ * that user code calls — validates the declaration, computes the
+ * content-derived id, registers the entry, and returns it.
+ *
+ * Returning the full {@link EventFilterRuntimeEntry} is what makes the
+ * authoring shape from the architecture doc work directly — modules can
+ * write `eventFilters: [trigger.on(...)]` without a registry round-trip:
+ * the entry already structurally satisfies `EventFilterDescriptor`
+ * (matching `id` + `eventType` fields) and carries the `manifest` payload
+ * `createApp()`'s wireWorkflowRuntime needs to register with the driver.
+ */
+export function compileAndRegister<T>(
+  eventType: string,
+  declaration: EventFilterDeclaration<T>,
+): EventFilterRuntimeEntry {
+  // Run validation + compile synchronously where possible. The async
+  // boundary is the SHA-256 digest from Web Crypto; we bridge via a
+  // synchronous canonical-JSON hash so trigger.on() can stay sync.
+  const entry = compileEventFilterSync(eventType, declaration)
+  getEventFilterRegistry().add(entry)
+  return entry
+}
+
+/**
+ * Synchronous compile — uses a deterministic but non-cryptographic hash
+ * over the canonical JSON. Suitable for the registry id (we just need
+ * stable + collision-resistant-enough across realistic registration
+ * counts). The crypto-grade `sha256(...)` is used at *manifest build*
+ * time when async is fine.
+ */
+export function compileEventFilterSync<T>(
+  eventType: string,
+  declaration: EventFilterDeclaration<T>,
+): EventFilterRuntimeEntry {
+  if (typeof eventType !== "string" || eventType.length === 0) {
+    throw new EventFilterCompileError(
+      `trigger.on(eventType, ...): eventType must be a non-empty string`,
+    )
+  }
+  if (typeof declaration !== "object" || declaration === null) {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}", ...): declaration must be an object`,
+    )
+  }
+  if (!declaration.target || typeof declaration.target !== "object") {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}", ...): "target" must be a workflow definition (got ${typeof declaration.target})`,
+    )
+  }
+  const targetWorkflowId =
+    typeof (declaration.target as { id?: unknown }).id === "string"
+      ? (declaration.target as { id: string }).id
+      : ""
+  if (targetWorkflowId.length === 0) {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}", ...): "target.id" must be a non-empty string`,
+    )
+  }
+
+  const where = (declaration as { where?: PredicateExpr }).where
+  if (where !== undefined) {
+    const result = validatePredicate(where)
+    if (!result.ok) {
+      throw new EventFilterCompileError(
+        `trigger.on("${eventType}", target=${targetWorkflowId}): invalid where clause`,
+        result.errors,
+      )
+    }
+  }
+
+  const input = (declaration as { input?: InputMapper }).input
+  if (input !== undefined) {
+    const result = validateInputMapper(input)
+    if (!result.ok) {
+      throw new EventFilterCompileError(
+        `trigger.on("${eventType}", target=${targetWorkflowId}): invalid input mapper`,
+        result.errors,
+      )
+    }
+  }
+
+  if (typeof (declaration as { match?: unknown }).match === "function") {
+    throw new EventFilterCompileError(
+      `trigger.on("${eventType}"): the "match" callback is no longer supported. ` +
+        `Use the structured "where" predicate instead. See architecture doc §12.`,
+    )
+  }
+
+  const canonicalDeclaration = {
+    eventType,
+    where: where ?? null,
+    input: input ?? null,
+    targetWorkflowId,
+  }
+  const json = canonicalJson(canonicalDeclaration)
+  const shortId = nonCryptoHash16(json)
+  const id = `ef_${shortId}`
+
+  const manifest: EventFilterManifestEntry = {
+    id,
+    eventType,
+    // payloadHash on the manifest is stable (same canonical JSON) but
+    // upgraded to the crypto-grade sha256 at manifest-build time. Until
+    // then it carries the same short hash so consumers that read it pre-
+    // build (e.g. dashboards in dev mode) still see something sensible.
+    payloadHash: shortId,
+    targetWorkflowId,
+    ...(where !== undefined ? { where } : {}),
+    ...(input !== undefined ? { input } : {}),
+  }
+
+  return {
+    id,
+    eventType,
+    manifest,
+    declaration: declaration as EventFilterDeclaration<unknown>,
+    targetWorkflowId,
+  }
+}
+
+/**
+ * Deterministic 16-hex-char hash for synchronous registration. Uses FNV-1a
+ * 64-bit folded into hex — collision-resistant enough at the cardinality of
+ * "filters per project" (low thousands at most). The cryptographic SHA-256
+ * is the source of truth for manifest-level identity; this is just enough
+ * to be a stable id for the in-process registry.
+ */
+function nonCryptoHash16(text: string): string {
+  // FNV-1a 64-bit, computed as two 32-bit halves to avoid bigint overhead
+  // in tight loops. Output: 16 hex chars (concatenation of the two halves).
+  let h1 = 0xcbf29ce4
+  let h2 = 0x84222325
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i)
+    h1 = (h1 ^ c) >>> 0
+    h2 = (h2 ^ c) >>> 0
+    // Multiply by 0x100000001b3 split into the two halves.
+    const lo = h2 * 0x01b3
+    const hi = h1 * 0x01b3 + Math.floor(lo / 0x100000000)
+    h2 = (lo & 0xffffffff) >>> 0
+    h1 = hi >>> 0
+  }
+  return h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0")
+}

package/src/events/index.ts

@@ -0,0 +1,42 @@
+// `@voyantjs/workflows/events` — the events runtime: structured `where`
+// predicate + `input` mapper, event-filter registry, manifest builder.
+//
+// Authoritative architecture: docs/architecture/workflows-runtime-architecture.md
+// §12 (trigger.on runtime), §13 (DSLs), §14 (manifest lifecycle).
+
+export {
+  compileAndRegister,
+  compileEventFilterSync,
+  EventFilterCompileError,
+} from "./compile.js"
+export type { InputMapper } from "./input-mapper.js"
+export {
+  type InputMapperValidationResult,
+  projectInput,
+  validateInputMapper,
+} from "./input-mapper.js"
+export {
+  type BuildManifestArgs,
+  buildManifest,
+} from "./manifest-builder.js"
+export {
+  canonicalize,
+  canonicalJson,
+  deriveStableEventId,
+  sha256,
+  shortHash,
+} from "./payload-hash.js"
+export {
+  evaluatePredicate,
+  type PathOrLit,
+  type PredicateEnvelope,
+  type PredicateExpr,
+  type PredicateValidationResult,
+  resolvePath,
+  validatePredicate,
+} from "./predicate.js"
+export {
+  __resetEventFilterRegistry,
+  type EventFilterRuntimeEntry,
+  getEventFilterRegistry,
+} from "./registry.js"