@flowdular/sdk 0.1.0

package/packages/database/src/record-history.ts

@@ -0,0 +1,201 @@
+import { randomUUID } from 'node:crypto';
+import {
+	MAX_HISTORY_PAGE,
+	type Actor,
+	type ActorKind,
+	type HistoryEntry,
+	type HistoryPage,
+	type HistoryQuery,
+	type HistoryWrite,
+	type RecordChanges,
+} from '@flowdular/sdk/kernel';
+import {
+	assertSchemaName,
+	type DatabaseParameter,
+	type DatabaseSession,
+} from './contracts.ts';
+
+interface HistoryRow {
+	readonly id: string;
+	readonly record_id: string;
+	readonly version: number | bigint | string;
+	readonly action: string;
+	readonly actor_kind: ActorKind;
+	readonly actor_id: string;
+	readonly actor_label: string;
+	readonly run_id: string | null;
+	readonly configured_by_json: string | null;
+	readonly changes_json: string;
+	readonly occurred_at: number | bigint | string;
+}
+
+/* The server driver returns BIGINT as a string while the embedded build returns
+   a number, so every integer read crosses the same normalizer instead of
+   trusting whichever one a deployment happens to open. */
+function integer(value: number | bigint | string, field: string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized) || normalized < 0) {
+		throw new Error(`The history table returned an invalid ${field}.`);
+	}
+	return normalized;
+}
+
+function actorFromRow(row: HistoryRow): Actor {
+	if (row.actor_kind === 'user') {
+		return { kind: 'user', id: row.actor_id, label: row.actor_label };
+	}
+	if (row.actor_kind === 'service') {
+		if (row.configured_by_json === null) {
+			throw new Error(
+				`Service history entry "${row.id}" has no configuring user.`,
+			);
+		}
+		const configuredBy = JSON.parse(row.configured_by_json) as Actor;
+		if (configuredBy.kind !== 'user') {
+			throw new Error(
+				`Service history entry "${row.id}" has an invalid configuring user.`,
+			);
+		}
+		return {
+			kind: 'service',
+			id: row.actor_id,
+			label: row.actor_label,
+			configuredBy,
+		};
+	}
+	if (row.run_id === null) {
+		throw new Error(
+			`Agent history entry "${row.id}" has no traceable run identifier.`,
+		);
+	}
+	return {
+		kind: 'agent',
+		id: row.actor_id,
+		label: row.actor_label,
+		runId: row.run_id,
+	};
+}
+
+function placeholders(
+	database: DatabaseSession,
+	count: number,
+	from = 1,
+): string {
+	return Array.from({ length: count }, (_value, index) =>
+		database.capabilities.sql.placeholder(from + index),
+	).join(', ');
+}
+
+/**
+ * Appends one history version. Call it inside the same transaction as the
+ * record write, or the trail can disagree with the record it describes. The
+ * version is read under that transaction and the unique index is the backstop.
+ */
+export async function appendRecordHistory(
+	database: DatabaseSession,
+	table: string,
+	write: HistoryWrite,
+): Promise<number> {
+	assertSchemaName(table);
+	const supportsService = await database.schema.hasColumn(
+		table,
+		'configured_by_json',
+	);
+	if (write.actor.kind === 'service' && !supportsService) {
+		throw new Error(
+			`History table "${table}" must add configured_by_json before it can store service actors.`,
+		);
+	}
+	const previous = await database.query<{
+		version: number | bigint | string | null;
+	}>({
+		text: `SELECT max(version) AS version FROM ${table}
+		       WHERE tenant_id = ${database.capabilities.sql.placeholder(1)}
+		         AND record_id = ${database.capabilities.sql.placeholder(2)}`,
+		parameters: [write.tenantId, write.recordId],
+	});
+	const current = previous.rows[0]?.version ?? null;
+	const version = (current === null ? 0 : integer(current, 'version')) + 1;
+	const values: DatabaseParameter[] = [
+		randomUUID(),
+		write.tenantId,
+		write.recordId,
+		version,
+		write.action,
+		write.actor.kind,
+		write.actor.id,
+		write.actor.label,
+		write.actor.kind === 'agent' ? write.actor.runId : null,
+		JSON.stringify(write.changes),
+		write.occurredAt,
+	];
+	if (supportsService) {
+		values.push(
+			write.actor.kind === 'service'
+				? JSON.stringify(write.actor.configuredBy)
+				: null,
+		);
+	}
+	const columns = supportsService ? ', configured_by_json' : '';
+	await database.execute({
+		text: `INSERT INTO ${table}
+		       (id, tenant_id, record_id, version, action, actor_kind, actor_id,
+		        actor_label, run_id, changes_json, occurred_at${columns})
+		       VALUES (${placeholders(database, values.length)})`,
+		parameters: values,
+	});
+	return version;
+}
+
+/** One keyset page of a record's trail, newest version first. */
+export async function queryRecordHistory(
+	database: DatabaseSession,
+	table: string,
+	query: HistoryQuery,
+): Promise<HistoryPage> {
+	assertSchemaName(table);
+	const configuredBy = (await database.schema.hasColumn(
+		table,
+		'configured_by_json',
+	))
+		? 'configured_by_json'
+		: 'NULL AS configured_by_json';
+	const limit = Math.min(
+		Math.max(1, Math.trunc(query.limit)),
+		MAX_HISTORY_PAGE,
+	);
+	const cursor = Number(query.cursor ?? Number.NaN);
+	const bounded = Number.isSafeInteger(cursor) && cursor > 0 ? cursor : null;
+	const parameters: DatabaseParameter[] =
+		bounded === null
+			? [query.tenantId, query.recordId, limit + 1]
+			: [query.tenantId, query.recordId, bounded, limit + 1];
+	const marker = (position: number) =>
+		database.capabilities.sql.placeholder(position);
+	const versionFilter = bounded === null ? '' : ` AND version < ${marker(3)}`;
+	const result = await database.query<HistoryRow>({
+		text: `SELECT id, record_id, version, action, actor_kind, actor_id,
+		              actor_label, run_id, ${configuredBy}, changes_json, occurred_at
+		       FROM ${table}
+		       WHERE tenant_id = ${marker(1)} AND record_id = ${marker(2)}${versionFilter}
+		       ORDER BY version DESC LIMIT ${marker(parameters.length)}`,
+		parameters,
+	});
+	const page = result.rows.slice(0, limit).map(
+		(row): HistoryEntry => ({
+			id: row.id,
+			recordId: row.record_id,
+			version: integer(row.version, 'version'),
+			action: row.action,
+			actor: actorFromRow(row),
+			changes: JSON.parse(row.changes_json) as RecordChanges,
+			occurredAt: integer(row.occurred_at, 'timestamp'),
+		}),
+	);
+	const last = page[page.length - 1];
+	return {
+		entries: page,
+		nextCursor:
+			result.rows.length > limit && last ? String(last.version) : null,
+	};
+}

