@lunora/workflow 0.0.0 → 1.0.0-alpha.2

package/dist/do/index.d.mts

@@ -0,0 +1,25 @@
+import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
+import { W as WorkflowDefinition } from "../packem_shared/types.d-CQO_koGe.mjs";
+import '@lunora/values';
+/**
+* Base class for the generated `WorkflowEntrypoint` classes. Applies a
+* `defineWorkflow` definition onto Cloudflare's `WorkflowEntrypoint`: `run`
+* assembles the Lunora context (native `step`/`event` + the `ctx.run` function
+* dispatcher + a logger) and invokes the user's handler.
+*
+* Generated subclasses stay one line of behavior:
+*
+* ```ts
+* export class OrderPipelineWorkflow extends LunoraWorkflow {
+*     constructor(ctx: ExecutionContext, env: Record<string, unknown>) {
+*         super(ctx, env, orderPipeline, "orderPipeline");
+*     }
+* }
+* ```
+*/
+declare class LunoraWorkflow<Params = Record<string, unknown>, Output = unknown> extends WorkflowEntrypoint<Record<string, unknown>, Params> {
+  #private;
+  constructor(context: ConstructorParameters<typeof WorkflowEntrypoint>[0], env: Record<string, unknown>, definition: WorkflowDefinition<Params, Output>, exportName?: string);
+  override run(event: Readonly<WorkflowEvent<Params>>, step: WorkflowStep): Promise<Output>;
+}
+export { LunoraWorkflow as default };

package/dist/do/index.d.ts

@@ -0,0 +1,25 @@
+import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
+import { W as WorkflowDefinition } from "../packem_shared/types.d-CQO_koGe.js";
+import '@lunora/values';
+/**
+* Base class for the generated `WorkflowEntrypoint` classes. Applies a
+* `defineWorkflow` definition onto Cloudflare's `WorkflowEntrypoint`: `run`
+* assembles the Lunora context (native `step`/`event` + the `ctx.run` function
+* dispatcher + a logger) and invokes the user's handler.
+*
+* Generated subclasses stay one line of behavior:
+*
+* ```ts
+* export class OrderPipelineWorkflow extends LunoraWorkflow {
+*     constructor(ctx: ExecutionContext, env: Record<string, unknown>) {
+*         super(ctx, env, orderPipeline, "orderPipeline");
+*     }
+* }
+* ```
+*/
+declare class LunoraWorkflow<Params = Record<string, unknown>, Output = unknown> extends WorkflowEntrypoint<Record<string, unknown>, Params> {
+  #private;
+  constructor(context: ConstructorParameters<typeof WorkflowEntrypoint>[0], env: Record<string, unknown>, definition: WorkflowDefinition<Params, Output>, exportName?: string);
+  override run(event: Readonly<WorkflowEvent<Params>>, step: WorkflowStep): Promise<Output>;
+}
+export { LunoraWorkflow as default };

package/dist/do/index.mjs

@@ -0,0 +1,32 @@
+import { WorkflowEntrypoint } from 'cloudflare:workers';
+import { NonRetryableError } from 'cloudflare:workflows';
+import { convertNonRetryableError } from '../packem_shared/NonRetryableError-Dn2dTyBS.mjs';
+import { createWorkflowRunContext } from '../packem_shared/createWorkflowLogger-DR8P4ZoY.mjs';
+
+class LunoraWorkflow extends WorkflowEntrypoint {
+  /** The `lunora/workflows.ts` export name, for log correlation. */
+  #lunoraName;
+  /** The `defineWorkflow` result this entrypoint runs. */
+  #definition;
+  constructor(context, env, definition, exportName) {
+    super(context, env);
+    this.#definition = definition;
+    this.#lunoraName = exportName ?? "workflow";
+  }
+  async run(event, step) {
+    const context = createWorkflowRunContext({
+      env: this.env,
+      event,
+      exportName: this.#lunoraName,
+      nonRetryableErrorClass: NonRetryableError,
+      step
+    });
+    try {
+      return await this.#definition.handler(context);
+    } catch (error) {
+      return convertNonRetryableError(error, NonRetryableError);
+    }
+  }
+}
+
+export { LunoraWorkflow as default };

package/dist/index.d.mts

