@flowdular/sdk 0.2.3 → 0.3.0

package/modules/workflows/src/client/state.ts

@@ -1,3 +1,4 @@
+import type { TableSort } from '@flowdular/sdk/ui';
 import { cell, createStore } from 'segment-state';
 import type {
 	WorkflowDefinition,
@@ -6,16 +7,110 @@ import type {
 	WorkflowGraphV1,
 	WorkflowRunDetail,
 	WorkflowRunSummary,
+	WorkflowSortDirection,
 } from '../domain/types.ts';
 import type {
 	WorkflowActionCatalogItem,
 	WorkflowAgentCatalogItem,
 } from './api.ts';
 
+/**
+ * The pages a reader has walked. `cursors[i]` is the cursor that opened page
+ * `i`; page 0 opens with none. `nextCursor` is what the page on screen handed
+ * back, null on the last page.
+ */
+export interface PageCursors {
+	readonly pageIndex: number;
+	readonly cursors: readonly string[];
+	readonly nextCursor: string | null;
+}
+
+export const FIRST_PAGE: PageCursors = {
+	pageIndex: 0,
+	cursors: [],
+	nextCursor: null,
+};
+
+export interface PageRequest {
+	readonly pageIndex: number;
+	readonly cursor: string | null;
+}
+
+export const FIRST_PAGE_REQUEST: PageRequest = { pageIndex: 0, cursor: null };
+
+/**
+ * How to reach `pageIndex` from the pages walked so far: an earlier page
+ * reopens with the cursor stored for it, the next page with the cursor the
+ * current one handed back. Null when no cursor leads there.
+ */
+export function pageRequest(
+	pages: PageCursors,
+	pageIndex: number,
+): PageRequest | null {
+	if (pageIndex <= 0) return { pageIndex: 0, cursor: null };
+	if (pageIndex <= pages.pageIndex) {
+		const cursor = pages.cursors[pageIndex];
+		return cursor ? { pageIndex, cursor } : null;
+	}
+	if (pageIndex === pages.pageIndex + 1 && pages.nextCursor) {
+		return { pageIndex, cursor: pages.nextCursor };
+	}
+	return null;
+}
+
+/** The pages walked once the requested one arrived with `nextCursor` behind it. */
+export function pageOpened(
+	pages: PageCursors,
+	request: PageRequest,
+	nextCursor: string | null,
+): PageCursors {
+	const cursors = pages.cursors.slice(0, request.pageIndex);
+	while (cursors.length < request.pageIndex) cursors.push('');
+	cursors.push(request.cursor ?? '');
+	return { pageIndex: request.pageIndex, cursors, nextCursor };
+}
+
+export interface ListOrder<Sort extends string> {
+	readonly sort: Sort;
+	readonly direction: WorkflowSortDirection;
+}
+
+/**
+ * The server order a table's sorting state asks for. `columns` maps a column
+ * key to the sort key it carries; a table sorted by nothing, or by a column
+ * the server does not sort on, asks for the default order.
+ */
+export function listOrder<Sort extends string>(
+	sorts: readonly TableSort[],
+	columns: Readonly<Record<string, Sort>>,
+	fallback: ListOrder<Sort>,
+): ListOrder<Sort> {
+	const first = sorts[0];
+	const sort = first ? columns[first.key] : undefined;
+	return first && sort
+		? { sort, direction: first.desc ? 'desc' : 'asc' }
+		: fallback;
+}
+
+/**
+ * Whether the typed term still has to reach the server. The rows on screen
+ * answer it only once a page was loaded with exactly this term.
+ */
+export function searchPending(query: string, applied: string): boolean {
+	return query.trim() !== applied;
+}
+
 export function createWorkflowsClientState() {
 	const store = createStore({
 		definitions: cell<readonly WorkflowDefinition[]>([]),
+		definitionSorts: cell<readonly TableSort[]>([]),
+		definitionPages: cell<PageCursors>(FIRST_PAGE),
+		/* The term the rows on screen were loaded with. */
+		appliedQuery: '',
 		runs: cell<readonly WorkflowRunSummary[]>([]),
+		runSorts: cell<readonly TableSort[]>([]),
+		runPages: cell<PageCursors>(FIRST_PAGE),
+		appliedRunQuery: '',
 		detail: cell<WorkflowDefinitionDetail | null>(null),
 		graph: cell<WorkflowGraphV1 | null>(null),
 		selectedNodeId: '',

package/modules/workflows/src/domain/events.ts

@@ -83,6 +83,13 @@ const EVENT_REQUIREMENTS = {
 } as const satisfies Record<WorkflowRunEventTypeV1, readonly string[]>;
 
 const EVENT_TYPES = new Set<string>(Object.keys(EVENT_REQUIREMENTS));
+/** Statuses a run may settle from; every one of them is a claimed live run. */
+const SETTLEABLE: readonly string[] = [
+	'running',
+	'waiting-agent',
+	'waiting-approval',
+	'waiting-retry',
+];
 const TERMINAL = new Set<WorkflowRunStatus>([
 	'succeeded',
 	'failed',
@@ -237,9 +244,13 @@ export function projectWorkflowRunEvents(
 				break;
 			case 'run.claimed':
 				if (
-					!['queued', 'running', 'waiting-agent', 'waiting-retry'].includes(
-						status,
-					)
+					![
+						'queued',
+						'running',
+						'waiting-agent',
+						'waiting-approval',
+						'waiting-retry',
+					].includes(status)
 				)
 					transitionError(event, status);
 				status = 'running';
@@ -284,10 +295,15 @@ export function projectWorkflowRunEvents(
 					outcomePort: null,
 				});
 				nodeStatuses.set(nodeId, 'waiting-child');
-				status =
-					requiredString(event.payload, 'childKind') === 'agent'
-						? 'waiting-agent'
-						: 'running';
+				{
+					const childKind = requiredString(event.payload, 'childKind');
+					status =
+						childKind === 'agent'
+							? 'waiting-agent'
+							: childKind === 'approval'
+								? 'waiting-approval'
+								: 'running';
+				}
 				break;
 			}
 			case 'node.attempt.settled': {
@@ -347,13 +363,11 @@ export function projectWorkflowRunEvents(
 				status = 'cancel-requested';
 				break;
 			case 'run.succeeded':
-				if (!['running', 'waiting-agent', 'waiting-retry'].includes(status))
-					transitionError(event, status);
+				if (!SETTLEABLE.includes(status)) transitionError(event, status);
 				status = 'succeeded';
 				break;
 			case 'run.failed':
-				if (!['running', 'waiting-agent', 'waiting-retry'].includes(status))
-					transitionError(event, status);
+				if (!SETTLEABLE.includes(status)) transitionError(event, status);
 				status = 'failed';
 				break;
 			case 'run.refused':

package/modules/workflows/src/domain/graph.ts

@@ -5,13 +5,14 @@ import type {
 	WorkflowDryRunResponseV1,
 	WorkflowGateExpressionV1,
 	WorkflowGraphV1,
+	WorkflowHumanApprovalNodeV1,
 	WorkflowNodeV1,
 	WorkflowPayloadEvidenceV1,
 	WorkflowReferenceSummaryV1,
 	WorkflowTargetMappingV1,
 	WorkflowValidationIssueV1,
 } from './types.ts';
-import { WORKFLOW_LIMITS } from './types.ts';
+import { APPROVAL_LIMITS, WORKFLOW_LIMITS } from './types.ts';
 
 const IDENTIFIER = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
 const PORT = /^[a-z][a-z0-9-]*$/;
@@ -43,6 +44,16 @@ export interface WorkflowReferenceCatalog {
 		readonly risk?: 'read' | 'workspace-write' | 'external' | 'destructive';
 		readonly idempotency?: 'required' | 'none';
 	};
+	/**
+	 * approvals.core and the roles the workspace defines, resolved once before
+	 * the compiler walks the graph. A catalog without this member reads as an
+	 * absent approvals module, which is the answer a graph compiled with no
+	 * catalog at all already gets.
+	 */
+	approval?(): {
+		readonly available: boolean;
+		readonly roleKeys: readonly string[];
+	};
 }
 
 export const EMPTY_WORKFLOW_GRAPH: WorkflowGraphV1 = Object.freeze({
@@ -137,6 +148,7 @@ const EXPECTED_PORTS: Record<
 	gate: { inputs: ['input'], outputs: ['pass', 'fail'] },
 	validator: { inputs: ['input'], outputs: ['pass', 'fail'] },
 	action: { inputs: ['input'], outputs: ['success', 'failure'] },
+	'human-approval': { inputs: ['input'], outputs: ['approved'] },
 	merge: { inputs: ['items'], outputs: ['data'] },
 	output: { inputs: ['input'], outputs: [] },
 };
@@ -449,6 +461,112 @@ function stableTopologicalOrder(
 	return { order, cyclic: order.length !== nodes.length };
 }
 
+/**
+ * A human-approval node carries the whole requirement in the published graph,
+ * so publishing is where a role the workspace does not define has to be caught:
+ * a run that reached the node with an unresolvable requirement would pause on
+ * nobody. An absent approvals module is the same class of problem and gets its
+ * own stable code.
+ */
+function approvalIssues(
+	node: WorkflowHumanApprovalNodeV1,
+	catalog: WorkflowReferenceCatalog | undefined,
+): readonly WorkflowValidationIssueV1[] {
+	const issues: WorkflowValidationIssueV1[] = [];
+	const at = { kind: 'node', nodeId: node.id } as const;
+	const approval = catalog?.approval?.();
+	if (!approval?.available) {
+		issues.push(
+			issue(
+				'WORKFLOW_APPROVAL_CAPABILITY_UNAVAILABLE',
+				`Node "${node.id}" needs approvals.core, which is not composed.`,
+				at,
+			),
+		);
+	}
+	/* approvals.core receives `prompt ?? label` as the request title and a
+	   summary naming the label, so a value it would refuse has to fail the
+	   publish rather than the run that reaches the node. The label carries the
+	   title limit because it is the title whenever no prompt is set, and being
+	   bounded there keeps the composed summary inside APPROVAL_LIMITS.summary. */
+	for (const [name, value] of [
+		['prompt', node.prompt],
+		['label', node.label],
+	] as const) {
+		if (typeof value === 'string' && value.length > APPROVAL_LIMITS.title) {
+			issues.push(
+				issue(
+					'WORKFLOW_LIMIT_EXCEEDED',
+					`Node "${node.id}" sets a ${name} of ${value.length} characters; approvals.core accepts ${APPROVAL_LIMITS.title}.`,
+					{ ...at, path: `/${name}` },
+				),
+			);
+		}
+	}
+	const requirement: unknown = node.requirement;
+	if (!isRecord(requirement)) {
+		issues.push(
+			issue(
+				'WORKFLOW_APPROVAL_REQUIREMENT_INVALID',
+				`Node "${node.id}" declares no approval requirement.`,
+				{ ...at, path: '/requirement' },
+			),
+		);
+		return issues;
+	}
+	const roleKey = requirement.roleKey;
+	const scope = requirement.scope;
+	const hasRole = typeof roleKey === 'string' && roleKey !== '';
+	const hasScope = typeof scope === 'string' && scope !== '';
+	if (!hasRole && !hasScope) {
+		issues.push(
+			issue(
+				'WORKFLOW_APPROVAL_REQUIREMENT_INVALID',
+				`Node "${node.id}" must name a role key or a scope.`,
+				{ ...at, path: '/requirement' },
+			),
+		);
+	}
+	const bound = (value: unknown, name: string, max: number): void => {
+		if (value === undefined) return;
+		if (
+			!Number.isSafeInteger(value) ||
+			(value as number) < 1 ||
+			(value as number) > max
+		) {
+			issues.push(
+				issue(
+					'WORKFLOW_APPROVAL_REQUIREMENT_INVALID',
+					`Node "${node.id}" must set ${name} between 1 and ${max}.`,
+					{ ...at, path: `/requirement/${name}` },
+				),
+			);
+		}
+	};
+	bound(
+		requirement.decisions,
+		'decisions',
+		WORKFLOW_LIMITS.maxApprovalDecisions,
+	);
+	bound(
+		requirement.expiresInDays,
+		'expiresInDays',
+		WORKFLOW_LIMITS.maxApprovalExpiryDays,
+	);
+	/* A scope requirement is shape-checked only: scopes come from every composed
+	   module, and this compiler resolves the workspace's roles alone. */
+	if (hasRole && approval && !approval.roleKeys.includes(roleKey as string)) {
+		issues.push(
+			issue(
+				'WORKFLOW_APPROVAL_ROLE_UNKNOWN',
+				`Node "${node.id}" names role "${roleKey as string}", which this workspace does not define.`,
+				{ ...at, path: '/requirement/roleKey' },
+			),
+		);
+	}
+	return issues;
+}
+
 export function compileWorkflowGraph(
 	graph: WorkflowGraphV1,
 	catalog?: WorkflowReferenceCatalog,
@@ -623,6 +741,22 @@ export function compileWorkflowGraph(
 				available,
 			});
 		}
+		if (node.type === 'human-approval') {
+			issues.push(...approvalIssues(node, catalog));
+			/* validate() accepts an unparsed graph, so the node may carry no
+			   requirement at all. `approvalIssues` has already reported that;
+			   the reference names nothing rather than throwing over it. */
+			const requirement: unknown = node.requirement;
+			const named = isRecord(requirement)
+				? (requirement.roleKey ?? requirement.scope)
+				: undefined;
+			references.push({
+				kind: 'approval',
+				id: typeof named === 'string' ? named : '',
+				version: '1',
+				available: catalog?.approval?.().available === true,
+			});
+		}
 		if (node.type === 'action') {
 			const action = catalog?.action(
 				node.action.actionId,

package/modules/workflows/src/domain/types.ts

@@ -22,8 +22,34 @@ export const WORKFLOW_LIMITS = Object.freeze({
 	maxRunEvents: 10_000,
 	maxInteractivePage: 100,
 	maxReplayEvents: 100,
+	/* What a node may ask approvals.core for, bounded where approvals.core
+	   bounds it: a requirement it would refuse has to be a publish issue rather
+	   than a run that reaches the node and refuses there. */
+	maxApprovalDecisions: 16,
+	maxApprovalExpiryDays: 90,
 });
 
+/**
+ * Longest values approvals.core accepts on a request, mirrored so a node whose
+ * prompt or label it would refuse is caught at validation instead of at the
+ * node. It must not drift from `APPROVAL_LIMITS` in that module's
+ * `domain/capability.ts`.
+ */
+export const APPROVAL_LIMITS = Object.freeze({
+	title: 200,
+	summary: 2_000,
+});
+
+/**
+ * How long a run paused on a human approval sleeps before it looks at the
+ * request again. approvals.core calls back in process when a decision lands, so
+ * this is what resumes a run whose callback never arrives: the process that
+ * opened the request restarted, or approvals.core dropped the callback to stay
+ * inside its own bound on the pending ones. Shorter costs one claim per pending
+ * approval per interval.
+ */
+export const WORKFLOW_APPROVAL_RECHECK_MS = 5 * 60 * 1_000;
+
 export interface WorkflowPortV1 {
 	readonly name: string;
 	readonly schemaId: string;
@@ -128,6 +154,25 @@ export interface WorkflowActionNodeV1 extends WorkflowNodeBaseV1 {
 	};
 }
 
+/**
+ * The requirement a human-approval node carries. It is the kernel
+ * `ApprovalRequirement` pinned into the published graph: who has to agree, how
+ * many of them, and how long the run waits before the request expires.
+ */
+export interface WorkflowApprovalRequirementV1 {
+	readonly roleKey?: string;
+	readonly scope?: string;
+	readonly decisions?: number;
+	readonly expiresInDays?: number;
+}
+
+export interface WorkflowHumanApprovalNodeV1 extends WorkflowNodeBaseV1 {
+	readonly type: 'human-approval';
+	readonly requirement: WorkflowApprovalRequirementV1;
+	/** Shown to the deciders; the node label is the fallback. */
+	readonly prompt?: string;
+}
+
 export interface WorkflowMergeNodeV1 extends WorkflowNodeBaseV1 {
 	readonly type: 'merge';
 	readonly mode: 'all';
@@ -144,6 +189,7 @@ export type WorkflowNodeV1 =
 	| WorkflowGateNodeV1
 	| WorkflowValidatorNodeV1
 	| WorkflowActionNodeV1
+	| WorkflowHumanApprovalNodeV1
 	| WorkflowMergeNodeV1
 	| WorkflowOutputNodeV1;
 
@@ -226,7 +272,7 @@ export interface WorkflowValidationIssueV1 {
 }
 
 export interface WorkflowReferenceSummaryV1 {
-	readonly kind: 'agent' | 'action' | 'schema';
+	readonly kind: 'agent' | 'action' | 'schema' | 'approval';
 	readonly id: string;
 	readonly version: string;
 	readonly available: boolean;
@@ -258,6 +304,10 @@ export type WorkflowRunStatus =
 	| 'queued'
 	| 'running'
 	| 'waiting-agent'
+	/* A run asleep on a person. It leaves the worker's claim queue until the
+	   approval resolves or its recheck falls due, so a request open for days
+	   costs nothing and never starves a newly queued run. */
+	| 'waiting-approval'
 	| 'waiting-retry'
 	| 'cancel-requested'
 	| 'succeeded'
@@ -355,7 +405,7 @@ export interface WorkflowNodeAttempt {
 	readonly sideEffectIdempotencyKey: string;
 	readonly input: WorkflowPayloadEvidenceV1;
 	readonly output: WorkflowPayloadEvidenceV1;
-	readonly childKind: 'agent' | 'action' | null;
+	readonly childKind: 'agent' | 'action' | 'approval' | null;
 	readonly childId: string | null;
 	readonly childObservationDeadlineAt: number | null;
 	readonly failureCode: string | null;
@@ -438,21 +488,58 @@ export interface WorkflowRunDetail {
 	readonly output: WorkflowPayloadEvidenceV1;
 }
 
+export type WorkflowSortDirection = 'asc' | 'desc';
+
+/** The page of a keyset list: `sort` and `direction` name an indexed order. */
+export interface WorkflowListQuery<Sort extends string> {
+	readonly sort?: Sort;
+	readonly direction?: WorkflowSortDirection;
+	readonly limit?: number;
+	readonly cursor?: string | null;
+}
+
+export interface WorkflowDefinitionFilters {
+	readonly status?: WorkflowDefinition['status'];
+	/** Matched inside the name or the key, case-insensitively. */
+	readonly search?: string;
+}
+
+export type WorkflowDefinitionSort = 'name' | 'updatedAt';
+
+export interface WorkflowDefinitionListQuery
+	extends WorkflowDefinitionFilters,
+		WorkflowListQuery<WorkflowDefinitionSort> {}
+
+export interface WorkflowDefinitionPage {
+	readonly definitions: readonly WorkflowDefinition[];
+	readonly nextCursor: string | null;
+}
+
 export interface WorkflowRunFilters {
 	readonly workflowId?: string;
 	readonly mode?: WorkflowRunMode;
 	readonly status?: WorkflowRunStatus;
 	readonly actorKind?: Actor['kind'];
 	readonly originKind?: WorkflowExecutionOrigin['kind'];
-	readonly limit?: number;
-	readonly cursor?: string | null;
+	/** Matched inside the workflow name or key, the actor label or the run id. */
+	readonly search?: string;
 }
 
+export type WorkflowRunSort = 'queuedAt';
+
+export interface WorkflowRunListQuery
+	extends WorkflowRunFilters,
+		WorkflowListQuery<WorkflowRunSort> {}
+
 export interface WorkflowRunPage {
 	readonly runs: readonly WorkflowRunSummary[];
 	readonly nextCursor: string | null;
 }
 
+export type WorkflowAuditSort = 'sequence' | 'occurredAt';
+
+export type WorkflowAuditListQuery = WorkflowListQuery<WorkflowAuditSort>;
+
 export interface WorkflowSimulationFixture {
 	readonly nodeId: string;
 	readonly outcomePort?: string;

package/modules/workflows/src/platform.ts

@@ -11,6 +11,7 @@ import {
 	WORKFLOW_EXECUTION_CAPABILITY,
 	type WorkflowExecutionCapability,
 } from './domain/types.ts';
+import { workflowsDataClasses } from './services/data-classes.ts';
 
 export function createServerComposition(
 	context: PlatformServerContext,
@@ -22,6 +23,13 @@ export function createServerComposition(
 		),
 		databases: context.databases,
 		capabilities: context.capabilities,
+		/* Which roles a workspace defines is auth.core's answer, asked when a
+		   graph carrying a human-approval node is validated, never cached, so a
+		   role deleted since the last publish is caught by the next one. */
+		roles: async (tenantId) =>
+			(await (await context.auth.service()).listRoles(tenantId)).map(
+				(role) => role.key,
+			),
 	});
 	/* The runtime opens its database leases lazily, so the capability is a
 	   forwarder rather than a resolved object: registration must not force a
@@ -40,6 +48,10 @@ export function createServerComposition(
 		cancel: async (runId, contextValue) =>
 			(await capability()).cancel(runId, contextValue),
 	} satisfies WorkflowExecutionCapability);
+	/* The sweep, the export and the erasure run here, on this module's own
+	   leases and under its own tenant transaction; the platform only holds the
+	   declaration. */
+	context.dataClasses.declare(workflowsDataClasses(() => runtime.repository()));
 	return {
 		routes: createWorkflowsRoutes(context.auth, runtime),
 		start: () => runtime.start(),

package/modules/workflows/src/server/runtime.ts

@@ -8,12 +8,22 @@ import {
 } from '@flowdular/sdk/database';
 import {
 	createPlatformCapabilityRegistry,
+	parsePreviousKeys,
 	type PlatformCapabilityRegistry,
 } from '@flowdular/sdk/kernel';
-import { createWorkflowCursorCodec } from '../services/cursor-codec.ts';
+import {
+	APPROVALS_REQUESTS_CAPABILITY,
+	type ApprovalsRequests,
+	type WorkspaceRolesResolver,
+} from '../services/approvals.ts';
+import {
+	NOTIFICATIONS_PUBLISH_CAPABILITY,
+	type NotificationPublisher,
+} from '../services/notifications.ts';
 import {
 	createWorkflowPayloadCodec,
 	decodeWorkflowPayloadKey,
+	type WorkflowPayloadCodec,
 } from '../services/payload-codec.ts';
 import {
 	DatabaseWorkflowsRepository,
@@ -37,8 +47,15 @@ export interface WorkflowsRuntimeOptions {
 		| undefined;
 	readonly repository?: WorkflowsRepository;
 	readonly capabilities?: PlatformCapabilityRegistry;
+	/* Roles the workspace defines, read through auth.core when a graph carries a
+	   human-approval node. */
+	readonly roles?: WorkspaceRolesResolver;
 	readonly payloadKey?: Buffer;
+	/* Keys a rotation has not finished retiring. They open stored payloads and
+	   verify outstanding cursors; nothing is ever written or signed with them. */
+	readonly previousPayloadKeys?: readonly Buffer[];
 	readonly cursorKey?: Buffer;
+	readonly previousCursorKeys?: readonly Buffer[];
 	readonly payloadRetentionMs?: number;
 	readonly worker?: WorkflowWorkerOptions;
 	readonly environment?: NodeJS.ProcessEnv;
@@ -47,6 +64,10 @@ export interface WorkflowsRuntimeOptions {
 
 export interface WorkflowsRuntime {
 	service(): Promise<WorkflowsService>;
+	/* The store the declared data classes sweep, export and erase through. It
+	   opens the runtime's own leases on first use, like the service does, so
+	   declaring a class at composition opens no connection. */
+	repository(): Promise<WorkflowsRepository>;
 	start(): void;
 	stop(): void | Promise<void>;
 	dispose(): void | Promise<void>;
@@ -109,9 +130,22 @@ export function workflowsRuntimeOptionsFromEnvironment(
 		payloadKey: environment.FD_WORKFLOWS_PAYLOAD_KEY
 			? decodeWorkflowPayloadKey(environment.FD_WORKFLOWS_PAYLOAD_KEY)
 			: derivedDevelopmentKey(workspaceRoot, 'payload'),
+		previousPayloadKeys: parsePreviousKeys(
+			environment.FD_WORKFLOWS_PAYLOAD_KEY_PREVIOUS,
+			(entry) =>
+				decodeWorkflowPayloadKey(entry, 'FD_WORKFLOWS_PAYLOAD_KEY_PREVIOUS'),
+		),
 		cursorKey: environment.FD_WORKFLOWS_CURSOR_KEY
-			? decodeWorkflowPayloadKey(environment.FD_WORKFLOWS_CURSOR_KEY)
+			? decodeWorkflowPayloadKey(
+					environment.FD_WORKFLOWS_CURSOR_KEY,
+					'FD_WORKFLOWS_CURSOR_KEY',
+				)
 			: derivedDevelopmentKey(workspaceRoot, 'cursor'),
+		previousCursorKeys: parsePreviousKeys(
+			environment.FD_WORKFLOWS_CURSOR_KEY_PREVIOUS,
+			(entry) =>
+				decodeWorkflowPayloadKey(entry, 'FD_WORKFLOWS_CURSOR_KEY_PREVIOUS'),
+		),
 		worker: {
 			leaseMs: environmentInteger(
 				environment.FD_WORKFLOWS_WORKER_LEASE_MS,
@@ -140,6 +174,24 @@ export function workflowsRuntimeOptionsFromEnvironment(
 	};
 }
 
+/**
+ * The codec a process outside the runtime seals with: the same current key and
+ * retired keys the runtime itself would resolve from this environment.
+ */
+export function workflowPayloadCodecFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+	workspaceRoot = process.cwd(),
+): WorkflowPayloadCodec {
+	const options = workflowsRuntimeOptionsFromEnvironment(
+		environment,
+		workspaceRoot,
+	);
+	return createWorkflowPayloadCodec(
+		options.payloadKey ?? derivedDevelopmentKey(workspaceRoot, 'payload'),
+		options.previousPayloadKeys ?? [],
+	);
+}
+
 export function createWorkflowsRuntime(
 	options: WorkflowsRuntimeOptions,
 ): WorkflowsRuntime {
@@ -210,7 +262,7 @@ export function createWorkflowsRuntime(
 				runtime: runtimeLease.database,
 				background: backgroundLease.database,
 			},
-			createWorkflowPayloadCodec(payloadKey),
+			createWorkflowPayloadCodec(payloadKey, options.previousPayloadKeys ?? []),
 			options.payloadRetentionMs,
 		);
 	};
@@ -221,7 +273,11 @@ export function createWorkflowsRuntime(
 		if (!service) {
 			const serviceOptions: WorkflowsServiceOptions = {
 				capabilities,
-				cursorCodec: createWorkflowCursorCodec(cursorKey),
+				cursorKeys: {
+					current: cursorKey,
+					previous: options.previousCursorKeys ?? [],
+				},
+				...(options.roles ? { roles: options.roles } : {}),
 				onRunQueued: () => worker?.kick(),
 			};
 			service = new WorkflowsService(repository, serviceOptions);
@@ -229,7 +285,20 @@ export function createWorkflowsRuntime(
 		worker ??= new WorkflowWorker(
 			repository,
 			() => service?.executionDependencies() ?? null,
-			options.worker,
+			{
+				...options.worker,
+				/* notifications.core is optional and is not declared as a
+				   dependency. The lookup happens when a run settles, so a module
+				   composed after this one is found and an absent one is a no-op. */
+				notifications: () =>
+					capabilities.get<NotificationPublisher>(
+						NOTIFICATIONS_PUBLISH_CAPABILITY,
+					),
+				/* approvals.core is optional too. A human-approval node refuses with
+				   a stable code when it is absent; every other node is unaffected. */
+				approvals: () =>
+					capabilities.get<ApprovalsRequests>(APPROVALS_REQUESTS_CAPABILITY),
+			},
 		);
 		if (started) worker.start();
 		return service;
@@ -240,6 +309,10 @@ export function createWorkflowsRuntime(
 
 	return {
 		service: resolved,
+		repository: async () => {
+			await resolved();
+			return repository!;
+		},
 		start() {
 			if (disposed) throw new Error('Workflows runtime is disposed.');
 			started = true;