convex-effect-workflows 0.1.0

package/dist/component/journalSteps.d.ts

@@ -0,0 +1,261 @@
+export declare const appendJournalStep: import("convex/server").RegisteredMutation<"public", {
+    spanId?: string | undefined;
+    attempt?: number | undefined;
+    executionId: string;
+    stepNumber: number;
+    kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+    input: any;
+    name: string;
+    signature: {
+        attempt?: number | undefined;
+        scheduleMeta?: any;
+        schemaVersion?: number | undefined;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        opName: string;
+    };
+}, Promise<{
+    _id: import("convex/values").GenericId<"journalSteps">;
+    _creationTime: number;
+    workId?: string | undefined;
+    spanId?: string | undefined;
+    attempt?: number | undefined;
+    runResult?: {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        kind: "success";
+    } | {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        error: string;
+        kind: "failed";
+    } | {
+        kind: "canceled";
+    } | undefined;
+    resumeToken?: string | undefined;
+    completedAt?: number | undefined;
+    inputRef?: import("convex/values").GenericId<"payloads"> | undefined;
+    inputPreview?: any;
+    executionId: string;
+    stepNumber: number;
+    kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+    state: "suspended" | "completed" | "failed" | "started" | "canceled";
+    startedAt: number;
+    name: string;
+    signature: {
+        attempt?: number | undefined;
+        scheduleMeta?: any;
+        schemaVersion?: number | undefined;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        opName: string;
+    };
+    inputSize: number;
+} | null>>;
+export declare const suspendJournalStep: import("convex/server").RegisteredMutation<"public", {
+    resumeToken?: string | undefined;
+    workId: string;
+    executionId: string;
+    stepNumber: number;
+}, Promise<{
+    changed: boolean;
+}>>;
+export declare const completeJournalStep: import("convex/server").RegisteredMutation<"public", {
+    executionId: string;
+    stepNumber: number;
+    runResult: {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        kind: "success";
+    } | {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        error: string;
+        kind: "failed";
+    } | {
+        kind: "canceled";
+    };
+}, Promise<{
+    changed: boolean;
+}>>;
+export declare const failJournalStep: import("convex/server").RegisteredMutation<"public", {
+    executionId: string;
+    stepNumber: number;
+    error: string;
+}, Promise<{
+    changed: boolean;
+}>>;
+export declare const getJournalStep: import("convex/server").RegisteredQuery<"public", {
+    executionId: string;
+    stepNumber: number;
+}, Promise<{
+    _id: import("convex/values").GenericId<"journalSteps">;
+    _creationTime: number;
+    workId?: string | undefined;
+    spanId?: string | undefined;
+    attempt?: number | undefined;
+    runResult?: {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        kind: "success";
+    } | {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        error: string;
+        kind: "failed";
+    } | {
+        kind: "canceled";
+    } | undefined;
+    resumeToken?: string | undefined;
+    completedAt?: number | undefined;
+    inputRef?: import("convex/values").GenericId<"payloads"> | undefined;
+    inputPreview?: any;
+    executionId: string;
+    stepNumber: number;
+    kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+    state: "suspended" | "completed" | "failed" | "started" | "canceled";
+    startedAt: number;
+    name: string;
+    signature: {
+        attempt?: number | undefined;
+        scheduleMeta?: any;
+        schemaVersion?: number | undefined;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        opName: string;
+    };
+    inputSize: number;
+} | null>>;
+/**
+ * Validate deterministic replay signature for a specific step.
+ * Throws on mismatch to make determinism violations explicit.
+ */
+export declare const assertReplayStepSignature: import("convex/server").RegisteredQuery<"public", {
+    executionId: string;
+    stepNumber: number;
+    expectedSignature: {
+        attempt?: number | undefined;
+        scheduleMeta?: any;
+        schemaVersion?: number | undefined;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        opName: string;
+    };
+}, Promise<{
+    _id: import("convex/values").GenericId<"journalSteps">;
+    _creationTime: number;
+    workId?: string | undefined;
+    spanId?: string | undefined;
+    attempt?: number | undefined;
+    runResult?: {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        kind: "success";
+    } | {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        error: string;
+        kind: "failed";
+    } | {
+        kind: "canceled";
+    } | undefined;
+    resumeToken?: string | undefined;
+    completedAt?: number | undefined;
+    inputRef?: import("convex/values").GenericId<"payloads"> | undefined;
+    inputPreview?: any;
+    executionId: string;
+    stepNumber: number;
+    kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+    state: "suspended" | "completed" | "failed" | "started" | "canceled";
+    startedAt: number;
+    name: string;
+    signature: {
+        attempt?: number | undefined;
+        scheduleMeta?: any;
+        schemaVersion?: number | undefined;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        opName: string;
+    };
+    inputSize: number;
+} | null>>;
+export declare const loadJournalForExecution: import("convex/server").RegisteredQuery<"public", {
+    executionId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"journalSteps">;
+    _creationTime: number;
+    workId?: string | undefined;
+    spanId?: string | undefined;
+    attempt?: number | undefined;
+    runResult?: {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        kind: "success";
+    } | {
+        valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        valuePreview?: any;
+        error: string;
+        kind: "failed";
+    } | {
+        kind: "canceled";
+    } | undefined;
+    resumeToken?: string | undefined;
+    completedAt?: number | undefined;
+    inputRef?: import("convex/values").GenericId<"payloads"> | undefined;
+    inputPreview?: any;
+    executionId: string;
+    stepNumber: number;
+    kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+    state: "suspended" | "completed" | "failed" | "started" | "canceled";
+    startedAt: number;
+    name: string;
+    signature: {
+        attempt?: number | undefined;
+        scheduleMeta?: any;
+        schemaVersion?: number | undefined;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        opName: string;
+    };
+    inputSize: number;
+}[]>>;
+export declare const listJournalSteps: import("convex/server").RegisteredQuery<"public", {
+    afterStepNumber?: number | undefined;
+    state?: "suspended" | "completed" | "failed" | "started" | "canceled" | undefined;
+    executionId: string;
+    limit: number;
+}, Promise<{
+    page: {
+        _id: import("convex/values").GenericId<"journalSteps">;
+        _creationTime: number;
+        workId?: string | undefined;
+        spanId?: string | undefined;
+        attempt?: number | undefined;
+        runResult?: {
+            valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+            valuePreview?: any;
+            kind: "success";
+        } | {
+            valueRef?: import("convex/values").GenericId<"payloads"> | undefined;
+            valuePreview?: any;
+            error: string;
+            kind: "failed";
+        } | {
+            kind: "canceled";
+        } | undefined;
+        resumeToken?: string | undefined;
+        completedAt?: number | undefined;
+        inputRef?: import("convex/values").GenericId<"payloads"> | undefined;
+        inputPreview?: any;
+        executionId: string;
+        stepNumber: number;
+        kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+        state: "suspended" | "completed" | "failed" | "started" | "canceled";
+        startedAt: number;
+        name: string;
+        signature: {
+            attempt?: number | undefined;
+            scheduleMeta?: any;
+            schemaVersion?: number | undefined;
+            kind: "activity" | "system" | "deferred" | "clock" | "nestedWorkflow";
+            opName: string;
+        };
+        inputSize: number;
+    }[];
+    nextAfterStepNumber: number | undefined;
+}>>;
+//# sourceMappingURL=journalSteps.d.ts.map

