@voyant-travel/workflows 0.107.10

package/dist/events/predicate.d.ts

@@ -0,0 +1,77 @@
+/** Either a path into the envelope or an inline literal value. */
+export type PathOrLit = {
+    path: string;
+} | {
+    lit: string | number | boolean | null;
+};
+export type PredicateExpr = {
+    eq: [PathOrLit, PathOrLit];
+} | {
+    neq: [PathOrLit, PathOrLit];
+} | {
+    in: [PathOrLit, PathOrLit[]];
+} | {
+    gt: [PathOrLit, PathOrLit];
+} | {
+    gte: [PathOrLit, PathOrLit];
+} | {
+    lt: [PathOrLit, PathOrLit];
+} | {
+    lte: [PathOrLit, PathOrLit];
+} | {
+    exists: PathOrLit;
+} | {
+    not: PredicateExpr;
+} | {
+    and: PredicateExpr[];
+} | {
+    or: PredicateExpr[];
+};
+/**
+ * Minimal structural envelope the evaluator reads. Matches the standard
+ * `EventEnvelope` from `@voyant-travel/core`. Declared structurally here so the
+ * SDK package stays a leaf.
+ */
+export interface PredicateEnvelope<TData = unknown> {
+    name: string;
+    data: TData;
+    metadata?: Record<string, unknown> | undefined;
+    emittedAt: string;
+}
+/**
+ * Evaluate a predicate against an event envelope. Returns `true` / `false`.
+ * Path resolution against missing keys yields `undefined`, which makes
+ * comparison ops `false` (not throw). The evaluator never throws on data
+ * mismatches — registration-time linting catches structural errors via
+ * {@link validatePredicate}.
+ *
+ * Throws `PredicateEvalError` only on unexpected shape errors (the predicate
+ * itself was constructed wrong, e.g. malformed operator). Drivers catch
+ * this and surface it as `IngestMatch.status === "skipped"` with reason
+ * `"where_eval_error"`.
+ */
+export declare function evaluatePredicate(expr: PredicateExpr, envelope: PredicateEnvelope): boolean;
+/**
+ * Resolve a path string against an envelope. Public so consumers (input
+ * mapper, manifest builder) can share the same path semantics without
+ * re-implementing them.
+ *
+ * Path syntax: dot-separated; `[N]` for array index; missing intermediate
+ * keys produce `undefined`. Roots: `data`, `metadata`, `name`, `emittedAt`.
+ *
+ * Returns `undefined` on any shape mismatch — that's how runtime evaluation
+ * stays no-throw.
+ */
+export declare function resolvePath(path: string, envelope: PredicateEnvelope): unknown;
+export interface PredicateValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Static structural check on a `PredicateExpr`. Catches path roots that
+ * aren't `data`/`metadata`/`name`/`emittedAt`, type mismatches on
+ * comparison operators (number vs string lhs/rhs), and malformed grammars.
+ * Surfaced at `trigger.on()` registration so authoring errors fail fast.
+ */
+export declare function validatePredicate(expr: PredicateExpr): PredicateValidationResult;
+//# sourceMappingURL=predicate.d.ts.map

package/dist/events/predicate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/events/predicate.ts"],"names":[],"mappings":"AAkBA,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;CAAE,CAAA;AAIpF,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CAAE,GAC9B;IAAE,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CAAE,GAC9B;IAAE,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CAAE,GAC9B;IAAE,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CAAE,GAC/B;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,GAAG,EAAE,aAAa,CAAA;CAAE,GACtB;IAAE,GAAG,EAAE,aAAa,EAAE,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,aAAa,EAAE,CAAA;CAAE,CAAA;AAI3B;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,KAAK,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAC9C,SAAS,EAAE,MAAM,CAAA;CAClB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAiC3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAkC9E;AAID,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,yBAAyB,CAIhF"}

package/dist/events/predicate.js

