@flowdular/sdk 0.2.3 → 0.3.0

package/modules/workflows/src/services/migration.ts

@@ -332,6 +332,129 @@ const TENANT_TABLES: readonly (readonly [string, string, string])[] = [
 	],
 ];
 
+export const WORKFLOWS_MIGRATION_004 = `-- The rotation command has to find the payloads still sealed with a retired key
+-- before it knows whose they are. The retention sweep sees only payloads with an
+-- expiry; a rotation covers every live one, so it reads under a policy of its
+-- own and is granted the key id alone. The ciphertext stays unreadable on this
+-- connection, and every payload it re-seals is read again under the tenant that
+-- row named.
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'coreloom_background') THEN
+    RAISE EXCEPTION 'The coreloom_background role must exist before this migration.';
+  END IF;
+END
+$$;
+CREATE POLICY workflow_payloads_rotation_policy ON workflow_payloads
+  FOR SELECT TO coreloom_background
+  USING (kind = 'execution');
+GRANT SELECT (encryption_key_id) ON workflow_payloads TO coreloom_background;
+`;
+
+/* Mirrors migrations/0005_workflows_human_approval.up.sql byte for byte. */
+export const WORKFLOWS_MIGRATION_005_HUMAN_APPROVAL = `-- A run waiting on a person waits for days, not for the seconds an agent or an
+-- action takes. Leaving it in 'running' would keep it at the head of the claim
+-- queue, where it would be re-claimed every poll and, because the queue is
+-- ordered by queued_at, would starve every run queued after it.
+--
+-- 'waiting-approval' is the status that takes such a run out of the queue. It
+-- comes back when approvals.core calls back, which sets the node's
+-- next_attempt_at to now, or when the recheck the node armed falls due; the
+-- claim predicate reads that column exactly as it already does for a retry.
+--
+-- The approval itself is the third child kind. It reuses the attempt's
+-- waiting-child machinery, so the request id is stored in child_id and recovery
+-- after a restart finds the open request instead of opening a second one.
+ALTER TABLE workflow_runs DROP CONSTRAINT IF EXISTS workflow_runs_status_check;
+ALTER TABLE workflow_runs ADD CONSTRAINT workflow_runs_status_check
+  CHECK (status IN ('queued', 'running', 'waiting-agent', 'waiting-approval', 'waiting-retry', 'cancel-requested', 'succeeded', 'failed', 'refused', 'cancelled'));
+ALTER TABLE workflow_node_attempts DROP CONSTRAINT IF EXISTS workflow_node_attempts_child_kind_check;
+ALTER TABLE workflow_node_attempts ADD CONSTRAINT workflow_node_attempts_child_kind_check
+  CHECK (child_kind IN ('agent', 'action', 'approval'));
+-- The claim poll has to see that a node is asleep on an approval before it can
+-- decide whether the run is due, and the cross-tenant policy showed it retries
+-- only. It is widened to the second waiting state and no further: the four
+-- routing columns it was already granted stay the whole of what it can read,
+-- and the run is read again under its own tenant before anything is written.
+DROP POLICY IF EXISTS workflow_node_states_background_policy ON workflow_node_states;
+CREATE POLICY workflow_node_states_background_policy ON workflow_node_states
+  FOR SELECT TO coreloom_background
+  USING (status IN ('waiting-retry', 'waiting-child'));
+`;
+
+/* Mirrors migrations/0006_workflows_retention_indexes.up.sql byte for byte. */
+export const WORKFLOWS_MIGRATION_006_RETENTION_INDEXES = `-- The retention sweep of workflows.core.runs asks one workspace for its oldest
+-- settled runs, and a subject erasure asks it for the runs one account
+-- requested. Both are bounded batches, so both need a range scan rather than a
+-- pass over the workspace's runs. The requester lives inside the stored actor
+-- document, so the index is over that one field of it; the export walks the
+-- order workflow_runs_tenant_queue_idx already carries and needs no index of
+-- its own.
+CREATE INDEX IF NOT EXISTS workflow_runs_tenant_settled_idx
+  ON workflow_runs (tenant_id, completed_at);
+CREATE INDEX IF NOT EXISTS workflow_runs_tenant_requester_idx
+  ON workflow_runs (tenant_id, (actor_json::jsonb ->> 'id'), id);
+`;
+
+/* Mirrors migrations/0007_workflows_erasure_subject_indexes.up.sql byte for byte. */
+export const WORKFLOWS_MIGRATION_007_ERASURE_SUBJECT_INDEXES = `-- A subject erasure asks one workspace for the runs a person is behind, and
+-- that is three questions rather than one: the runs the person started, the
+-- runs a service actor they configured started, and the runs an agent started
+-- on their behalf. 0006 indexed the first, which is the only one held in the
+-- actor's own id. These give the other two the same support.
+-- Neither is reachable from the connection the erasure runs on, and 0006's is
+-- not either. The jsonb extraction operator is not leakproof, so under the
+-- forced row level security policy PostgreSQL applies the policy first and the
+-- comparison stays a filter rather than an index condition: measured over
+-- 20000 runs, the runtime role scans the workspace while the migration role
+-- uses the index. The batch limit is what bounds an erasure until the subject
+-- account is stored in a column of its own, which compares leakproof and
+-- indexes plainly; that column is the precise fix and it retires all three.
+CREATE INDEX IF NOT EXISTS workflow_runs_tenant_configured_by_idx
+  ON workflow_runs (tenant_id, (actor_json::jsonb -> 'configuredBy' ->> 'id'), id);
+CREATE INDEX IF NOT EXISTS workflow_runs_tenant_subject_idx
+  ON workflow_runs (tenant_id, (authorization_subject_json::jsonb ->> 'id'), id);
+`;
+
+/* Mirrors migrations/0008_workflows_subject_account.up.sql byte for byte. */
+export const WORKFLOWS_MIGRATION_008_SUBJECT_ACCOUNT = `-- The person behind a run, resolved once at write time instead of read out of
+-- the stored actor document on every erasure. A run started by a person names
+-- them in its actor, a run started by a schedule, a webhook or an automation
+-- names them in the service actor's configuredBy, and a run an agent started
+-- names them in the delegated authorization subject; this column is that one
+-- answer, and the three predicates it replaces become a single equality.
+-- This supersedes the expression indexes of 0006 and 0007, which the erasure
+-- cannot use: the jsonb extraction operator is not leakproof, so under the
+-- forced row level security policy PostgreSQL applies the policy first and the
+-- comparison can never become an index condition. A plain text column compares
+-- leakproof and indexes normally, so the same query becomes an index scan on
+-- the connection the erasure actually runs on. Both older indexes stay because
+-- an applied migration is immutable; they are dead weight, not a hazard.
+ALTER TABLE workflow_runs
+  ADD COLUMN subject_account_id TEXT;
+UPDATE workflow_runs
+SET subject_account_id = COALESCE(
+  actor_json::jsonb -> 'configuredBy' ->> 'id',
+  authorization_subject_json::jsonb ->> 'id',
+  actor_json::jsonb ->> 'id'
+)
+WHERE subject_account_id IS NULL;
+CREATE INDEX IF NOT EXISTS workflow_runs_tenant_subject_account_idx
+  ON workflow_runs (tenant_id, subject_account_id, id);
+`;
+
+/* Mirrors migrations/0009_workflows_definition_list_indexes.up.sql byte for byte. */
+export const WORKFLOWS_MIGRATION_009_DEFINITION_LIST_INDEXES = `-- The definitions screen pages by keyset over the order it shows, by name or by
+-- last update, each ending in the id. 0001 indexed (tenant_id, name, id), which
+-- serves neither an ORDER BY over lower(name) nor one over updated_at, so both
+-- orders walked the workspace's rows and sorted them. These two carry each
+-- order the way the page reads it.
+CREATE INDEX IF NOT EXISTS workflow_definitions_tenant_lower_name_idx
+  ON workflow_definitions (tenant_id, lower(name), id);
+CREATE INDEX IF NOT EXISTS workflow_definitions_tenant_updated_idx
+  ON workflow_definitions (tenant_id, updated_at, id);
+`;
+
 export const databaseMigrations: readonly DatabaseMigration[] = [
 	{
 		id: '0001_workflows_core',
@@ -372,4 +495,121 @@ export const databaseMigrations: readonly DatabaseMigration[] = [
 				() => database.schema.hasIndex('workflow_payloads_retention_idx'),
 			]),
 	},
