@voltro/workflow 0.1.0

package/dist/index.js

@@ -0,0 +1,3 @@
+import { C as e, E as t, T as n, _ as r, a as i, b as a, c as o, d as s, f as c, g as l, h as u, i as d, l as f, m as p, n as m, o as h, p as g, r as _, s as v, t as y, u as b, v as x, w as S, x as C, y as w } from "./primitives-CWy1iu5w.js";
+import { _ as T, a as E, b as D, c as O, d as k, f as A, g as j, h as M, i as N, l as P, m as F, n as I, o as L, p as R, r as z, s as B, t as V, u as H, v as U, x as W, y as G } from "./src-CNeLb-4L.js";
+export { a as CurrentWorkflowExecutionId, C as CurrentWorkflowRunId, y as WorkflowMessagesProperty, e as WorkflowRunRecorder, S as WorkflowStepInterceptorTag, m as WorkflowVersionTypeId, _ as WorkflowWorkerLayerTypeId, U as _voltroWorkflowRunEventsTable, G as _voltroWorkflowRunStepsTable, D as _voltroWorkflowRunsTable, T as _voltroWorkflowStartContextsTable, j as awaitSignal, P as awaitSignalSuspending, O as awaitUpdate, z as closeWorkflowChildrenForParent, H as completeSuspendingSignal, d as durableClock, i as durableQueue, h as durableQueueModule, v as durableRateLimiterModule, n as getCurrentWorkflowExecutionId, t as getCurrentWorkflowRunId, o as getWorkflowVersionMetadata, W as inMemoryWorkflowEngineLayer, I as inspectWorkflow, f as isWorkflowWorkerLayer, V as makeInMemoryRecorder, N as makeWorkflowRunRecorder, A as makeWorkflowUpdateId, b as processQueue, s as queueWorker, c as rateLimit, R as resolveWorkflowMessageRun, F as sendWorkflowSignal, M as sendWorkflowUpdate, E as serialiseWorkflowRowForWire, g as sleep, p as step, u as stepIdempotencyKey, l as stepModule, k as suspendingSignalDeferredName, L as truncateWorkflowValue, r as withCompensation, x as workflow, w as workflowModule, B as wrapWorkflowExecuteWithRunRecording };

package/dist/primitives-CWy1iu5w.js