@@ -0,0 +1,347 @@
+// Predicate DSL — the structured `where` filter on EventFilterDeclaration.
+//
+// Closed grammar of 12 operators, evaluated against the standard
+// EventEnvelope shape (`data`, `metadata`, `name`, `emittedAt`). No `eval`,
+// no Function constructor, no callback-via-network — everything is data.
+//
+// Authoring shape (from a module's source):
+//
+//     trigger.on("promotion.changed", {
+//       target: bulkReindexProducts,
+//       where: { eq: [{ path: "data.affected.kind" }, { lit: "all" }] },
+//       input: { ... },
+//     })
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §13.1.
+// ---- Public API ----
+/**
+ * Evaluate a predicate against an event envelope. Returns `true` / `false`.
+ * Path resolution against missing keys yields `undefined`, which makes
+ * comparison ops `false` (not throw). The evaluator never throws on data
+ * mismatches — registration-time linting catches structural errors via
+ * {@link validatePredicate}.
+ *
+ * Throws `PredicateEvalError` only on unexpected shape errors (the predicate
+ * itself was constructed wrong, e.g. malformed operator). Drivers catch
+ * this and surface it as `IngestMatch.status === "skipped"` with reason
+ * `"where_eval_error"`.
+ */
+export function evaluatePredicate(expr, envelope) {
+    if ("eq" in expr) {
+        return strictEquals(resolveSide(expr.eq[0], envelope), resolveSide(expr.eq[1], envelope));
+    }
+    if ("neq" in expr) {
+        return !strictEquals(resolveSide(expr.neq[0], envelope), resolveSide(expr.neq[1], envelope));
+    }
+    if ("in" in expr) {
+        const lhs = resolveSide(expr.in[0], envelope);
+        const rhs = expr.in[1].map((item) => resolveSide(item, envelope));
+        return rhs.some((candidate) => strictEquals(lhs, candidate));
+    }
+    if ("gt" in expr)
+        return compareTwo(expr.gt, envelope, ">");
+    if ("gte" in expr)
+        return compareTwo(expr.gte, envelope, ">=");
+    if ("lt" in expr)
+        return compareTwo(expr.lt, envelope, "<");
+    if ("lte" in expr)
+        return compareTwo(expr.lte, envelope, "<=");
+    if ("exists" in expr) {
+        return resolveSide(expr.exists, envelope) !== undefined;
+    }
+    if ("not" in expr)
+        return !evaluatePredicate(expr.not, envelope);
+    if ("and" in expr) {
+        if (!Array.isArray(expr.and)) {
+            throw new PredicateEvalError("`and` clause must be an array of predicates");
+        }
+        return expr.and.every((sub) => evaluatePredicate(sub, envelope));
+    }
+    if ("or" in expr) {
+        if (!Array.isArray(expr.or)) {
+            throw new PredicateEvalError("`or` clause must be an array of predicates");
+        }
+        return expr.or.some((sub) => evaluatePredicate(sub, envelope));
+    }
+    throw new PredicateEvalError(`unknown predicate operator: ${stringify(expr)}`);
+}
+/**
+ * Resolve a path string against an envelope. Public so consumers (input
+ * mapper, manifest builder) can share the same path semantics without
+ * re-implementing them.
+ *
+ * Path syntax: dot-separated; `[N]` for array index; missing intermediate
+ * keys produce `undefined`. Roots: `data`, `metadata`, `name`, `emittedAt`.
+ *
+ * Returns `undefined` on any shape mismatch — that's how runtime evaluation
+ * stays no-throw.
+ */
+export function resolvePath(path, envelope) {
+    const segments = parsePath(path);
+    if (segments.length === 0)
+        return undefined;
+    const [root, ...rest] = segments;
+    let value;
+    switch (root) {
+        case "name":
+            value = envelope.name;
+            break;
+        case "emittedAt":
+            value = envelope.emittedAt;
+            break;
+        case "data":
+            value = envelope.data;
+            break;
+        case "metadata":
+            value = envelope.metadata;
+            break;
+        default:
+            // Unknown roots evaluate to undefined at runtime. Registration-time
+            // linter surfaces this as a structural error so callers see it earlier.
+            return undefined;
+    }
+    for (const segment of rest) {
+        if (value === undefined || value === null)
+            return undefined;
+        if (typeof segment === "number") {
+            if (!Array.isArray(value))
+                return undefined;
+            value = value[segment];
+        }
+        else {
+            if (typeof value !== "object")
+                return undefined;
+            value = value[segment];
+        }
+    }
+    return value;
+}
+/**
+ * Static structural check on a `PredicateExpr`. Catches path roots that
+ * aren't `data`/`metadata`/`name`/`emittedAt`, type mismatches on
+ * comparison operators (number vs string lhs/rhs), and malformed grammars.
+ * Surfaced at `trigger.on()` registration so authoring errors fail fast.
+ */
+export function validatePredicate(expr) {
+    const errors = [];
+    walk(expr, errors, []);
+    return { ok: errors.length === 0, errors };
+}
+function walk(expr, errors, path) {
+    if (typeof expr !== "object" || expr === null) {
+        errors.push(`${pathLabel(path)}: predicate must be an object, got ${typeof expr}`);
+        return;
+    }
+    const keys = Object.keys(expr);
+    if (keys.length !== 1) {
+        errors.push(`${pathLabel(path)}: a predicate object must have exactly one operator key, got ${keys.length} (${keys.join(", ")})`);
+        return;
+    }
+    const op = keys[0];
+    switch (op) {
+        case "eq":
+        case "neq":
+        case "gt":
+        case "gte":
+        case "lt":
+        case "lte": {
+            const raw = expr[op];
+            if (!Array.isArray(raw) || raw.length !== 2) {
+                errors.push(`${pathLabel([...path, op])}: expected [lhs, rhs] tuple`);
+                return;
+            }
+            const sides = raw;
+            validateSide(sides[0], errors, [...path, op, "0"]);
+            validateSide(sides[1], errors, [...path, op, "1"]);
+            // Type-sanity for ordered comparisons: both literals must be the same numeric/string flavor.
+            if (op !== "eq" && op !== "neq") {
+                const lhsLit = sideLitType(sides[0]);
+                const rhsLit = sideLitType(sides[1]);
+                if (lhsLit !== "unknown" &&
+                    rhsLit !== "unknown" &&
+                    lhsLit !== rhsLit &&
+                    (lhsLit === "number" || lhsLit === "string")) {
+                    errors.push(`${pathLabel([...path, op])}: ordered comparison sides must agree on type (got ${lhsLit} vs ${rhsLit})`);
+                }
+            }
+            return;
+        }
+        case "in": {
+            const tuple = expr.in;
+            if (!Array.isArray(tuple) || tuple.length !== 2) {
+                errors.push(`${pathLabel([...path, "in"])}: expected [lhs, rhs[]] tuple`);
+                return;
+            }
+            validateSide(tuple[0], errors, [...path, "in", "0"]);
+            if (!Array.isArray(tuple[1])) {
+                errors.push(`${pathLabel([...path, "in", "1"])}: rhs must be an array of paths/literals`);
+                return;
+            }
+            for (let i = 0; i < tuple[1].length; i++) {
+                const s = tuple[1][i];
+                validateSide(s, errors, [...path, "in", "1", String(i)]);
+            }
+            return;
+        }
+        case "exists":
+            validateSide(expr.exists, errors, [...path, "exists"]);
+            return;
+        case "not":
+            walk(expr.not, errors, [...path, "not"]);
+            return;
+        case "and":
+        case "or": {
+            const raw = expr[op];
+            if (!Array.isArray(raw)) {
+                errors.push(`${pathLabel([...path, op])}: ${op} must be an array of predicates`);
+                return;
+            }
+            const arr = raw;
+            for (let i = 0; i < arr.length; i++) {
+                const sub = arr[i];
+                walk(sub, errors, [...path, op, String(i)]);
+            }
+            return;
+        }
+        default:
+            errors.push(`${pathLabel(path)}: unknown predicate operator "${String(op)}"`);
+    }
+}
+function validateSide(side, errors, path) {
+    if (typeof side !== "object" || side === null) {
+        errors.push(`${pathLabel(path)}: expected { path } or { lit }, got ${typeof side}`);
+        return;
+    }
+    if ("path" in side) {
+        if (typeof side.path !== "string" || side.path.length === 0) {
+            errors.push(`${pathLabel(path)}: "path" must be a non-empty string`);
+            return;
+        }
+        const root = parsePath(side.path)[0];
+        if (root !== "data" && root !== "metadata" && root !== "name" && root !== "emittedAt") {
+            errors.push(`${pathLabel(path)}: path root "${String(root)}" is not one of data | metadata | name | emittedAt`);
+        }
+        return;
+    }
+    if ("lit" in side) {
+        const t = typeof side.lit;
+        if (t !== "string" && t !== "number" && t !== "boolean" && side.lit !== null) {
+            errors.push(`${pathLabel(path)}: lit must be string | number | boolean | null`);
+        }
+        return;
+    }
+    errors.push(`${pathLabel(path)}: must specify "path" or "lit"`);
+}
+// ---- Internal helpers ----
+class PredicateEvalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PredicateEvalError";
+    }
+}
+function resolveSide(side, envelope) {
+    if ("lit" in side)
+        return side.lit;
+    if ("path" in side)
+        return resolvePath(side.path, envelope);
+    return undefined;
+}
+function strictEquals(a, b) {
+    if (a === undefined || b === undefined)
+        return false;
+    if (a === null && b === null)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === "object") {
+        // Strict equality only for primitives + null. Object equality is not
+        // supported in v1; users who need it project specific paths to compare.
+        return false;
+    }
+    return a === b;
+}
+function compareTwo(sides, envelope, op) {
+    const lhs = resolveSide(sides[0], envelope);
+    const rhs = resolveSide(sides[1], envelope);
+    if (lhs === undefined || rhs === undefined)
+        return false;
+    if (typeof lhs !== typeof rhs)
+        return false;
+    if (typeof lhs !== "number" && typeof lhs !== "string")
+        return false;
+    switch (op) {
+        case ">":
+            return lhs > rhs;
+        case ">=":
+            return lhs >= rhs;
+        case "<":
+            return lhs < rhs;
+        case "<=":
+            return lhs <= rhs;
+    }
+}
+function sideLitType(side) {
+    if ("lit" in side) {
+        if (side.lit === null)
+            return "null";
+        const t = typeof side.lit;
+        if (t === "number" || t === "string" || t === "boolean")
+            return t;
+    }
+    return "unknown";
+}
+/**
+ * Parse a dot-and-bracket path into segments. `data.items[0].id` becomes
+ * `["data", "items", 0, "id"]`. Numeric segments inside `[N]` are returned
+ * as numbers; everything else as strings. Malformed input yields `[]`.
+ */
+function parsePath(path) {
+    if (typeof path !== "string" || path.length === 0)
+        return [];
+    const segments = [];
+    let i = 0;
+    let buf = "";
+    const flushBuf = () => {
+        if (buf.length > 0) {
+            segments.push(buf);
+            buf = "";
+        }
+    };
+    while (i < path.length) {
+        const c = path[i];
+        if (c === ".") {
+            flushBuf();
+            i++;
+            continue;
+        }
+        if (c === "[") {
+            flushBuf();
+            const end = path.indexOf("]", i);
+            if (end === -1)
+                return [];
+            const idx = Number(path.slice(i + 1, end));
+            if (!Number.isInteger(idx) || idx < 0)
+                return [];
+            segments.push(idx);
+            i = end + 1;
+            continue;
+        }
+        buf += c;
+        i++;
+    }
+    flushBuf();
+    return segments;
+}
+function pathLabel(path) {
+    return path.length === 0 ? "(root)" : path.join(".");
+}
+function stringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/events/registry.d.ts

