convex-effect-workflows 0.1.0

package/src/component/deferreds.ts

@@ -0,0 +1,162 @@
+import { v } from "convex/values";
+import { mutation, query, type MutationCtx, type QueryCtx } from "./_generated/server.js";
+import { scheduleRunnerFanIn } from "./boundaries.js";
+import { persistBoundedPayload, hydratePayload } from "./payloads.js";
+import { nowTs } from "./utils.js";
+
+type DbReaderCtx = Pick<QueryCtx, "db">;
+
+async function getDeferredRow(
+  ctx: DbReaderCtx,
+  executionId: string,
+  deferredName: string,
+) {
+  return await ctx.db
+    .query("deferreds")
+    .withIndex("by_execution_name", (q) =>
+      q.eq("executionId", executionId).eq("deferredName", deferredName),
+    )
+    .unique();
+}
+
+export const deferredResult = query({
+  args: {
+    executionId: v.string(),
+    deferredName: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const deferred = await getDeferredRow(ctx, args.executionId, args.deferredName);
+    if (!deferred || !deferred.completed) {
+      return undefined;
+    }
+    return await hydratePayload(ctx, deferred.exitRef, deferred.exitPreview);
+  },
+});
+
+export const deferredDone = mutation({
+  args: {
+    executionId: v.string(),
+    deferredName: v.string(),
+    exit: v.any(),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const existing = await getDeferredRow(ctx, args.executionId, args.deferredName);
+    if (existing?.completed) {
+      return { changed: false };
+    }
+
+    const exitPayload = await persistBoundedPayload(ctx, "deferredExit", args.exit);
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        completed: true,
+        completedAt: nowTs(),
+        exitRef: exitPayload.ref,
+        exitPreview: exitPayload.preview,
+      });
+    } else {
+      await ctx.db.insert("deferreds", {
+        executionId: args.executionId,
+        deferredName: args.deferredName,
+        completed: true,
+        completedAt: nowTs(),
+        exitRef: exitPayload.ref,
+        exitPreview: exitPayload.preview,
+      });
+    }
+
+    const execution = await ctx.db
+      .query("executions")
+      .withIndex("by_execution_id", (q) => q.eq("executionId", args.executionId))
+      .unique();
+
+    if (
+      execution &&
+      execution.runnerHandle &&
+      execution.status !== "completed" &&
+      execution.status !== "failed" &&
+      execution.status !== "interrupted"
+    ) {
+      await scheduleRunnerFanIn(ctx.scheduler, {
+        executionId: execution.executionId,
+        generation: execution.generation,
+      });
+    }
+
+    return { changed: true };
+  },
+});
+
+export const registerDeferred = mutation({
+  args: {
+    executionId: v.string(),
+    deferredName: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await getDeferredRow(ctx, args.executionId, args.deferredName);
+    if (!existing) {
+      await ctx.db.insert("deferreds", {
+        executionId: args.executionId,
+        deferredName: args.deferredName,
+        completed: false,
+      });
+    }
+    return null;
+  },
+});
+
+/**
+ * Test helper for creating a deferred record.
+ */
+export const createDeferred = mutation({
+  args: {
+    executionId: v.string(),
+    deferredName: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await getDeferredRow(ctx, args.executionId, args.deferredName);
+    if (existing) {
+      return null;
+    }
+    await ctx.db.insert("deferreds", {
+      executionId: args.executionId,
+      deferredName: args.deferredName,
+      completed: false,
+    });
+    return null;
+  },
+});
+
+/**
+ * Test helper for completing a deferred with exit value.
+ */
+export const completeDeferred = mutation({
+  args: {
+    executionId: v.string(),
+    deferredName: v.string(),
+    exit: v.any(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const exitPayload = await persistBoundedPayload(
+      ctx,
+      "deferredExit",
+      args.exit,
+    );
+
+    const existing = await getDeferredRow(ctx, args.executionId, args.deferredName);
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        completed: true,
+        completedAt: nowTs(),
+        exitRef: exitPayload.ref,
+        exitPreview: exitPayload.preview,
+      });
+    }
+    return null;
+  },
+});

package/src/component/executions.ts