+	{
+		id: '0004_payload_rotation_inventory',
+		sql: { postgresql: WORKFLOWS_MIGRATION_004 },
+		/* A policy and a grant leave no object the schema reader can see, so the
+		   policy itself proves this migration ran. */
+		inspectExisting: async (database) => {
+			const result = await database.query<{ present: boolean }>({
+				text: `SELECT EXISTS (
+				         SELECT 1 FROM pg_policy
+				         JOIN pg_class ON pg_class.oid = pg_policy.polrelid
+				         JOIN pg_namespace ON pg_namespace.oid = pg_class.relnamespace
+				         WHERE pg_namespace.nspname = current_schema()
+				           AND pg_class.relname = 'workflow_payloads'
+				           AND pg_policy.polname = 'workflow_payloads_rotation_policy'
+				       ) AS present`,
+			});
+			return result.rows[0]?.present === true ? 'complete' : 'absent';
+		},
+	},
+	{
+		id: '0005_workflows_human_approval',
+		sql: { postgresql: WORKFLOWS_MIGRATION_005_HUMAN_APPROVAL },
+		/* A replaced check constraint leaves no new schema object behind, so each
+		   of the two is proved against the catalogue and a schema carrying only
+		   one of them is partial. The rows are narrowed to this schema's objects
+		   before anything is deparsed: a deparse over the whole catalogue reaches
+		   relations another connection is dropping and fails with a cache lookup
+		   error instead of an answer. */
+		inspectExisting: (database) =>
+			migrationObjectState([
+				async () =>
+					(
+						await database.query<{ present: boolean }>({
+							text: `WITH candidate AS MATERIALIZED (
+							         SELECT oid FROM pg_constraint
+							         WHERE conrelid = to_regclass('workflow_runs')
+							           AND conname = 'workflow_runs_status_check'
+							       )
+							       SELECT EXISTS (
+							         SELECT 1 FROM candidate
+							         WHERE pg_get_constraintdef(oid) LIKE '%waiting-approval%'
+							       ) AS present`,
+						})
+					).rows[0]?.present === true,
+				async () =>
+					(
+						await database.query<{ present: boolean }>({
+							text: `WITH candidate AS MATERIALIZED (
+							         SELECT oid FROM pg_constraint
+							         WHERE conrelid = to_regclass('workflow_node_attempts')
+							           AND conname = 'workflow_node_attempts_child_kind_check'
+							       )
+							       SELECT EXISTS (
+							         SELECT 1 FROM candidate
+							         WHERE pg_get_constraintdef(oid) LIKE '%approval%'
+							       ) AS present`,
+						})
+					).rows[0]?.present === true,
+				async () =>
+					(
+						await database.query<{ present: boolean }>({
+							text: `WITH candidate AS MATERIALIZED (
+							         SELECT pg_policy.polqual, pg_policy.polrelid
+							         FROM pg_policy
+							         WHERE pg_policy.polrelid = to_regclass('workflow_node_states')
+							           AND pg_policy.polname = 'workflow_node_states_background_policy'
+							       )
+							       SELECT EXISTS (
+							         SELECT 1 FROM candidate
+							         WHERE pg_get_expr(polqual, polrelid) LIKE '%waiting-child%'
+							       ) AS present`,
+						})
+					).rows[0]?.present === true,
+			]),
+	},
+	{
+		id: '0006_workflows_retention_indexes',
+		sql: { postgresql: WORKFLOWS_MIGRATION_006_RETENTION_INDEXES },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasIndex('workflow_runs_tenant_settled_idx'),
+				() => database.schema.hasIndex('workflow_runs_tenant_requester_idx'),
+			]),
+	},
+	{
+		id: '0007_workflows_erasure_subject_indexes',
+		sql: { postgresql: WORKFLOWS_MIGRATION_007_ERASURE_SUBJECT_INDEXES },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() =>
+					database.schema.hasIndex('workflow_runs_tenant_configured_by_idx'),
+				() => database.schema.hasIndex('workflow_runs_tenant_subject_idx'),
+			]),
+	},
+	{
+		id: '0008_workflows_subject_account',
+		sql: { postgresql: WORKFLOWS_MIGRATION_008_SUBJECT_ACCOUNT },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasColumn('workflow_runs', 'subject_account_id'),
+				() =>
+					database.schema.hasIndex('workflow_runs_tenant_subject_account_idx'),
+			]),
+	},
+	{
+		id: '0009_workflows_definition_list_indexes',
+		sql: { postgresql: WORKFLOWS_MIGRATION_009_DEFINITION_LIST_INDEXES },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() =>
+					database.schema.hasIndex(
+						'workflow_definitions_tenant_lower_name_idx',
+					),
+				() =>
+					database.schema.hasIndex('workflow_definitions_tenant_updated_idx'),
+			]),
+	},
 ];