@@ -0,0 +1,37 @@
+import type { EventFilterManifestEntry } from "../protocol/index.js";
+import type { EventFilterDeclaration } from "../trigger.js";
+/**
+ * Internal/runtime form of a registered event filter. Carries:
+ *   - The serializable manifest entry (sent to drivers, persisted in
+ *     manifest stores, evaluated by the event router).
+ *   - A debug-only structural copy of the original declaration. Not
+ *     serialized; used by the dashboard / dev mode for human-readable
+ *     filter inspection.
+ *
+ * Concrete `WorkflowDefinition` from `workflow.ts` satisfies the structural
+ * `target` shape via TypeScript compat.
+ */
+export interface EventFilterRuntimeEntry {
+    readonly id: string;
+    readonly eventType: string;
+    readonly manifest: EventFilterManifestEntry;
+    /** Debug-only — non-serializable. */
+    readonly declaration: EventFilterDeclaration<unknown>;
+    /** Workflow id this filter targets, for quick lookup. */
+    readonly targetWorkflowId: string;
+}
+interface EventFilterRegistry {
+    add(entry: EventFilterRuntimeEntry): void;
+    list(): EventFilterRuntimeEntry[];
+    /** Reset to empty. Test-only — production code never calls this. */
+    reset(): void;
+}
+/** Process-local event-filter registry. Singleton per realm. */
+export declare function getEventFilterRegistry(): EventFilterRegistry;
+/**
+ * Internal: clear every registered filter. Used by tests that import the
+ * SDK and need a clean slate between cases. Not part of the public API.
+ */
+export declare function __resetEventFilterRegistry(): void;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/events/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/events/registry.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAI3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAA;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAA;IACrD,yDAAyD;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,UAAU,mBAAmB;IAC3B,GAAG,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAA;IACzC,IAAI,IAAI,uBAAuB,EAAE,CAAA;IACjC,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAAA;CACd;AA8BD,gEAAgE;AAChE,wBAAgB,sBAAsB,IAAI,mBAAmB,CAE5D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/events/registry.js

