@voyantjs/workflows 0.6.7 → 0.6.9

package/dist/protocol/index.d.ts

@@ -0,0 +1,187 @@
+export type ProtocolVersion = 1;
+export declare const PROTOCOL_VERSION: ProtocolVersion;
+export type { CompensationJournalEntry, JournalSlice, StepJournalEntry, WaitpointResolutionEntry, } from "../runtime/journal.js";
+export type ExecutionStatus = "CREATED" | "QUEUED" | "EXECUTING" | "EXECUTING_WITH_WAITPOINTS" | "SUSPENDED" | "PENDING_CANCEL" | "FINISHED";
+export type WaitpointKind = "DATETIME" | "EVENT" | "SIGNAL" | "RUN" | "MANUAL";
+export interface SerializedError {
+    category: "USER_ERROR" | "RUNTIME_ERROR";
+    code: string;
+    message: string;
+    name?: string;
+    stack?: string;
+    cause?: SerializedError;
+    data?: Record<string, unknown>;
+}
+export type PayloadLocation = "INLINE" | "EXTERNAL";
+export interface WorkflowManifest {
+    schemaVersion: 1;
+    projectId: string;
+    versionId: string;
+    builtAt: number;
+    builderVersion: string;
+    capabilities: string[];
+    workflows: WorkflowManifestEntry[];
+    eventFilters: EventFilterManifestEntry[];
+    bindings: Record<string, {
+        type: "d1" | "r2" | "kv" | "queue";
+        name: string;
+    }>;
+    environments: Record<string, {
+        customDomain?: string;
+    }>;
+}
+export interface WorkflowManifestEntry {
+    id: string;
+    version: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    steps: ManifestStep[];
+    schedules: ManifestSchedule[];
+    defaultRuntime: "edge" | "node";
+    hasCompensation: boolean;
+    sourceLocation: {
+        file: string;
+        line: number;
+    };
+}
+export interface ManifestStep {
+    id: string;
+    runtime: "edge" | "node";
+    hasCompensation: boolean;
+    sourceLocation: {
+        file: string;
+        line: number;
+    };
+}
+export interface ManifestSchedule {
+    cron?: string;
+    every?: string;
+    at?: string;
+    timezone?: string;
+    environments?: ("production" | "preview" | "development")[];
+    name?: string;
+}
+export interface EventFilterManifestEntry {
+    id: string;
+    eventType: string;
+    scope?: string;
+    matchExpression?: string;
+    payloadHash: string;
+    targetWorkflowId: string;
+}
+export type StreamEvent = {
+    kind: "step.started";
+    eventId: string;
+    at: number;
+    stepId: string;
+    runtime: "edge" | "node";
+    machine?: string;
+} | {
+    kind: "step.ok";
+    eventId: string;
+    at: number;
+    stepId: string;
+    attempt: number;
+    durationMs: number;
+    output?: unknown;
+} | {
+    kind: "step.err";
+    eventId: string;
+    at: number;
+    stepId: string;
+    attempt: number;
+    error: SerializedError;
+} | {
+    kind: "step.skipped";
+    eventId: string;
+    at: number;
+    stepId: string;
+    reason: string;
+} | {
+    kind: "step.compensated";
+    eventId: string;
+    at: number;
+    stepId: string;
+    status: "ok" | "err";
+    error?: SerializedError;
+} | {
+    kind: "waitpoint.registered";
+    eventId: string;
+    at: number;
+    waitpointId: string;
+    waitpointKind: WaitpointKind;
+    meta: Record<string, unknown>;
+} | {
+    kind: "waitpoint.resolved";
+    eventId: string;
+    at: number;
+    waitpointId: string;
+    payload?: unknown;
+    source: "live" | "inbox" | "replay";
+} | {
+    kind: "metadata.changed";
+    eventId: string;
+    at: number;
+    metadata: Record<string, unknown>;
+} | {
+    kind: "stream.chunk";
+    eventId: string;
+    at: number;
+    streamId: string;
+    chunk: unknown;
+    encoding: "json" | "text" | "base64";
+    final: boolean;
+} | {
+    kind: "log";
+    eventId: string;
+    at: number;
+    level: "info" | "warn" | "error";
+    message: string;
+    stepId?: string;
+    data?: object;
+} | {
+    kind: "version.rebased";
+    eventId: string;
+    at: number;
+    fromVersion: string;
+    toVersion: string;
+} | {
+    kind: "run.cancelled";
+    eventId: string;
+    at: number;
+    reason?: string;
+} | {
+    kind: "run.finished";
+    eventId: string;
+    at: number;
+    status: string;
+    output?: unknown;
+    error?: SerializedError;
+};
+export interface JournalEventEnvelope<TKind extends string = string, TData = unknown> {
+    eventId: string;
+    runId: string;
+    createdAt: number;
+    kind: TKind;
+    data: TData;
+    snapshotId?: string;
+    writtenBy: "orchestrator" | "tenant" | "node";
+}
+export interface PublicAccessTokenClaims {
+    sub: "pat";
+    tenantId: string;
+    environment: "production" | "preview" | "development";
+    scope: ("read" | "trigger" | "cancel")[];
+    target: {
+        kind: "run";
+        runId: string;
+    } | {
+        kind: "workflow";
+        workflowId: string;
+    } | {
+        kind: "tag";
+        tag: string;
+    };
+    exp: number;
+}
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/protocol/index.js