package/modules/workflows/src/services/notifications.ts

@@ -0,0 +1,98 @@
+import type { UserActor } from '@flowdular/sdk/kernel';
+
+/* The notifications.core publish contract, declared here rather than imported.
+   notifications.core is optional: workflows.core composes, runs and settles
+   runs with that module absent, so it may not be a package dependency. This
+   mirror is the contract notifications.core owns and must not drift from it.
+   modules/agents/src/services/notifications.ts holds the same mirror and stays
+   identical to this file apart from the module id; change both. */
+export const NOTIFICATIONS_PUBLISH_CAPABILITY = 'notifications.publish.v1';
+
+export type NotificationKind =
+	| 'agent-run-completed'
+	| 'agent-run-failed'
+	| 'workflow-run-completed'
+	| 'workflow-run-failed'
+	| 'webhook-dead-letter'
+	| 'approval-requested'
+	| 'approval-decided'
+	| 'meter-threshold';
+
+export interface NotificationPublishInput {
+	readonly tenantId: string;
+	readonly kind: NotificationKind;
+	readonly sourceModule: string;
+	readonly sourceRef: string;
+	readonly title: string;
+	readonly body?: string;
+	readonly recipients: readonly string[];
+}
+
+export interface NotificationPublishResult {
+	readonly inboxItemIds: readonly string[];
+	readonly deliveryIds: readonly string[];
+}
+
+export interface NotificationPublisher {
+	publish(input: NotificationPublishInput): Promise<NotificationPublishResult>;
+}
+
+/* Read at the point of use, never at composition time: the platform may
+   register notifications.core after workflows.core, or never. */
+export type NotificationPublisherResolver = () => NotificationPublisher | null;
+
+const LIMITS = {
+	sourceModule: 64,
+	sourceRef: 200,
+	title: 200,
+	body: 4_000,
+	recipients: 64,
+	recipientId: 128,
+} as const;
+
+function clamp(value: string, limit: number): string {
+	return value.length > limit ? value.slice(0, limit) : value;
+}
+
+/* The person accountable for the run. The service that enqueued it already
+   derived and validated one: the member who started the run, or the member who
+   configured the service identity that did. A run with no person behind it,
+   such as one an agent started for itself, has nobody to notify. */
+export function runNotificationRecipients(
+	authorizationSubject: UserActor | null,
+): readonly string[] {
+	return authorizationSubject ? [authorizationSubject.id] : [];
+}
+
+/* Advisory and post-commit. An absent notifications module, nobody to notify,
+   or a publisher that throws never changes a settled run, so this never
+   rejects. The caller passes the run id as sourceRef, which makes a retried
+   terminal step publish the same notification instead of a second one. */
+export async function publishRunOutcome(
+	resolve: NotificationPublisherResolver | undefined,
+	input: NotificationPublishInput,
+): Promise<void> {
+	if (input.recipients.length === 0) return;
+	try {
+		const publisher = resolve?.();
+		if (!publisher) return;
+		await publisher.publish({
+			tenantId: input.tenantId,
+			kind: input.kind,
+			sourceModule: clamp(input.sourceModule, LIMITS.sourceModule),
+			sourceRef: clamp(input.sourceRef, LIMITS.sourceRef),
+			title: clamp(input.title, LIMITS.title),
+			...(input.body === undefined
+				? {}
+				: { body: clamp(input.body, LIMITS.body) }),
+			recipients: input.recipients
+				.slice(0, LIMITS.recipients)
+				.map((recipient) => clamp(recipient, LIMITS.recipientId)),
+		});
+	} catch (error) {
+		console.warn(
+			`[workflows] notification publish for run ${input.sourceRef} failed:`,
+			error instanceof Error ? error.message : error,
+		);
+	}
+}