package/dist/component/journalSteps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journalSteps.d.ts","sourceRoot":"","sources":["../../src/component/journalSteps.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuC5B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;GAyB7B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;GA6C9B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;GAwB1B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UASzB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuBpC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAalC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6B3B,CAAC"}

package/dist/component/journalSteps.js

@@ -0,0 +1,203 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+import { vDeterminismSignature, vResultEnvelope, vStepKind, vStepState, } from "../shared/validators.js";
+import { nowTs } from "./utils.js";
+import { persistBoundedPayload } from "./payloads.js";
+async function getStep(ctx, executionId, stepNumber) {
+    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 };
+    },
+});
+//# sourceMappingURL=journalSteps.js.map

package/dist/component/journalSteps.js.map

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

package/dist/component/logs.d.ts

@@ -0,0 +1,68 @@
+export declare const appendLog: import("convex/server").RegisteredMutation<"public", {
+    stepNumber?: number | undefined;
+    spanId?: string | undefined;
+    traceId?: string | undefined;
+    data?: any;
+    timestamp?: number | undefined;
+    executionId: string;
+    level: "debug" | "info" | "warn" | "error";
+    source: "workflow" | "activity" | "engine" | "system";
+    message: string;
+}, Promise<null>>;
+export declare const listExecutionLogs: import("convex/server").RegisteredQuery<"public", {
+    afterTimestamp?: number | undefined;
+    level?: "debug" | "info" | "warn" | "error" | undefined;
+    source?: "workflow" | "activity" | "engine" | "system" | undefined;
+    spanId?: string | undefined;
+    executionId: string;
+    limit: number;
+}, Promise<{
+    page: {
+        _id: import("convex/values").GenericId<"logs">;
+        _creationTime: number;
+        stepNumber?: number | undefined;
+        spanId?: string | undefined;
+        traceId?: string | undefined;
+        data?: any;
+        executionId: string;
+        level: "debug" | "info" | "warn" | "error";
+        source: "workflow" | "activity" | "engine" | "system";
+        message: string;
+        timestamp: number;
+    }[];
+    nextAfterTimestamp: number | undefined;
+}>>;
+export declare const listSpanLogs: import("convex/server").RegisteredQuery<"public", {
+    afterTimestamp?: number | undefined;
+    limit: number;
+    spanId: string;
+}, Promise<{
+    page: {
+        _id: import("convex/values").GenericId<"logs">;
+        _creationTime: number;
+        stepNumber?: number | undefined;
+        spanId?: string | undefined;
+        traceId?: string | undefined;
+        data?: any;
+        executionId: string;
+        level: "debug" | "info" | "warn" | "error";
+        source: "workflow" | "activity" | "engine" | "system";
+        message: string;
+        timestamp: number;
+    }[];
+    nextAfterTimestamp: number | undefined;
+}>>;
+/**
+ * Test helper for creating a simple log entry.
+ */
+export declare const createLog: import("convex/server").RegisteredMutation<"public", {
+    stepNumber?: number | undefined;
+    spanId?: string | undefined;
+    traceId?: string | undefined;
+    executionId: string;
+    level: "debug" | "info" | "warn" | "error";
+    source: "workflow" | "activity" | "engine" | "system";
+    message: string;
+    timestamp: number;
+}, Promise<null>>;
+//# sourceMappingURL=logs.d.ts.map

