@rivet-dev/vercel-world 2.3.6

package/src/actors/coordinator.ts

@@ -0,0 +1,360 @@
+import {
+	type ListHooksParams,
+	type ListWorkflowRunsParams,
+	type WorkflowRun,
+} from "@workflow/world";
+import { actor } from "rivetkit";
+import { encodeValue } from "../codec.js";
+import { coordinatorDb } from "./db.js";
+import {
+	filterData,
+	one,
+	rowToRun,
+	toMs,
+	withActorTransaction,
+	type Ctx,
+} from "./shared.js";
+
+export type CoordinatorContext = Ctx;
+
+type CorrelationKind = "step" | "hook" | "wait";
+type Timestamp = Date | number | string;
+
+export type CoordinatorIndexUpdate =
+	| { type: "run.upsert"; run: WorkflowRun; runRevision: number }
+	| {
+			type: "correlation.put" | "correlation.delete";
+			correlationId: string;
+			runId: string;
+			kind: CorrelationKind;
+			runRevision: number;
+	  }
+	| {
+			type: "hook.upsert" | "hook.delete";
+			hookId: string;
+			runId: string;
+			token: string;
+			runRevision: number;
+			createdAt: Timestamp;
+			updatedAt: Timestamp;
+	  };
+
+function assertCoordinatorKey(c: { key: readonly unknown[] }) {
+	if (String(c.key[0] ?? "") !== "coordinator" || c.key.length !== 1) {
+		throw new Error('coordinator actor key must be ["coordinator"]');
+	}
+}
+
+function assertRevision(revision: number) {
+	if (!Number.isSafeInteger(revision) || revision < 0) {
+		throw new Error("coordinator update requires a non-negative run revision");
+	}
+}
+
+function timestamp(value: Timestamp): number {
+	const result = toMs(value);
+	if (result == null || !Number.isFinite(result)) {
+		throw new Error("coordinator update requires a valid timestamp");
+	}
+	return result;
+}
+
+async function upsertRun(c: Ctx, run: WorkflowRun, runRevision: number) {
+	await c.db.execute(
+		`
+		INSERT INTO runs_index (
+			run_id, run_revision, status, deployment_id, workflow_name,
+			spec_version, execution_context, attributes, input, output, error,
+			expired_at, started_at, completed_at, created_at, updated_at
+		)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(run_id) DO UPDATE SET
+			run_revision = excluded.run_revision,
+			status = excluded.status,
+			deployment_id = excluded.deployment_id,
+			workflow_name = excluded.workflow_name,
+			spec_version = excluded.spec_version,
+			execution_context = excluded.execution_context,
+			attributes = excluded.attributes,
+			input = excluded.input,
+			output = excluded.output,
+			error = excluded.error,
+			expired_at = excluded.expired_at,
+			started_at = excluded.started_at,
+			completed_at = excluded.completed_at,
+			created_at = excluded.created_at,
+			updated_at = excluded.updated_at
+		WHERE excluded.run_revision >= runs_index.run_revision
+		`,
+		run.runId,
+		runRevision,
+		run.status,
+		run.deploymentId,
+		run.workflowName,
+		run.specVersion ?? null,
+		encodeValue(run.executionContext),
+		encodeValue(run.attributes),
+		encodeValue(run.input),
+		encodeValue(run.output),
+		encodeValue(run.error),
+		toMs(run.expiredAt),
+		toMs(run.startedAt),
+		toMs(run.completedAt),
+		toMs(run.createdAt),
+		toMs(run.updatedAt),
+	);
+}
+
+async function updateCorrelation(
+	c: Ctx,
+	input: Extract<
+		CoordinatorIndexUpdate,
+		{ type: "correlation.put" | "correlation.delete" }
+	>,
+) {
+	const existing = await one(
+		c,
+		"SELECT run_id, kind FROM correlation_index WHERE correlation_id = ?",
+		input.correlationId,
+	);
+	if (
+		existing &&
+		(String(existing.run_id) !== input.runId ||
+			String(existing.kind) !== input.kind)
+	) {
+		throw new Error(
+			`correlation "${input.correlationId}" is already owned by another workflow entity`,
+		);
+	}
+
+	const status = input.type === "correlation.put" ? "active" : "deleted";
+	await c.db.execute(
+		`
+		INSERT INTO correlation_index (
+			correlation_id, run_id, kind, run_revision, status
+		)
+		VALUES (?, ?, ?, ?, ?)
+		ON CONFLICT(correlation_id) DO UPDATE SET
+			run_revision = excluded.run_revision,
+			status = excluded.status
+		WHERE
+			NOT (
+				correlation_index.status = 'deleted'
+				AND excluded.status = 'active'
+			)
+			AND (
+				excluded.run_revision > correlation_index.run_revision
+				OR (
+					excluded.run_revision = correlation_index.run_revision
+					AND (
+						excluded.status = 'deleted'
+						OR correlation_index.status = excluded.status
+					)
+				)
+			)
+		`,
+		input.correlationId,
+		input.runId,
+		input.kind,
+		input.runRevision,
+		status,
+	);
+}
+
+async function updateHook(
+	c: Ctx,
+	input: Extract<
+		CoordinatorIndexUpdate,
+		{ type: "hook.upsert" | "hook.delete" }
+	>,
+) {
+	const existing = await one(
+		c,
+		"SELECT run_id FROM hooks_index WHERE hook_id = ?",
+		input.hookId,
+	);
+	if (existing && String(existing.run_id) !== input.runId) {
+		throw new Error(`hook "${input.hookId}" is already owned by another workflow run`);
+	}
+
+	const status = input.type === "hook.upsert" ? "active" : "deleted";
+	await c.db.execute(
+		`
+		INSERT INTO hooks_index (
+			hook_id, run_id, run_revision, token, status, created_at, updated_at
+		)
+		VALUES (?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(hook_id) DO UPDATE SET
+			run_revision = excluded.run_revision,
+			token = excluded.token,
+			status = excluded.status,
+			created_at = excluded.created_at,
+			updated_at = excluded.updated_at
+		WHERE
+			NOT (hooks_index.status = 'deleted' AND excluded.status = 'active')
+			AND (
+				excluded.run_revision > hooks_index.run_revision
+				OR (
+					excluded.run_revision = hooks_index.run_revision
+					AND (
+						excluded.status = 'deleted'
+						OR hooks_index.status = excluded.status
+					)
+				)
+			)
+		`,
+		input.hookId,
+		input.runId,
+		input.runRevision,
+		input.token,
+		status,
+		timestamp(input.createdAt),
+		timestamp(input.updatedAt),
+	);
+}
+
+/** Applies one derived index update. Canonical workflow progress never awaits this. */
+export async function applyCoordinatorUpdate(
+	c: CoordinatorContext,
+	input: CoordinatorIndexUpdate,
+) {
+	assertRevision(input.runRevision);
+	await withActorTransaction(c, async (tx) => {
+		switch (input.type) {
+			case "run.upsert":
+				await upsertRun(tx, input.run, input.runRevision);
+				break;
+			case "correlation.put":
+			case "correlation.delete":
+				await updateCorrelation(tx, input);
+				break;
+			case "hook.upsert":
+			case "hook.delete":
+				await updateHook(tx, input);
+				break;
+		}
+	});
+}
+
+type IndexCursor = readonly [createdAt: number, id: string];
+
+function encodeCursor(createdAt: unknown, id: unknown): string {
+	return JSON.stringify([Number(createdAt), String(id)] satisfies IndexCursor);
+}
+
+function decodeCursor(cursor: string | undefined): IndexCursor | undefined {
+	if (cursor == null) return undefined;
+	try {
+		const value: unknown = JSON.parse(cursor);
+		if (
+			!Array.isArray(value) ||
+			value.length !== 2 ||
+			!Number.isFinite(value[0]) ||
+			typeof value[1] !== "string"
+		) {
+			throw new Error();
+		}
+		return [Number(value[0]), value[1]];
+	} catch {
+		throw new Error("invalid coordinator pagination cursor");
+	}
+}
+
+export const coordinator = actor({
+	db: coordinatorDb,
+	actions: {
+		update: async (c, input: CoordinatorIndexUpdate) => {
+			assertCoordinatorKey(c);
+			await applyCoordinatorUpdate(c as unknown as CoordinatorContext, input);
+		},
+		getRunIdByCorrelation: async (c, correlationId: string) => {
+			assertCoordinatorKey(c);
+			const row = await one(
+				c,
+				`SELECT run_id FROM correlation_index
+				 WHERE correlation_id = ? AND status = 'active'`,
+				correlationId,
+			);
+			return row?.run_id == null ? null : String(row.run_id);
+		},
+		getRunIdByHook: async (c, hookId: string) => {
+			assertCoordinatorKey(c);
+			const row = await one(
+				c,
+				"SELECT run_id FROM hooks_index WHERE hook_id = ? AND status = 'active'",
+				hookId,
+			);
+			return row?.run_id == null ? null : String(row.run_id);
+		},
+		listHookIndex: async (c, params?: ListHooksParams) => {
+			assertCoordinatorKey(c);
+			const limit = params?.pagination?.limit ?? 100;
+			const cursor = decodeCursor(params?.pagination?.cursor);
+			const where = ["status = 'active'"];
+			const args: unknown[] = [];
+			if (cursor) {
+				where.push("(created_at, hook_id) < (?, ?)");
+				args.push(...cursor);
+			}
+			const rows = await c.db.execute(
+				`
+				SELECT hook_id, run_id, created_at
+				FROM hooks_index
+				WHERE ${where.join(" AND ")}
+				ORDER BY created_at DESC, hook_id DESC
+				LIMIT ?
+				`,
+				...args,
+				limit + 1,
+			);
+			const values = rows.slice(0, limit);
+			const last = values.at(-1);
+			return {
+				data: values.map((row) => ({
+					hookId: String(row.hook_id),
+					runId: String(row.run_id),
+				})),
+				cursor: last ? encodeCursor(last.created_at, last.hook_id) : null,
+				hasMore: rows.length > limit,
+			};
+		},
+		listRuns: async (c, params?: ListWorkflowRunsParams) => {
+			assertCoordinatorKey(c);
+			const limit = params?.pagination?.limit ?? 20;
+			const cursor = decodeCursor(params?.pagination?.cursor);
+			const where: string[] = [];
+			const args: unknown[] = [];
+			if (cursor) {
+				where.push("(created_at, run_id) < (?, ?)");
+				args.push(...cursor);
+			}
+			if (params?.workflowName) {
+				where.push("workflow_name = ?");
+				args.push(params.workflowName);
+			}
+			if (params?.status) {
+				where.push("status = ?");
+				args.push(params.status);
+			}
+			const rows = await c.db.execute(
+				`
+				SELECT * FROM runs_index
+				${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+				ORDER BY created_at DESC, run_id DESC
+				LIMIT ?
+				`,
+				...args,
+				limit + 1,
+			);
+			const values = rows.slice(0, limit);
+			const last = values.at(-1);
+			return {
+				data: values.map((row) =>
+					filterData(rowToRun(row), params?.resolveData),
+				),
+				cursor: last ? encodeCursor(last.created_at, last.run_id) : null,
+				hasMore: rows.length > limit,
+			};
+		},
+	},
+});