@@ -0,0 +1,47 @@
+// Process-local registry for event-filter runtime entries.
+//
+// `trigger.on(eventName, filter)` adds an entry here at module-load time.
+// `createApp()` (PR4) walks `getEventFilterRegistry().list()` to build a
+// manifest, hand it to the configured driver, and install the EventBus
+// forwarder.
+//
+// Backed by `globalThis` so bundles that inline their own copy of
+// `@voyant-travel/workflows` still share the registry with the loader's copy
+// — same pattern `getWorkflow()` uses for the workflow registry.
+//
+// Architecture: docs/architecture/workflows-runtime-architecture.md §12.
+const REGISTRY_KEY = "__voyantEventFilterRegistry";
+const globalRef = globalThis;
+const REGISTRY = globalRef[REGISTRY_KEY] ?? new Map();
+globalRef[REGISTRY_KEY] = REGISTRY;
+const registry = {
+    add(entry) {
+        if (REGISTRY.has(entry.id)) {
+            // Same id implies same canonicalized declaration. HMR re-imports
+            // and re-evaluations of the same module file land here; replace
+            // (overwrite is harmless since the entry is content-addressed).
+            // For genuine duplicates from different declarations, the canonical
+            // hash would differ, so different ids would result.
+            REGISTRY.set(entry.id, entry);
+            return;
+        }
+        REGISTRY.set(entry.id, entry);
+    },
+    list() {
+        return [...REGISTRY.values()];
+    },
+    reset() {
+        REGISTRY.clear();
+    },
+};
+/** Process-local event-filter registry. Singleton per realm. */
+export function getEventFilterRegistry() {
+    return registry;
+}
+/**
+ * Internal: clear every registered filter. Used by tests that import the
+ * SDK and need a clean slate between cases. Not part of the public API.
+ */
+export function __resetEventFilterRegistry() {
+    registry.reset();
+}

