cvx-kit 0.0.1

package/src/components/approvals/validators.ts

@@ -0,0 +1,272 @@
+import { zid } from 'convex-helpers/server/zod4'
+import { z } from 'zod'
+
+import {
+	APPROVAL_CALLBACK_KINDS,
+	APPROVAL_DECISIONS,
+	APPROVAL_DESCRIPTOR_SCHEMA_VERSION,
+	APPROVAL_QUORUM_KINDS,
+	APPROVAL_RUN_STATES,
+	APPROVAL_STEP_KINDS,
+	MAX_APPROVAL_CAPABILITIES,
+	MAX_APPROVAL_DECISIONS_PER_STEP,
+	MAX_APPROVAL_METADATA_ENTRIES,
+	MAX_APPROVAL_METADATA_KEY_LENGTH,
+	MAX_APPROVAL_METADATA_VALUE_LENGTH,
+	MAX_APPROVAL_NAME_LENGTH,
+	MAX_APPROVAL_REASON_LENGTH,
+	MAX_APPROVAL_REFERENCE_LENGTH,
+	MAX_APPROVAL_WORKFLOW_STEPS,
+} from './constants'
+
+export const approvalRunState = z.enum(APPROVAL_RUN_STATES)
+export const approvalDecision = z.enum(APPROVAL_DECISIONS)
+export const approvalStepKind = z.enum(APPROVAL_STEP_KINDS)
+export const approvalCallbackKind = z.enum(APPROVAL_CALLBACK_KINDS)
+export const approvalQuorumKind = z.enum(APPROVAL_QUORUM_KINDS)
+
+export const approvalReference = z
+	.string()
+	.trim()
+	.min(1)
+	.max(MAX_APPROVAL_REFERENCE_LENGTH)
+
+export const approvalName = z
+	.string()
+	.trim()
+	.min(1)
+	.max(MAX_APPROVAL_NAME_LENGTH)
+	.regex(/^[A-Za-z][A-Za-z0-9._-]*$/)
+
+export const approvalReason = z
+	.string()
+	.trim()
+	.min(1)
+	.max(MAX_APPROVAL_REASON_LENGTH)
+
+export const approvalMetadata = z
+	.record(
+		z
+			.string()
+			.min(1)
+			.max(MAX_APPROVAL_METADATA_KEY_LENGTH)
+			.regex(/^(?![$_])[\x20-\x7E]+$/),
+		z.string().max(MAX_APPROVAL_METADATA_VALUE_LENGTH),
+	)
+	.refine(
+		(value) => Object.keys(value).length <= MAX_APPROVAL_METADATA_ENTRIES,
+		`Metadata may contain at most ${MAX_APPROVAL_METADATA_ENTRIES} entries`,
+	)
+
+export const approvalActor = z
+	.object({
+		actorRef: approvalReference,
+		capabilities: z.array(approvalName).max(MAX_APPROVAL_CAPABILITIES),
+		metadata: approvalMetadata.optional(),
+	})
+	.strict()
+
+export const approvalMutationCallback = z
+	.object({
+		kind: z.literal('mutation'),
+		handle: approvalReference,
+		retry: z.boolean(),
+	})
+	.strict()
+
+export const approvalActionCallback = z
+	.object({
+		kind: z.literal('action'),
+		handle: approvalReference,
+		retry: z.boolean(),
+	})
+	.strict()
+
+export const approvalCallback = z.discriminatedUnion('kind', [
+	approvalMutationCallback,
+	approvalActionCallback,
+])
+
+export const approvalQuorum = z
+	.object({
+		kind: approvalQuorumKind,
+		approvals: z.number().int().positive().max(MAX_APPROVAL_DECISIONS_PER_STEP),
+	})
+	.strict()
+
+export const approvalCallbackStep = z.discriminatedUnion('kind', [
+	z
+		.object({
+			kind: z.literal('mutation'),
+			key: approvalName,
+			callback: approvalMutationCallback,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('action'),
+			key: approvalName,
+			callback: approvalActionCallback,
+		})
+		.strict(),
+])
+
+export const approvalNotifyStep = z
+	.object({
+		kind: z.literal('notify'),
+		key: approvalName,
+		callback: approvalActionCallback,
+	})
+	.strict()
+
+export const approvalDecisionStep = z
+	.object({
+		kind: z.literal('decision'),
+		key: approvalName,
+		decisions: z
+			.array(approvalDecision)
+			.min(1)
+			.max(MAX_APPROVAL_DECISIONS_PER_STEP),
+		quorum: approvalQuorum,
+		makerChecker: z.boolean(),
+		expiresAfterMs: z.number().int().positive().optional(),
+	})
+	.strict()
+
+export const approvalBranchStep = z
+	.object({
+		kind: z.literal('branch'),
+		key: approvalName,
+		approvedStepKey: approvalName,
+		rejectedStepKey: approvalName,
+	})
+	.strict()
+
+export const approvalWorkflowStep = z.discriminatedUnion('kind', [
+	approvalCallbackStep,
+	approvalNotifyStep,
+	approvalDecisionStep,
+	approvalBranchStep,
+])
+
+export const approvalWorkflowDescriptor = z
+	.object({
+		schemaVersion: z.literal(APPROVAL_DESCRIPTOR_SCHEMA_VERSION),
+		compatibilityKey: approvalName,
+		name: approvalName,
+		steps: z
+			.array(approvalWorkflowStep)
+			.min(1)
+			.max(MAX_APPROVAL_WORKFLOW_STEPS),
+	})
+	.strict()
+	.superRefine((descriptor, context) => {
+		const keys = new Set<string>()
+		const stepsByKey = new Map(
+			descriptor.steps.map((step) => [step.key, step] as const),
+		)
+		const branchTargetOwners = new Map<string, number>()
+		for (const [index, step] of descriptor.steps.entries()) {
+			if (keys.has(step.key))
+				context.addIssue({
+					code: 'custom',
+					message: `Duplicate workflow step key: ${step.key}`,
+					path: ['steps', index, 'key'],
+				})
+			keys.add(step.key)
+			if (
+				step.kind === 'decision' &&
+				new Set(step.decisions).size !== step.decisions.length
+			)
+				context.addIssue({
+					code: 'custom',
+					message: `Duplicate decision value in step: ${step.key}`,
+					path: ['steps', index, 'decisions'],
+				})
+		}
+		for (const [index, step] of descriptor.steps.entries()) {
+			if (step.kind !== 'branch') continue
+			if (descriptor.steps[index - 1]?.kind !== 'decision')
+				context.addIssue({
+					code: 'custom',
+					message: `Branch must immediately follow a decision: ${step.key}`,
+					path: ['steps', index],
+				})
+			for (const target of [step.approvedStepKey, step.rejectedStepKey]) {
+				const targetStep = stepsByKey.get(target)
+				const targetIndex = descriptor.steps.findIndex(
+					(candidate) => candidate.key === target,
+				)
+				if (!targetStep)
+					context.addIssue({
+						code: 'custom',
+						message: `Unknown branch target: ${target}`,
+						path: ['steps', index],
+					})
+				else if (
+					targetStep.kind !== 'mutation' &&
+					targetStep.kind !== 'action' &&
+					targetStep.kind !== 'notify'
+				)
+					context.addIssue({
+						code: 'custom',
+						message: `Branch target must be a callback step: ${target}`,
+						path: ['steps', index],
+					})
+				else if (targetIndex <= index)
+					context.addIssue({
+						code: 'custom',
+						message: `Branch target must be declared after its branch: ${target}`,
+						path: ['steps', index],
+					})
+				branchTargetOwners.set(
+					target,
+					(branchTargetOwners.get(target) ?? 0) + 1,
+				)
+			}
+		}
+		for (const [target, owners] of branchTargetOwners) {
+			if (owners !== 1)
+				context.addIssue({
+					code: 'custom',
+					message: `Branch callback must belong to exactly one branch: ${target}`,
+					path: ['steps'],
+				})
+		}
+	})
+
+export const approvalRunDocument = z
+	.object({
+		scopeRef: approvalReference,
+		resourceType: approvalName,
+		resourceRef: approvalReference,
+		requester: approvalActor,
+		metadata: approvalMetadata.optional(),
+		workflow: approvalWorkflowDescriptor,
+		state: approvalRunState,
+		currentStepKey: approvalName.optional(),
+		executionFailedStepKey: approvalName.optional(),
+		expiresAt: z.number().optional(),
+		workflowId: approvalReference.optional(),
+		createdAt: z.number(),
+		updatedAt: z.number(),
+		terminalAt: z.number().optional(),
+	})
+	.strict()
+
+export const approvalDecisionDocument = z
+	.object({
+		runId: zid('approvalRuns'),
+		stepKey: approvalName,
+		actor: approvalActor,
+		decision: approvalDecision,
+		reason: approvalReason.optional(),
+		decidedAt: z.number(),
+	})
+	.strict()
+
+export type ApprovalWorkflowDescriptor = z.infer<
+	typeof approvalWorkflowDescriptor
+>
+export type ApprovalActor = z.infer<typeof approvalActor>
+export type ApprovalMetadata = z.infer<typeof approvalMetadata>