package/src/actors/db.ts

@@ -0,0 +1,291 @@
+import { db } from "rivetkit/db";
+import {
+	migrations,
+	type MigrationDatabase,
+} from "rivetkit/unstable/migrations";
+
+const bootstrapWorkflowDb = async (database: MigrationDatabase) => {
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS workflow_runs (
+			run_id TEXT PRIMARY KEY,
+			run_revision INTEGER NOT NULL DEFAULT 0,
+			status TEXT NOT NULL,
+			deployment_id TEXT NOT NULL,
+			workflow_name TEXT NOT NULL,
+			spec_version INTEGER,
+			execution_context BLOB,
+			attributes BLOB,
+			input BLOB,
+			output BLOB,
+			error BLOB,
+			expired_at INTEGER,
+			started_at INTEGER,
+			completed_at INTEGER,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL
+		)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS workflow_events (
+			event_id TEXT PRIMARY KEY,
+			run_id TEXT NOT NULL,
+			event_type TEXT NOT NULL,
+			correlation_id TEXT,
+			event_data BLOB,
+			spec_version INTEGER,
+			created_at INTEGER NOT NULL
+		)
+	`);
+	await database.execute(`
+		CREATE UNIQUE INDEX IF NOT EXISTS uq_events_create_step
+		ON workflow_events(correlation_id)
+		WHERE event_type = 'step_created'
+	`);
+	await database.execute(`
+		CREATE UNIQUE INDEX IF NOT EXISTS uq_events_create_hook
+		ON workflow_events(correlation_id)
+		WHERE event_type = 'hook_created'
+	`);
+	await database.execute(`
+		CREATE UNIQUE INDEX IF NOT EXISTS uq_events_create_wait
+		ON workflow_events(correlation_id)
+		WHERE event_type = 'wait_created'
+	`);
+	// Creation-event dedup (SPEC §3.2). IMPORTANT: every index here is scoped to a
+	// SINGLE workflowRun actor's own `c.db` — there is one `workflow_events` table
+	// per run. `uq_events_create_run` enforces "one run_created per database",
+	// which is correct ONLY because each run owns its database. Do NOT move these
+	// tables into a shared/global database without re-scoping these indexes by
+	// `run_id`, or the run-singleton guarantee silently collapses.
+	await database.execute(`
+		CREATE UNIQUE INDEX IF NOT EXISTS uq_events_create_run
+		ON workflow_events(event_type)
+		WHERE event_type = 'run_created'
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS workflow_steps (
+			step_id TEXT PRIMARY KEY,
+			run_id TEXT NOT NULL,
+			step_name TEXT NOT NULL,
+			status TEXT NOT NULL,
+			input BLOB,
+			output BLOB,
+			error BLOB,
+			attempt INTEGER NOT NULL,
+			started_at INTEGER,
+			completed_at INTEGER,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			retry_after INTEGER,
+			spec_version INTEGER
+		)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS workflow_hooks (
+			hook_id TEXT PRIMARY KEY,
+			run_id TEXT NOT NULL,
+			token TEXT NOT NULL,
+			token_generation INTEGER,
+			owner_id TEXT NOT NULL,
+			project_id TEXT NOT NULL,
+			environment TEXT NOT NULL,
+			metadata BLOB,
+			created_at INTEGER NOT NULL,
+			spec_version INTEGER,
+			is_webhook INTEGER
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS idx_workflow_hooks_token
+		ON workflow_hooks(token)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS workflow_waits (
+			wait_id TEXT PRIMARY KEY,
+			run_id TEXT NOT NULL,
+			status TEXT NOT NULL,
+			resume_at INTEGER,
+			runtime_url TEXT,
+			queue_name TEXT,
+			headers TEXT,
+			resume_enqueued_at INTEGER,
+			completed_at INTEGER,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			spec_version INTEGER
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS idx_workflow_waits_due
+		ON workflow_waits(status, resume_at)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS idx_workflow_events_correlation
+		ON workflow_events(correlation_id, event_id)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS dispatcher_queue (
+			message_id TEXT PRIMARY KEY,
+			queue_name TEXT NOT NULL,
+			route TEXT NOT NULL,
+			runtime_url TEXT NOT NULL,
+			body TEXT NOT NULL,
+			headers TEXT,
+			idem_key TEXT,
+			status TEXT NOT NULL,
+			attempt INTEGER NOT NULL DEFAULT 0,
+			next_at INTEGER NOT NULL,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			started_at INTEGER,
+			finished_at INTEGER,
+			http_status INTEGER,
+			error TEXT
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS idx_dispatcher_queue_ready
+		ON dispatcher_queue(status, next_at, created_at)
+	`);
+	await database.execute(`
+		CREATE UNIQUE INDEX IF NOT EXISTS uq_dispatcher_queue_idem
+		ON dispatcher_queue(idem_key) WHERE idem_key IS NOT NULL
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS stream_chunks (
+			stream_id TEXT NOT NULL,
+			sequence INTEGER NOT NULL,
+			chunk_data BLOB,
+			eof INTEGER NOT NULL,
+			created_at INTEGER NOT NULL,
+			PRIMARY KEY (stream_id, sequence)
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS idx_stream_chunks_stream
+		ON stream_chunks(stream_id, sequence)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS run_streams (
+			stream_id TEXT PRIMARY KEY
+		)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS pending_ops (
+			op_id TEXT PRIMARY KEY,
+			op_type TEXT NOT NULL,
+			payload BLOB NOT NULL,
+			operation_revision INTEGER NOT NULL,
+			status TEXT NOT NULL CHECK (status IN ('ready', 'inflight')),
+			claim_id TEXT,
+			next_at INTEGER NOT NULL,
+			attempt INTEGER NOT NULL DEFAULT 0,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS idx_pending_ops_due
+		ON pending_ops(status, next_at, created_at)
+	`);
+};
+
+const bootstrapCoordinatorDb = async (database: MigrationDatabase) => {
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS runs_index (
+			run_id TEXT PRIMARY KEY,
+			run_revision INTEGER NOT NULL,
+			status TEXT NOT NULL,
+			deployment_id TEXT NOT NULL,
+			workflow_name TEXT NOT NULL,
+			spec_version INTEGER,
+			execution_context BLOB,
+			attributes BLOB,
+			input BLOB,
+			output BLOB,
+			error BLOB,
+			expired_at INTEGER,
+			started_at INTEGER,
+			completed_at INTEGER,
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS runs_index_list
+		ON runs_index(created_at DESC, run_id DESC)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS runs_index_name_list
+		ON runs_index(workflow_name, created_at DESC, run_id DESC)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS runs_index_status_list
+		ON runs_index(status, created_at DESC, run_id DESC)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS runs_index_name_status_list
+		ON runs_index(workflow_name, status, created_at DESC, run_id DESC)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS correlation_index (
+			correlation_id TEXT PRIMARY KEY,
+			run_id TEXT NOT NULL,
+			kind TEXT NOT NULL CHECK (kind IN ('step', 'hook', 'wait')),
+			run_revision INTEGER NOT NULL,
+			status TEXT NOT NULL CHECK (status IN ('active', 'deleted'))
+		)
+	`);
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS hooks_index (
+			hook_id TEXT PRIMARY KEY,
+			run_id TEXT NOT NULL,
+			run_revision INTEGER NOT NULL,
+			token TEXT NOT NULL,
+			status TEXT NOT NULL CHECK (status IN ('active', 'deleted')),
+			created_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL
+		)
+	`);
+	await database.execute(`
+		CREATE INDEX IF NOT EXISTS hooks_index_list
+		ON hooks_index(status, created_at DESC, hook_id DESC)
+	`);
+};
+
+const bootstrapHookTokenDb = async (database: MigrationDatabase) => {
+	await database.execute(`
+		CREATE TABLE IF NOT EXISTS hook_token_state (
+			singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+			generation INTEGER NOT NULL,
+			run_id TEXT,
+			hook_id TEXT,
+			status TEXT NOT NULL CHECK (status IN ('empty', 'pending', 'confirmed')),
+			created_at INTEGER,
+			updated_at INTEGER NOT NULL,
+			expires_at INTEGER
+		)
+	`);
+	await database.execute(
+		`INSERT OR IGNORE INTO hook_token_state (
+			singleton, generation, status, updated_at
+		) VALUES (1, 0, 'empty', ?)`,
+		Date.now(),
+	);
+};
+
+export const migrateWorkflowDb = migrations({
+	tableName: "vercel_world_workflow_schema_version",
+	migrations: [{ version: 1, up: bootstrapWorkflowDb }],
+});
+export const migrateCoordinatorDb = migrations({
+	tableName: "vercel_world_coordinator_schema_version",
+	migrations: [{ version: 1, up: bootstrapCoordinatorDb }],
+});
+export const migrateHookTokenDb = migrations({
+	tableName: "vercel_world_hook_token_schema_version",
+	migrations: [{ version: 1, up: bootstrapHookTokenDb }],
+});
+export const workflowDb = db({ onMigrate: migrateWorkflowDb });
+export const coordinatorDb = db({ onMigrate: migrateCoordinatorDb });
+export const hookTokenDb = db({ onMigrate: migrateHookTokenDb });