package/packages/database/src/registry.ts

@@ -0,0 +1,265 @@
+import {
+	assertDatabaseId,
+	assertDatabaseRequirements,
+	assertNamespace,
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+	type DatabaseAdapter,
+	type DatabaseAdapterId,
+	type DatabaseCapabilityId,
+	type DatabaseDialectId,
+	type DatabaseIsolationLevel,
+	type DatabaseRequirements,
+} from './contracts.ts';
+
+export type DatabaseConfigurationValue = boolean | number | string;
+export type DatabaseSafeConfiguration = Readonly<
+	Record<string, DatabaseConfigurationValue>
+>;
+export type DatabaseSecretConfiguration = Readonly<Record<string, string>>;
+
+export interface DatabaseConfigurationField {
+	readonly key: string;
+	readonly label: string;
+	readonly description: string;
+	readonly kind: 'boolean' | 'integer' | 'select' | 'text';
+	readonly required: boolean;
+	readonly secret: boolean;
+	readonly options?: readonly {
+		readonly label: string;
+		readonly value: string;
+	}[];
+}
+
+export interface DatabaseAdapterCapabilityProfile {
+	readonly features: readonly DatabaseCapabilityId[];
+	readonly isolationLevels: readonly DatabaseIsolationLevel[];
+}
+
+export interface DatabaseAdapterPublicDescriptor {
+	readonly adapterId: DatabaseAdapterId;
+	readonly dialectId: DatabaseDialectId;
+	readonly label: string;
+	readonly description: string;
+	readonly capabilities: DatabaseAdapterCapabilityProfile;
+	readonly configurationSchema: {
+		readonly version: 1;
+		readonly fields: readonly DatabaseConfigurationField[];
+	};
+}
+
+export interface DatabaseAdapterConnectionInput {
+	readonly config: DatabaseSafeConfiguration;
+	readonly secrets: DatabaseSecretConfiguration;
+}
+
+export interface DatabaseAdapterValidationIssue {
+	readonly field: string;
+	readonly code: string;
+	readonly message: string;
+}
+
+export interface DatabaseAdapterProbeResult {
+	readonly status: 'ready' | 'unavailable';
+	readonly latencyMs: number;
+	readonly message?: string;
+}
+
+export interface DatabaseAdapterDescriptor
+	extends DatabaseAdapterPublicDescriptor {
+	validate(
+		input: DatabaseAdapterConnectionInput,
+	): readonly DatabaseAdapterValidationIssue[];
+	probe(
+		input: DatabaseAdapterConnectionInput,
+	): Promise<DatabaseAdapterProbeResult>;
+	provision(
+		input: DatabaseAdapterConnectionInput,
+		authorization: { readonly intent: 'confirmed-first-run' },
+	): Promise<void>;
+	connect(input: DatabaseAdapterConnectionInput): Promise<DatabaseAdapter>;
+}
+
+export interface DatabaseAdapterRegistry {
+	register(descriptor: DatabaseAdapterDescriptor): void;
+	get(adapterId: DatabaseAdapterId): DatabaseAdapterDescriptor | undefined;
+	list(): readonly DatabaseAdapterPublicDescriptor[];
+	seal(): void;
+	readonly sealed: boolean;
+}
+
+export interface ModuleDatabaseRequirements extends DatabaseRequirements {
+	readonly moduleId: string;
+	readonly tenantOwned: boolean;
+}
+
+/** Persistable first-run state. It intentionally cannot contain credentials. */
+export interface DatabaseSelection {
+	readonly version: 1;
+	readonly defaultAdapterId: DatabaseAdapterId;
+	readonly moduleOverrides?: Readonly<Record<string, DatabaseAdapterId>>;
+	readonly configurations?: Readonly<
+		Record<DatabaseAdapterId, DatabaseSafeConfiguration>
+	>;
+}
+
+export interface DatabaseSelectionIssue {
+	readonly moduleId: string | null;
+	readonly code:
+		| 'ADAPTER_NOT_REGISTERED'
+		| 'CAPABILITY_MISMATCH'
+		| 'POSTGRESQL_RLS_REQUIRED';
+	readonly message: string;
+}
+
+function assertField(field: DatabaseConfigurationField): void {
+	if (!/^[a-z][a-z0-9-]{0,63}$/.test(field.key)) {
+		throw new Error(`"${field.key}" is not a valid database config field key.`);
+	}
+	if (!field.label.trim() || !field.description.trim()) {
+		throw new Error(`Database config field "${field.key}" needs UI copy.`);
+	}
+	if (field.kind === 'select' && !field.options?.length) {
+		throw new Error(`Select field "${field.key}" needs at least one option.`);
+	}
+}
+
+function publicDescriptor(
+	descriptor: DatabaseAdapterDescriptor,
+): DatabaseAdapterPublicDescriptor {
+	return Object.freeze({
+		adapterId: descriptor.adapterId,
+		dialectId: descriptor.dialectId,
+		label: descriptor.label,
+		description: descriptor.description,
+		capabilities: Object.freeze({
+			features: Object.freeze([...descriptor.capabilities.features]),
+			isolationLevels: Object.freeze([
+				...descriptor.capabilities.isolationLevels,
+			]),
+		}),
+		configurationSchema: Object.freeze({
+			version: 1 as const,
+			fields: Object.freeze(
+				descriptor.configurationSchema.fields.map((field) =>
+					Object.freeze({ ...field }),
+				),
+			),
+		}),
+	});
+}
+
+export function createDatabaseAdapterRegistry(): DatabaseAdapterRegistry {
+	const descriptors = new Map<DatabaseAdapterId, DatabaseAdapterDescriptor>();
+	let sealed = false;
+	return {
+		register(descriptor) {
+			if (sealed) throw new Error('The database adapter registry is sealed.');
+			assertDatabaseId(descriptor.adapterId, 'adapter');
+			assertDatabaseId(descriptor.dialectId, 'dialect');
+			for (const capability of descriptor.capabilities.features) {
+				assertDatabaseId(capability, 'capability');
+			}
+			const fields = new Set<string>();
+			for (const field of descriptor.configurationSchema.fields) {
+				assertField(field);
+				if (fields.has(field.key)) {
+					throw new Error(
+						`Database adapter "${descriptor.adapterId}" repeats config field "${field.key}".`,
+					);
+				}
+				fields.add(field.key);
+			}
+			if (descriptors.has(descriptor.adapterId)) {
+				throw new Error(
+					`Database adapter "${descriptor.adapterId}" is already registered.`,
+				);
+			}
+			descriptors.set(descriptor.adapterId, descriptor);
+		},
+		get: (adapterId) => descriptors.get(adapterId),
+		list: () =>
+			[...descriptors.values()]
+				.sort((left, right) => left.adapterId.localeCompare(right.adapterId))
+				.map(publicDescriptor),
+		seal() {
+			sealed = true;
+		},
+		get sealed() {
+			return sealed;
+		},
+	};
+}
+
+function selectedAdapter(
+	selection: DatabaseSelection,
+	moduleId: string,
+): DatabaseAdapterId {
+	return selection.moduleOverrides?.[moduleId] ?? selection.defaultAdapterId;
+}
+
+function requirementView(descriptor: DatabaseAdapterDescriptor) {
+	return {
+		adapterId: descriptor.adapterId,
+		dialectId: descriptor.dialectId,
+		capabilities: {
+			features: descriptor.capabilities.features,
+			isolationLevels: descriptor.capabilities.isolationLevels,
+		},
+	};
+}
+
+export function validateDatabaseSelection(
+	registry: DatabaseAdapterRegistry,
+	selection: DatabaseSelection,
+	modules: readonly ModuleDatabaseRequirements[],
+): readonly DatabaseSelectionIssue[] {
+	assertDatabaseId(selection.defaultAdapterId, 'adapter');
+	const issues: DatabaseSelectionIssue[] = [];
+	if (!registry.get(selection.defaultAdapterId)) {
+		issues.push({
+			moduleId: null,
+			code: 'ADAPTER_NOT_REGISTERED',
+			message: `Default database adapter "${selection.defaultAdapterId}" is not registered.`,
+		});
+	}
+	for (const module of modules) {
+		assertNamespace(module.moduleId);
+		const adapterId = selectedAdapter(selection, module.moduleId);
+		const descriptor = registry.get(adapterId);
+		if (!descriptor) {
+			issues.push({
+				moduleId: module.moduleId,
+				code: 'ADAPTER_NOT_REGISTERED',
+				message: `Database adapter "${adapterId}" is not registered.`,
+			});
+			continue;
+		}
+		try {
+			assertDatabaseRequirements(requirementView(descriptor), module);
+		} catch (error) {
+			issues.push({
+				moduleId: module.moduleId,
+				code: 'CAPABILITY_MISMATCH',
+				message: error instanceof Error ? error.message : String(error),
+			});
+		}
+		if (
+			module.tenantOwned &&
+			descriptor.dialectId === DATABASE_DIALECT_IDS.postgresql &&
+			(!descriptor.capabilities.features.includes(
+				DATABASE_CAPABILITY_IDS.ROW_LEVEL_SECURITY,
+			) ||
+				!descriptor.capabilities.features.includes(
+					DATABASE_CAPABILITY_IDS.TENANT_CONTEXT,
+				))
+		) {
+			issues.push({
+				moduleId: module.moduleId,
+				code: 'POSTGRESQL_RLS_REQUIRED',
+				message: `Tenant-owned module "${module.moduleId}" requires transaction-local PostgreSQL RLS.`,
+			});
+		}
+	}
+	return issues;
+}

