@flowdular/sdk 0.2.4 → 0.3.0

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

@@ -4,8 +4,10 @@ import type {
 } from '@flowdular/sdk/harness';
 import type {
 	AgentAuditEvent,
-	AgentAuditPage,
+	AgentAuditListQuery,
 	AgentDefinition,
+	AgentListPage,
+	AgentListQuery,
 	AgentDefinitionRevision,
 	ModuleAgentBinding,
 	ModuleAgentDefinition,
@@ -13,6 +15,7 @@ import type {
 	AgentRun,
 	AgentRunDetail,
 	AgentRunExecution,
+	AgentRunListQuery,
 	AgentProcedure,
 	AgentUsageAgent,
 	AgentUsageBucket,
@@ -69,11 +72,32 @@ export interface CompletedRunCost {
 	readonly costMicroUsd: number | null;
 }
 
+/** Where a run export page resumes: newest queue time first, then run id. */
+export interface AgentRunExportCursor {
+	readonly queuedAt: number;
+	readonly id: string;
+}
+
+/** One run and its steps, as the workspace export presents them. */
+export interface ExportedAgentRun {
+	readonly run: AgentRun;
+	readonly events: readonly AgentExecutionEvent[];
+}
+
 export type PendingAgentAuditEvent = Omit<
 	AgentAuditEvent,
 	'id' | 'sequence' | 'previousHash' | 'eventHash'
 >;
 
+/**
+ * What a caller that may be abandoned hands down to the statement. A read on a
+ * request path passes the signal the caller is bounded by, so the statement is
+ * cancelled with the work nobody is waiting for any more.
+ */
+export interface AgentReadOptions {
+	readonly signal?: AbortSignal | undefined;
+}
+
 export interface AgentRepository {
 	close(): Promise<void>;
 	reconcileModuleAgents(
@@ -93,7 +117,13 @@ export interface AgentRepository {
 		expectedRevision: number,
 		audit: PendingAgentAuditEvent,
 	): Promise<ModuleAgentBinding>;
+	/* Every definition of the tenant, for the run queue capability and revision
+	   adoption, which need the whole catalog. Screens read `listAgentsPage`. */
 	listAgents(tenantId: string): Promise<readonly AgentDefinition[]>;
+	listAgentsPage(
+		tenantId: string,
+		query: AgentListQuery,
+	): Promise<AgentListPage>;
 	getAgent(tenantId: string, agentId: string): Promise<AgentDefinition | null>;
 	getAgentRevision(
 		tenantId: string,
@@ -133,7 +163,10 @@ export interface AgentRepository {
 		readonly assignments: number;
 		readonly activeDefinitions: number;
 	}>;
-	listRuns(tenantId: string, limit: number): Promise<readonly AgentRun[]>;
+	listRuns(
+		tenantId: string,
+		query: AgentRunListQuery,
+	): Promise<readonly AgentRun[]>;
 	getRun(tenantId: string, runId: string): Promise<AgentRunDetail | null>;
 	listRunEvents(
 		tenantId: string,
@@ -240,6 +273,13 @@ export interface AgentRepository {
 		workerId: string,
 		leaseExpiresAt: number,
 	): Promise<boolean>;
+	/* Hands a claim back to the queue, clearing the lease, for work this worker
+	   took but will not perform. Answers whether the row was still its own. */
+	releaseAction(
+		tenantId: string,
+		invocationId: string,
+		workerId: string,
+	): Promise<boolean>;
 	completeAction(
 		tenantId: string,
 		invocationId: string,
@@ -262,23 +302,63 @@ export interface AgentRepository {
 		completedAt: number,
 		audit: PendingAgentAuditEvent,
 	): Promise<AgentActionInvocation['status'] | null>;
+	/* Keyset page of the run export, newest queue time first, with the steps of
+	   every run on the page. */
+	exportRunsPage(
+		tenantId: string,
+		after: AgentRunExportCursor | null,
+		limit: number,
+	): Promise<readonly ExportedAgentRun[]>;
+	/* Removes at most `limit` settled runs completed before `before`, taking
+	   their steps and child rows with them. A queued or running run is never
+	   removed, whatever the age of the request behind it. */
+	deleteSettledRunsBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+	/* Removes at most `limit` runs one account requested, in any state. */
+	deleteRunsRequestedBy(
+		tenantId: string,
+		accountId: string,
+		limit: number,
+	): Promise<number>;
+	/**
+	 * Takes the standing refusal of one workspace, meter and month, and answers
+	 * whether this call is the one that took it. A refusal stands until the
+	 * month turns or the limit is raised, so only the call that takes it writes
+	 * the audit event and a retry loop adds no second row. The claim removes the
+	 * rows of earlier months, so a workspace holds one row per meter.
+	 */
+	claimMeterRefusal(
+		tenantId: string,
+		meter: string,
+		period: string,
+		at: number,
+	): Promise<boolean>;
 	appendAuditEvent(event: PendingAgentAuditEvent): Promise<AgentAuditEvent>;
 	listAuditEvents(
 		tenantId: string,
 		limit: number,
 	): Promise<readonly AgentAuditEvent[]>;
-	/* Keyset page over the tenant trail, newest first, cursor `occurredAt:sequence`. */
-	pageAuditEvents(
+	/* Keyset page of the tenant trail in chain order, oldest first. */
+	exportAuditEventsPage(
 		tenantId: string,
-		cursor: { readonly occurredAt: number; readonly sequence: number } | null,
+		afterSequence: number,
 		limit: number,
-	): Promise<AgentAuditPage>;
+	): Promise<readonly AgentAuditEvent[]>;
+	/* Keyset page over the tenant trail, newest first. */
+	pageAuditEvents(
+		tenantId: string,
+		query: AgentAuditListQuery,
+	): Promise<readonly AgentAuditEvent[]>;
 	verifyAuditChain(tenantId: string): Promise<boolean>;
 	verifyAuditChainDetailed(tenantId: string): Promise<AuditChainVerification>;
 	usageByDay(
 		tenantId: string,
 		fromDay: string,
 		toDay: string,
+		options?: AgentReadOptions,
 	): Promise<readonly AgentUsageDay[]>;
 	usageByAgent(
 		tenantId: string,

package/modules/agents/src/services/usage-service.ts

@@ -54,6 +54,7 @@ export class AgentUsageService {
 		const to = usageDay(now);
 		const from = usageDay(now - (window - 1) * DAY_MS);
 		const monthFrom = firstDayOfMonth(now);
+		await this.settings?.prime(tenantId);
 		return {
 			from,
 			to,
@@ -87,6 +88,7 @@ export class AgentUsageService {
 		agentId: string,
 		now = this.now(),
 	): Promise<BudgetRefusal | null> {
+		await this.settings?.prime(tenantId);
 		const caps = this.caps(tenantId);
 		if (caps.monthlyCostMicroUsd === 0 && caps.agentMonthlyCostMicroUsd === 0) {
 			return null;

package/modules/agents/src/services/worker.ts

@@ -1,6 +1,16 @@
 import type { AgentHarness, AgentProvider } from '@flowdular/sdk/harness';
-import type { AgentRunExecution, AgentWorkerStatus } from '../domain/types.ts';
+import type {
+	AgentRun,
+	AgentRunExecution,
+	AgentWorkerStatus,
+} from '../domain/types.ts';
 import type { AgentRepository, RecoverableRun } from './repository.ts';
+import {
+	publishRunOutcome,
+	runNotificationRecipients,
+	type NotificationPublisherResolver,
+} from './notifications.ts';
+import { AGENT_METERS, type MeterRegistryResolver } from './metering.ts';
 import type { AgentProviderBroker } from './provider-broker.ts';
 import type { AgentRunGrantAuthority } from './run-grant.ts';
 
@@ -12,6 +22,13 @@ export interface AgentWorkerOptions {
 	readonly leaseMs: number;
 	readonly runGrantAuthority?: AgentRunGrantAuthority;
 	readonly providerBroker?: AgentProviderBroker;
+	/* Resolved when a run settles. Absent, or resolving to null, means the
+	   optional notifications module is not composed and nothing is published. */
+	readonly notifications?: NotificationPublisherResolver;
+	/* Resolved when a run settles, so the registry is the one the platform holds
+	   then. Absent only in a process that built a worker outside the module
+	   composition, such as a test; a composed deployment always has it. */
+	readonly meters?: MeterRegistryResolver;
 	readonly now?: () => number;
 }
 
@@ -35,10 +52,17 @@ const CANCELLED = 'cancelled';
 const SHUTDOWN = 'worker-shutdown';
 const LEASE_LOST = 'lease-lost';
 
+/* A provider, a driver or the database can put any text on `code`. Only a
+   stable code may reach the failure record, the audit metadata and the
+   notification body a person reads. */
+const STABLE_CODE = /^[A-Z][A-Z0-9_]+$/;
+
 function failure(error: unknown): { code: string; message: string } {
 	if (error instanceof Error) {
 		const code =
-			'code' in error && typeof error.code === 'string'
+			'code' in error &&
+			typeof error.code === 'string' &&
+			STABLE_CODE.test(error.code)
 				? error.code
 				: 'AGENT_EXECUTION_FAILED';
 		return { code, message: error.message.slice(0, 1_000) };
@@ -242,6 +266,10 @@ export class AgentWorker {
 	): Promise<void> {
 		let eventWrites = Promise.resolve();
 		let eventFailure: unknown;
+		/* The abort a refused event write decides on waits for one ownership
+		   probe; the failure path awaits this so the reason is known before the
+		   run is settled, and the release waits for it so nothing outruns it. */
+		let eventClassification = Promise.resolve();
 		const renewal = setInterval(
 			async () => {
 				try {
@@ -312,9 +340,25 @@ export class AgentWorker {
 						event,
 					),
 				);
-				void eventWrites.catch((error) => {
+				eventClassification = eventWrites.catch(async (error) => {
+					/* An event refused on a run this worker no longer holds is the lost
+					   lease, not a persistence fault: an erasure or another worker took
+					   the row, and which failure surfaces first is a matter of timing.
+					   One rejection reaches every later write; classify it once. */
+					if (eventFailure !== undefined) return;
 					eventFailure = error;
-					controller.abort('event-persistence-failed');
+					let owned = false;
+					try {
+						owned = await this.repository.renewLease(
+							candidate.tenantId,
+							candidate.runId,
+							this.options.workerId,
+							this.#now() + this.options.leaseMs,
+						);
+					} catch {
+						owned = false;
+					}
+					controller.abort(owned ? 'event-persistence-failed' : LEASE_LOST);
 				});
 			};
 			const result = await this.harness.execute(
@@ -356,13 +400,19 @@ export class AgentWorker {
 					occurredAt: result.completedAt,
 				},
 			);
+			await this.#reportMeters(execution.run, result.usage.totalTokens);
 			await this.#recordRunSuccess(
 				execution,
 				result.completedAt,
 				result.startedAt,
 			);
+			await this.#publishOutcome(execution.run, 'agent-run-completed', {
+				title: `Agent ${execution.run.agentName} finished`,
+				body: `The run finished in ${result.completedAt - result.startedAt} ms and used ${result.usage.totalTokens} tokens.`,
+			});
 		} catch (error) {
 			await eventWrites.catch(() => undefined);
+			await eventClassification;
 			/* The service already moved a cancelled row and wrote its audit event;
 			   the worker only had to stop. */
 			if (controller.signal.aborted && controller.signal.reason === CANCELLED) {
@@ -412,10 +462,70 @@ export class AgentWorker {
 					`[agents] run ${candidate.runId} failed with ${failed.code} and could not be settled:`,
 					settleError instanceof Error ? settleError.message : settleError,
 				);
+				return;
 			}
+			await this.#reportMeters(execution.run, 0);
+			await this.#publishOutcome(execution.run, 'agent-run-failed', {
+				title: `Agent ${execution.run.agentName} failed`,
+				body: `The run stopped with ${failed.code}.`,
+			});
 		} finally {
 			clearInterval(renewal);
 			await eventWrites.catch(() => undefined);
+			await eventClassification;
+		}
+	}
+
+	/* Called after the terminal row is committed and outside its transaction.
+	   The run id is the source reference, so a terminal step that runs twice
+	   reports the same outcome instead of adding a second notification. A run a
+	   workflow owns stays silent: workflows.core reports the outcome the person
+	   actually asked for, once, instead of one notification per agent step. */
+	async #publishOutcome(
+		run: AgentRun,
+		kind: 'agent-run-completed' | 'agent-run-failed',
+		copy: { readonly title: string; readonly body: string },
+	): Promise<void> {
+		if (run.workflowRunId !== null) return;
+		await publishRunOutcome(this.options.notifications, {
+			tenantId: run.tenantId,
+			kind,
+			sourceModule: 'agents.core',
+			sourceRef: run.id,
+			title: copy.title,
+			body: copy.body,
+			recipients: runNotificationRecipients(run.authorizationSubject),
+		});
+	}
+
+	/* Called after the terminal row is committed and outside its transaction.
+	   The run id is the source reference, so a terminal step that runs twice
+	   counts the run once. Counting is advisory: metering.core commits the fact
+	   in its own transaction and a failure there never changes a settled run. A
+	   run that reported no tokens counts none rather than claiming zero. */
+	async #reportMeters(run: AgentRun, totalTokens: number): Promise<void> {
+		const meters = this.options.meters?.();
+		if (!meters) return;
+		try {
+			await meters.record({
+				tenantId: run.tenantId,
+				meter: AGENT_METERS.runs,
+				amount: 1,
+				sourceRef: run.id,
+			});
+			if (totalTokens > 0) {
+				await meters.record({
+					tenantId: run.tenantId,
+					meter: AGENT_METERS.runTokens,
+					amount: totalTokens,
+					sourceRef: run.id,
+				});
+			}
+		} catch (error) {
+			console.warn(
+				`[agents] metering for run ${run.id} failed:`,
+				error instanceof Error ? error.message : error,
+			);
 		}
 	}
 

package/modules/agents/src/settings.ts

@@ -1,5 +1,6 @@
 import {
 	defineModuleSettings,
+	ModuleSettingsError,
 	PLATFORM_SETTINGS_TENANT,
 	type ModuleSettingsDeclaration,
 	type ModuleSettingsRuntime,
@@ -166,6 +167,8 @@ export function agentsModuleSettingsFromEnvironment(
 }
 
 export interface AgentSettingsReader {
+	/** Loads a workspace's settings; a tenant-scoped read needs it first. */
+	prime(tenantId: string): Promise<void>;
 	workerConcurrency(): number;
 	workerLeaseMs(): number;
 	providerReadinessTtlMs(): number;
@@ -185,8 +188,9 @@ function settingsSource(value: unknown): ModuleSettingsRuntime | null {
 		: null;
 }
 
-/* Reads are live and per call. Without a settings runtime, or when a read
-   fails, the environment decides exactly as before. */
+/* Reads are live and per call. Without a settings runtime, or when the
+   module's settings are not declared, the environment decides exactly as
+   before; a workspace nobody primed stays a loud caller defect. */
 export function agentSettings(context: {
 	readonly environment: NodeJS.ProcessEnv;
 	readonly settings?: unknown;
@@ -204,11 +208,18 @@ export function agentSettings(context: {
 			return typeof value === typeof fallbackValue
 				? (value as T)
 				: fallbackValue;
-		} catch {
+		} catch (error) {
+			if (
+				error instanceof ModuleSettingsError &&
+				error.code === 'SETTINGS_NOT_PRIMED'
+			) {
+				throw error;
+			}
 			return fallbackValue;
 		}
 	};
 	return {
+		prime: (tenantId) => source?.prime(tenantId) ?? Promise.resolve(),
 		workerConcurrency: () =>
 			read(
 				PLATFORM_SETTINGS_TENANT,

package/modules/agents/translations/en.json

@@ -8,6 +8,10 @@
 	"common.actions": "Agent actions",
 	"common.requestFailed": "The agent operation failed.",
 	"common.view": "View",
+	"common.page.label": "List pages",
+	"common.page.previous": "Previous",
+	"common.page.next": "Next",
+	"common.page.summary": "Page {page} · from {from}",
 	"navigation.agents": "Agents",
 	"navigation.agentsDescription": "Reusable worker definitions",
 	"navigation.providers": "Providers",
@@ -132,7 +136,7 @@
 	"definitions.lifecycle.delete.confirm": "Delete agent",
 	"definitions.lifecycle.delete.description": "Permanently delete {name}. Agents with run history cannot be deleted.",
 	"definitions.table.title": "Custom agents",
-	"definitions.table.count": "{active} active · {total} defined",
+	"definitions.table.count": "{count} on this page",
 	"definitions.table.caption": "Agent definitions",
 	"definitions.loading": "Loading custom agents…",
 	"definitions.search.placeholder": "Filter by name, key, or description",
@@ -148,6 +152,7 @@
 	"definitions.column.agent": "Agent",
 	"definitions.column.purpose": "Purpose",
 	"definitions.column.model": "Model",
+	"definitions.column.updated": "Updated",
 	"definitions.column.status": "Status",
 	"definitions.form.name": "Name",
 	"definitions.form.key": "Stable key",
@@ -284,9 +289,9 @@
 	"runs.error.cancel": "Could not cancel the run.",
 	"runs.error.load": "Could not load agent runs.",
 	"runs.table.title": "Execution history",
-	"runs.table.count": "{count} recent runs",
+	"runs.table.count": "{count} on this page",
 	"runs.table.caption": "Agent runs",
-	"runs.search.placeholder": "Search agent, input, or run id",
+	"runs.search.placeholder": "Search by agent name or run id",
 	"runs.search.label": "Search agent runs",
 	"runs.filter.status": "Status",
 	"runs.filter.allStatuses": "All statuses",
@@ -399,5 +404,10 @@
 	"settings.monthlyCostCapUsd.label": "Monthly agent budget (USD)",
 	"settings.monthlyCostCapUsd.description": "Enqueue is refused once the calendar month costs this much. Zero means no cap. A run already executing is never stopped.",
 	"settings.agentMonthlyCostCapUsd.label": "Monthly budget per agent (USD)",
-	"settings.agentMonthlyCostCapUsd.description": "Applied to every agent on its own, in addition to the workspace budget. Zero means no cap."
+	"settings.agentMonthlyCostCapUsd.description": "Applied to every agent on its own, in addition to the workspace budget. Zero means no cap.",
+	"report.runs.label": "Agent runs",
+	"report.runs.tile.runs": "Runs",
+	"report.runs.tile.tokens": "Tokens",
+	"report.runs.series.runsPerDay": "Runs per day",
+	"report.runs.series.tokensPerDay": "Tokens per day"
 }

package/modules/agents/translations/pl.json

@@ -8,6 +8,10 @@
 	"common.actions": "Akcje agenta",
 	"common.requestFailed": "Operacja agenta nie powiodła się.",
 	"common.view": "Zobacz",
+	"common.page.label": "Strony listy",
+	"common.page.previous": "Poprzednia",
+	"common.page.next": "Następna",
+	"common.page.summary": "Strona {page} · od {from}",
 	"navigation.agents": "Agenci",
 	"navigation.agentsDescription": "Definicje agentów wielokrotnego użytku",
 	"navigation.providers": "Dostawcy modeli",
@@ -132,7 +136,7 @@
 	"definitions.lifecycle.delete.confirm": "Usuń agenta",
 	"definitions.lifecycle.delete.description": "Trwale usuń agenta {name}. Agenta z historią uruchomień nie można usunąć.",
 	"definitions.table.title": "Agenci własni",
-	"definitions.table.count": "aktywni: {active} · zdefiniowani: {total}",
+	"definitions.table.count": "Na tej stronie: {count}",
 	"definitions.table.caption": "Definicje agentów",
 	"definitions.loading": "Wczytywanie agentów własnych…",
 	"definitions.search.placeholder": "Szukaj po nazwie, kluczu lub opisie",
@@ -148,6 +152,7 @@
 	"definitions.column.agent": "Agent",
 	"definitions.column.purpose": "Zadanie",
 	"definitions.column.model": "Model",
+	"definitions.column.updated": "Zaktualizowano",
 	"definitions.column.status": "Status",
 	"definitions.form.name": "Nazwa",
 	"definitions.form.key": "Stały klucz",
@@ -284,9 +289,9 @@
 	"runs.error.cancel": "Nie udało się anulować uruchomienia.",
 	"runs.error.load": "Nie udało się wczytać uruchomień agentów.",
 	"runs.table.title": "Historia wykonań",
-	"runs.table.count": "Ostatnie uruchomienia: {count}",
+	"runs.table.count": "Na tej stronie: {count}",
 	"runs.table.caption": "Uruchomienia agentów",
-	"runs.search.placeholder": "Szukaj agenta, danych wejściowych lub identyfikatora",
+	"runs.search.placeholder": "Szukaj po nazwie agenta lub identyfikatorze uruchomienia",
 	"runs.search.label": "Szukaj uruchomień agentów",
 	"runs.filter.status": "Status",
 	"runs.filter.allStatuses": "Wszystkie statusy",
@@ -399,5 +404,10 @@
 	"settings.monthlyCostCapUsd.label": "Miesięczny budżet agentów (USD)",
 	"settings.monthlyCostCapUsd.description": "Po osiągnięciu tej kwoty w miesiącu nowe uruchomienia są odrzucane. Zero wyłącza limit. Trwające uruchomienie nie jest przerywane.",
 	"settings.agentMonthlyCostCapUsd.label": "Miesięczny budżet jednego agenta (USD)",
-	"settings.agentMonthlyCostCapUsd.description": "Obowiązuje osobno dla każdego agenta, niezależnie od budżetu przestrzeni roboczej. Zero wyłącza limit."
+	"settings.agentMonthlyCostCapUsd.description": "Obowiązuje osobno dla każdego agenta, niezależnie od budżetu przestrzeni roboczej. Zero wyłącza limit.",
+	"report.runs.label": "Uruchomienia agentów",
+	"report.runs.tile.runs": "Uruchomienia",
+	"report.runs.tile.tokens": "Tokeny",
+	"report.runs.series.runsPerDay": "Uruchomienia dziennie",
+	"report.runs.series.tokensPerDay": "Tokeny dziennie"
 }

package/modules/approvals/migrations/0001_approvals_core.down.sql

@@ -0,0 +1,3 @@
+DROP TABLE IF EXISTS approvals_decisions;
+DROP TABLE IF EXISTS approvals_eligible;
+DROP TABLE IF EXISTS approvals_requests;

package/modules/approvals/migrations/0001_approvals_core.up.sql

@@ -0,0 +1,78 @@
+CREATE TABLE IF NOT EXISTS approvals_requests (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  subject_module TEXT NOT NULL,
+  subject_ref TEXT NOT NULL,
+  permission TEXT NOT NULL,
+  action TEXT NOT NULL,
+  title TEXT NOT NULL,
+  summary TEXT,
+  requester_account_id TEXT NOT NULL,
+  requirement_json TEXT NOT NULL,
+  decisions_needed BIGINT NOT NULL CHECK (decisions_needed >= 1),
+  status TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'rejected', 'expired', 'cancelled')),
+  expires_at BIGINT NOT NULL,
+  resolved_at BIGINT,
+  created_at BIGINT NOT NULL
+);
+-- A subject module that reopens after a crash has to find the request it
+-- already opened instead of asking the same question twice. One pending
+-- request per subject reference is what makes opening idempotent.
+CREATE UNIQUE INDEX IF NOT EXISTS approvals_requests_pending_subject_idx
+  ON approvals_requests (tenant_id, subject_module, subject_ref)
+  WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS approvals_requests_tenant_status_idx
+  ON approvals_requests (tenant_id, status, created_at DESC, id);
+CREATE INDEX IF NOT EXISTS approvals_requests_requester_idx
+  ON approvals_requests (tenant_id, requester_account_id, created_at DESC, id);
+-- The cross-tenant expiry poll reads in this order and stops at the first
+-- request that is not due yet.
+CREATE INDEX IF NOT EXISTS approvals_requests_routing_idx
+  ON approvals_requests (status, expires_at, tenant_id, id);
+ALTER TABLE approvals_requests ENABLE ROW LEVEL SECURITY;
+ALTER TABLE approvals_requests FORCE ROW LEVEL SECURITY;
+CREATE POLICY approvals_requests_tenant_policy ON approvals_requests
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+-- The eligibility snapshot taken when the request opened. It decides whose
+-- inbox the request appears in, so it is a row per decider with its own index
+-- rather than a list inside the request: the screen asks "what may I decide"
+-- once per open workspace and that question has to stay one index lookup.
+CREATE TABLE IF NOT EXISTS approvals_eligible (
+  tenant_id TEXT NOT NULL,
+  request_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, request_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS approvals_eligible_account_idx
+  ON approvals_eligible (tenant_id, account_id, request_id);
+ALTER TABLE approvals_eligible ENABLE ROW LEVEL SECURITY;
+ALTER TABLE approvals_eligible FORCE ROW LEVEL SECURITY;
+CREATE POLICY approvals_eligible_tenant_policy ON approvals_eligible
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+CREATE TABLE IF NOT EXISTS approvals_decisions (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  request_id TEXT NOT NULL,
+  decider_account_id TEXT,
+  decision TEXT NOT NULL CHECK (decision IN ('approve', 'reject', 'expire', 'cancel')),
+  comment TEXT,
+  decided_at BIGINT NOT NULL,
+  -- Expiry is the one decision no member makes. Every other row names the
+  -- account answerable for it, and the pair is checked here rather than only
+  -- in the service that writes it.
+  CHECK ((decision = 'expire') = (decider_account_id IS NULL))
+);
+-- One approval or rejection per member per request. The service checks first,
+-- but this index is what actually guarantees the conflict it reports.
+CREATE UNIQUE INDEX IF NOT EXISTS approvals_decisions_decider_idx
+  ON approvals_decisions (tenant_id, request_id, decider_account_id)
+  WHERE decision IN ('approve', 'reject');
+CREATE INDEX IF NOT EXISTS approvals_decisions_request_idx
+  ON approvals_decisions (tenant_id, request_id, decided_at, id);
+ALTER TABLE approvals_decisions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE approvals_decisions FORCE ROW LEVEL SECURITY;
+CREATE POLICY approvals_decisions_tenant_policy ON approvals_decisions
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/approvals/migrations/0002_approvals_expiry_routing_role.down.sql

@@ -0,0 +1,2 @@
+REVOKE SELECT (tenant_id, id, expires_at, status) ON approvals_requests FROM coreloom_background;
+DROP POLICY IF EXISTS approvals_requests_background_policy ON approvals_requests;

package/modules/approvals/migrations/0002_approvals_expiry_routing_role.up.sql

@@ -0,0 +1,19 @@
+-- The expiry loop has to find due pending requests before it knows whose they
+-- are, and the requests table is invisible to the cross-tenant role: it carries
+-- no background policy and the role holds no default table grant. This adds the
+-- four routing columns and nothing else. The subject, the requester, the
+-- requirement, the eligibility snapshot and the title stay unreadable on this
+-- connection, and every request it names is read again under its own tenant
+-- before anything about it is written.
+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 approvals_requests_background_policy ON approvals_requests
+  FOR SELECT TO coreloom_background
+  USING (true);
+REVOKE SELECT ON approvals_requests FROM coreloom_background;
+GRANT SELECT (tenant_id, id, expires_at, status) ON approvals_requests TO coreloom_background;

package/modules/approvals/migrations/0003_approvals_retention_indexes.down.sql

@@ -0,0 +1,6 @@
+-- The three indexes carry no data of their own, so dropping them returns the
+-- schema to what 0002 left and costs only the scans the retention operations
+-- then have to perform.
+DROP INDEX IF EXISTS approvals_decisions_decider_account_idx;
+DROP INDEX IF EXISTS approvals_requests_export_idx;
+DROP INDEX IF EXISTS approvals_requests_resolved_idx;

package/modules/approvals/migrations/0003_approvals_retention_indexes.up.sql

@@ -0,0 +1,14 @@
+-- The retention sweep of approvals.core.requests asks one workspace for its
+-- oldest resolved requests, the export walks every request of a workspace in
+-- id order, and a subject erasure asks it for the decisions one account made.
+-- None of the three is covered by what the module already carries: the status
+-- index orders by creation rather than by resolution, the requester index
+-- answers who asked rather than who decided, and no index carries the export's
+-- own key order. All three are bounded batches, so all three need a range scan
+-- rather than a pass over the workspace's requests.
+CREATE INDEX IF NOT EXISTS approvals_requests_resolved_idx
+  ON approvals_requests (tenant_id, status, resolved_at, id);
+CREATE INDEX IF NOT EXISTS approvals_requests_export_idx
+  ON approvals_requests (tenant_id, id);
+CREATE INDEX IF NOT EXISTS approvals_decisions_decider_account_idx
+  ON approvals_decisions (tenant_id, decider_account_id, id);

package/modules/approvals/migrations/0004_approvals_inbox_keyset_indexes.down.sql

@@ -0,0 +1,5 @@
+-- The three indexes carry no data of their own, so dropping them returns the
+-- schema to what 0003 left and costs only the sort every inbox page then pays.
+DROP INDEX IF EXISTS approvals_requests_created_idx;
+DROP INDEX IF EXISTS approvals_requests_requester_created_idx;
+DROP INDEX IF EXISTS approvals_requests_status_created_idx;

package/modules/approvals/migrations/0004_approvals_inbox_keyset_indexes.up.sql

@@ -0,0 +1,12 @@
+-- The inbox pages by keyset on (created_at, id) in one direction, under a
+-- status filter, a requester filter, or neither. The two indexes 0001 carries
+-- order created_at DESC with id ASC, so a page walked in either direction ends
+-- in a sort, and a workspace-wide page has no index at all. These three carry
+-- both keys ascending: a newest-first page is a backward scan of the same
+-- index, and a page continued from a cursor starts where the cursor names.
+CREATE INDEX IF NOT EXISTS approvals_requests_status_created_idx
+  ON approvals_requests (tenant_id, status, created_at, id);
+CREATE INDEX IF NOT EXISTS approvals_requests_requester_created_idx
+  ON approvals_requests (tenant_id, requester_account_id, created_at, id);
+CREATE INDEX IF NOT EXISTS approvals_requests_created_idx
+  ON approvals_requests (tenant_id, created_at, id);

package/modules/approvals/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Migrations in this directory are append-only after release.