@flowdular/sdk 0.2.4 → 0.3.0

package/modules/{automations-workflows-integration/src/server/adapter.ts → automations/src/server/workflow-target.ts}

@@ -2,18 +2,17 @@ import {
 	serviceActor,
 	type PlatformCapabilityRegistry,
 } from '@flowdular/sdk/kernel';
-import {
-	AUTOMATION_TARGETS_CAPABILITY,
-	type AutomationTargetAdapter,
-	type AutomationTargetAuthorizationContext,
-	type AutomationTargetInvocationContext,
-	type AutomationTargetRegistry,
-} from '@flowdular/sdk/modules/automations/server';
 import { WORKFLOWS_PERMISSIONS } from '@flowdular/sdk/modules/workflows';
 import {
 	WORKFLOW_EXECUTION_CAPABILITY,
 	type WorkflowExecutionCapability,
 } from '@flowdular/sdk/modules/workflows/server';
+import type {
+	AutomationTargetAdapter,
+	AutomationTargetAuthorizationContext,
+	AutomationTargetInvocationContext,
+	AutomationTargetRegistry,
+} from './targets.ts';
 
 type WorkflowInput = Parameters<
 	WorkflowExecutionCapability['enqueue']
@@ -114,6 +113,8 @@ async function requireExecutable(
 	return reference;
 }
 