@@ -0,0 +1,111 @@
+import { Activity as e, Activity as t, DurableClock as n, DurableClock as r, DurableQueue as i, DurableQueue as a, DurableRateLimiter as o, DurableRateLimiter as s, Workflow as c, Workflow as l } from "@effect/workflow";
+import { Cause as u, Context as d, Duration as f, Effect as p, FiberRef as m } from "effect";
+//#region src/recorder.ts
+var h = class extends d.Tag("@voltro/WorkflowRunRecorder")() {}, g = m.unsafeMake(void 0), _ = m.unsafeMake(void 0), v = m.unsafeMake(void 0), y = () => m.get(g), b = () => m.get(_), x = class extends d.Tag("@voltro/WorkflowStepInterceptor")() {}, S = Symbol.for("voltro.workflow.workerLayer"), C = Symbol.for("voltro.workflow.version"), w = "__voltroWorkflowMessages", T = (e) => typeof e == "object" && !!e && e[S] === !0, E = (e) => typeof e == "object" && e && e[C] !== void 0 ? e[C] : {
+	version: "1",
+	compatibleWith: ["1"],
+	patches: []
+}, D = ((e) => {
+	let t = c.make(e), n = String(e.version ?? "1"), r = {
+		version: n,
+		compatibleWith: (e.compatibleWith ?? [n]).map(String),
+		patches: [...e.patches ?? []]
+	}, i = {
+		signals: { ...e.messages?.signals ?? {} },
+		updates: { ...e.messages?.updates ?? {} },
+		queries: { ...e.messages?.queries ?? {} }
+	};
+	return Object.defineProperty(t, C, {
+		value: r,
+		enumerable: !1
+	}), Object.defineProperty(t, w, {
+		value: i,
+		enumerable: !1
+	}), t;
+}), O = i.make, k = i.process, A = ((...e) => {
+	let t = i.worker(...e);
+	return Object.defineProperty(t, S, {
+		value: !0,
+		enumerable: !1
+	}), t;
+}), j = o.rateLimit, M = (e) => p.gen(function* () {
+	let t = yield* g, r = yield* p.serviceOption(h), i = f.toMillis(f.decode(e.duration));
+	if (t !== void 0 && r._tag === "Some") {
+		let a = r.value, o = new Date(Date.now() + i).toISOString(), s = yield* v;
+		yield* p.promise(() => a.recordEvent({
+			runId: t,
+			eventType: "timer-set",
+			payload: {
+				name: e.name,
+				durationMs: i,
+				scheduledWakeAt: o,
+				...s === void 0 ? {} : { tenantId: s }
+			}
+		}).catch(() => {}));
+		let c = Date.now();
+		yield* n.sleep(e), yield* p.promise(() => a.recordEvent({
+			runId: t,
+			eventType: "timer-fired",
+			payload: {
+				name: e.name,
+				actualDurationMs: Date.now() - c,
+				...s === void 0 ? {} : { tenantId: s }
+			}
+		}).catch(() => {}));
+		return;
+	}
+	yield* n.sleep(e);
+}), N = (t, n, r, i) => p.gen(function* () {
+	let a = yield* g, o = yield* e.CurrentAttempt, s = yield* p.serviceOption(h), c = yield* p.serviceOption(x), l = c._tag === "Some" ? c.value.interceptor(n, {
+		runId: a ?? "unrecorded",
+		stepName: t,
+		attempt: o
+	}) : n, d, f;
+	if (a !== void 0 && s._tag === "Some") {
+		f = s.value;
+		try {
+			d = yield* p.promise(() => f.startStep({
+				runId: a,
+				stepName: t,
+				attempt: o,
+				stepInput: r,
+				...i === void 0 ? {} : { retryPolicy: i }
+			}));
+		} catch {
+			d = void 0;
+		}
+	}
+	let m = Date.now();
+	return yield* l.pipe(p.tap((e) => d && f ? p.promise(async () => {
+		try {
+			await f.endStepSuccess({
+				stepRecordId: d,
+				output: e,
+				durationMs: Date.now() - m
+			});
+		} catch {}
+	}) : p.void), p.tapErrorCause((e) => d && f && !u.isInterruptedOnly(e) ? p.promise(async () => {
+		try {
+			let t = u.failureOption(e), n = Array.from(u.failures(e)), r = Array.from(u.defects(e)), i = t._tag === "Some" ? t.value : r[0] ?? u.squash(e), a = i?.message ?? String(i), o = i && typeof i == "object" && "_tag" in i ? String(i._tag) : null;
+			await f.endStepFailure({
+				stepRecordId: d,
+				errorTag: o,
+				errorMessage: a,
+				errorCause: {
+					pretty: u.pretty(e),
+					failures: n,
+					defects: r
+				},
+				durationMs: Date.now() - m
+			});
+		} catch {}
+	}) : p.void));
+}), P = (t) => {
+	let { input: n, retry: r, ...i } = t;
+	return e.make({
+		...i,
+		execute: N(i.name, i.execute, n, r)
+	});
+}, F = c.withCompensation, I = e.idempotencyKey;
+//#endregion
+export { h as C, y as E, v as S, b as T, F as _, O as a, _ as b, E as c, A as d, j as f, t as g, I as h, r as i, T as l, P as m, C as n, a as o, M as p, S as r, s, w as t, k as u, D as v, x as w, g as x, l as y };

package/dist/primitives.d.ts