package/dist/handler/index.d.ts

@@ -0,0 +1,114 @@
+import { type ExecuteWorkflowStepRequest, type ExecuteWorkflowStepResponse, executeWorkflowStep, type StepRunner } from "../runtime/executor.js";
+export type { StepJournalEntry } from "../runtime/journal.js";
+export type { ExecuteWorkflowStepRequest, ExecuteWorkflowStepResponse, StepRunner };
+export { executeWorkflowStep };
+import { type ProtocolVersion, type WorkflowActivationMetadata } from "../protocol/index.js";
+import type { RateLimiter } from "../rate-limit/index.js";
+import type { JournalSlice } from "../runtime/journal.js";
+import type { RunTrigger } from "../types.js";
+export interface StepHandlerDeps {
+    /**
+     * Optional. Called before parsing the body. Should throw / reject
+     * if the request is not from a trusted orchestrator. In production
+     * this verifies the `X-Voyant-Dispatch-Auth` HMAC against a public
+     * key embedded by `voyant build`.
+     */
+    verifyRequest?: (req: Request) => void | Promise<void>;
+    /** Injectable clock. Defaults to Date.now. */
+    now?: () => number;
+    /** Optional structured logger. */
+    logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+    /**
+     * Rate limiter shared across step invocations. Required when any
+     * registered workflow declares `options.rateLimit` on a step; see
+     * `createInMemoryRateLimiter` in `@voyant-travel/workflows/rate-limit` for
+     * the reference impl. One instance per Worker process is the
+     * intended cardinality — state is kept in the limiter's closure.
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * Runner for steps declared with `options.runtime === "node"`.
+     * Leave unset for handlers that only run edge steps; any node step
+     * will then fail with `NODE_RUNTIME_UNAVAILABLE`.
+     *
+     * Typical impl dispatches to a separate sandboxed context:
+     *   - Local dev: an in-process passthrough (same Node process).
+     *   - CF production: a Cloudflare Container binding, via
+     *     `createCfContainerStepRunner` from `@voyant-travel/workflows-orchestrator-cloudflare`.
+     *
+     * This is bring-your-own because the right dispatch shape depends on
+     * the target runtime; the executor only cares that a runner exists.
+     */
+    nodeStepRunner?: StepRunner;
+    /**
+     * Read-only service resolver, surfaced to step bodies as `ctx.services`.
+     * The framework's `createApp()` wires this from its `ModuleContainer`;
+     * raw orchestrator harnesses (tests, ad-hoc scripts) typically leave
+     * it unset, in which case `ctx.services.resolve(...)` throws with a
+     * clear message. See architecture doc §11.
+     */
+    services?: import("../driver.js").ServiceResolver;
+}
+/** The HTTP request body the orchestrator sends. */
+export interface WorkflowStepRequest {
+    protocolVersion: ProtocolVersion;
+    runId: string;
+    workflowId: string;
+    workflowVersion: string;
+    invocationCount: number;
+    input: unknown;
+    journal: JournalSlice;
+    environment: "production" | "preview" | "development";
+    deadline: number;
+    tenantMeta: {
+        tenantId: string;
+        projectId: string;
+        organizationId: string;
+        projectSlug?: string;
+        organizationSlug?: string;
+    };
+    runMeta: {
+        number: number;
+        attempt: number;
+        triggeredBy: RunTrigger;
+        tags: string[];
+        startedAt: number;
+    };
+    activation?: WorkflowActivationMetadata;
+}
+/** The JSON response body the tenant returns. */
+export type WorkflowStepResponse = ExecuteWorkflowStepResponse;
+/** Error-response envelope used for HTTP 4xx/5xx. */
+export interface StepHandlerError {
+    error: string;
+    message: string;
+    details?: unknown;
+}
+export { type BuildResumeStepRequestInput, type BuildResumeStepRequestResult, buildResumeStepRequest, } from "./resume.js";
+/** Build an HTTP fetch-style handler. */
+export declare function createStepHandler(deps?: StepHandlerDeps): (req: Request) => Promise<Response>;
+/** Per-invocation options available to callers of the transport-free entry point. */
+export interface StepRequestOptions {
+    /** AbortSignal forwarded to `ctx.signal` inside the step body. */
+    signal?: AbortSignal;
+    /**
+     * Fires synchronously from `ctx.stream.*` as each chunk is produced.
+     * Used by orchestrators that want to broadcast chunks live
+     * (dashboards, queues) before the invocation returns.
+     */
+    onStreamChunk?: (chunk: import("../runtime/executor.js").StreamChunk) => void;
+}
+/**
+ * Transport-free entry point. Callers that already parsed the body
+ * (e.g. local orchestrator in-memory, tests) invoke this directly.
+ * Returns either the step response or an error envelope with the HTTP
+ * status the caller should use.
+ */
+export declare function handleStepRequest(raw: unknown, deps?: StepHandlerDeps, opts?: StepRequestOptions): Promise<{
+    status: number;
+    body: WorkflowStepResponse;
+} | {
+    status: number;
+    body: StepHandlerError;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/handler/index.d.ts.map

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