@@ -0,0 +1,225 @@
+import { v } from "convex/values";
+import { mutation, query, type MutationCtx, type QueryCtx } from "./_generated/server.js";
+import { nowTs, generateTraceId } from "./utils.js";
+import { persistBoundedPayload } from "./payloads.js";
+import { vExecutionStatus } from "../shared/validators.js";
+import type { Doc } from "./_generated/dataModel.js";
+
+type DbReaderCtx = Pick<QueryCtx, "db">;
+
+async function getExecutionByExecutionId(
+  ctx: DbReaderCtx,
+  executionId: string,
+) {
+  return await ctx.db
+    .query("executions")
+    .withIndex("by_execution_id", (q) => q.eq("executionId", executionId))
+    .unique();
+}
+
+export async function mustGetExecution(
+  ctx: DbReaderCtx,
+  executionId: string,
+): Promise<Doc<"executions">> {
+  const execution = await getExecutionByExecutionId(ctx, executionId);
+  if (!execution) {
+    throw new Error(`Execution not found: ${executionId}`);
+  }
+  return execution;
+}
+
+export const createExecution = mutation({
+  args: {
+    workflowName: v.string(),
+    executionId: v.string(),
+    payload: v.any(),
+    tenantId: v.optional(v.string()),
+    parentExecutionId: v.optional(v.string()),
+    traceId: v.optional(v.string()),
+    runnerHandle: v.optional(v.string()),
+  },
+  returns: v.object({
+    created: v.boolean(),
+    executionId: v.id("executions"),
+  }),
+  handler: async (ctx, args) => {
+    const existing = await getExecutionByExecutionId(ctx, args.executionId);
+    if (existing) {
+      return { created: false, executionId: existing._id };
+    }
+
+    const payload = await persistBoundedPayload(
+      ctx,
+      "executionPayload",
+      args.payload,
+    );
+
+    const id = await ctx.db.insert("executions", {
+      workflowName: args.workflowName,
+      executionId: args.executionId,
+      status: "pending",
+      generation: 0,
+      tenantId: args.tenantId,
+      parentExecutionId: args.parentExecutionId,
+      payloadRef: payload.ref,
+      payloadPreview: payload.preview,
+      payloadSize: payload.size,
+      traceId: args.traceId ?? generateTraceId(),
+      runnerHandle: args.runnerHandle,
+      startedAt: nowTs(),
+    });
+
+    return { created: true, executionId: id };
+  },
+});
+
+export const setExecutionRunning = mutation({
+  args: {
+    executionId: v.string(),
+    generation: v.number(),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, { executionId, generation }) => {
+    const execution = await mustGetExecution(ctx, executionId);
+    if (execution.generation !== generation) {
+      return { changed: false };
+    }
+    if (
+      execution.status === "completed" ||
+      execution.status === "failed" ||
+      execution.status === "interrupted"
+    ) {
+      return { changed: false };
+    }
+    await ctx.db.patch(execution._id, {
+      status: "running",
+      lastResumedAt: nowTs(),
+    });
+    return { changed: true };
+  },
+});
+
+export const setExecutionSuspended = mutation({
+  args: {
+    executionId: v.string(),
+    generation: v.number(),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, { executionId, generation }) => {
+    const execution = await mustGetExecution(ctx, executionId);
+    if (execution.generation !== generation) {
+      return { changed: false };
+    }
+    if (
+      execution.status === "completed" ||
+      execution.status === "failed" ||
+      execution.status === "interrupted"
+    ) {
+      return { changed: false };
+    }
+    await ctx.db.patch(execution._id, {
+      status: "suspended",
+      lastSuspendedAt: nowTs(),
+    });
+    return { changed: true };
+  },
+});
+
+export const completeExecution = mutation({
+  args: {
+    executionId: v.string(),
+    generation: v.number(),
+    kind: v.union(v.literal("success"), v.literal("failure")),
+    result: v.optional(v.any()),
+    error: v.optional(v.string()),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const execution = await mustGetExecution(ctx, args.executionId);
+    if (execution.generation !== args.generation) {
+      return { changed: false };
+    }
+    if (
+      execution.status === "completed" ||
+      execution.status === "failed" ||
+      execution.status === "interrupted"
+    ) {
+      return { changed: false };
+    }
+
+    let resultRef = execution.resultRef;
+    let resultPreview = execution.resultPreview;
+    if (args.result !== undefined) {
+      const resultPayload = await persistBoundedPayload(
+        ctx,
+        "stepOutput",
+        args.result,
+      );
+      resultRef = resultPayload.ref;
+      resultPreview = resultPayload.preview;
+    }
+
+    await ctx.db.patch(execution._id, {
+      status: args.kind === "success" ? "completed" : "failed",
+      resultKind: args.kind,
+      resultRef,
+      resultPreview,
+      error: args.error,
+      completedAt: nowTs(),
+    });
+    return { changed: true };
+  },
+});
+
+export const interruptExecution = mutation({
+  args: {
+    executionId: v.string(),
+    reason: v.optional(v.string()),
+  },
+  returns: v.object({ generation: v.number() }),
+  handler: async (ctx, { executionId, reason }) => {
+    const execution = await mustGetExecution(ctx, executionId);
+    if (
+      execution.status === "completed" ||
+      execution.status === "failed" ||
+      execution.status === "interrupted"
+    ) {
+      return { generation: execution.generation };
+    }
+
+    const generation = execution.generation + 1;
+    await ctx.db.patch(execution._id, {
+      status: "interrupted",
+      generation,
+      error: reason ?? "Interrupted",
+      completedAt: nowTs(),
+    });
+    return { generation };
+  },
+});
+
+export const getExecution = query({
+  args: {
+    executionId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, { executionId }) => {
+    return await getExecutionByExecutionId(ctx, executionId);
+  },
+});
+
+/**
+ * Test helper for patching execution startedAt (simulates old executions).
+ */
+export const internalPatchExecution = mutation({
+  args: {
+    executionId: v.string(),
+    startedAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, { executionId, startedAt }) => {
+    const execution = await mustGetExecution(ctx, executionId);
+    await ctx.db.patch(execution._id, { startedAt });
+    return null;
+  },
+});