package/packages/database/src/reset.ts

@@ -0,0 +1,87 @@
+import {
+	assertNotAborted,
+	assertSchemaName,
+	DATABASE_DIALECT_IDS,
+	DatabaseError,
+	operationSignal,
+	type DatabaseDialectId,
+	type DatabaseHandle,
+	type DatabaseOperationOptions,
+} from './contracts.ts';
+
+/** Named so a reset can never be reached by an accidental call. */
+export interface DatabaseResetAuthorization {
+	readonly intent: 'confirmed-destructive-reset';
+}
+
+export interface DatabaseResetResult {
+	readonly dialectId: DatabaseDialectId;
+	/** Catalog order. Empty when the database held no table. */
+	readonly droppedTables: readonly string[];
+}
+
+const TABLE_QUERY: Readonly<Record<string, string>> = Object.freeze({
+	[DATABASE_DIALECT_IDS.postgresql]: `SELECT tablename AS name FROM pg_tables
+	       WHERE schemaname = current_schema()
+	       ORDER BY tablename`,
+});
+
+function tableQuery(dialectId: DatabaseDialectId): string {
+	const text = TABLE_QUERY[dialectId];
+	if (text) return text;
+	throw new DatabaseError(
+		'UNSUPPORTED_CAPABILITY',
+		`Resetting a database is not implemented for dialect "${dialectId}".`,
+	);
+}
+
+/**
+ * Every table the handle can see, in the order a reset would drop them. A
+ * runtime handle that requires tenant context refuses this, so only a
+ * migration lease can plan or run a reset.
+ */
+export async function databaseResetPlan(
+	database: DatabaseHandle,
+	options: DatabaseOperationOptions = {},
+): Promise<readonly string[]> {
+	const result = await database.query<{ name: string }>(
+		{ text: tableQuery(database.dialectId) },
+		options,
+	);
+	const names = result.rows.map((row) => row.name);
+	for (const name of names) assertSchemaName(name);
+	return names;
+}
+
+/**
+ * Drops every table the handle can see, including the migration ledger, so the
+ * next start migrates from zero. Data is not recoverable afterwards.
+ */
+export async function resetDatabase(
+	database: DatabaseHandle,
+	authorization: DatabaseResetAuthorization,
+	options: DatabaseOperationOptions = {},
+): Promise<DatabaseResetResult> {
+	if (authorization.intent !== 'confirmed-destructive-reset') {
+		throw new DatabaseError(
+			'INVALID_ARGUMENT',
+			'Resetting a database requires an explicit confirmed intent.',
+		);
+	}
+	const signal = operationSignal(options);
+	assertNotAborted(signal);
+	const dialectId = database.dialectId;
+	const tables = await databaseResetPlan(database, options);
+	if (tables.length === 0) return { dialectId, droppedTables: [] };
+	const quoted = tables.map((name) => `"${name}"`);
+	/* CASCADE rather than a dependency sort: the catalog order is not one, and
+	   a reset drops the whole module schema anyway. */
+	await database.transaction(
+		(transaction) =>
+			transaction.executeScript(
+				`DROP TABLE IF EXISTS ${quoted.join(', ')} CASCADE;`,
+			),
+		{ ...options, access: 'write' },
+	);
+	return { dialectId, droppedTables: tables };
+}

package/packages/database-pglite/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@flowdular/database-pglite",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/database": "workspace:*",
+		"@electric-sql/pglite": "0.5.8"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "packages/database-pglite"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}