convex-effect-workflows 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# convex-effect-workflows
+
+Effect-native durable workflows for Convex with first-class observability tables.
+
+## Current capabilities
+
+- Convex component schema + storage APIs for:
+  - executions
+  - ordered journal steps
+  - spans
+  - logs
+  - deferreds
+  - payload offload
+  - activity completion idempotency
+- Dashboard query endpoints:
+  - `listExecutions`
+  - `getExecution`
+  - `listExecutionSteps`
+  - `listExecutionSpans`
+  - `listExecutionLogs`
+- Client-side runtime utilities:
+  - `ConvexWorkflowEngine` (start/poll/resume/interrupt + dashboard reads)
+  - `makeConvexEncoded` + `makeWorkflowEngine` for `WorkflowEngine.Encoded`
+  - `defineWorkflowRunner` for workflow-style one-tick runner mutations
+  - `defineActivityWorker` + registry (`registerActivity`, `registerWorkflow`)
+
+## Workflow-style usage (current)
+
+```ts
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Workflow from "@effect/workflow/Workflow";
+import * as Activity from "@effect/workflow/Activity";
+import { components } from "./_generated/api";
+import {
+  ConvexWorkflowEngine,
+  defineWorkflowRunner,
+  defineActivityWorker,
+  registerActivity,
+  functionHandleForRunner,
+} from "convex-effect-workflows";
+
+const ProcessOrder = Workflow.make({
+  name: "processOrder",
+  payload: Schema.Struct({ orderId: Schema.String }),
+  success: Schema.Struct({ status: Schema.String }),
+  error: Schema.String,
+  idempotencyKey: (p) => p.orderId,
+});
+
+const validateOrder = Activity.make({
+  name: "validateOrder",
+  success: Schema.Boolean,
+  execute: Effect.succeed(true),
+});
+registerActivity(validateOrder);
+
+const activityWorker = defineActivityWorker();
+
+const runner = defineWorkflowRunner(
+  components.effectWorkflows,
+  ProcessOrder,
+  (payload) =>
+    Effect.gen(function*() {
+      const ok = yield* validateOrder;
+      if (!ok) return yield* Effect.fail("invalid");
+      return { status: "processed" };
+    }),
+  { activityWorker: "myModule:activityWorker" },
+);
+
+export const startOrder = mutation({
+  args: { orderId: v.string() },
+  handler: async (ctx, args) => {
+    const engine = new ConvexWorkflowEngine(components.effectWorkflows);
+    const runnerHandle = await functionHandleForRunner("myModule:runner");
+    return await engine.start(ctx, {
+      workflowName: ProcessOrder.name,
+      executionId: await Effect.runPromise(ProcessOrder.executionId({ orderId: args.orderId })),
+      payload: { orderId: args.orderId },
+      runner: runnerHandle,
+    });
+  },
+});
+```
+
+## Example host app
+
+A host app scaffold lives at `example/convex/`.
+
+For real `convex dev` / `convex deploy` from this repo, use
+`example/convex-deploy/` (wired via repo-root `convex.json`).
+
+This is the deployment model for standalone components: the host app mounts
+`convex-effect-workflows/convex.config` when published, or `../../src/component/convex.config.js`
+for local repo testing.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun run build
+bun run test
+```
+
+> `convex codegen --component-dir ./src/component` requires a configured Convex deployment (`CONVEX_DEPLOYMENT`).

package/dist/client/ConvexCtx.d.ts

@@ -0,0 +1,12 @@
+import * as Context from "effect/Context";
+import type { GenericActionCtx, GenericDataModel, GenericMutationCtx } from "convex/server";
+export type ConvexWorkflowCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation" | "runQuery" | "scheduler">;
+export type ConvexWorkflowActionCtx = Pick<GenericActionCtx<GenericDataModel>, "runMutation" | "runQuery" | "runAction">;
+declare const ConvexCtx_base: Context.TagClass<ConvexCtx, "convex-effect-workflows/ConvexCtx", ConvexWorkflowCtx>;
+export declare class ConvexCtx extends ConvexCtx_base {
+}
+declare const ConvexActionCtx_base: Context.TagClass<ConvexActionCtx, "convex-effect-workflows/ConvexActionCtx", ConvexWorkflowActionCtx>;
+export declare class ConvexActionCtx extends ConvexActionCtx_base {
+}
+export {};
+//# sourceMappingURL=ConvexCtx.d.ts.map

package/dist/client/ConvexCtx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexCtx.d.ts","sourceRoot":"","sources":["../../src/client/ConvexCtx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE5F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,kBAAkB,CAAC,gBAAgB,CAAC,EACpC,aAAa,GAAG,UAAU,GAAG,WAAW,CACzC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,IAAI,CACxC,gBAAgB,CAAC,gBAAgB,CAAC,EAClC,aAAa,GAAG,UAAU,GAAG,WAAW,CACzC,CAAC;;AAEF,qBAAa,SAAU,SAAQ,cAG5B;CAAG;;AAEN,qBAAa,eAAgB,SAAQ,oBAEQ;CAAG"}

package/dist/client/ConvexCtx.js

@@ -0,0 +1,6 @@
+import * as Context from "effect/Context";
+export class ConvexCtx extends Context.Tag("convex-effect-workflows/ConvexCtx")() {
+}
+export class ConvexActionCtx extends Context.Tag("convex-effect-workflows/ConvexActionCtx")() {
+}
+//# sourceMappingURL=ConvexCtx.js.map

package/dist/client/ConvexCtx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexCtx.js","sourceRoot":"","sources":["../../src/client/ConvexCtx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAa1C,MAAM,OAAO,SAAU,SAAQ,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,EAG5E;CAAG;AAEN,MAAM,OAAO,eAAgB,SAAQ,OAAO,CAAC,GAAG,CAC9C,yCAAyC,CAC1C,EAA4C;CAAG"}

package/dist/client/ConvexLogger.d.ts

@@ -0,0 +1,7 @@
+import * as Logger from "effect/Logger";
+import type { GenericMutationCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+type MutationRunCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
+export declare function makeConvexLogger(component: ComponentApi, ctx: MutationRunCtx, executionId: string, traceId?: string): Logger.Logger<unknown, void>;
+export {};
+//# sourceMappingURL=ConvexLogger.d.ts.map

package/dist/client/ConvexLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexLogger.d.ts","sourceRoot":"","sources":["../../src/client/ConvexLogger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,KAAK,cAAc,GAAG,IAAI,CACxB,kBAAkB,CAAC,gBAAgB,CAAC,EACpC,aAAa,CACd,CAAC;AAWF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,YAAY,EACvB,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAwB9B"}

package/dist/client/ConvexLogger.js

@@ -0,0 +1,39 @@
+import * as HashMap from "effect/HashMap";
+import * as List from "effect/List";
+import * as Logger from "effect/Logger";
+import * as Option from "effect/Option";
+function messageToString(message) {
+    if (typeof message === "string")
+        return message;
+    try {
+        return JSON.stringify(message);
+    }
+    catch {
+        return String(message);
+    }
+}
+export function makeConvexLogger(component, ctx, executionId, traceId) {
+    return Logger.make((options) => {
+        const span = List.head(options.spans);
+        const spanId = Option.match(span, {
+            onNone: () => undefined,
+            onSome: (currentSpan) => currentSpan.label,
+        });
+        void ctx
+            .runMutation(component.logs.appendLog, {
+            executionId,
+            traceId,
+            spanId,
+            level: options.logLevel.label.toLowerCase(),
+            source: "workflow",
+            message: messageToString(options.message),
+            data: {
+                annotations: HashMap.toEntries(options.annotations),
+            },
+        })
+            .catch(() => {
+            // Never fail the workflow because logging persistence fails.
+        });
+    });
+}
+//# sourceMappingURL=ConvexLogger.js.map

package/dist/client/ConvexLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexLogger.js","sourceRoot":"","sources":["../../src/client/ConvexLogger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAUxC,SAAS,eAAe,CAAC,OAAgB;IACvC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAuB,EACvB,GAAmB,EACnB,WAAmB,EACnB,OAAgB;IAEhB,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE;YAChC,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS;YACvB,MAAM,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK;SAC3C,CAAC,CAAC;QAEH,KAAK,GAAG;aACL,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE;YACrC,WAAW;YACX,OAAO;YACP,MAAM;YACN,KAAK,EAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAA0C;YACpF,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC;YACzC,IAAI,EAAE;gBACJ,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC;aACpD;SACF,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,6DAA6D;QAC/D,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/client/ConvexTracer.d.ts

@@ -0,0 +1,7 @@
+import * as Tracer from "effect/Tracer";
+import type { GenericDataModel, GenericMutationCtx } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+type MutationRunCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
+export declare function makeConvexTracer(component: ComponentApi, ctx: MutationRunCtx, executionId: string, traceId: string): Tracer.Tracer;
+export {};
+//# sourceMappingURL=ConvexTracer.d.ts.map

package/dist/client/ConvexTracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexTracer.d.ts","sourceRoot":"","sources":["../../src/client/ConvexTracer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,KAAK,cAAc,GAAG,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,CAAC;AAEhF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,YAAY,EACvB,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,CA4Df"}

package/dist/client/ConvexTracer.js

@@ -0,0 +1,60 @@
+import * as Context from "effect/Context";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Tracer from "effect/Tracer";
+export function makeConvexTracer(component, ctx, executionId, traceId) {
+    return Tracer.make({
+        span: (name, parent, _context, _links, _startTime, kind, options) => {
+            const parentSpanId = Option.match(parent, {
+                onNone: () => undefined,
+                onSome: (span) => span.spanId,
+            });
+            const spanId = crypto.randomUUID().replaceAll("-", "").slice(0, 16);
+            void ctx
+                .runMutation(component.spans.createSpan, {
+                executionId,
+                traceId,
+                spanId,
+                parentSpanId,
+                name,
+                kind: "system",
+                input: undefined,
+                attributes: options?.attributes,
+            })
+                .catch(() => { });
+            const attributes = new Map(options?.attributes ? Object.entries(options.attributes) : []);
+            const span = {
+                _tag: "Span",
+                name,
+                spanId,
+                traceId,
+                parent,
+                context: Context.empty(),
+                status: { _tag: "Started", startTime: 0n },
+                attributes,
+                links: [],
+                sampled: true,
+                kind,
+                end: (_endTime, exit) => {
+                    void ctx
+                        .runMutation(component.spans.endSpan, {
+                        executionId,
+                        spanId,
+                        output: Exit.isSuccess(exit) ? exit.value : undefined,
+                        error: Exit.isFailure(exit) ? String(exit.cause) : undefined,
+                        attributes: Object.fromEntries(attributes.entries()),
+                    })
+                        .catch(() => { });
+                },
+                attribute: (key, value) => {
+                    attributes.set(key, value);
+                },
+                event: () => { },
+                addLinks: () => { },
+            };
+            return span;
+        },
+        context: (f) => f(),
+    });
+}
+//# sourceMappingURL=ConvexTracer.js.map

package/dist/client/ConvexTracer.js.map

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

package/dist/client/ConvexWorkflowEngine.d.ts

@@ -0,0 +1,308 @@
+import type { FunctionHandle, GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { ExecutionStatus, LogLevel, LogSource, SortOrder, SpanKind, SpanStatus, StepState } from "../shared/validators.js";
+export type MutationRunCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation" | "runQuery" | "scheduler">;
+export type QueryRunCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+export type RunnerArgs = {
+    executionId: string;
+    generation: number;
+};
+export type RunnerHandle = FunctionHandle<"mutation", RunnerArgs, void>;
+export type StartWorkflowArgs = {
+    workflowName: string;
+    executionId: string;
+    payload: unknown;
+    runner: RunnerHandle;
+    tenantId?: string;
+    parentExecutionId?: string;
+    traceId?: string;
+};
+export type ResumeWorkflowArgs = {
+    executionId: string;
+};
+export declare class ConvexWorkflowEngine {
+    component: ComponentApi;
+    constructor(component: ComponentApi);
+    start(ctx: MutationRunCtx, args: StartWorkflowArgs): Promise<string>;
+    poll(ctx: QueryRunCtx, executionId: string): Promise<any>;
+    interrupt(ctx: MutationRunCtx, executionId: string, reason?: string): Promise<{
+        generation: number;
+    }>;
+    resume(ctx: MutationRunCtx, args: ResumeWorkflowArgs): Promise<void>;
+    listExecutions(ctx: QueryRunCtx, args?: {
+        workflowName?: string;
+        status?: ExecutionStatus;
+        tenantId?: string;
+        startedAfter?: number;
+        startedBefore?: number;
+        limit?: number;
+        cursorStartedAt?: number;
+        cursorExecutionId?: string;
+        order?: SortOrder;
+    }): Promise<{
+        cursor: {
+            executionId: string;
+            startedAt: number;
+        } | null;
+        isDone: boolean;
+        page: Array<{
+            _creationTime: number;
+            _id: string;
+            completedAt?: number;
+            error?: string;
+            executionId: string;
+            generation: number;
+            lastResumedAt?: number;
+            lastSuspendedAt?: number;
+            parentExecutionId?: string;
+            payloadPreview?: any;
+            payloadRef?: string;
+            payloadSize: number;
+            resultKind?: "success" | "failure";
+            resultPreview?: any;
+            resultRef?: string;
+            runnerHandle?: string;
+            startedAt: number;
+            status: "pending" | "running" | "suspended" | "completed" | "failed" | "interrupted";
+            tenantId?: string;
+            traceId: string;
+            workflowName: string;
+        }>;
+    }>;
+    getExecution(ctx: QueryRunCtx, executionId: string): Promise<{
+        execution: {
+            _creationTime: number;
+            _id: string;
+            completedAt?: number;
+            error?: string;
+            executionId: string;
+            generation: number;
+            lastResumedAt?: number;
+            lastSuspendedAt?: number;
+            parentExecutionId?: string;
+            payloadPreview?: any;
+            payloadRef?: string;
+            payloadSize: number;
+            resultKind?: "success" | "failure";
+            resultPreview?: any;
+            resultRef?: string;
+            runnerHandle?: string;
+            startedAt: number;
+            status: "pending" | "running" | "suspended" | "completed" | "failed" | "interrupted";
+            tenantId?: string;
+            traceId: string;
+            workflowName: string;
+        };
+        logs: Array<{
+            _creationTime: number;
+            _id: string;
+            data?: any;
+            executionId: string;
+            level: "debug" | "info" | "warn" | "error";
+            message: string;
+            source: "workflow" | "activity" | "engine" | "system";
+            spanId?: string;
+            stepNumber?: number;
+            timestamp: number;
+            traceId?: string;
+        }>;
+        spans: Array<{
+            _creationTime: number;
+            _id: string;
+            attempt?: number;
+            attributes?: any;
+            endTime?: number;
+            error?: string;
+            executionId: string;
+            inputPreview?: any;
+            inputRef?: string;
+            inputSize?: number;
+            kind: "workflow" | "activity" | "deferred" | "clock" | "system";
+            name: string;
+            outputPreview?: any;
+            outputRef?: string;
+            outputSize?: number;
+            parentSpanId?: string;
+            spanId: string;
+            startTime: number;
+            status: "started" | "ended";
+            stepNumber?: number;
+            traceId: string;
+        }>;
+        steps: Array<{
+            _creationTime: number;
+            _id: string;
+            attempt?: number;
+            completedAt?: number;
+            executionId: string;
+            inputPreview?: any;
+            inputRef?: string;
+            inputSize: number;
+            kind: "activity" | "deferred" | "clock" | "nestedWorkflow" | "system";
+            name: string;
+            resumeToken?: string;
+            runResult?: {
+                kind: "success";
+                valuePreview?: any;
+                valueRef?: string;
+            } | {
+                error: string;
+                kind: "failed";
+                valuePreview?: any;
+                valueRef?: string;
+            } | {
+                kind: "canceled";
+            };
+            signature: {
+                attempt?: number;
+                kind: "activity" | "deferred" | "clock" | "nestedWorkflow" | "system";
+                opName: string;
+                scheduleMeta?: any;
+                schemaVersion?: number;
+            };
+            spanId?: string;
+            startedAt: number;
+            state: "started" | "suspended" | "completed" | "failed" | "canceled";
+            stepNumber: number;
+            workId?: string;
+        }>;
+    } | null>;
+    listExecutionSteps(ctx: QueryRunCtx, args: {
+        executionId: string;
+        state?: StepState;
+        limit?: number;
+        afterStepNumber?: number;
+    }): Promise<{
+        cursor: number | null;
+        isDone: boolean;
+        page: Array<{
+            _creationTime: number;
+            _id: string;
+            attempt?: number;
+            completedAt?: number;
+            executionId: string;
+            inputPreview?: any;
+            inputRef?: string;
+            inputSize: number;
+            kind: "activity" | "deferred" | "clock" | "nestedWorkflow" | "system";
+            name: string;
+            resumeToken?: string;
+            runResult?: {
+                kind: "success";
+                valuePreview?: any;
+                valueRef?: string;
+            } | {
+                error: string;
+                kind: "failed";
+                valuePreview?: any;
+                valueRef?: string;
+            } | {
+                kind: "canceled";
+            };
+            signature: {
+                attempt?: number;
+                kind: "activity" | "deferred" | "clock" | "nestedWorkflow" | "system";
+                opName: string;
+                scheduleMeta?: any;
+                schemaVersion?: number;
+            };
+            spanId?: string;
+            startedAt: number;
+            state: "started" | "suspended" | "completed" | "failed" | "canceled";
+            stepNumber: number;
+            workId?: string;
+        }>;
+    }>;
+    listExecutionSpans(ctx: QueryRunCtx, args: {
+        executionId: string;
+        kind?: SpanKind;
+        status?: SpanStatus;
+        limit?: number;
+        afterStartTime?: number;
+    }): Promise<{
+        cursor: {
+            spanId: string;
+            startTime: number;
+        } | null;
+        isDone: boolean;
+        page: Array<{
+            _creationTime: number;
+            _id: string;
+            attempt?: number;
+            attributes?: any;
+            endTime?: number;
+            error?: string;
+            executionId: string;
+            inputPreview?: any;
+            inputRef?: string;
+            inputSize?: number;
+            kind: "workflow" | "activity" | "deferred" | "clock" | "system";
+            name: string;
+            outputPreview?: any;
+            outputRef?: string;
+            outputSize?: number;
+            parentSpanId?: string;
+            spanId: string;
+            startTime: number;
+            status: "started" | "ended";
+            stepNumber?: number;
+            traceId: string;
+        }>;
+    }>;
+    listExecutionLogs(ctx: QueryRunCtx, args: {
+        executionId: string;
+        level?: LogLevel;
+        source?: LogSource;
+        spanId?: string;
+        limit?: number;
+        afterTimestamp?: number;
+        order?: SortOrder;
+    }): Promise<{
+        cursor: {
+            logId: string;
+            timestamp: number;
+        } | null;
+        isDone: boolean;
+        page: Array<{
+            _creationTime: number;
+            _id: string;
+            data?: any;
+            executionId: string;
+            level: "debug" | "info" | "warn" | "error";
+            message: string;
+            source: "workflow" | "activity" | "engine" | "system";
+            spanId?: string;
+            stepNumber?: number;
+            timestamp: number;
+            traceId?: string;
+        }>;
+    }>;
+    getConfig(ctx: QueryRunCtx): Promise<{
+        defaultLogLevel: "debug" | "info" | "warn" | "error";
+        maxInlineBytes: number;
+        maxLogDataBytes: number;
+        maxSpanAttrBytes: number;
+        retentionDays: number;
+    }>;
+    setConfig(ctx: MutationRunCtx, args: {
+        maxInlineBytes?: number;
+        maxLogDataBytes?: number;
+        maxSpanAttrBytes?: number;
+        retentionDays?: number;
+        defaultLogLevel?: LogLevel;
+    }): Promise<{
+        defaultLogLevel: "debug" | "info" | "warn" | "error";
+        maxInlineBytes: number;
+        maxLogDataBytes: number;
+        maxSpanAttrBytes: number;
+        retentionDays: number;
+    }>;
+    cleanup(ctx: MutationRunCtx, args?: {
+        retentionDays?: number;
+        limit?: number;
+    }): Promise<{
+        deletedCount: number;
+        hasMore: boolean;
+    }>;
+}
+//# sourceMappingURL=ConvexWorkflowEngine.d.ts.map

package/dist/client/ConvexWorkflowEngine.d.ts.map

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

package/dist/client/ConvexWorkflowEngine.js

@@ -0,0 +1,88 @@
+import { scheduleRunnerFanIn, serializeRunnerHandle, } from "./boundaries.js";
+export class ConvexWorkflowEngine {
+    component;
+    constructor(component) {
+        this.component = component;
+    }
+    async start(ctx, args) {
+        const { created } = await ctx.runMutation(this.component.executions.createExecution, {
+            workflowName: args.workflowName,
+            executionId: args.executionId,
+            payload: args.payload,
+            tenantId: args.tenantId,
+            parentExecutionId: args.parentExecutionId,
+            traceId: args.traceId,
+            runnerHandle: serializeRunnerHandle(args.runner),
+        });
+        if (created) {
+            await scheduleRunnerFanIn(ctx.scheduler, this.component, {
+                executionId: args.executionId,
+                generation: 0,
+            });
+        }
+        return args.executionId;
+    }
+    async poll(ctx, executionId) {
+        return await ctx.runQuery(this.component.executions.getExecution, {
+            executionId,
+        });
+    }
+    async interrupt(ctx, executionId, reason) {
+        return await ctx.runMutation(this.component.executions.interruptExecution, {
+            executionId,
+            reason,
+        });
+    }
+    async resume(ctx, args) {
+        const execution = await ctx.runQuery(this.component.executions.getExecution, {
+            executionId: args.executionId,
+        });
+        if (!execution ||
+            execution.status === "completed" ||
+            execution.status === "failed" ||
+            execution.status === "interrupted") {
+            return;
+        }
+        await scheduleRunnerFanIn(ctx.scheduler, this.component, {
+            executionId: args.executionId,
+            generation: execution.generation,
+        });
+    }
+    async listExecutions(ctx, args) {
+        return await ctx.runQuery(this.component.dashboard.listExecutions, {
+            workflowName: args?.workflowName,
+            status: args?.status,
+            tenantId: args?.tenantId,
+            startedAfter: args?.startedAfter,
+            startedBefore: args?.startedBefore,
+            limit: args?.limit,
+            cursorStartedAt: args?.cursorStartedAt,
+            cursorExecutionId: args?.cursorExecutionId,
+            order: args?.order,
+        });
+    }
+    async getExecution(ctx, executionId) {
+        return await ctx.runQuery(this.component.dashboard.getExecution, {
+            executionId,
+        });
+    }
+    async listExecutionSteps(ctx, args) {
+        return await ctx.runQuery(this.component.dashboard.listExecutionSteps, args);
+    }
+    async listExecutionSpans(ctx, args) {
+        return await ctx.runQuery(this.component.dashboard.listExecutionSpans, args);
+    }
+    async listExecutionLogs(ctx, args) {
+        return await ctx.runQuery(this.component.dashboard.listExecutionLogs, args);
+    }
+    async getConfig(ctx) {
+        return await ctx.runQuery(this.component.config.getConfig, {});
+    }
+    async setConfig(ctx, args) {
+        return await ctx.runMutation(this.component.config.setConfig, args);
+    }
+    async cleanup(ctx, args) {
+        return await ctx.runMutation(this.component.cleanup.cleanupOldExecutions, args ?? {});
+    }
+}
+//# sourceMappingURL=ConvexWorkflowEngine.js.map