package/src/components/approvals/workflow.ts

@@ -0,0 +1,204 @@
+import { WorkflowManager, type WorkflowCtx } from '@convex-dev/workflow'
+import { v } from 'convex/values'
+
+import { components, internal } from './_generated/api'
+import type { Doc } from './_generated/dataModel'
+import { APPROVAL_DECISIONS, APPROVAL_RUN_STATES } from './constants'
+import {
+	approvalDecisionEventName,
+	callbackReference,
+	resolveWorkflowStepIndex,
+	type ApprovalCallbackInput,
+} from './workflow_steps'
+
+export const approvalWorkflow = new WorkflowManager(components.workflow)
+
+export const run = approvalWorkflow.define({
+	args: { runId: v.id('approvalRuns') },
+	returns: v.null(),
+	handler: async (step, input) => {
+		let failedStepKey: string | undefined
+		try {
+			const run: Doc<'approvalRuns'> | null = await step.runQuery(
+				internal.requests.getForWorkflow,
+				{ runId: input.runId },
+				{ name: 'loadLinkedApproval' },
+			)
+			if (!run) throw new Error('Approval request not found')
+			if (run.workflowId !== step.workflowId)
+				throw new Error('Approval workflow linkage is incomplete')
+
+			const callbackInput = buildCallbackInput(run)
+			const stepKeys = run.workflow.steps.map(
+				(workflowStep) => workflowStep.key,
+			)
+			const branchTargets = new Set(
+				run.workflow.steps.flatMap((workflowStep) =>
+					workflowStep.kind === 'branch'
+						? [workflowStep.approvedStepKey, workflowStep.rejectedStepKey]
+						: [],
+				),
+			)
+			let lastDecision: 'approved' | 'rejected' | 'expired' | null = null
+			let lastDecisionStepKey: string | null = null
+			let terminalEvidence:
+				| {
+						actorRef: string
+						decision: 'approved' | 'rejected'
+						reason?: string
+						decidedAt: number
+				  }
+				| undefined
+			let index = 0
+			while (index < run.workflow.steps.length) {
+				const workflowStep = run.workflow.steps[index]
+				if (
+					workflowStep.kind === 'mutation' ||
+					workflowStep.kind === 'action' ||
+					workflowStep.kind === 'notify'
+				) {
+					if (branchTargets.has(workflowStep.key)) {
+						index += 1
+						continue
+					}
+					failedStepKey = workflowStep.key
+					await executeCallback(step, workflowStep, callbackInput)
+					failedStepKey = undefined
+					index += 1
+					continue
+				}
+				if (workflowStep.kind === 'decision') {
+					await step.runMutation(
+						internal.decisions.enter,
+						{
+							runId: run._id,
+							stepKey: workflowStep.key,
+							workflowId: step.workflowId,
+							...(workflowStep.expiresAfterMs === undefined
+								? {}
+								: { expiresAfterMs: workflowStep.expiresAfterMs }),
+						},
+						{ name: `enter:${workflowStep.key}` },
+					)
+					const event = await step.awaitEvent({
+						name: approvalDecisionEventName(run._id, workflowStep.key),
+						validator: v.object({
+							outcome: v.union(
+								v.literal(APPROVAL_DECISIONS[0]),
+								v.literal(APPROVAL_DECISIONS[1]),
+								v.literal(APPROVAL_RUN_STATES[3]),
+							),
+							terminalEvidence: v.optional(
+								v.object({
+									actorRef: v.string(),
+									decision: v.union(
+										v.literal(APPROVAL_DECISIONS[0]),
+										v.literal(APPROVAL_DECISIONS[1]),
+									),
+									reason: v.optional(v.string()),
+									decidedAt: v.number(),
+								}),
+							),
+						}),
+					})
+					lastDecision = event.outcome
+					terminalEvidence = event.terminalEvidence
+					lastDecisionStepKey = workflowStep.key
+					if (
+						lastDecision !== 'approved' &&
+						run.workflow.steps[index + 1]?.kind !== 'branch'
+					)
+						break
+					index += 1
+					continue
+				}
+				if (!lastDecision)
+					throw new Error('Branch requires a preceding decision step')
+				const targetKey =
+					lastDecision === 'approved'
+						? workflowStep.approvedStepKey
+						: workflowStep.rejectedStepKey
+				const targetIndex = resolveWorkflowStepIndex(stepKeys, targetKey)
+				const target = run.workflow.steps[targetIndex]
+				if (
+					target.kind !== 'mutation' &&
+					target.kind !== 'action' &&
+					target.kind !== 'notify'
+				)
+					throw new Error('Approval branch target must be a callback step')
+				const evidence = await step.runQuery(
+					internal.decisions.listForWorkflow,
+					{ runId: run._id, stepKey: lastDecisionStepKey ?? workflowStep.key },
+					{ name: `evidence:${workflowStep.key}` },
+				)
+				failedStepKey = target.key
+				await executeCallback(step, target, {
+					...callbackInput,
+					decision: {
+						stepKey: lastDecisionStepKey ?? workflowStep.key,
+						outcome: lastDecision,
+						evidence,
+						...(terminalEvidence === undefined ? {} : { terminalEvidence }),
+					},
+				})
+				failedStepKey = undefined
+				if (lastDecision === 'rejected' || lastDecision === 'expired') break
+				index += 1
+				continue
+			}
+
+			await step.runMutation(
+				internal.requests.recordExecutionTerminal,
+				{ runId: run._id, outcome: 'completed' },
+				{ name: 'recordExecutionCompleted' },
+			)
+			return null
+		} catch (error) {
+			await step.runMutation(
+				internal.requests.recordExecutionTerminal,
+				{
+					runId: input.runId,
+					outcome: 'failed',
+					...(failedStepKey === undefined ? {} : { failedStepKey }),
+				},
+				{ name: 'recordExecutionFailed' },
+			)
+			throw error
+		}
+	},
+})
+
+type CallbackStep = Extract<
+	Doc<'approvalRuns'>['workflow']['steps'][number],
+	{ kind: 'mutation' | 'action' | 'notify' }
+>
+
+function buildCallbackInput(run: Doc<'approvalRuns'>): ApprovalCallbackInput {
+	return {
+		runId: run._id,
+		scopeRef: run.scopeRef,
+		resourceType: run.resourceType,
+		resourceRef: run.resourceRef,
+		...(run.metadata === undefined ? {} : { metadata: run.metadata }),
+	}
+}
+
+async function executeCallback(
+	step: WorkflowCtx,
+	workflowStep: CallbackStep,
+	input: ApprovalCallbackInput,
+): Promise<void> {
+	if (workflowStep.callback.kind === 'mutation') {
+		await step.runMutation(
+			callbackReference<'mutation'>(workflowStep.callback.handle),
+			input,
+			{ name: workflowStep.key },
+		)
+		return
+	}
+	await step.runAction(
+		callbackReference<'action'>(workflowStep.callback.handle),
+		input,
+		{ name: workflowStep.key, retry: workflowStep.callback.retry },
+	)
+}