+/* The key prefixes are persisted in the workflows idempotency ledger, so they
+   keep the name of the former integration module. */
 function idempotencyKey(context: AutomationTargetInvocationContext): string {
 	const source = context.source;
 	if (source.kind === 'schedule') {
@@ -254,13 +255,12 @@ export function createWorkflowAutomationTargetAdapter(
 	};
 }
 
-export function registerAutomationsWorkflowsIntegration(
+/* The workflow capability is resolved per call: workflows.core may compose
+   after automations.core, and a workspace may leave it uninstalled. */
+export function registerWorkflowAutomationTarget(
+	targets: AutomationTargetRegistry,
 	capabilities: PlatformCapabilityRegistry,
-): boolean {
-	const targets = capabilities.get<AutomationTargetRegistry>(
-		AUTOMATION_TARGETS_CAPABILITY,
-	);
-	if (!targets) return false;
+): void {
 	targets.register(
 		createWorkflowAutomationTargetAdapter(() =>
 			capabilities.get<WorkflowExecutionCapability>(
@@ -268,5 +268,4 @@ export function registerAutomationsWorkflowsIntegration(
 			),
 		),
 	);
-	return true;
 }

package/modules/automations/src/services/data-classes.ts

@@ -0,0 +1,62 @@
+import type {
+	DataClassDeclaration,
+	DataClassExportSummary,
+} from '@flowdular/sdk/kernel';
+import type { AutomationsRepository } from './repository.ts';
+
+/** Rows one keyset page carries. Bounded so a walk never loads a whole table. */
+export const AUDIT_EXPORT_PAGE = 500;
+
+/**
+ * The classes automations.core owns. Schedules and triggers are configuration a
+ * person manages rather than history that ages, so the trail is the only class
+ * here: it is what the workspace accumulates.
+ *
+ * It carries no sweep. The trail is hash chained per workspace, every event
+ * naming the hash of the one before it, and verifyAuditChain walks it from
+ * sequence 1 with no previous hash. Deleting the oldest events by age would
+ * leave the first surviving event pointing at a row that is gone, so the next
+ * verification would report the chain broken and could not tell retention from
+ * tampering. audit.core keeps its own chained ledgers for the same reason. The
+ * precise fix is chain archival, sealing a removed prefix under one anchor
+ * event; until that exists these rows are kept until a person deletes them.
+ *
+ * The repository arrives as a thunk because declaring happens while the
+ * platform composes, before anything has opened a database.
+ */
+export function automationsDataClasses(
+	repository: () => Promise<AutomationsRepository>,
+	pageSize = AUDIT_EXPORT_PAGE,
+): readonly DataClassDeclaration[] {
+	return [
+		{
+			key: 'audit-events',
+			label: 'Automation audit trail',
+			defaultRetentionDays: null,
+			exportable: true,
+			export: async ({ tenantId, sink }): Promise<DataClassExportSummary> => {
+				let afterId = '';
+				let rows = 0;
+				let from: Date | null = null;
+				let to: Date | null = null;
+				for (;;) {
+					const page = await (
+						await repository()
+					).exportAuditEventsPage(tenantId, afterId, pageSize);
+					for (const event of page) {
+						const at = new Date(event.occurredAt);
+						if (!from || at < from) from = at;
+						if (!to || at > to) to = at;
+						afterId = event.id;
+						rows += 1;
+						await sink.write({
+							...event,
+							occurredAt: at.toISOString(),
+						});
+					}
+					if (page.length < pageSize) return { rows, from, to };
+				}
+			},
+		},
+	];
+}

package/modules/automations/src/services/database-repository.ts

@@ -1,7 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import type { DatabaseHandle, DatabaseTransaction } from '@flowdular/sdk/database';
-import { runDatabaseMigrations } from '@flowdular/sdk/database';
+import { integer, runDatabaseMigrations } from '@flowdular/sdk/database';
 import { normalizeActor } from '@flowdular/sdk/kernel';
+import { keysetWhere } from '@flowdular/sdk/server';
 import type { UserActor } from '@flowdular/sdk/kernel';
 import type {
 	AutomationAuditEvent,
@@ -9,6 +10,9 @@ import type {
 } from '../domain/types.ts';
 import { databaseMigrations } from './migration.ts';
 import type {
+	AutomationListCursor,
+	AutomationListPage,
+	AutomationListQuery,
 	AutomationScheduleRouting,
 	AutomationsRepository,
 	AutomationTriggerRecord,
@@ -77,21 +81,11 @@ interface AuditRow {
 	event_hash: string;
 }
 
-/* PostgreSQL returns BIGINT as a string. The audit hash covers sequence and
-   occurredAt, so a string here would break the chain rather than merely look
-   wrong. */
-function integer(value: number | bigint | string): number {
-	const normalized = Number(value);
-	if (!Number.isSafeInteger(normalized)) {
-		throw new Error('The automations database returned an invalid integer.');
-	}
-	return normalized;
-}
-
 function optionalInteger(
 	value: number | bigint | string | null,
+	field: string,
 ): number | null {
-	return value === null ? null : integer(value);
+	return value === null ? null : integer(value, field);
 }
 
 function configuredBy(value: string | null, createdBy: string): UserActor {
@@ -131,14 +125,14 @@ function schedule(row: ScheduleRow): StoredAutomationSchedule {
 		label: row.label,
 		inputTemplate: row.input_template,
 		cadence: row.cadence,
-		enabled: integer(row.enabled) === 1,
+		enabled: integer(row.enabled, 'enabled') === 1,
 		disabledReason: row.disabled_reason,
-		nextRunAt: integer(row.next_run_at),
-		lastRunAt: optionalInteger(row.last_run_at),
+		nextRunAt: integer(row.next_run_at, 'next_run_at'),
+		lastRunAt: optionalInteger(row.last_run_at, 'last_run_at'),
 		lastRunId: row.last_run_id,
 		lastError: row.last_error,
-		createdAt: integer(row.created_at),
-		updatedAt: integer(row.updated_at),
+		createdAt: integer(row.created_at, 'created_at'),
+		updatedAt: integer(row.updated_at, 'updated_at'),
 		createdBy: row.created_by,
 		configuredBy: configuredBy(row.configured_by_json, row.created_by),
 		permissionSnapshot: permissionSnapshot(row.permission_snapshot_json),
@@ -155,14 +149,14 @@ function trigger(row: TriggerRow): StoredAutomationTrigger {
 		targetKey,
 		agentId: targetKind === 'agent' ? targetKey : '',
 		label: row.label,
-		enabled: integer(row.enabled) === 1,
-		secretRevision: integer(row.secret_revision),
-		createdAt: integer(row.created_at),
-		updatedAt: integer(row.updated_at),
+		enabled: integer(row.enabled, 'enabled') === 1,
+		secretRevision: integer(row.secret_revision, 'secret_revision'),
+		createdAt: integer(row.created_at, 'created_at'),
+		updatedAt: integer(row.updated_at, 'updated_at'),
 		createdBy: row.created_by,
-		lastFiredAt: optionalInteger(row.last_fired_at),
-		acceptedCount: integer(row.accepted_count),
-		rejectedCount: integer(row.rejected_count),
+		lastFiredAt: optionalInteger(row.last_fired_at, 'last_fired_at'),
+		acceptedCount: integer(row.accepted_count, 'accepted_count'),
+		rejectedCount: integer(row.rejected_count, 'rejected_count'),
 		configuredBy: configuredBy(row.configured_by_json, row.created_by),
 		permissionSnapshot: permissionSnapshot(row.permission_snapshot_json),
 	};
@@ -221,7 +215,7 @@ function audit(row: AuditRow): AutomationAuditEvent {
 	return {
 		id: row.id,
 		tenantId: row.tenant_id,
-		sequence: integer(row.sequence),
+		sequence: integer(row.sequence, 'sequence'),
 		actorId: row.actor_id,
 		action: row.action,
 		subjectType: row.subject_type,
@@ -229,7 +223,7 @@ function audit(row: AuditRow): AutomationAuditEvent {
 		metadata: JSON.parse(row.metadata_json) as Readonly<
 			Record<string, string | number | boolean>
 		>,
-		occurredAt: integer(row.occurred_at),
+		occurredAt: integer(row.occurred_at, 'occurred_at'),
 		previousHash: row.previous_hash,
 		eventHash: row.event_hash,
 	};
@@ -257,6 +251,76 @@ function markers(count: number): string {
 	);
 }
 
+/* The three characters LIKE reads as syntax are escaped with the backslash
+   PostgreSQL takes as the default escape character, so a `%` a reader types
+   searches for a percent sign. */
+function likePattern(term: string): string {
+	return '%' + term.replace(/[\\%_]/g, (character) => '\\' + character) + '%';
+}
+
+const LIST_SORT_COLUMNS = {
+	label: 'label_key',
+	updatedAt: 'updated_at',
+} as const;
+
+interface ListSortRow {
+	label_key: string;
+	updated_at: number | bigint | string;
+	id: string;
+}
+
+/* `label_key` is lower(label) aliased in a subselect, because a keyset column
+   must be a plain identifier. The planner pulls the subselect up, so the
+   expression index on (tenant_id, lower(label), id) still serves the order. */
+function listPageStatement(
+	table: 'automations_schedules' | 'automations_triggers',
+	tenantId: string,
+	query: AutomationListQuery,
+): { readonly text: string; readonly parameters: unknown[] } {
+	const column = LIST_SORT_COLUMNS[query.sort];
+	const parameters: unknown[] = [
+		tenantId,
+		query.enabled === undefined ? null : query.enabled ? 1 : 0,
+		query.search === undefined ? null : likePattern(query.search),
+	];
+	let keyset = '';
+	if (query.after) {
+		const predicate = keysetWhere(
+			[column, 'id'],
+			[query.after.value, query.after.id],
+			{ direction: query.direction, parameterOffset: parameters.length },
+		);
+		keyset = ` AND ${predicate.text}`;
+		parameters.push(...predicate.parameters);
+	}
+	parameters.push(query.limit);
+	const order = query.direction === 'desc' ? 'DESC' : 'ASC';
+	return {
+		text: `SELECT * FROM (SELECT s.*, lower(s.label) AS label_key FROM ${table} s) s
+		 WHERE tenant_id = $1
+		   AND ($2::integer IS NULL OR enabled = $2)
+		   AND ($3::text IS NULL OR label ILIKE $3 OR target_key ILIKE $3)${keyset}
+		 ORDER BY ${column} ${order}, id ${order}
+		 LIMIT $${parameters.length}`,
+		parameters,
+	};
+}
+
+function listCursor(
+	rows: readonly ListSortRow[],
+	query: AutomationListQuery,
+): AutomationListCursor | null {
+	const last = rows.at(-1);
+	if (!last || rows.length < query.limit) return null;
+	return {
+		value:
+			query.sort === 'label'
+				? last.label_key
+				: integer(last.updated_at, 'updated_at'),
+		id: last.id,
+	};
+}
+
 const SQL = {
 	listSchedules: `SELECT * FROM automations_schedules WHERE tenant_id = $1
 	 ORDER BY lower(label), id`,
@@ -283,11 +347,13 @@ const SQL = {
 	 updated_at = $5
 	 WHERE tenant_id = $6 AND id = $7 AND enabled = 1
 	   AND next_run_at = $8`,
+	retimeSchedule: `UPDATE automations_schedules SET next_run_at = $1,
+	 updated_at = $2
+	 WHERE tenant_id = $3 AND id = $4 AND enabled = 1
+	   AND next_run_at = $5`,
 	disableSchedule: `UPDATE automations_schedules SET enabled = 0,
 	 disabled_reason = $1, updated_at = $2
 	 WHERE tenant_id = $3 AND id = $4 AND enabled = 1`,
-	listTriggers: `SELECT * FROM automations_triggers WHERE tenant_id = $1
-	 ORDER BY lower(label), id`,
 	getTrigger: `SELECT * FROM automations_triggers
 	 WHERE tenant_id = $1 AND id = $2`,
 	/* Read through the cross-tenant background lease. It routes a webhook to a
@@ -320,6 +386,9 @@ const SQL = {
 	 ORDER BY sequence DESC LIMIT $2`,
 	auditChain: `SELECT * FROM automations_audit_events WHERE tenant_id = $1
 	 ORDER BY sequence ASC`,
+	exportAudit: `SELECT * FROM automations_audit_events
+	 WHERE tenant_id = $1 AND id > $2
+	 ORDER BY id LIMIT $3`,
 } as const;
 
 export async function migrateAutomationsDatabase(
@@ -353,6 +422,17 @@ export class DatabaseAutomationsRepository implements AutomationsRepository {
 		return result.map(schedule);
 	}
 
+	async listSchedulesPage(
+		tenantId: string,
+		query: AutomationListQuery,
+	): Promise<AutomationListPage<StoredAutomationSchedule>> {
+		const rows = await this.#read<ScheduleRow & ListSortRow>(
+			tenantId,
+			listPageStatement('automations_schedules', tenantId, query),
+		);
+		return { items: rows.map(schedule), next: listCursor(rows, query) };
+	}
+
 	async getSchedule(
 		tenantId: string,
 		scheduleId: string,
@@ -443,7 +523,7 @@ export class DatabaseAutomationsRepository implements AutomationsRepository {
 		return result.rows.map((row) => ({
 			tenantId: row.tenant_id,
 			id: row.id,
-			nextRunAt: integer(row.next_run_at),
+			nextRunAt: integer(row.next_run_at, 'next_run_at'),
 		}));
 	}
 
@@ -472,6 +552,26 @@ export class DatabaseAutomationsRepository implements AutomationsRepository {
 		return affected === 1;
 	}
 
+	async retimeSchedule(input: {
+		readonly tenantId: string;
+		readonly scheduleId: string;
+		readonly expectedNextRunAt: number;
+		readonly nextRunAt: number;
+		readonly updatedAt: number;
+	}): Promise<boolean> {
+		const affected = await this.#write(input.tenantId, {
+			text: SQL.retimeSchedule,
+			parameters: [
+				input.nextRunAt,
+				input.updatedAt,
+				input.tenantId,
+				input.scheduleId,
+				input.expectedNextRunAt,
+			],
+		});
+		return affected === 1;
+	}
+
 	async disableSchedule(
 		tenantId: string,
 		scheduleId: string,
@@ -485,14 +585,15 @@ export class DatabaseAutomationsRepository implements AutomationsRepository {
 		return affected === 1;
 	}
 
-	async listTriggers(
+	async listTriggersPage(
 		tenantId: string,
-	): Promise<readonly StoredAutomationTrigger[]> {
-		const rows = await this.#read<TriggerRow>(tenantId, {
-			text: SQL.listTriggers,
-			parameters: [tenantId],
-		});
-		return rows.map(trigger);
+		query: AutomationListQuery,
+	): Promise<AutomationListPage<StoredAutomationTrigger>> {
+		const rows = await this.#read<TriggerRow & ListSortRow>(
+			tenantId,
+			listPageStatement('automations_triggers', tenantId, query),
+		);
+		return { items: rows.map(trigger), next: listCursor(rows, query) };
 	}
 
 	async getTrigger(
@@ -643,7 +744,8 @@ export class DatabaseAutomationsRepository implements AutomationsRepository {
 					parameters: [event.tenantId],
 				});
 				const previous = latest.rows[0];
-				const sequence = (previous ? integer(previous.sequence) : 0) + 1;
+				const sequence =
+					(previous ? integer(previous.sequence, 'sequence') : 0) + 1;
 				const previousHash = previous?.event_hash ?? null;
 				const metadataJson = stableMetadata(event.metadata);
 				const created: AutomationAuditEvent = {
@@ -696,6 +798,18 @@ export class DatabaseAutomationsRepository implements AutomationsRepository {
 		return rows.map(audit);
 	}
 
+	async exportAuditEventsPage(
+		tenantId: string,
+		afterId: string,
+		limit: number,
+	): Promise<readonly AutomationAuditEvent[]> {
+		const rows = await this.#read<AuditRow>(tenantId, {
+			text: SQL.exportAudit,
+			parameters: [tenantId, afterId, limit],
+		});
+		return rows.map(audit);
+	}
+
 	async verifyAuditChain(
 		tenantId: string,
 	): Promise<AutomationAuditVerification> {

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

@@ -1,4 +1,4 @@
-import type { DatabaseMigration } from '@flowdular/sdk/database';
+import type { DatabaseMigration, DatabaseSession } from '@flowdular/sdk/database';
 import {
 	migrationObjectState,
 	postgresTenantTableState,
@@ -166,6 +166,58 @@ REVOKE SELECT ON automations_triggers FROM coreloom_background;
 GRANT SELECT (tenant_id, id) ON automations_triggers TO coreloom_background;
 `;
 
+export const AUTOMATIONS_MIGRATION_005_SECRET_ROTATION_INVENTORY = `-- The rotation command has to find the triggers still sealed with a retired key
+-- before it knows whose they are. The cross-tenant lookup already reads the two
+-- routing columns; this adds the key id and nothing else. The nonce, the tag and
+-- the ciphertext stay unreadable on this connection, and every row it re-seals
+-- is read again under the tenant that row named.
+GRANT SELECT (secret_key_id) ON automations_triggers TO coreloom_background;
+`;
+
+/* Mirrors migrations/0006_automations_list_sort_indexes.up.sql byte for byte. */
+export const AUTOMATIONS_MIGRATION_006_LIST_SORT_INDEXES = `-- The schedule and trigger lists page by keyset over the same order they show,
+-- lower(label) then id, or updated_at then id, so each order gets an index
+-- that starts with the tenant and ends with the id the keyset breaks ties on.
+CREATE INDEX IF NOT EXISTS automations_schedules_tenant_label_key_idx
+  ON automations_schedules (tenant_id, lower(label), id);
+CREATE INDEX IF NOT EXISTS automations_schedules_tenant_updated_idx
+  ON automations_schedules (tenant_id, updated_at, id);
+CREATE INDEX IF NOT EXISTS automations_triggers_tenant_label_key_idx
+  ON automations_triggers (tenant_id, lower(label), id);
+CREATE INDEX IF NOT EXISTS automations_triggers_tenant_updated_idx
+  ON automations_triggers (tenant_id, updated_at, id);
+`;
+
+/* Narrowed to this schema's relation through to_regclass and never deparsed:
+   a deparse over the whole catalogue reaches relations another connection is
+   dropping and fails with a cache lookup error instead of an answer. */
+async function backgroundPolicyPresent(
+	database: DatabaseSession,
+	table: string,
+	policy: string,
+): Promise<boolean> {
+	const result = await database.query<{ present: boolean }>({
+		text: `SELECT EXISTS (
+		         SELECT 1 FROM pg_policy
+		         WHERE polrelid = to_regclass('${table}') AND polname = '${policy}'
+		       ) AS present`,
+	});
+	return result.rows[0]?.present === true;
+}
+
+async function backgroundColumnGranted(
+	database: DatabaseSession,
+	table: string,
+	column: string,
+): Promise<boolean> {
+	const result = await database.query<{ granted: boolean }>({
+		text: `SELECT CASE WHEN to_regclass('${table}') IS NOT NULL THEN
+		  has_column_privilege('coreloom_background', '${table}', '${column}', 'SELECT')
+		ELSE false END AS granted`,
+	});
+	return result.rows[0]?.granted === true;
+}
+
 export const databaseMigrations: readonly DatabaseMigration[] = [
 	{
 		id: '0001_automations_core',
@@ -207,17 +259,75 @@ export const databaseMigrations: readonly DatabaseMigration[] = [
 	{
 		id: '0003_automations_scheduler_role',
 		sql: { postgresql: AUTOMATIONS_MIGRATION_003_SCHEDULER_ROLE },
-		inspectExisting: async (database) =>
-			(await database.schema.hasIndex('automations_schedules_routing_idx'))
-				? 'complete'
-				: 'absent',
+		/* The index is one of three objects; the background policy and the
+		   column grant leave nothing the schema reader sees, so each is proved
+		   against the catalogue and a schema carrying only some is partial. */
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasIndex('automations_schedules_routing_idx'),
+				() =>
+					backgroundPolicyPresent(
+						database,
+						'automations_schedules',
+						'automations_schedules_background_policy',
+					),
+				() =>
+					backgroundColumnGranted(
+						database,
+						'automations_schedules',
+						'next_run_at',
+					),
+			]),
 	},
 	{
 		id: '0004_automations_trigger_routing_role',
 		sql: { postgresql: AUTOMATIONS_MIGRATION_004_TRIGGER_ROUTING_ROLE },
-		inspectExisting: async (database) =>
-			(await database.schema.hasIndex('automations_triggers_routing_idx'))
-				? 'complete'
-				: 'absent',
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasIndex('automations_triggers_routing_idx'),
+				() =>
+					backgroundPolicyPresent(
+						database,
+						'automations_triggers',
+						'automations_triggers_background_policy',
+					),
+				() =>
+					backgroundColumnGranted(
+						database,
+						'automations_triggers',
+						'tenant_id',
+					),
+			]),
+	},
+	{
+		id: '0005_secret_rotation_inventory',
+		sql: { postgresql: AUTOMATIONS_MIGRATION_005_SECRET_ROTATION_INVENTORY },
+		/* A grant leaves no object behind, so the column privilege itself is what
+		   proves this migration ran. */
+		inspectExisting: async (database) => {
+			const result = await database.query<{ granted: boolean }>({
+				text: `SELECT CASE WHEN to_regclass('automations_triggers') IS NOT NULL THEN
+				  has_column_privilege('coreloom_background', 'automations_triggers', 'secret_key_id', 'SELECT')
+				ELSE false END AS granted`,
+			});
+			return result.rows[0]?.granted === true ? 'complete' : 'absent';
+		},
+	},
+	{
+		id: '0006_automations_list_sort_indexes',
+		sql: { postgresql: AUTOMATIONS_MIGRATION_006_LIST_SORT_INDEXES },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() =>
+					database.schema.hasIndex(
+						'automations_schedules_tenant_label_key_idx',
+					),
+				() =>
+					database.schema.hasIndex('automations_schedules_tenant_updated_idx'),
+				() =>
+					database.schema.hasIndex('automations_triggers_tenant_label_key_idx'),
+				() =>
+					database.schema.hasIndex('automations_triggers_tenant_updated_idx'),
+			]),
 	},
 ];

package/modules/automations/src/services/repository.ts

@@ -46,8 +46,42 @@ export interface AutomationScheduleRouting {
 	readonly nextRunAt: number;
 }
 
+export type AutomationListSortKey = 'label' | 'updatedAt';
+
+export const AUTOMATION_LIST_SORT_KEYS: readonly AutomationListSortKey[] = [
+	'label',
+	'updatedAt',
+];
+
+/** The keyset of the last row of a page: the sort value, then the id. */
+export interface AutomationListCursor {
+	readonly value: string | number;
+	readonly id: string;
+}
+
+export interface AutomationListQuery {
+	readonly sort: AutomationListSortKey;
+	readonly direction: 'asc' | 'desc';
+	readonly enabled?: boolean | undefined;
+	/** Substring of the label or the target key. */
+	readonly search?: string | undefined;
+	readonly limit: number;
+	readonly after?: AutomationListCursor | null | undefined;
+}
+
+export interface AutomationListPage<Item> {
+	readonly items: readonly Item[];
+	/** The keyset to continue from; null once the page was short. */
+	readonly next: AutomationListCursor | null;
+}
+
 export interface AutomationsRepository {
+	/** Every schedule of one workspace; only `retime` walks a whole workspace. */
 	listSchedules(tenantId: string): Promise<readonly StoredAutomationSchedule[]>;
+	listSchedulesPage(
+		tenantId: string,
+		query: AutomationListQuery,
+	): Promise<AutomationListPage<StoredAutomationSchedule>>;
 	getSchedule(
 		tenantId: string,
 		scheduleId: string,
@@ -72,13 +106,24 @@ export interface AutomationsRepository {
 		readonly lastRunId: string | null;
 		readonly lastError: string | null;
 	}): Promise<boolean>;
+	/** Moves a pending slot only while it still holds the value that was read. */
+	retimeSchedule(input: {
+		readonly tenantId: string;
+		readonly scheduleId: string;
+		readonly expectedNextRunAt: number;
+		readonly nextRunAt: number;
+		readonly updatedAt: number;
+	}): Promise<boolean>;
 	disableSchedule(
 		tenantId: string,
 		scheduleId: string,
 		reason: string,
 		now: number,
 	): Promise<boolean>;
-	listTriggers(tenantId: string): Promise<readonly StoredAutomationTrigger[]>;
+	listTriggersPage(
+		tenantId: string,
+		query: AutomationListQuery,
+	): Promise<AutomationListPage<StoredAutomationTrigger>>;
 	getTrigger(
 		tenantId: string,
 		triggerId: string,
@@ -116,4 +161,10 @@ export interface AutomationsRepository {
 		limit: number,
 	): Promise<readonly AutomationAuditEvent[]>;
 	verifyAuditChain(tenantId: string): Promise<AutomationAuditVerification>;
+	/** One keyset page of the trail, ordered by id, for the data class export. */
+	exportAuditEventsPage(
+		tenantId: string,
+		afterId: string,
+		limit: number,
+	): Promise<readonly AutomationAuditEvent[]>;
 }