@@ -0,0 +1,229 @@
+import { DurableClock as durableClock } from '@effect/workflow';
+import { DurableQueue as durableQueueModule } from '@effect/workflow';
+import { DurableRateLimiter as durableRateLimiterModule } from '@effect/workflow';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { Activity as stepModule } from '@effect/workflow';
+import { Workflow as workflowModule } from '@effect/workflow';
+
+export { durableClock }
+
+/** Define a durable queue for concurrency-controlled side work. */
+export declare const durableQueue: typeof durableQueueModule.make;
+
+export { durableQueueModule }
+
+export { durableRateLimiterModule }
+
+export declare const getWorkflowVersionMetadata: (value: unknown) => WorkflowVersionMetadata;
+
+export declare const isWorkflowWorkerLayer: (value: unknown) => value is WorkflowWorkerLayerBrand;
+
+declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefined> = {
+    readonly signals: M extends {
+        readonly signals: infer Signals;
+    } ? NonNullable<Signals> & Readonly<Record<string, Schema.Schema.Any>> : {};
+    readonly updates: M extends {
+        readonly updates: infer Updates;
+    } ? NonNullable<Updates> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
+    readonly queries: M extends {
+        readonly queries: infer Queries;
+    } ? NonNullable<Queries> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
+};
+
+/** Enqueue work and await the durable queue worker's result. */
+export declare const processQueue: typeof durableQueueModule.process;
+
+/** Start a durable queue worker layer with bounded concurrency.
+ *
+ *  `DurableQueue.worker` is itself generic (`<Payload, Success, Error, R>`), so
+ *  a hand-written wrapper can't re-state that generic signature — the body runs
+ *  against erased args and the const's explicit `: typeof DurableQueue.worker`
+ *  annotation restores the full generic public type. That annotation (not an
+ *  inferred type) is what emits in the `.d.ts`, so it stays portable. */
+export declare const queueWorker: typeof durableQueueModule.worker;
+
+/** Durable rate limiter activity. Delays through the workflow clock. */
+export declare const rateLimit: typeof durableRateLimiterModule.rateLimit;
+
+/**
+ * Durable sleep — wake time journaled in the cluster. Wrapper around
+ * `DurableClock.sleep` that emits `timer-set` / `timer-fired` events
+ * to the recorder so the dashboard's Gantt timeline renders the wait
+ * as a visible bar — a workflow waiting on a cron-style delay should
+ * not look like a black hole.
+ *
+ * The wrap is transparent: signature matches `DurableClock.sleep`,
+ * no observable behavior change beyond the event emissions. When no
+ * recorder is in scope (unit tests, no `voltro dev`/`voltro start`
+ * wrapper around the workflow) it's a zero-overhead passthrough.
+ */
+export declare const sleep: typeof durableClock.sleep;
+
+export declare const step: <R, Success extends Schema.Schema.Any = typeof Schema.Void, Error extends Schema.Schema.All = typeof Schema.Never>(options: StepOptions<R, Success, Error>) => ReturnType<typeof stepModule.make<R, Success, Error>>;
+
+/**
+ * Derive a deterministic idempotency key for the current workflow run,
+ * scoped to `name`. Call it inside a `step()` so a retried external
+ * side-effect converges on a single key instead of double-creating —
+ * pair it with a read-before-write provider-operations ledger. Pass
+ * `{ includeAttempt: true }` to vary the key per attempt.
+ *
+ * Named for the framework's `step` vocabulary (it is upstream's
+ * `Activity.idempotencyKey`).
+ */
+export declare const stepIdempotencyKey: typeof stepModule.idempotencyKey;
+
+export { stepModule }
+
+/**
+ * Define a checkpointed step (activity) inside a workflow body.
+ *
+ * Wraps `@effect/workflow`'s `Activity.make` to record every
+ * invocation in `_voltro_workflow_run_steps`. The wrapping is
+ * transparent — accepts everything `Activity.make` accepts, plus an
+ * optional `input` field whose value is persisted to the step row
+ * (truncated to 8 KB by the recorder). The dashboard surfaces it as
+ * "Input" alongside Output, so operators can answer "what arguments
+ * did this step receive?" without grep-ing logs.
+ *
+ * ```ts
+ * step({
+ *   name: 'fetch-todos',
+ *   input: { tenantId, since: lastFetch },  // ← optional, recorded
+ *   execute: Effect.tryPromise({ try: () => ctx.store.query(...) }),
+ * })
+ * ```
+ *
+ * Without the recorder service in scope (unit tests, etc.) the input
+ * is dropped and the wrap is a no-op.
+ */
+declare type StepOptions<R, Success extends Schema.Schema.Any, Error extends Schema.Schema.All> = {
+    readonly name: string;
+    readonly success?: Success | undefined;
+    readonly error?: Error | undefined;
+    readonly execute: Effect.Effect<Success['Type'], Error['Type'], R>;
+    readonly interruptRetryPolicy?: Parameters<typeof stepModule.make<R, Success, Error>>[0]['interruptRetryPolicy'];
+    /** Structured value recorded into `_voltro_workflow_run_steps.input`.
+     *  Pass whatever makes the step debuggable in isolation. */
+    readonly input?: unknown;
+    /** Declarative retry-policy summary recorded into
+     *  `_voltro_workflow_run_steps.retryPolicy`. Pure metadata — does
+     *  NOT change retry behavior on its own. Wire actual retries via
+     *  `Effect.retry` inside `execute:` or via `interruptRetryPolicy`
+     *  above; this field tells the dashboard what the intended policy
+     *  looks like so the per-attempt panel can show "attempt 2 of 5,
+     *  exponential 1s base" instead of just "attempt 2". */
+    readonly retry?: StepRetryPolicy;
+};
+
+/**
+ * Declarative retry-policy summary. Pure metadata for the dashboard;
+ * the framework does NOT apply this. Users wire actual retry behavior
+ * via `Effect.retry(Schedule.*)` inside `execute:` or
+ * `Activity.make`'s `interruptRetryPolicy`.
+ *
+ * Shape is intentionally close to Effect's Schedule combinators so a
+ * future framework version can auto-translate declarative policies
+ * into a Schedule + apply it. For now: record + display.
+ *
+ *   { strategy: 'exponential', maxAttempts: 5, baseDelay: '1 second', maxDelay: '30 seconds' }
+ *   { strategy: 'fixed',       maxAttempts: 3, baseDelay: '500 millis' }
+ *   { strategy: 'linear',      maxAttempts: 4, baseDelay: '1 second',  step: '2 seconds' }
+ */
+declare interface StepRetryPolicy {
+    readonly strategy: 'exponential' | 'fixed' | 'linear';
+    readonly maxAttempts: number;
+    /** Effect Duration string, e.g. `'1 second'`, `'500 millis'`. */
+    readonly baseDelay?: string;
+    /** Cap on exponential / linear growth, e.g. `'30 seconds'`. */
+    readonly maxDelay?: string;
+    /** Increment for `linear` strategy. */
+    readonly step?: string;
+    /** Free-form note rendered as a chip in the dashboard. Useful when
+     *  the retry behavior is partially implemented in the user's
+     *  Effect chain and the summary is just documentation. */
+    readonly note?: string;
+}
+
+/**
+ * Add compensating (rollback) logic to a top-level effect in a workflow
+ * body. The finalizer runs if the WHOLE workflow later fails — use it for
+ * saga-style undo: release a half-acquired resource, revert a partial
+ * promotion. Upstream constraint: compensation is registered only for
+ * top-level effects in the workflow, NOT for nested steps/activities.
+ *
+ * Pinned with `typeof` to keep the emitted .d.ts portable (see the TS2742
+ * note above the type-explicit re-exports).
+ *
+ * ```ts
+ * yield* withCompensation(
+ *   step({ name: 'provision-db', execute: ... }),
+ *   (resource) => releaseResource(resource),  // runs only if the workflow fails
+ * )
+ * ```
+ */
+export declare const withCompensation: typeof workflowModule.withCompensation;
+
+/** Define a durable workflow. Adds Voltro version metadata on top of `Workflow.make`. */
+export declare const workflow: WorkflowFn;
+
+/** Callable shape of `workflow`: the raw `Workflow.make` surface PLUS the
+ *  Voltro-typed overload that threads the message-schema metadata onto the
+ *  returned definition. Explicit alias so the `.d.ts` names this type by its
+ *  own alias — the inferred `Workflow.make` type references internal `@effect`
+ *  modules via `.pnpm` paths and is not portable (TS2742) when re-emitted. */
+declare type WorkflowFn = WorkflowMake & (<const Options extends WorkflowOptions>(options: Options) => ReturnType<WorkflowMake> & WorkflowMessagesCarrier<NormaliseWorkflowMessages<Options['messages']>>);
+
+declare type WorkflowMake = typeof workflowModule.make;
+
+export declare interface WorkflowMessagePairSchemas {
+    readonly payload: Schema.Schema.Any;
+    readonly success: Schema.Schema.Any;
+}
+
+export declare interface WorkflowMessagesCarrier<M extends WorkflowMessagesMetadata = WorkflowMessagesMetadata> {
+    readonly [WorkflowMessagesProperty]: M;
+}
+
+export declare interface WorkflowMessageSchemas {
+    readonly signals?: Readonly<Record<string, Schema.Schema.Any>>;
+    readonly updates?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+    readonly queries?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+}
+
+export declare interface WorkflowMessagesMetadata {
+    readonly signals: Readonly<Record<string, Schema.Schema.Any>>;
+    readonly updates: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+    readonly queries: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+}
+
+export declare const WorkflowMessagesProperty = "__voltroWorkflowMessages";
+
+export { workflowModule }
+
+declare type WorkflowOptions = Parameters<WorkflowMake>[0] & WorkflowVersionOptions & {
+    readonly messages?: WorkflowMessageSchemas;
+};
+
+export declare interface WorkflowVersionMetadata {
+    readonly version: string;
+    readonly compatibleWith: ReadonlyArray<string>;
+    readonly patches: ReadonlyArray<string>;
+}
+
+export declare interface WorkflowVersionOptions {
+    readonly version?: string | number;
+    readonly compatibleWith?: ReadonlyArray<string | number>;
+    readonly patches?: ReadonlyArray<string>;
+}
+
+export declare const WorkflowVersionTypeId: unique symbol;
+
+export declare interface WorkflowWorkerLayerBrand {
+    readonly [WorkflowWorkerLayerTypeId]: true;
+}
+
+export declare const WorkflowWorkerLayerTypeId: unique symbol;
+
+export { }

package/dist/primitives.js

@@ -0,0 +1,2 @@
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _, y as v } from "./primitives-CWy1iu5w.js";
+export { h as WorkflowMessagesProperty, u as WorkflowVersionTypeId, p as WorkflowWorkerLayerTypeId, s as durableClock, t as durableQueue, d as durableQueueModule, m as durableRateLimiterModule, n as getWorkflowVersionMetadata, c as isWorkflowWorkerLayer, g as processQueue, r as queueWorker, i as rateLimit, f as sleep, l as step, o as stepIdempotencyKey, a as stepModule, e as withCompensation, _ as workflow, v as workflowModule };