@voyantjs/workflow-runs 0.21.0

package/dist/schema.js

@@ -0,0 +1,96 @@
+/**
+ * `@voyantjs/workflow-runs` — schema for the lightweight observability
+ * surface that records in-process workflow lifecycles (saga steps the
+ * `@voyantjs/core/workflows` primitive runs, plus any other "I'm a
+ * workflow" code path that opts in via `recordWorkflowRun`).
+ *
+ * Distinct from the durable `@voyantjs/workflows` SDK's
+ * `voyant_snapshot_runs` schema — that one needs an orchestrator
+ * process to drive it, which doesn't fit the Cloudflare Workers
+ * deployment shape. This schema is edge-compatible (postgres-js or
+ * neon-http) so templates can register the routes inside their
+ * existing API surface.
+ *
+ * Tags as JSONB array — lets callers query "all runs for booking X"
+ * without hard-coding domain joins. The recorder's convention is to
+ * tag with `bookingId:<id>`, `paymentSessionId:<id>`, etc.
+ */
+import { typeId, typeIdRef } from "@voyantjs/db";
+import { sql } from "drizzle-orm";
+import { check, index, integer, jsonb, pgEnum, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+export const workflowRunStatusEnum = pgEnum("workflow_run_status", [
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+]);
+export const workflowRunStepStatusEnum = pgEnum("workflow_run_step_status", [
+    "running",
+    "succeeded",
+    "failed",
+    "skipped",
+    "compensated",
+]);
+export const workflowRuns = pgTable("workflow_runs", {
+    id: typeId("workflow_runs"),
+    workflowName: text("workflow_name").notNull(),
+    /** Where the run came from — usually an event name or a trigger id. */
+    trigger: text("trigger").notNull().default("manual"),
+    correlationId: text("correlation_id"),
+    /** Free-form domain tags. Convention is `<key>:<value>` strings. */
+    tags: jsonb("tags").$type().notNull().default([]),
+    status: workflowRunStatusEnum("status").notNull().default("running"),
+    input: jsonb("input").$type(),
+    result: jsonb("result").$type(),
+    /** Compact error payload — message + optional code + step name. */
+    error: jsonb("error").$type(),
+    /**
+     * Parent run id when this run was triggered as a rerun/resume of
+     * another run. Self-references the same table; nullable because
+     * the original run has no parent.
+     */
+    parentRunId: text("parent_run_id"),
+    /** User who triggered the rerun/resume (null for system runs). */
+    triggeredByUserId: text("triggered_by_user_id"),
+    /**
+     * When set, the run is a resume — the executor skips steps until
+     * (and not including) this step name, hydrating ctx.results from
+     * the parent run's recorded step outputs.
+     */
+    resumeFromStep: text("resume_from_step"),
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    durationMs: integer("duration_ms"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    index("idx_workflow_runs_workflow").on(table.workflowName, table.startedAt),
+    index("idx_workflow_runs_status_started").on(table.status, table.startedAt),
+    index("idx_workflow_runs_correlation").on(table.correlationId),
+    index("idx_workflow_runs_parent").on(table.parentRunId),
+    // GIN index on tags so `tags @> '["bookingId:bk_…"]'::jsonb` is fast.
+    index("idx_workflow_runs_tags_gin").using("gin", sql `${table.tags}`),
+    check("ck_workflow_runs_completion", sql `(
+        ${table.status} = 'running' AND ${table.completedAt} IS NULL
+      ) OR (
+        ${table.status} <> 'running' AND ${table.completedAt} IS NOT NULL
+      )`),
+]);
+export const workflowRunSteps = pgTable("workflow_run_steps", {
+    id: typeId("workflow_run_steps"),
+    runId: typeIdRef("run_id")
+        .notNull()
+        .references(() => workflowRuns.id, { onDelete: "cascade" }),
+    stepName: text("step_name").notNull(),
+    /** Order within the workflow — incremented as the step is reached. */
+    sequence: integer("sequence").notNull(),
+    status: workflowRunStepStatusEnum("status").notNull().default("running"),
+    output: jsonb("output").$type(),
+    error: jsonb("error").$type(),
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    durationMs: integer("duration_ms"),
+}, (table) => [
+    index("idx_workflow_run_steps_run").on(table.runId, table.sequence),
+    index("idx_workflow_run_steps_status").on(table.status),
+]);

package/dist/service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Read-side service for the workflow runs UI. The recorder writes
+ * rows; this is what the dashboard SPA / admin endpoints query.
+ */
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type WorkflowRun, type WorkflowRunStep } from "./schema.js";
+export interface ListWorkflowRunsQuery {
+    /** Filter by workflow id (e.g. "checkout-finalize"). */
+    workflowName?: string;
+    /** Filter by status. */
+    status?: "running" | "succeeded" | "failed" | "cancelled";
+    /** Filter by tag membership — exact tag string match. */
+    tag?: string;
+    /** Filter to runs that descend from this parent (children only). */
+    parentRunId?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ListWorkflowRunsResult {
+    data: WorkflowRun[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export declare const workflowRunsService: {
+    listRuns(db: PostgresJsDatabase, query: ListWorkflowRunsQuery): Promise<ListWorkflowRunsResult>;
+    getRunById(db: PostgresJsDatabase, id: string): Promise<{
+        run: WorkflowRun;
+        steps: WorkflowRunStep[];
+    } | null>;
+};
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAkC,MAAM,aAAa,CAAA;AAEpG,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wBAAwB;IACxB,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;IACzD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,EAAE,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,eAAO,MAAM,mBAAmB;iBAExB,kBAAkB,SACf,qBAAqB,GAC3B,OAAO,CAAC,sBAAsB,CAAC;mBAiC5B,kBAAkB,MAClB,MAAM,GACT,OAAO,CAAC;QAAE,GAAG,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,eAAe,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;CAUlE,CAAA"}

package/dist/service.js

@@ -0,0 +1,54 @@
+/**
+ * Read-side service for the workflow runs UI. The recorder writes
+ * rows; this is what the dashboard SPA / admin endpoints query.
+ */
+import { and, desc, eq, sql } from "drizzle-orm";
+import { workflowRunSteps, workflowRuns } from "./schema.js";
+export const workflowRunsService = {
+    async listRuns(db, query) {
+        const limit = clamp(query.limit ?? 50, 1, 200);
+        const offset = Math.max(query.offset ?? 0, 0);
+        const conds = [];
+        if (query.workflowName)
+            conds.push(eq(workflowRuns.workflowName, query.workflowName));
+        if (query.status)
+            conds.push(eq(workflowRuns.status, query.status));
+        if (query.parentRunId)
+            conds.push(eq(workflowRuns.parentRunId, query.parentRunId));
+        if (query.tag) {
+            // jsonb contains — `tags @> '["bookingId:bk_…"]'::jsonb`
+            conds.push(sql `${workflowRuns.tags} @> ${JSON.stringify([query.tag])}::jsonb`);
+        }
+        const where = conds.length > 0 ? and(...conds) : undefined;
+        const [rows, countRow] = await Promise.all([
+            db
+                .select()
+                .from(workflowRuns)
+                .where(where)
+                .orderBy(desc(workflowRuns.startedAt))
+                .limit(limit)
+                .offset(offset),
+            db.select({ count: sql `count(*)::int` }).from(workflowRuns).where(where),
+        ]);
+        return {
+            data: rows,
+            total: countRow[0]?.count ?? 0,
+            limit,
+            offset,
+        };
+    },
+    async getRunById(db, id) {
+        const [run] = await db.select().from(workflowRuns).where(eq(workflowRuns.id, id)).limit(1);
+        if (!run)
+            return null;
+        const steps = await db
+            .select()
+            .from(workflowRunSteps)
+            .where(eq(workflowRunSteps.runId, id))
+            .orderBy(workflowRunSteps.sequence);
+        return { run, steps };
+    },
+};
+function clamp(n, min, max) {
+    return Math.max(min, Math.min(max, Math.floor(n)));
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@voyantjs/workflow-runs",
+  "version": "0.21.0",
+  "description": "Workflow run recording, admin routes, and rerun/resume dispatch primitives for Voyant operator apps.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schema": "./src/schema.ts",
+    "./service": "./src/service.ts",
+    "./routes": "./src/routes.ts",
+    "./recorder": "./src/recorder.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "@voyantjs/core": "workspace:*",
+    "@voyantjs/db": "workspace:*",
+    "@voyantjs/hono": "workspace:*",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.12.10",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@voyantjs/voyant-typescript-config": "workspace:*",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./schema": {
+        "types": "./dist/schema.d.ts",
+        "import": "./dist/schema.js",
+        "default": "./dist/schema.js"
+      },
+      "./service": {
+        "types": "./dist/service.d.ts",
+        "import": "./dist/service.js",
+        "default": "./dist/service.js"
+      },
+      "./routes": {
+        "types": "./dist/routes.d.ts",
+        "import": "./dist/routes.js",
+        "default": "./dist/routes.js"
+      },
+      "./recorder": {
+        "types": "./dist/recorder.d.ts",
+        "import": "./dist/recorder.js",
+        "default": "./dist/recorder.js"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyantjs/voyant.git",
+    "directory": "packages/workflow-runs"
+  }
+}