@@ -0,0 +1,269 @@
+import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowInstanceStatus, f as WorkflowLogger, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-CQO_koGe.mjs";
+export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, l as RunStepOptions, m as StepHandler, n as StepRollbackContext, o as StepRollbackHandler, p as StepRunContext, q as WorkflowBindingLike, r as WorkflowCreateOptions, s as WorkflowHandle, t as WorkflowHandler, u as WorkflowInstanceLike, v as WorkflowRollbackContextLike, w as WorkflowRollbackHandlerLike, x as WorkflowStatusResult, y as WorkflowStepConfigLike, z as WorkflowStepContextLike, B as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CQO_koGe.mjs";
+import '@lunora/values';
+/** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
+interface WorkflowBindingSpec {
+  /** The Cloudflare `Workflow` binding name, e.g. `WORKFLOW_ORDER_PIPELINE`. */
+  binding: string;
+  /** The `lunora/workflows.ts` export name, e.g. `orderPipeline`. */
+  exportName: string;
+}
+/**
+* Build the `ctx.workflows` handle for a request: resolve every spec's
+* `env[binding]` into the `exportName → Workflow binding` map and wrap it in
+* {@link createWorkflows}. A spec whose binding is absent from `env` is skipped
+* here — the helpful "no workflow named …" error is raised lazily by
+* `workflows.get(name)` when the missing workflow is actually used.
+*/
+declare const createWorkflowContext: (env: Record<string, unknown>, specs: ReadonlyArray<WorkflowBindingSpec>) => Workflows;
+/**
+* Build the `ctx.workflows` handle from a map of `lunora/workflows.ts` export
+* name → Cloudflare `Workflow` binding. `get(name)` resolves the typed handle;
+* an unknown name throws with the list of declared workflows.
+*/
+declare const createWorkflows: (options: LunoraWorkflowsOptions) => Workflows;
+/**
+* Declare a reusable durable step. Same `args` map shape a Lunora `query` /
+* `mutation` / `action` uses, so a step reads like a function:
+*
+* ```ts
+* // lunora/steps.ts
+* import { defineStep } from "@lunora/workflow";
+* import { v } from "@lunora/values";
+*
+* export const fetchImage = defineStep("fetch image", {
+*     args: { imageKey: v.string() },
+*     returns: v.object({ data: v.bytes() }),
+*     handler: async (ctx, { imageKey }) => {
+*         const object = await (ctx.env.BUCKET as R2Bucket).get(imageKey);
+*         return { data: new Uint8Array(await object!.arrayBuffer()) };
+*     },
+*     rollback: async (ctx) => {
+*         await (ctx.env.BUCKET as R2Bucket).delete(`tmp/${ctx.args.imageKey}`);
+*     },
+* });
+* ```
+*
+* Then, inside a `defineWorkflow` handler:
+*
+* ```ts
+* const { data } = await ctx.runStep(fetchImage, { imageKey: ctx.params.imageKey });
+* ```
+*/
+declare const defineStep: <A extends StepArgsValidator, Result>(name: string, config: StepConfig<A, Result>) => StepDefinition<A, Result>;
+/** True when a value is a `defineStep` result (the runtime brand check). */
+declare const isStepDefinition: (value: unknown) => value is StepDefinition;
+/**
+* The generated `WorkflowEntrypoint` class name for a `lunora/workflows.ts`
+* export: `orderPipeline` → `OrderPipelineWorkflow`. wrangler's
+* `workflows[].class_name` references it, so codegen and the config layer MUST
+* derive it identically — always via this helper.
+*/
+declare const workflowClassName: (exportName: string) => string;
+/**
+* The wrangler binding name for a workflow export: `orderPipeline` →
+* `WORKFLOW_ORDER_PIPELINE`, `etl` → `WORKFLOW_ETL`. The `WORKFLOW_` prefix
+* namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`/`CONTAINER_*` so a
+* workflow export can never collide with the built-in bindings.
+*/
+declare const workflowBindingName: (exportName: string) => string;
+/**
+* The stable workflow name wrangler registers (`workflows[].name`):
+* `orderPipeline` → `order-pipeline`. Used as the deployed workflow's
+* identifier when no explicit `name` override is given.
+*/
+declare const workflowDefaultName: (exportName: string) => string;
+/**
+* Declare a durable workflow deployed alongside the app. Pure validation +
+* branding: codegen discovers the export, emits the `WorkflowEntrypoint`
+* subclass (`_generated/workflows.ts`), and wires the typed `ctx.workflows`
+* handle; the config layer reconciles the wrangler `workflows[]` entry from the
+* same definition.
+*
+* ```ts
+* // lunora/workflows.ts
+* import { defineWorkflow } from "@lunora/workflow";
+* import { api } from "./_generated/api";
+*
+* export const orderPipeline = defineWorkflow&lt;{ orderId: string }>({
+*     handler: async (ctx) => {
+*         const order = await ctx.step.do("load", () => ctx.run(api.orders.get, { id: ctx.params.orderId }));
+*         await ctx.step.sleep("cool-off", "1 minute");
+*         await ctx.step.do("charge", () => ctx.run(api.payments.charge, { orderId: ctx.params.orderId }));
+*         return order;
+*     },
+* });
+* ```
+*/
+declare const defineWorkflow: <Params = Record<string, unknown>, Output = unknown>(config: WorkflowConfig<Params, Output>) => WorkflowDefinition<Params, Output>;
+/** True when a value is a `defineWorkflow` result (the runtime brand check). */
+declare const isWorkflowDefinition: (value: unknown) => value is WorkflowDefinition;
+/**
+* Throw from a workflow step (or handler) to fail the instance immediately
+* **without** retrying — the portable mirror of `cloudflare:workflows`'
+* `NonRetryableError`. Importable from Node, so workflow code stays unit-testable.
+*
+* ```ts
+* import { NonRetryableError } from "@lunora/workflow";
+*
+* if (order.status === "cancelled") {
+*     throw new NonRetryableError("order already cancelled — no point retrying");
+* }
+* ```
+*/
+declare class NonRetryableError extends Error {
+  constructor(message: string, name?: string);
+}
+/** True when `value` is a Lunora portable {@link NonRetryableError}. */
+declare const isNonRetryableError: (value: unknown) => value is NonRetryableError;
+/** Constructor shape of `cloudflare:workflows`' native `NonRetryableError`. */
+type NativeNonRetryableErrorConstructor = new (message: string, name?: string) => Error;
+/**
+* Rebuild a portable {@link NonRetryableError} as the native Cloudflare one,
+* preserving its `name`, `message`, `cause`, and `stack`. Used at the `src/do`
+* boundary where the native constructor is available; everywhere else the
+* portable error is thrown unchanged (and still honored by name).
+*/
+declare const toNativeNonRetryableError: (error: NonRetryableError, NativeNonRetryableError: NativeNonRetryableErrorConstructor) => Error;
+/**
+* If `error` is a portable {@link NonRetryableError} and a native constructor is
+* available, rethrow it as the native error; otherwise rethrow `error` as-is.
+* Always throws — the `never` return lets callers `return convertNonRetryableError(...)`.
+*/
+declare const convertNonRetryableError: (error: unknown, NativeNonRetryableError: NativeNonRetryableErrorConstructor | undefined) => never;
+/** The lifecycle mutations the REST API exposes via `PATCH .../instances/{id}`. */
+type WorkflowInstanceAction = "pause" | "resume" | "terminate";
+/** Configuration for a {@link WorkflowsRestClient}. */
+interface WorkflowsRestConfig {
+  /** Cloudflare account id that owns the workflow. */
+  accountId: string;
+  /** API token with `Workflows: Read` (and `Edit` for status mutation). A secret — never a binding. */
+  apiToken: string;
+  /** `fetch` implementation. Defaults to the global `fetch`; injected in tests so the path never touches the network. */
+  fetch?: typeof globalThis.fetch;
+}
+/** One row of the instance list — the summary the studio table renders. */
+interface WorkflowInstanceSummary {
+  createdOn?: string;
+  endedOn?: string;
+  id: string;
+  startedOn?: string;
+  status: WorkflowInstanceStatus;
+}
+/** One durable step of an instance, normalized from the REST `steps[]` array. */
+interface WorkflowStepDetail {
+  /** 1-based attempt count (`> 1` means the step retried). */
+  attempts?: number;
+  end?: string;
+  error?: unknown;
+  name: string;
+  output?: unknown;
+  start?: string;
+  success?: boolean;
+  /** `step` / `sleep` / `waitForEvent` / … (Cloudflare's step `type`). */
+  type?: string;
+}
+/** A single instance's full detail: its summary plus params/output/error and the step timeline. */
+interface WorkflowInstanceDetail extends WorkflowInstanceSummary {
+  error?: unknown;
+  output?: unknown;
+  params?: unknown;
+  steps: WorkflowStepDetail[];
+}
+/** A page of instances plus the cursor info Cloudflare returns in `result_info`. */
+interface WorkflowInstancePage {
+  instances: WorkflowInstanceSummary[];
+  page: number;
+  perPage: number;
+  totalCount?: number;
+}
+/** Thrown when the REST API responds non-2xx or `success: false`; carries the status plus body for the caller to surface. */
+declare class WorkflowsRestError extends Error {
+  readonly status: number;
+  constructor(status: number, body: string);
+}
+/** The observe client: list instances, read one instance's steps, and (with Edit scope) mutate its status. */
+interface WorkflowsRestClient {
+  getInstance: (args: {
+    instanceId: string;
+    workflowName: string;
+  }) => Promise<WorkflowInstanceDetail>;
+  listInstances: (args: {
+    page?: number;
+    perPage?: number;
+    status?: WorkflowInstanceStatus;
+    workflowName: string;
+  }) => Promise<WorkflowInstancePage>;
+  setInstanceStatus: (args: {
+    action: WorkflowInstanceAction;
+    instanceId: string;
+    workflowName: string;
+  }) => Promise<{
+    status: WorkflowInstanceStatus;
+  }>;
+}
+/**
+* Build a {@link WorkflowsRestClient}. Each call hits the account-scoped REST
+* endpoint with the bearer token, unwraps Cloudflare's
+* `{ success, errors, result, result_info }` envelope, and normalizes the
+* snake_case payload into the camelCase shapes the studio renders.
+*/
+declare const createWorkflowsRestClient: (config: WorkflowsRestConfig) => WorkflowsRestClient;
+interface RunnerOptions {
+  /** Worker `env` — read `LUNORA_ORIGIN_URL` + `LUNORA_ADMIN_TOKEN` at call time. */
+  env: Record<string, unknown>;
+  /** Injectable fetch (tests); defaults to the global. */
+  fetchImpl?: typeof fetch;
+}
+/**
+* Build a {@link WorkflowRunFunction} that invokes a Lunora function by POSTing
+* to the Worker's `/_lunora/scheduler/dispatch` endpoint — the same path the
+* SchedulerDO and the Queues workpool dispatch through — authenticated with the
+* admin bearer. The parsed JSON body (the function's return value) is resolved;
+* an empty/non-JSON body resolves to `undefined`.
+*
+* Wrap calls in `ctx.step.do(...)` to make them durable + memoized + retried.
+*/
+declare const createWorkflowRunner: (options: RunnerOptions) => WorkflowRunFunction;
+/** Console-backed logger, prefixed with the workflow name for log correlation. */
+declare const createWorkflowLogger: (exportName: string) => WorkflowLogger;
+interface RunContextOptions<Params> {
+  env: Record<string, unknown>;
+  event: WorkflowEventLike<Params>;
+  exportName: string;
+  fetchImpl?: typeof fetch;
+  /** Native `cloudflare:workflows` `NonRetryableError` — injected by `src/do`; absent in Node tests. */
+  nonRetryableErrorClass?: NativeNonRetryableErrorConstructor;
+  step: WorkflowStepLike;
+}
+/** Assemble the {@link WorkflowRunContext} passed to a `defineWorkflow` handler. */
+declare const createWorkflowRunContext: <Params = Record<string, unknown>>(options: RunContextOptions<Params>) => WorkflowRunContext<Params>;
+/**
+* Validate a step's args through its validator map, prefixing any
+* `ValidationError` with `step args.&lt;key>` so the failure points at the
+* offending field. Delegates to `@lunora/values`' shared {@link parseValidatorMap}
+* — the same parser the procedure builder and HTTP routes use — so the
+* optional-skip and error-prefix semantics stay in lockstep across the framework.
+*/
+declare const validateStepArgs: (validators: StepArgsValidator, source: Record<string, unknown>) => Record<string, unknown>;
+/** Dependencies needed to run a step: the native step API plus the workflow's env / runner / logger. */
+interface RunStepDeps {
+  /** The Worker environment bindings, surfaced on the step context. */
+  env: Record<string, unknown>;
+  /** Structured logger surfaced on the step context. */
+  log: WorkflowLogger;
+  /** Native `cloudflare:workflows` `NonRetryableError` constructor — injected by `src/do`; absent in Node tests. */
+  nonRetryableErrorClass?: NativeNonRetryableErrorConstructor;
+  /** The Lunora function runner, surfaced on the step context. */
+  run: WorkflowRunFunction;
+  /** The native Cloudflare durable-step API. */
+  step: WorkflowStepLike;
+}
+/**
+* Build the `ctx.runStep` function bound to one workflow invocation. Each call
+* runs the step through `step.do(...)`: validate args → run body → validate
+* result (when `returns` is declared), with any portable `NonRetryableError`
+* converted to the native one and any declared rollback forwarded to Cloudflare.
+*/
+declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
+export { type LunoraWorkflowsOptions, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowInstanceStatus, f as WorkflowLogger, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-CQO_koGe.js";
+export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, l as RunStepOptions, m as StepHandler, n as StepRollbackContext, o as StepRollbackHandler, p as StepRunContext, q as WorkflowBindingLike, r as WorkflowCreateOptions, s as WorkflowHandle, t as WorkflowHandler, u as WorkflowInstanceLike, v as WorkflowRollbackContextLike, w as WorkflowRollbackHandlerLike, x as WorkflowStatusResult, y as WorkflowStepConfigLike, z as WorkflowStepContextLike, B as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CQO_koGe.js";
+import '@lunora/values';
+/** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
+interface WorkflowBindingSpec {
+  /** The Cloudflare `Workflow` binding name, e.g. `WORKFLOW_ORDER_PIPELINE`. */
+  binding: string;
+  /** The `lunora/workflows.ts` export name, e.g. `orderPipeline`. */
+  exportName: string;
+}
+/**
+* Build the `ctx.workflows` handle for a request: resolve every spec's
+* `env[binding]` into the `exportName → Workflow binding` map and wrap it in
+* {@link createWorkflows}. A spec whose binding is absent from `env` is skipped
+* here — the helpful "no workflow named …" error is raised lazily by
+* `workflows.get(name)` when the missing workflow is actually used.
+*/
+declare const createWorkflowContext: (env: Record<string, unknown>, specs: ReadonlyArray<WorkflowBindingSpec>) => Workflows;
+/**
+* Build the `ctx.workflows` handle from a map of `lunora/workflows.ts` export
+* name → Cloudflare `Workflow` binding. `get(name)` resolves the typed handle;
+* an unknown name throws with the list of declared workflows.
+*/
+declare const createWorkflows: (options: LunoraWorkflowsOptions) => Workflows;
+/**
+* Declare a reusable durable step. Same `args` map shape a Lunora `query` /
+* `mutation` / `action` uses, so a step reads like a function:
+*
+* ```ts
+* // lunora/steps.ts
+* import { defineStep } from "@lunora/workflow";
+* import { v } from "@lunora/values";
+*
+* export const fetchImage = defineStep("fetch image", {
+*     args: { imageKey: v.string() },
+*     returns: v.object({ data: v.bytes() }),
+*     handler: async (ctx, { imageKey }) => {
+*         const object = await (ctx.env.BUCKET as R2Bucket).get(imageKey);
+*         return { data: new Uint8Array(await object!.arrayBuffer()) };
+*     },
+*     rollback: async (ctx) => {
+*         await (ctx.env.BUCKET as R2Bucket).delete(`tmp/${ctx.args.imageKey}`);
+*     },
+* });
+* ```
+*
+* Then, inside a `defineWorkflow` handler:
+*
+* ```ts
+* const { data } = await ctx.runStep(fetchImage, { imageKey: ctx.params.imageKey });
+* ```
+*/
+declare const defineStep: <A extends StepArgsValidator, Result>(name: string, config: StepConfig<A, Result>) => StepDefinition<A, Result>;
+/** True when a value is a `defineStep` result (the runtime brand check). */
+declare const isStepDefinition: (value: unknown) => value is StepDefinition;
+/**
+* The generated `WorkflowEntrypoint` class name for a `lunora/workflows.ts`
+* export: `orderPipeline` → `OrderPipelineWorkflow`. wrangler's
+* `workflows[].class_name` references it, so codegen and the config layer MUST
+* derive it identically — always via this helper.
+*/
+declare const workflowClassName: (exportName: string) => string;
+/**
+* The wrangler binding name for a workflow export: `orderPipeline` →
+* `WORKFLOW_ORDER_PIPELINE`, `etl` → `WORKFLOW_ETL`. The `WORKFLOW_` prefix
+* namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`/`CONTAINER_*` so a
+* workflow export can never collide with the built-in bindings.
+*/
+declare const workflowBindingName: (exportName: string) => string;
+/**
+* The stable workflow name wrangler registers (`workflows[].name`):
+* `orderPipeline` → `order-pipeline`. Used as the deployed workflow's
+* identifier when no explicit `name` override is given.
+*/
+declare const workflowDefaultName: (exportName: string) => string;
+/**
+* Declare a durable workflow deployed alongside the app. Pure validation +
+* branding: codegen discovers the export, emits the `WorkflowEntrypoint`
+* subclass (`_generated/workflows.ts`), and wires the typed `ctx.workflows`
+* handle; the config layer reconciles the wrangler `workflows[]` entry from the
+* same definition.
+*
+* ```ts
+* // lunora/workflows.ts
+* import { defineWorkflow } from "@lunora/workflow";
+* import { api } from "./_generated/api";
+*
+* export const orderPipeline = defineWorkflow&lt;{ orderId: string }>({
+*     handler: async (ctx) => {
+*         const order = await ctx.step.do("load", () => ctx.run(api.orders.get, { id: ctx.params.orderId }));
+*         await ctx.step.sleep("cool-off", "1 minute");
+*         await ctx.step.do("charge", () => ctx.run(api.payments.charge, { orderId: ctx.params.orderId }));
+*         return order;
+*     },
+* });
+* ```
+*/
+declare const defineWorkflow: <Params = Record<string, unknown>, Output = unknown>(config: WorkflowConfig<Params, Output>) => WorkflowDefinition<Params, Output>;
+/** True when a value is a `defineWorkflow` result (the runtime brand check). */
+declare const isWorkflowDefinition: (value: unknown) => value is WorkflowDefinition;
+/**
+* Throw from a workflow step (or handler) to fail the instance immediately
+* **without** retrying — the portable mirror of `cloudflare:workflows`'
+* `NonRetryableError`. Importable from Node, so workflow code stays unit-testable.
+*
+* ```ts
+* import { NonRetryableError } from "@lunora/workflow";
+*
+* if (order.status === "cancelled") {
+*     throw new NonRetryableError("order already cancelled — no point retrying");
+* }
+* ```
+*/
+declare class NonRetryableError extends Error {
+  constructor(message: string, name?: string);
+}
+/** True when `value` is a Lunora portable {@link NonRetryableError}. */
+declare const isNonRetryableError: (value: unknown) => value is NonRetryableError;
+/** Constructor shape of `cloudflare:workflows`' native `NonRetryableError`. */
+type NativeNonRetryableErrorConstructor = new (message: string, name?: string) => Error;
+/**
+* Rebuild a portable {@link NonRetryableError} as the native Cloudflare one,
+* preserving its `name`, `message`, `cause`, and `stack`. Used at the `src/do`
+* boundary where the native constructor is available; everywhere else the
+* portable error is thrown unchanged (and still honored by name).
+*/
+declare const toNativeNonRetryableError: (error: NonRetryableError, NativeNonRetryableError: NativeNonRetryableErrorConstructor) => Error;
+/**
+* If `error` is a portable {@link NonRetryableError} and a native constructor is
+* available, rethrow it as the native error; otherwise rethrow `error` as-is.
+* Always throws — the `never` return lets callers `return convertNonRetryableError(...)`.
+*/
+declare const convertNonRetryableError: (error: unknown, NativeNonRetryableError: NativeNonRetryableErrorConstructor | undefined) => never;
+/** The lifecycle mutations the REST API exposes via `PATCH .../instances/{id}`. */
+type WorkflowInstanceAction = "pause" | "resume" | "terminate";
+/** Configuration for a {@link WorkflowsRestClient}. */
+interface WorkflowsRestConfig {
+  /** Cloudflare account id that owns the workflow. */
+  accountId: string;
+  /** API token with `Workflows: Read` (and `Edit` for status mutation). A secret — never a binding. */
+  apiToken: string;
+  /** `fetch` implementation. Defaults to the global `fetch`; injected in tests so the path never touches the network. */
+  fetch?: typeof globalThis.fetch;
+}
+/** One row of the instance list — the summary the studio table renders. */
+interface WorkflowInstanceSummary {
+  createdOn?: string;
+  endedOn?: string;
+  id: string;
+  startedOn?: string;
+  status: WorkflowInstanceStatus;
+}
+/** One durable step of an instance, normalized from the REST `steps[]` array. */
+interface WorkflowStepDetail {
+  /** 1-based attempt count (`> 1` means the step retried). */
+  attempts?: number;
+  end?: string;
+  error?: unknown;
+  name: string;
+  output?: unknown;
+  start?: string;
+  success?: boolean;
+  /** `step` / `sleep` / `waitForEvent` / … (Cloudflare's step `type`). */
+  type?: string;
+}
+/** A single instance's full detail: its summary plus params/output/error and the step timeline. */
+interface WorkflowInstanceDetail extends WorkflowInstanceSummary {
+  error?: unknown;
+  output?: unknown;
+  params?: unknown;
+  steps: WorkflowStepDetail[];
+}
+/** A page of instances plus the cursor info Cloudflare returns in `result_info`. */
+interface WorkflowInstancePage {
+  instances: WorkflowInstanceSummary[];
+  page: number;
+  perPage: number;
+  totalCount?: number;
+}
+/** Thrown when the REST API responds non-2xx or `success: false`; carries the status plus body for the caller to surface. */
+declare class WorkflowsRestError extends Error {
+  readonly status: number;
+  constructor(status: number, body: string);
+}
+/** The observe client: list instances, read one instance's steps, and (with Edit scope) mutate its status. */
+interface WorkflowsRestClient {
+  getInstance: (args: {
+    instanceId: string;
+    workflowName: string;
+  }) => Promise<WorkflowInstanceDetail>;
+  listInstances: (args: {
+    page?: number;
+    perPage?: number;
+    status?: WorkflowInstanceStatus;
+    workflowName: string;
+  }) => Promise<WorkflowInstancePage>;
+  setInstanceStatus: (args: {
+    action: WorkflowInstanceAction;
+    instanceId: string;
+    workflowName: string;
+  }) => Promise<{
+    status: WorkflowInstanceStatus;
+  }>;
+}
+/**
+* Build a {@link WorkflowsRestClient}. Each call hits the account-scoped REST
+* endpoint with the bearer token, unwraps Cloudflare's
+* `{ success, errors, result, result_info }` envelope, and normalizes the
+* snake_case payload into the camelCase shapes the studio renders.
+*/
+declare const createWorkflowsRestClient: (config: WorkflowsRestConfig) => WorkflowsRestClient;
+interface RunnerOptions {
+  /** Worker `env` — read `LUNORA_ORIGIN_URL` + `LUNORA_ADMIN_TOKEN` at call time. */
+  env: Record<string, unknown>;
+  /** Injectable fetch (tests); defaults to the global. */
+  fetchImpl?: typeof fetch;
+}
+/**
+* Build a {@link WorkflowRunFunction} that invokes a Lunora function by POSTing
+* to the Worker's `/_lunora/scheduler/dispatch` endpoint — the same path the
+* SchedulerDO and the Queues workpool dispatch through — authenticated with the
+* admin bearer. The parsed JSON body (the function's return value) is resolved;
+* an empty/non-JSON body resolves to `undefined`.
+*
+* Wrap calls in `ctx.step.do(...)` to make them durable + memoized + retried.
+*/
+declare const createWorkflowRunner: (options: RunnerOptions) => WorkflowRunFunction;
+/** Console-backed logger, prefixed with the workflow name for log correlation. */
+declare const createWorkflowLogger: (exportName: string) => WorkflowLogger;
+interface RunContextOptions<Params> {
+  env: Record<string, unknown>;
+  event: WorkflowEventLike<Params>;
+  exportName: string;
+  fetchImpl?: typeof fetch;
+  /** Native `cloudflare:workflows` `NonRetryableError` — injected by `src/do`; absent in Node tests. */
+  nonRetryableErrorClass?: NativeNonRetryableErrorConstructor;
+  step: WorkflowStepLike;
+}
+/** Assemble the {@link WorkflowRunContext} passed to a `defineWorkflow` handler. */
+declare const createWorkflowRunContext: <Params = Record<string, unknown>>(options: RunContextOptions<Params>) => WorkflowRunContext<Params>;
+/**
+* Validate a step's args through its validator map, prefixing any
+* `ValidationError` with `step args.&lt;key>` so the failure points at the
+* offending field. Delegates to `@lunora/values`' shared {@link parseValidatorMap}
+* — the same parser the procedure builder and HTTP routes use — so the
+* optional-skip and error-prefix semantics stay in lockstep across the framework.
+*/
+declare const validateStepArgs: (validators: StepArgsValidator, source: Record<string, unknown>) => Record<string, unknown>;
+/** Dependencies needed to run a step: the native step API plus the workflow's env / runner / logger. */
+interface RunStepDeps {
+  /** The Worker environment bindings, surfaced on the step context. */
+  env: Record<string, unknown>;
+  /** Structured logger surfaced on the step context. */
+  log: WorkflowLogger;
+  /** Native `cloudflare:workflows` `NonRetryableError` constructor — injected by `src/do`; absent in Node tests. */
+  nonRetryableErrorClass?: NativeNonRetryableErrorConstructor;
+  /** The Lunora function runner, surfaced on the step context. */
+  run: WorkflowRunFunction;
+  /** The native Cloudflare durable-step API. */
+  step: WorkflowStepLike;
+}
+/**
+* Build the `ctx.runStep` function bound to one workflow invocation. Each call
+* runs the step through `step.do(...)`: validate args → run body → validate
+* result (when `returns` is declared), with any portable `NonRetryableError`
+* converted to the native one and any declared rollback forwarded to Cloudflare.
+*/
+declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
+export { type LunoraWorkflowsOptions, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };

package/dist/index.mjs

@@ -0,0 +1,8 @@
+export { createWorkflowContext } from './packem_shared/createWorkflowContext-D6thzmlF.mjs';
+export { default as createWorkflows } from './packem_shared/createWorkflows-BoSYVIXg.mjs';
+export { defineStep, isStepDefinition } from './packem_shared/defineStep-DJQtLw7g.mjs';
+export { defineWorkflow, isWorkflowDefinition, workflowBindingName, workflowClassName, workflowDefaultName } from './packem_shared/defineWorkflow-DbUC-oCN.mjs';
+export { NonRetryableError, convertNonRetryableError, isNonRetryableError, toNativeNonRetryableError } from './packem_shared/NonRetryableError-Dn2dTyBS.mjs';
+export { WorkflowsRestError, createWorkflowsRestClient } from './packem_shared/WorkflowsRestError-b06i7K5j.mjs';
+export { createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner } from './packem_shared/createWorkflowLogger-DR8P4ZoY.mjs';
+export { createRunStep, validateStepArgs } from './packem_shared/createRunStep-8jOXxP2o.mjs';

package/dist/packem_shared/NonRetryableError-Dn2dTyBS.mjs

@@ -0,0 +1,27 @@
+const NON_RETRYABLE_BRAND = "__lunoraNonRetryable";
+class NonRetryableError extends Error {
+  constructor(message, name = "NonRetryableError") {
+    super(message);
+    this.name = name;
+    this[NON_RETRYABLE_BRAND] = true;
+  }
+}
+const isNonRetryableError = (value) => value instanceof Error && value[NON_RETRYABLE_BRAND] === true;
+const toNativeNonRetryableError = (error, NativeNonRetryableError) => {
+  const native = new NativeNonRetryableError(error.message, error.name);
+  if (error.stack !== void 0) {
+    native.stack = error.stack;
+  }
+  if (error.cause !== void 0 && native.cause === void 0) {
+    native.cause = error.cause;
+  }
+  return native;
+};
+const convertNonRetryableError = (error, NativeNonRetryableError) => {
+  if (NativeNonRetryableError !== void 0 && isNonRetryableError(error)) {
+    throw toNativeNonRetryableError(error, NativeNonRetryableError);
+  }
+  throw error;
+};
+
+export { NonRetryableError, convertNonRetryableError, isNonRetryableError, toNativeNonRetryableError };