package/src/components/approvals/workflow_steps.ts

@@ -0,0 +1,189 @@
+import {
+	createFunctionHandle,
+	type FunctionReference,
+	type FunctionType,
+} from 'convex/server'
+
+import type { ApprovalDecision } from './constants'
+import {
+	approvalWorkflowDescriptor,
+	type ApprovalWorkflowDescriptor,
+} from './validators'
+
+export type ApprovalMutationStep = Readonly<{
+	kind: 'mutation'
+	key: string
+	handler: FunctionReference<'mutation', 'internal'>
+	retry: boolean
+}>
+
+export type ApprovalActionStep = Readonly<{
+	kind: 'action'
+	key: string
+	handler: FunctionReference<'action', 'internal'>
+	retry: boolean
+}>
+
+export type ApprovalNotifyStep = Readonly<{
+	kind: 'notify'
+	key: string
+	handler: FunctionReference<'action', 'internal'>
+	retry: boolean
+}>
+
+export type ApprovalDecisionStep = Readonly<{
+	kind: 'decision'
+	key: string
+	decisions: readonly ApprovalDecision[]
+	quorum: Readonly<{ kind: 'count'; approvals: number }>
+	makerChecker: boolean
+	expiresAfterMs?: number
+}>
+
+export type ApprovalBranchStep = Readonly<{
+	kind: 'branch'
+	key: string
+	approvedStepKey: string
+	rejectedStepKey: string
+}>
+
+export type ApprovalWorkflowStep =
+	| ApprovalMutationStep
+	| ApprovalActionStep
+	| ApprovalNotifyStep
+	| ApprovalDecisionStep
+	| ApprovalBranchStep
+
+export type ApprovalDefinition = Readonly<{
+	name: string
+	compatibilityKey: string
+	steps: readonly ApprovalWorkflowStep[]
+}>
+
+export type CreateApprovalHandle = (
+	reference: FunctionReference<'mutation' | 'action', 'internal'>,
+) => Promise<string>
+
+export type ApprovalDecisionEvidence = Readonly<{
+	actorRef: string
+	decision: ApprovalDecision
+}>
+
+export type ApprovalCallbackInput = Readonly<{
+	runId: string
+	scopeRef: string
+	resourceType: string
+	resourceRef: string
+	metadata?: Readonly<Record<string, string>>
+	decision?: Readonly<{
+		stepKey: string
+		outcome: ApprovalDecision | 'expired'
+		evidence: readonly Readonly<{
+			actorRef: string
+			decision: ApprovalDecision
+			reason?: string
+			decidedAt: number
+		}>[]
+		terminalEvidence?: Readonly<{
+			actorRef: string
+			decision: ApprovalDecision
+			reason?: string
+			decidedAt: number
+		}>
+	}>
+}>
+
+export function approvalDecisionEventName(
+	runId: string,
+	stepKey: string,
+): string {
+	return `approval:${runId}:${stepKey}`
+}
+
+export function evaluateDecisionOutcome(
+	decisions: readonly ApprovalDecisionEvidence[],
+	approvalsRequired: number,
+): ApprovalDecision | null {
+	if (decisions.some((decision) => decision.decision === 'rejected'))
+		return 'rejected'
+	return decisions.filter((decision) => decision.decision === 'approved')
+		.length >= approvalsRequired
+		? 'approved'
+		: null
+}
+
+export function resolveWorkflowStepIndex(
+	stepKeys: readonly string[],
+	targetKey: string,
+): number {
+	const index = stepKeys.indexOf(targetKey)
+	if (index === -1)
+		throw new Error(`Unknown approval workflow step: ${targetKey}`)
+	return index
+}
+
+export function callbackReference<Type extends FunctionType>(
+	handle: string,
+): FunctionReference<Type, 'internal', ApprovalCallbackInput, unknown> {
+	return handle as unknown as FunctionReference<
+		Type,
+		'internal',
+		ApprovalCallbackInput,
+		unknown
+	>
+}
+
+export async function compileApprovalDescriptor(
+	definition: ApprovalDefinition,
+	createHandle: CreateApprovalHandle = createFunctionHandle,
+): Promise<Readonly<ApprovalWorkflowDescriptor>> {
+	const steps = await Promise.all(
+		definition.steps.map(async (step) => {
+			if (step.kind === 'mutation' || step.kind === 'action') {
+				return {
+					kind: step.kind,
+					key: step.key,
+					callback: {
+						kind: step.kind,
+						handle: await createHandle(step.handler),
+						retry: step.retry,
+					},
+				}
+			}
+			if (step.kind === 'notify') {
+				return {
+					kind: step.kind,
+					key: step.key,
+					callback: {
+						kind: 'action' as const,
+						handle: await createHandle(step.handler),
+						retry: step.retry,
+					},
+				}
+			}
+			if (step.kind === 'decision') {
+				return {
+					...step,
+					decisions: [...step.decisions],
+					quorum: { ...step.quorum },
+				}
+			}
+			return { ...step }
+		}),
+	)
+	const descriptor = approvalWorkflowDescriptor.parse({
+		schemaVersion: 1,
+		compatibilityKey: definition.compatibilityKey,
+		name: definition.name,
+		steps,
+	})
+	return deepFreeze(descriptor)
+}
+
+function deepFreeze<Value>(value: Value): Readonly<Value> {
+	if (value && typeof value === 'object') {
+		Object.freeze(value)
+		for (const nested of Object.values(value)) deepFreeze(nested)
+	}
+	return value
+}