package/dist/component/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/component/logs.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,SAAS;;;;;;;;;;iBAqCpB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;GAsC5B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;GAyBvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;iBAmCpB,CAAC"}

package/dist/component/logs.js

@@ -0,0 +1,123 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+import { vLogLevel, vLogSource } from "../shared/validators.js";
+import { nowTs } from "./utils.js";
+import { persistBoundedPayload } from "./payloads.js";
+import { MAX_LOG_DATA_BYTES } from "../shared/constants.js";
+export const appendLog = mutation({
+    args: {
+        executionId: v.string(),
+        traceId: v.optional(v.string()),
+        spanId: v.optional(v.string()),
+        stepNumber: v.optional(v.number()),
+        level: vLogLevel,
+        message: v.string(),
+        source: vLogSource,
+        data: v.optional(v.any()),
+        timestamp: v.optional(v.number()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const dataPayload = args.data === undefined
+            ? undefined
+            : await persistBoundedPayload(ctx, "logData", args.data, MAX_LOG_DATA_BYTES);
+        await ctx.db.insert("logs", {
+            executionId: args.executionId,
+            traceId: args.traceId,
+            spanId: args.spanId,
+            stepNumber: args.stepNumber,
+            level: args.level,
+            message: args.message,
+            source: args.source,
+            data: dataPayload?.preview,
+            timestamp: args.timestamp ?? nowTs(),
+        });
+        return null;
+    },
+});
+export const listExecutionLogs = query({
+    args: {
+        executionId: v.string(),
+        limit: v.number(),
+        afterTimestamp: v.optional(v.number()),
+        level: v.optional(vLogLevel),
+        source: v.optional(vLogSource),
+        spanId: v.optional(v.string()),
+    },
+    returns: v.any(),
+    handler: async (ctx, args) => {
+        const limit = Math.max(1, Math.min(args.limit, 500));
+        let rows = await ctx.db
+            .query("logs")
+            .withIndex("by_execution_time", (q) => q.eq("executionId", args.executionId))
+            .take(limit + 500);
+        if (args.afterTimestamp !== undefined) {
+            rows = rows.filter((row) => row.timestamp > args.afterTimestamp);
+        }
+        if (args.level) {
+            rows = rows.filter((row) => row.level === args.level);
+        }
+        if (args.source) {
+            rows = rows.filter((row) => row.source === args.source);
+        }
+        if (args.spanId) {
+            rows = rows.filter((row) => row.spanId === args.spanId);
+        }
+        rows.sort((a, b) => a.timestamp - b.timestamp);
+        const page = rows.slice(0, limit);
+        const nextAfterTimestamp = rows.length > limit ? page[page.length - 1]?.timestamp : undefined;
+        return { page, nextAfterTimestamp };
+    },
+});
+export const listSpanLogs = query({
+    args: {
+        spanId: v.string(),
+        limit: v.number(),
+        afterTimestamp: 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("logs")
+            .withIndex("by_span_time", (q) => q.eq("spanId", args.spanId))
+            .take(limit + 200);
+        if (args.afterTimestamp !== undefined) {
+            rows = rows.filter((row) => row.timestamp > args.afterTimestamp);
+        }
+        rows.sort((a, b) => a.timestamp - b.timestamp);
+        const page = rows.slice(0, limit);
+        const nextAfterTimestamp = rows.length > limit ? page[page.length - 1]?.timestamp : undefined;
+        return { page, nextAfterTimestamp };
+    },
+});
+/**
+ * Test helper for creating a simple log entry.
+ */
+export const createLog = mutation({
+    args: {
+        executionId: v.string(),
+        traceId: v.optional(v.string()),
+        level: v.union(v.literal("debug"), v.literal("info"), v.literal("warn"), v.literal("error")),
+        message: v.string(),
+        source: v.union(v.literal("workflow"), v.literal("activity"), v.literal("engine"), v.literal("system")),
+        timestamp: v.number(),
+        spanId: v.optional(v.string()),
+        stepNumber: v.optional(v.number()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.db.insert("logs", {
+            executionId: args.executionId,
+            traceId: args.traceId,
+            spanId: args.spanId,
+            stepNumber: args.stepNumber,
+            level: args.level,
+            message: args.message,
+            source: args.source,
+            timestamp: args.timestamp,
+        });
+        return null;
+    },
+});
+//# sourceMappingURL=logs.js.map