package/modules/workflows/src/services/payload-codec.ts

@@ -1,9 +1,9 @@
 import {
-	createCipheriv,
-	createDecipheriv,
-	createHash,
-	randomBytes,
-} from 'node:crypto';
+	createKeyring,
+	KeyringError,
+	keyFingerprint,
+	type Keyring,
+} from '@flowdular/sdk/kernel';
 import type {
 	JsonSchemaV1,
 	JsonValue,
@@ -46,21 +46,41 @@ function aad(context: {
 	);
 }
 
-export function decodeWorkflowPayloadKey(value: string): Buffer {
+export function decodeWorkflowPayloadKey(
+	value: string,
+	variable = 'FD_WORKFLOWS_PAYLOAD_KEY',
+): Buffer {
 	const trimmed = value.trim();
 	const decoded = /^[0-9a-f]{64}$/i.test(trimmed)
 		? Buffer.from(trimmed, 'hex')
 		: Buffer.from(trimmed, 'base64');
 	if (decoded.length !== 32) {
-		throw new Error('FD_WORKFLOWS_PAYLOAD_KEY must encode exactly 32 bytes.');
+		throw new Error(`${variable} must encode exactly 32 bytes.`);
 	}
 	return decoded;
 }
 
-export function createWorkflowPayloadCodec(key: Buffer): WorkflowPayloadCodec {
+/* The stored envelope spells the key id with the digest it came from. The ring
+   holds the bare fingerprint, so the prefix is added on the way out and
+   stripped on the way in; stored rows keep the format they were written in. */
+const KEY_ID_PREFIX = 'sha256:';
+
+export function workflowPayloadKeyId(key: Buffer): string {
+	return `${KEY_ID_PREFIX}${keyFingerprint(key)}`;
+}
+
+/**
+ * `previous` holds the payload keys a rotation has not finished retiring. They
+ * open stored payloads; every new payload is sealed with `key`.
+ */
+export function createWorkflowPayloadCodec(
+	key: Buffer,
+	previous: readonly Buffer[] = [],
+): WorkflowPayloadCodec {
 	if (key.length !== 32)
 		throw new Error('Workflow payload encryption requires 32 bytes.');
-	const keyId = `sha256:${createHash('sha256').update(key).digest('hex').slice(0, 16)}`;
+	const keyring: Keyring = createKeyring({ current: key, previous });
+	const keyId = `${KEY_ID_PREFIX}${keyring.keyId}`;
 	return {
 		keyId,
 		encrypt(value, context) {
@@ -68,16 +88,13 @@ export function createWorkflowPayloadCodec(key: Buffer): WorkflowPayloadCodec {
 			if (bytes.length > WORKFLOW_LIMITS.maxEnvelopeBytes) {
 				throw new Error('WORKFLOW_LIMIT_EXCEEDED');
 			}
-			const iv = randomBytes(12);
-			const cipher = createCipheriv('aes-256-gcm', key, iv);
-			cipher.setAAD(aad(context));
-			const encrypted = Buffer.concat([cipher.update(bytes), cipher.final()]);
+			const sealed = keyring.seal(bytes, aad(context));
 			return [
 				'v1',
 				keyId,
-				iv.toString('base64url'),
-				cipher.getAuthTag().toString('base64url'),
-				encrypted.toString('base64url'),
+				sealed.iv.toString('base64url'),
+				sealed.tag.toString('base64url'),
+				sealed.ciphertext.toString('base64url'),
 			].join('.');
 		},
 		decrypt(ciphertext, context) {
@@ -85,24 +102,30 @@ export function createWorkflowPayloadCodec(key: Buffer): WorkflowPayloadCodec {
 				ciphertext.split('.');
 			if (
 				version !== 'v1' ||
-				storedKeyId !== keyId ||
+				!storedKeyId?.startsWith(KEY_ID_PREFIX) ||
 				!encodedIv ||
 				!encodedTag ||
 				!encodedData
 			) {
 				throw new Error('WORKFLOW_PAYLOAD_UNREADABLE');
 			}
-			const decipher = createDecipheriv(
-				'aes-256-gcm',
-				key,
-				Buffer.from(encodedIv, 'base64url'),
-			);
-			decipher.setAAD(aad(context));
-			decipher.setAuthTag(Buffer.from(encodedTag, 'base64url'));
-			const clear = Buffer.concat([
-				decipher.update(Buffer.from(encodedData, 'base64url')),
-				decipher.final(),
-			]);
+			let clear: Buffer;
+			try {
+				clear = keyring.open(
+					{
+						keyId: storedKeyId.slice(KEY_ID_PREFIX.length),
+						iv: Buffer.from(encodedIv, 'base64url'),
+						tag: Buffer.from(encodedTag, 'base64url'),
+						ciphertext: Buffer.from(encodedData, 'base64url'),
+					},
+					aad(context),
+				);
+			} catch (error) {
+				if (error instanceof KeyringError) {
+					throw new Error('WORKFLOW_PAYLOAD_UNREADABLE', { cause: error });
+				}
+				throw error;
+			}
 			return JSON.parse(clear.toString('utf8')) as JsonValue;
 		},
 	};

package/modules/workflows/src/services/payload-rotation.ts

@@ -0,0 +1,171 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import type { WorkflowPayloadCodec } from './payload-codec.ts';
+
+/** Payloads re-sealed inside one tenant-scoped transaction. */
+export const PAYLOAD_ROTATION_BATCH = 200;
+
+export const PAYLOAD_ROTATION_TABLE = 'workflow_payloads';
+
+export interface PayloadKeyCount {
+	readonly keyId: string;
+	readonly rows: number;
+}
+
+export interface PayloadRotationReport {
+	readonly table: string;
+	/** Key id every payload should end on: the current key of the codec. */
+	readonly currentKeyId: string;
+	readonly counts: readonly PayloadKeyCount[];
+	/** Payloads on a retired key when the run started. */
+	readonly stale: number;
+	readonly tenants: number;
+	readonly rotated: number;
+	/** Payloads a concurrent write changed between the read and the update. */
+	readonly skipped: number;
+}
+
+export interface PayloadRotationOptions {
+	/** Tenant-scoped handle. Every read and write of a payload runs on it. */
+	readonly runtime: DatabaseHandle;
+	/** Cross-tenant handle. It is granted the key ids and nothing else. */
+	readonly background: DatabaseHandle;
+	readonly codec: WorkflowPayloadCodec;
+	readonly apply?: boolean;
+	readonly batchSize?: number;
+}
+
+interface StaleRow {
+	id: string;
+	run_id: string;
+	ciphertext: string;
+}
+
+/* Evidence rows hold a redacted preview and no ciphertext, so only execution
+   payloads carry an envelope a key can open. */
+const SQL = {
+	counts: `SELECT encryption_key_id AS key_id, count(*) AS row_count
+	         FROM workflow_payloads
+	         WHERE kind = 'execution'
+	         GROUP BY encryption_key_id
+	         ORDER BY encryption_key_id`,
+	staleTenants: `SELECT tenant_id, count(*) AS row_count
+	               FROM workflow_payloads
+	               WHERE kind = 'execution' AND encryption_key_id IS DISTINCT FROM $1
+	               GROUP BY tenant_id
+	               ORDER BY tenant_id`,
+	/* Paged by primary key: a payload the optimistic update skipped stays stale,
+	   so a query that only asked for stale rows would return it forever. */
+	staleBatch: `SELECT id, run_id, ciphertext
+	             FROM workflow_payloads
+	             WHERE tenant_id = $1 AND kind = 'execution'
+	               AND encryption_key_id IS DISTINCT FROM $2 AND id > $3
+	             ORDER BY id
+	             LIMIT $4`,
+	/* The envelope the row still holds is the optimistic check. A payload is
+	   written once and expired later, so a mismatch means retention or a
+	   concurrent rotation reached it first. */
+	reseal: `UPDATE workflow_payloads
+	         SET ciphertext = $1, encryption_key_id = $2
+	         WHERE tenant_id = $3 AND id = $4 AND ciphertext = $5`,
+};
+
+function count(value: number | bigint | string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized)) {
+		throw new Error('The workflows database returned an invalid count.');
+	}
+	return normalized;
+}
+
+/**
+ * Re-seals every stored execution payload that is not on the current key. The
+ * inventory is read once across tenants, and each batch of payloads is read,
+ * decrypted, re-sealed and written inside one transaction scoped to the tenant
+ * that owns them. It is idempotent: a second run finds nothing to do.
+ */
+export async function rotateWorkflowPayloads(
+	options: PayloadRotationOptions,
+): Promise<PayloadRotationReport> {
+	const currentKeyId = options.codec.keyId;
+	const batchSize = options.batchSize ?? PAYLOAD_ROTATION_BATCH;
+	const inventory = await options.background.transaction(
+		async (transaction) => ({
+			counts: (
+				await transaction.query<{
+					key_id: string | null;
+					row_count: number | bigint | string;
+				}>({ text: SQL.counts })
+			).rows,
+			stale: (
+				await transaction.query<{
+					tenant_id: string;
+					row_count: number | bigint | string;
+				}>({ text: SQL.staleTenants, parameters: [currentKeyId] })
+			).rows,
+		}),
+		{ access: 'read' },
+	);
+	const report = {
+		table: PAYLOAD_ROTATION_TABLE,
+		currentKeyId,
+		counts: inventory.counts.map((row) => ({
+			keyId: row.key_id ?? 'none',
+			rows: count(row.row_count),
+		})),
+		stale: inventory.stale.reduce(
+			(total, row) => total + count(row.row_count),
+			0,
+		),
+		tenants: inventory.stale.length,
+	};
+	if (options.apply !== true) {
+		return { ...report, rotated: 0, skipped: 0 };
+	}
+	let rotated = 0;
+	let skipped = 0;
+	for (const { tenant_id: tenantId } of inventory.stale) {
+		let cursor = '';
+		for (;;) {
+			const batch = await options.runtime.transaction(
+				async (transaction) => {
+					const rows = (
+						await transaction.query<StaleRow>({
+							text: SQL.staleBatch,
+							parameters: [tenantId, currentKeyId, cursor, batchSize],
+						})
+					).rows;
+					let written = 0;
+					for (const row of rows) {
+						const context = {
+							tenantId,
+							runId: row.run_id,
+							payloadId: row.id,
+						};
+						const sealed = options.codec.encrypt(
+							options.codec.decrypt(row.ciphertext, context),
+							context,
+						);
+						const result = await transaction.execute({
+							text: SQL.reseal,
+							parameters: [
+								sealed,
+								options.codec.keyId,
+								tenantId,
+								row.id,
+								row.ciphertext,
+							],
+						});
+						written += result.affectedRows;
+					}
+					return { read: rows.length, written, last: rows.at(-1)?.id };
+				},
+				{ access: 'write', tenantId },
+			);
+			rotated += batch.written;
+			skipped += batch.read - batch.written;
+			if (batch.read < batchSize || batch.last === undefined) break;
+			cursor = batch.last;
+		}
+	}
+	return { ...report, rotated, skipped };
+}