@@ -0,0 +1,7 @@
+// @voyantjs/workflows/protocol
+//
+// Wire-protocol types shared with the orchestrator. Full contract
+// in docs/runtime-protocol.md; types here are exported so callers
+// (test harness, adapters, dashboards) can build and inspect wire
+// payloads without reaching into runtime internals.
+export const PROTOCOL_VERSION = 1;

package/dist/rate-limit/index.d.ts

@@ -0,0 +1,40 @@
+import type { Duration } from "../types.js";
+export interface AcquireArgs {
+    /** Bucket key — usually a tenant id, a url host, a user id, etc. */
+    key: string;
+    /** Maximum units the bucket can hold. */
+    limit: number;
+    /** Units the current call consumes. */
+    units: number;
+    /** Refill window in ms. `limit` tokens per `windowMs`. */
+    windowMs: number;
+    /** `queue` → wait until capacity; `fail` → throw immediately. */
+    onLimit: "queue" | "fail";
+    /** Forwarded from the run; limiter observes aborts during queue waits. */
+    signal?: AbortSignal;
+}
+export interface RateLimiter {
+    acquire(args: AcquireArgs): Promise<void>;
+}
+/** Error thrown when `onLimit === "fail"` and the bucket is empty. */
+export declare class RateLimitExceededError extends Error {
+    readonly code = "RATE_LIMITED";
+    readonly retryAfterMs: number;
+    constructor(key: string, retryAfterMs: number);
+}
+export interface InMemoryLimiterOptions {
+    /** Injectable clock, ms since epoch. Defaults to Date.now. */
+    now?: () => number;
+    /** Injectable delay; defaults to setTimeout. Tests override this. */
+    delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Token-bucket rate limiter held in-process. Independent buckets per
+ * `key`; bucket parameters (`capacity`, `refillPerMs`) come from the
+ * `limit` / `windowMs` of the first `acquire` call and are updated on
+ * subsequent calls that change them.
+ */
+export declare function createInMemoryRateLimiter(opts?: InMemoryLimiterOptions): RateLimiter;
+/** Normalize a Duration to milliseconds. Same units as `toMs` in ctx.ts. */
+export declare function durationToMs(d: Duration): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/rate-limit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,OAAO,EAAE,OAAO,GAAG,MAAM,CAAA;IACzB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C;AAED,sEAAsE;AACtE,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,kBAAiB;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;gBACjB,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAK9C;AASD,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,sBAA2B,GAAG,WAAW,CA0CxF;AAgDD,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAqBhD"}

package/dist/rate-limit/index.js

@@ -0,0 +1,139 @@
+// @voyantjs/workflows/rate-limit
+//
+// Reference rate limiter used by `ctx.step({ rateLimit: ... })`.
+//
+// A RateLimiter is a small interface: `acquire()` blocks (or throws,
+// depending on `onLimit`) until `units` are available under `key` for
+// a sliding window of `windowMs`. One shared limiter instance lives
+// per tenant Worker process — callers wire it into `createStepHandler`
+// via `{ rateLimiter: createInMemoryRateLimiter() }`.
+//
+// The in-memory impl is a token bucket: `capacity = limit`, refill
+// rate = `limit / windowMs`. It's suitable for local dev and
+// single-process deployments. Multi-region / sharded deployments
+// should swap in a Durable-Object or Redis-backed implementation that
+// shares state across isolates.
+/** Error thrown when `onLimit === "fail"` and the bucket is empty. */
+export class RateLimitExceededError extends Error {
+    code = "RATE_LIMITED";
+    retryAfterMs;
+    constructor(key, retryAfterMs) {
+        super(`rate limit exceeded for key "${key}" (retry after ${retryAfterMs}ms)`);
+        this.name = "RateLimitExceededError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Token-bucket rate limiter held in-process. Independent buckets per
+ * `key`; bucket parameters (`capacity`, `refillPerMs`) come from the
+ * `limit` / `windowMs` of the first `acquire` call and are updated on
+ * subsequent calls that change them.
+ */
+export function createInMemoryRateLimiter(opts = {}) {
+    const now = opts.now ?? (() => Date.now());
+    const delay = opts.delay ?? defaultDelay;
+    const buckets = new Map();
+    return {
+        async acquire(args) {
+            if (args.units <= 0)
+                return;
+            if (args.limit <= 0) {
+                throw new Error(`rate-limit: "limit" must be > 0 (got ${args.limit}) for key "${args.key}"`);
+            }
+            if (args.windowMs <= 0) {
+                throw new Error(`rate-limit: "windowMs" must be > 0 (got ${args.windowMs}) for key "${args.key}"`);
+            }
+            if (args.units > args.limit) {
+                // The step will never be admissible — short-circuit regardless
+                // of onLimit to avoid hanging indefinitely under queue mode.
+                throw new Error(`rate-limit: units (${args.units}) > limit (${args.limit}) for key "${args.key}" — step can never be admitted`);
+            }
+            while (true) {
+                const bucket = refill(buckets, args, now());
+                if (bucket.tokens >= args.units) {
+                    bucket.tokens -= args.units;
+                    return;
+                }
+                const missing = args.units - bucket.tokens;
+                const waitMs = Math.ceil(missing / bucket.refillPerMs);
+                if (args.onLimit === "fail") {
+                    throw new RateLimitExceededError(args.key, waitMs);
+                }
+                await delay(waitMs, args.signal);
+                if (args.signal?.aborted) {
+                    throw args.signal.reason ?? new Error("rate-limit: aborted while queued");
+                }
+            }
+        },
+    };
+}
+function refill(buckets, args, nowMs) {
+    const refillPerMs = args.limit / args.windowMs;
+    let b = buckets.get(args.key);
+    if (!b) {
+        b = {
+            tokens: args.limit,
+            capacity: args.limit,
+            refillPerMs,
+            lastRefillAt: nowMs,
+        };
+        buckets.set(args.key, b);
+        return b;
+    }
+    // Re-parameterize if the caller changed limit / windowMs. Clamp
+    // tokens to the new capacity so a shrink doesn't leave stale excess.
+    if (b.capacity !== args.limit || b.refillPerMs !== refillPerMs) {
+        b.capacity = args.limit;
+        b.refillPerMs = refillPerMs;
+        if (b.tokens > b.capacity)
+            b.tokens = b.capacity;
+    }
+    const elapsed = Math.max(0, nowMs - b.lastRefillAt);
+    if (elapsed > 0) {
+        b.tokens = Math.min(b.capacity, b.tokens + elapsed * b.refillPerMs);
+        b.lastRefillAt = nowMs;
+    }
+    return b;
+}
+function defaultDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error("aborted"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new Error("aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Normalize a Duration to milliseconds. Same units as `toMs` in ctx.ts. */
+export function durationToMs(d) {
+    if (typeof d === "number")
+        return d;
+    const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(d);
+    if (!m)
+        throw new Error(`rate-limit: invalid duration "${d}"`);
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "ms":
+            return n;
+        case "s":
+            return n * 1_000;
+        case "m":
+            return n * 60_000;
+        case "h":
+            return n * 3_600_000;
+        case "d":
+            return n * 86_400_000;
+        case "w":
+            return n * 604_800_000;
+        default:
+            throw new Error(`rate-limit: invalid duration "${d}"`);
+    }
+}

package/dist/runtime/ctx.d.ts

@@ -0,0 +1,102 @@
+import type { RetryPolicy, WaitpointKind } from "../types.js";
+import type { EnvironmentContext, MetadataValue, RunContext, StepContext, StepFn, StepOptions, WorkflowContext } from "../workflow.js";
+import { type ClockState } from "./determinism.js";
+import type { JournalSlice, StepJournalEntry } from "./journal.js";
+/**
+ * Callbacks the executor provides for operations that must reach the
+ * orchestrator (over HTTP in production, in-memory in tests).
+ */
+export interface RuntimeCallbacks {
+    /** Run a new step and journal the result. Called only for steps not already in the journal. */
+    runStep(args: {
+        stepId: string;
+        attempt: number;
+        input: unknown;
+        options: StepOptions<unknown>;
+        fn: StepFn<unknown>;
+        stepCtx: StepContext;
+    }): Promise<StepJournalEntry>;
+    /**
+     * Called when a step completes successfully and had a `compensate`
+     * function declared. The executor collects these in completion order
+     * and runs them in reverse if the body throws or `ctx.compensate()`
+     * is invoked.
+     */
+    recordCompensable(args: {
+        stepId: string;
+        output: unknown;
+        compensate: (output: unknown) => Promise<void>;
+    }): void;
+    /** Current length of the compensable list. Used by `ctx.group` checkpoints. */
+    compensableLength(): number;
+    /**
+     * Remove and return compensables added since `fromIndex`. Used by
+     * `ctx.group` to run scoped rollback without touching outer
+     * compensables.
+     */
+    spliceCompensable(fromIndex: number): Array<{
+        stepId: string;
+        output: unknown;
+        compensate: (output: unknown) => Promise<void>;
+    }>;
+    /**
+     * Called by `ctx.stream()` for each chunk produced by the source.
+     * In production this emits a `stream.chunk` WebSocket event and
+     * journals the chunk; in tests the harness collects chunks.
+     */
+    pushStreamChunk(args: {
+        streamId: string;
+        seq: number;
+        encoding: "text" | "json" | "base64";
+        chunk: unknown;
+        final: boolean;
+    }): void;
+    /** Register a new waitpoint; execution will yield after this returns. */
+    registerWaitpoint(args: {
+        clientWaitpointId: string;
+        kind: WaitpointKind;
+        meta: Record<string, unknown>;
+        timeoutMs?: number;
+    }): void;
+    /** Push a metadata mutation; flushed on waitpoint yield and run completion. */
+    pushMetadata(op: {
+        op: "set" | "increment" | "append" | "remove";
+        key: string;
+        value?: unknown;
+        target?: "self" | "parent" | "root";
+    }): void;
+    /** Increment invocation counter when the body resumes after eviction. */
+    readonly invocationCount: number;
+    /** Cancellation signal exposed as `ctx.signal`. */
+    readonly abortSignal: AbortSignal;
+}
+export interface RuntimeEnvironment {
+    readonly run: RunContext;
+    readonly workflow: {
+        id: string;
+        version: string;
+    };
+    readonly environment: EnvironmentContext;
+    readonly project: {
+        id: string;
+        slug: string;
+    };
+    readonly organization: {
+        id: string;
+        slug: string;
+    };
+}
+export interface CtxBuildArgs {
+    env: RuntimeEnvironment;
+    journal: JournalSlice;
+    callbacks: RuntimeCallbacks;
+    clock: ClockState;
+    random: () => number;
+    /** Mutated as ctx.setRetry is called; each step option inherits. */
+    retryOverride: {
+        current: RetryPolicy | undefined;
+    };
+}
+export declare function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown>;
+export type { MetadataValue };
+//# sourceMappingURL=ctx.d.ts.map

package/dist/runtime/ctx.d.ts.map

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