package/src/component/journalSteps.ts

@@ -0,0 +1,252 @@
+import { v } from "convex/values";
+import { mutation, query, type MutationCtx, type QueryCtx } from "./_generated/server.js";
+import {
+  vDeterminismSignature,
+  vResultEnvelope,
+  vStepKind,
+  vStepState,
+} from "../shared/validators.js";
+import { nowTs } from "./utils.js";
+import { persistBoundedPayload } from "./payloads.js";
+
+type DbReaderCtx = Pick<QueryCtx, "db">;
+
+async function getStep(
+  ctx: DbReaderCtx,
+  executionId: string,
+  stepNumber: number,
+) {
+  return await ctx.db
+    .query("journalSteps")
+    .withIndex("by_execution_step", (q) =>
+      q.eq("executionId", executionId).eq("stepNumber", stepNumber),
+    )
+    .unique();
+}
+
+export const appendJournalStep = mutation({
+  args: {
+    executionId: v.string(),
+    stepNumber: v.number(),
+    kind: vStepKind,
+    name: v.string(),
+    signature: vDeterminismSignature,
+    attempt: v.optional(v.number()),
+    spanId: v.optional(v.string()),
+    input: v.any(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const existing = await getStep(ctx, args.executionId, args.stepNumber);
+    if (existing) {
+      throw new Error(
+        `Duplicate journal step: ${args.executionId}/${args.stepNumber}`,
+      );
+    }
+
+    const inputPayload = await persistBoundedPayload(ctx, "stepInput", args.input);
+
+    const id = await ctx.db.insert("journalSteps", {
+      executionId: args.executionId,
+      stepNumber: args.stepNumber,
+      kind: args.kind,
+      name: args.name,
+      signature: args.signature,
+      state: "started",
+      attempt: args.attempt,
+      spanId: args.spanId,
+      inputRef: inputPayload.ref,
+      inputPreview: inputPayload.preview,
+      inputSize: inputPayload.size,
+      startedAt: nowTs(),
+    });
+
+    return await ctx.db.get(id);
+  },
+});
+
+export const suspendJournalStep = mutation({
+  args: {
+    executionId: v.string(),
+    stepNumber: v.number(),
+    workId: v.string(),
+    resumeToken: v.optional(v.string()),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const step = await getStep(ctx, args.executionId, args.stepNumber);
+    if (!step) {
+      throw new Error(
+        `Journal step not found: ${args.executionId}/${args.stepNumber}`,
+      );
+    }
+    if (step.state === "completed" || step.state === "failed" || step.state === "canceled") {
+      return { changed: false };
+    }
+    await ctx.db.patch(step._id, {
+      state: "suspended",
+      workId: args.workId,
+      resumeToken: args.resumeToken,
+    });
+    return { changed: true };
+  },
+});
+
+export const completeJournalStep = mutation({
+  args: {
+    executionId: v.string(),
+    stepNumber: v.number(),
+    runResult: vResultEnvelope,
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const step = await getStep(ctx, args.executionId, args.stepNumber);
+    if (!step) {
+      throw new Error(
+        `Journal step not found: ${args.executionId}/${args.stepNumber}`,
+      );
+    }
+    if (step.state === "completed" || step.state === "failed" || step.state === "canceled") {
+      return { changed: false };
+    }
+
+    let runResult = args.runResult;
+    if (runResult.kind !== "canceled" && runResult.valuePreview !== undefined) {
+      const outputPayload = await persistBoundedPayload(
+        ctx,
+        "stepOutput",
+        runResult.valuePreview,
+      );
+      runResult = {
+        ...runResult,
+        valueRef: outputPayload.ref,
+        valuePreview: outputPayload.preview,
+      };
+    }
+
+    await ctx.db.patch(step._id, {
+      state:
+        runResult.kind === "success"
+          ? "completed"
+          : runResult.kind === "failed"
+            ? "failed"
+            : "canceled",
+      runResult,
+      completedAt: nowTs(),
+    });
+
+    return { changed: true };
+  },
+});
+
+export const failJournalStep = mutation({
+  args: {
+    executionId: v.string(),
+    stepNumber: v.number(),
+    error: v.string(),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const step = await getStep(ctx, args.executionId, args.stepNumber);
+    if (!step) {
+      throw new Error(
+        `Journal step not found: ${args.executionId}/${args.stepNumber}`,
+      );
+    }
+    if (step.state === "completed" || step.state === "failed" || step.state === "canceled") {
+      return { changed: false };
+    }
+    await ctx.db.patch(step._id, {
+      state: "failed",
+      runResult: { kind: "failed", error: args.error },
+      completedAt: nowTs(),
+    });
+    return { changed: true };
+  },
+});
+
+export const getJournalStep = query({
+  args: {
+    executionId: v.string(),
+    stepNumber: v.number(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await getStep(ctx, args.executionId, args.stepNumber);
+  },
+});
+
+/**
+ * Validate deterministic replay signature for a specific step.
+ * Throws on mismatch to make determinism violations explicit.
+ */
+export const assertReplayStepSignature = query({
+  args: {
+    executionId: v.string(),
+    stepNumber: v.number(),
+    expectedSignature: vDeterminismSignature,
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const step = await getStep(ctx, args.executionId, args.stepNumber);
+    if (!step) {
+      return null;
+    }
+
+    const actual = JSON.stringify(step.signature);
+    const expected = JSON.stringify(args.expectedSignature);
+    if (actual !== expected) {
+      throw new Error(
+        `Determinism violation for ${args.executionId}/${args.stepNumber}: expected ${expected}, got ${actual}`,
+      );
+    }
+
+    return step;
+  },
+});
+
+export const loadJournalForExecution = query({
+  args: {
+    executionId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const rows = await ctx.db
+      .query("journalSteps")
+      .withIndex("by_execution_step", (q) => q.eq("executionId", args.executionId))
+      .collect();
+    rows.sort((a, b) => a.stepNumber - b.stepNumber);
+    return rows;
+  },
+});
+
+export const listJournalSteps = query({
+  args: {
+    executionId: v.string(),
+    state: v.optional(vStepState),
+    limit: v.number(),
+    afterStepNumber: v.optional(v.number()),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const limit = Math.max(1, Math.min(args.limit, 500));
+
+    let rows = await ctx.db
+      .query("journalSteps")
+      .withIndex("by_execution_step", (q) => q.eq("executionId", args.executionId))
+      .take(limit + 1);
+
+    if (args.afterStepNumber !== undefined) {
+      rows = rows.filter((row) => row.stepNumber > args.afterStepNumber!);
+    }
+    if (args.state) {
+      rows = rows.filter((row) => row.state === args.state);
+    }
+
+    const page = rows.slice(0, limit);
+    const nextAfterStepNumber =
+      rows.length > limit ? page[page.length - 1]?.stepNumber : undefined;
+
+    return { page, nextAfterStepNumber };
+  },
+});