@zeyolabs/kit 0.0.0-stage → 2026.11.6

package/storage/clickhouse/testing.ts

@@ -0,0 +1,81 @@
+import type { z } from 'zod';
+
+import type { ClickHouseTable, IClickHouseClient, Select } from './client';
+import type { ClickHouseSettings } from './schema';
+
+export class FakeClickHouseClient implements IClickHouseClient {
+	readonly commands: string[] = [];
+	private rawSelectQueue: unknown[][] = [];
+	private readonly rows = new Map<string, Record<string, unknown>[]>();
+
+	async command(sql: string): Promise<void> {
+		this.commands.push(sql);
+	}
+
+	async insert<S extends z.ZodObject>(
+		table: string,
+		_schema: S,
+		rows: z.infer<S>[]
+	): Promise<void> {
+		const existing = this.rows.get(table) ?? [];
+		this.rows.set(table, [...existing, ...(rows as Record<string, unknown>[])]);
+	}
+
+	async rawSelect<S extends z.ZodObject>(): Promise<z.infer<S>[]> {
+		return (this.rawSelectQueue.shift() ?? []) as z.infer<S>[];
+	}
+
+	seedRawSelect(rows: unknown[]): void {
+		this.rawSelectQueue.push(rows);
+	}
+
+	seedTable(table: string, rows: Record<string, unknown>[]): void {
+		this.rows.set(table, rows);
+	}
+
+	select<T extends z.ZodObject, K extends keyof T['shape'] & string>(
+		table: ClickHouseTable<T>,
+		columns: K[]
+	): Select<T, K> {
+		const rows = () =>
+			(this.rows.get(table.name) ?? []).map(
+				(row) => Object.fromEntries(columns.map((c) => [c, row[c]])) as Pick<z.infer<T>, K>
+			);
+		return new FakeSelect(rows);
+	}
+}
+
+class FakeSelect<T extends z.ZodObject, K extends keyof T['shape'] & string> implements Select<
+	T,
+	K
+> {
+	constructor(private readonly rows: () => Pick<z.infer<T>, K>[]) {}
+
+	distinct(): Select<T, K> {
+		return this;
+	}
+	limit(): Select<T, K> {
+		return this;
+	}
+	limitBy(): Select<T, K> {
+		return this;
+	}
+	offset(): Select<T, K> {
+		return this;
+	}
+	orderBy(): Select<T, K> {
+		return this;
+	}
+	settings(_settings: ClickHouseSettings): Select<T, K> {
+		return this;
+	}
+	then<F = Pick<z.infer<T>, K>[], J = never>(
+		onFulfilled?: ((value: Pick<z.infer<T>, K>[]) => F | PromiseLike<F>) | null,
+		onRejected?: ((reason: unknown) => J | PromiseLike<J>) | null
+	): PromiseLike<F | J> {
+		return Promise.resolve(this.rows()).then(onFulfilled, onRejected);
+	}
+	where(): Select<T, K> {
+		return this;
+	}
+}

package/storage/manticore/client.ts

@@ -0,0 +1,165 @@
+import mysql, { type Connection, type RowDataPacket } from 'mysql2/promise';
+import { Duplex } from 'node:stream';
+
+import type { CfSocket, ManticoreConfig } from './schema';
+
+import { logger } from '../../monitoring/logger/client';
+
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 9306;
+const CONNECT_TIMEOUT_MS = 10_000;
+
+/** mysql2 sets this exact code (see its `base/connection.js`) when the underlying socket closes —
+ *  the only case worth a same-query retry, since the connection (not the query) was at fault. */
+function isConnectionLost(err: unknown): boolean {
+	return err instanceof Error && 'code' in err && err.code === 'PROTOCOL_CONNECTION_LOST';
+}
+
+type ManticoreClientConfig = {
+	connectTimeoutMs?: number;
+	password: string;
+	/** `host:port` (optionally `mysql://host:port`) — ignored when a VPC binding resolves. */
+	url?: string;
+	user: string;
+	/** The resolved Workers VPC Service binding (`.connect()` opens a raw socket to Manticore's
+	 *  `:9306` MySQL listener) — the caller reads it off its own `EnvStore`
+	 *  (`env.vpc('MANTICORE_VPC')`), not a binding name for this client to look up itself. Omit
+	 *  if this runtime has none (local dev). */
+	vpc?: Fetcher;
+};
+
+/** Parse `host:port` (optionally `mysql://host:port`) — defaults fill in whatever's missing. */
+function parseUrl(url: string | undefined): { host: string; port: number } {
+	if (!url) return { host: DEFAULT_HOST, port: DEFAULT_PORT };
+	const stripped = url.replace(/^mysql:\/\//, '');
+	const [host, port] = stripped.split(':');
+	return { host: host || DEFAULT_HOST, port: port ? Number(port) : DEFAULT_PORT };
+}
+
+/** Bridge a Cloudflare socket (Web `readable`/`writable`) to a Node `Duplex` so mysql2 can speak the
+ *  MySQL wire protocol over the VPC Service TCP socket. `Duplex.fromWeb` is available under
+ *  `nodejs_compat`; mysql2 only reads/writes the stream, so the missing net-socket extras
+ *  (`setNoDelay`/`setTimeout`) aren't needed. */
+function toDuplex(socket: CfSocket): Duplex {
+	// The Workers `ReadableStream`/`WritableStream` types (from workers-types) don't line up with the
+	// `stream/web` types `Duplex.fromWeb` expects, though they're the same runtime objects — cast the
+	// pair to the parameter type.
+	return Duplex.fromWeb({
+		readable: socket.readable,
+		writable: socket.writable,
+	} as unknown as Parameters<typeof Duplex.fromWeb>[0]);
+}
+
+/** Thin Manticore client over the MySQL protocol (mysql2). One MySQL connection per instance, opened
+ *  lazily on first `query()` and cached for the instance's life. Per-request (a Workers TCP socket
+ *  can't cross requests), not a per-isolate singleton like ClickHouse's HTTP client.
+ *
+ *  Queries use `conn.query` (client-side `?` interpolation), not `execute` (server-side prepared
+ *  statements) — Manticore's prepared-statement support over MySQL is limited, and search SQL
+ *  (`MATCH(...)`, faceting) is a poor ORM fit, so this stays a raw-SQL surface. */
+export class ManticoreClient {
+	private readonly config: ManticoreConfig;
+	private connPromise: null | Promise<Connection> = null;
+
+	constructor(config: ManticoreClientConfig) {
+		const { connectTimeoutMs = CONNECT_TIMEOUT_MS, password, url, user, vpc } = config;
+		// An explicit `url` (the local-dev override, `MANTICORE_URL` in `.dev.vars`) always wins over
+		// `vpc`, even when `vpc` resolves truthy — under `vite dev`, `env.vpcNull('MANTICORE_VPC')`
+		// hands back a connectable-looking stub for a `vpc_services` binding marked `"remote": true"`
+		// regardless of the platformProxy's `remoteBindings: false`, and routing an actual `.connect()`
+		// through it hits a Miniflare bug ("This ReadableStream is disturbed") — every query silently
+		// returns no rows instead of throwing. Prod never sets a `MANTICORE_URL` var, so this is a
+		// pure local-dev branch there.
+		if (!vpc || url) {
+			this.config = { ...parseUrl(url), connectTimeoutMs, password, user };
+			return;
+		}
+		// Workers' `connect()` requires a non-empty address, but the VPC service routes to its own
+		// registered target (`wrangler vpc service list`) and ignores this value.
+		const address = url ?? `${DEFAULT_HOST}:${DEFAULT_PORT}`;
+		this.config = {
+			connectTimeoutMs,
+			password,
+			socket: async () => vpc.connect(address),
+			user,
+		};
+	}
+
+	/** Close the connection if one was opened. Safe when never opened (lazy client, no query ran) and
+	 *  best-effort — runs in the request-teardown `finally`, so a failed close must not throw. */
+	async close(): Promise<void> {
+		if (!this.connPromise) return;
+		const conn = await this.connPromise.catch(() => null);
+		this.connPromise = null;
+		if (!conn) return;
+		try {
+			await conn.end();
+		} catch {
+			// best-effort close; nothing actionable on a failed teardown
+		}
+	}
+
+	/** Run a read and return the rows. Params fill `?` placeholders (client-side interpolation). */
+	async query<T = RowDataPacket>(sql: string, params?: unknown[]): Promise<T[]> {
+		try {
+			return await this.runQuery<T>(sql, params);
+		} catch (err) {
+			// A dropped connection (idle timeout, socket reset) is retried once on a fresh connection —
+			// most callers only run one query per request, so dropping `connPromise` for "next call"
+			// alone (as this used to) never actually got a retry: there was no next call. Anything else
+			// (bad SQL, a genuine query error) isn't retried — it'll just fail the same way again.
+			if (!isConnectionLost(err)) {
+				await logger.error(err, { op: 'manticore', summary: sql });
+				throw err;
+			}
+			try {
+				return await this.runQuery<T>(sql, params);
+			} catch (retryErr) {
+				await logger.error(retryErr, { op: 'manticore', retried: true, summary: sql });
+				throw retryErr;
+			}
+		}
+	}
+
+	private getConnection(): Promise<Connection> {
+		return (this.connPromise ??= (async () => {
+			const cfg = this.config;
+			// Prod: tunnel through the VPC Service socket (resolved async), bridged to a Node duplex.
+			// Dev: hand mysql2 host/port and let it dial the local Manticore itself.
+			const stream = cfg.socket ? toDuplex(await cfg.socket()) : undefined;
+			const conn = await mysql.createConnection({
+				...(stream ? { stream } : { host: cfg.host, port: cfg.port }),
+				connectTimeout: cfg.connectTimeoutMs,
+				// mysql2's row parser is JIT-compiled via `new Function` unless this is set — Workers
+				// has no `eval`/dynamic Function, so the first row-bearing result crashes mid-parse and
+				// tears down the stream (surfaces as a misleading "server closed the connection").
+				disableEval: true,
+				// Manticore has no databases and rejects a CONNECT_WITH_DB handshake with ER_NO_DB_ERROR
+				// (1046), so drop the capability and connect database-less, like the native `mysql` client.
+				flags: ['-CONNECT_WITH_DB'],
+				password: cfg.password,
+				user: cfg.user,
+			});
+			// The connection can die between queries (idle timeout, socket reset) without another
+			// query ever running to hit the catch in `query()` — drop the cache here too so the next
+			// `getConnection()` call dials fresh instead of returning the same dead object forever.
+			conn.on('error', () => {
+				this.connPromise = null;
+			});
+			return conn;
+		})());
+	}
+
+	private async runQuery<T>(sql: string, params?: unknown[]): Promise<T[]> {
+		try {
+			const conn = await this.getConnection();
+			const [rows] = await conn.query(sql, params);
+			return rows as T[];
+		} catch (err) {
+			// Leaves `connPromise` cached but unusable — drop it so the retry (or the next call, if this
+			// was already the retry) dials fresh instead of reusing the same dead connection.
+			this.connPromise = null;
+			throw err;
+		}
+	}
+}

package/storage/manticore/schema.ts

@@ -0,0 +1,23 @@
+/** A Cloudflare socket (from a VPC Service `.connect()` or `cloudflare:sockets`): Web streams, not a
+ *  Node duplex — the client bridges it to a `Duplex` before handing it to mysql2. */
+export type CfSocket = {
+	close?: () => Promise<void>;
+	readable: ReadableStream<Uint8Array>;
+	writable: WritableStream<Uint8Array>;
+};
+
+/** Resolved Manticore connection config. Exactly one transport is set:
+ *  - `socket` (prod): a thunk that opens the VPC Service TCP socket per connect. Resolving the binding
+ *    lazily (not capturing it) keeps a reused client pointed at the ACTIVE request's binding.
+ *  - `host`/`port` (dev): let mysql2 open its own TCP socket to the local Docker Manticore. */
+export type ManticoreConfig = {
+	/** Connect timeout (ms). */
+	connectTimeoutMs?: number;
+	/** Dev transport: mysql2 dials this directly. */
+	host?: string;
+	password: string;
+	port?: number;
+	/** Prod transport: open the VPC Service socket. Mutually exclusive with `host`/`port`. */
+	socket?: () => Promise<CfSocket>;
+	user: string;
+};

package/storage/postgres/client.ts

@@ -0,0 +1,44 @@
+// Generic Postgres-over-Cloudflare-Hyperdrive infra — no app domain knowledge. The schema is
+// generic (TSchema): kit never imports it, just forwards whatever the caller hands it to drizzle.
+// `drizzle-orm` itself is a fine kit dependency (a generic third-party ORM); the app's actual
+// schema never enters kit — it stays in the app, the only place that knows what it is.
+import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+
+export type PostgresClientConfig = {
+	connectionTimeoutMs?: number;
+	poolMax?: number;
+	queryTimeoutMs?: number;
+};
+
+/** A small `pg.Pool`, not a single `pg.Client` — Hyperdrive pools cheaply at the edge, and a lone
+ *  `Client` only serves one in-flight query at a time. One per request/invocation: opened lazily
+ *  (a pooled connection only dials on first query), closed via `close()` at the end. */
+export class PostgresClient<TSchema extends Record<string, unknown>> {
+	readonly db: NodePgDatabase<TSchema>;
+	private readonly pool: pg.Pool;
+
+	constructor(hyperdrive: Hyperdrive, schema: TSchema, config: PostgresClientConfig = {}) {
+		const { connectionTimeoutMs = 10_000, poolMax = 5, queryTimeoutMs = 20_000 } = config;
+		this.pool = new pg.Pool({
+			connectionString: hyperdrive.connectionString,
+			connectionTimeoutMillis: connectionTimeoutMs,
+			max: poolMax,
+			query_timeout: queryTimeoutMs,
+		});
+		// An idle pooled connection dropping (e.g. a WARP blip in dev) is otherwise an unhandled
+		// 'error' event that crashes the process — in-flight query errors still propagate normally
+		// through their own query() rejection, this only guards idle drops.
+		this.pool.on('error', () => {});
+		this.db = drizzle(this.pool, { schema });
+	}
+
+	/** Best-effort teardown — nothing actionable on a failed close. */
+	async close(): Promise<void> {
+		try {
+			await this.pool.end();
+		} catch {
+			// best-effort teardown — nothing actionable on a failed close
+		}
+	}
+}

package/storage/postgres/testing.ts

@@ -0,0 +1,275 @@
+import type { PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import type { PgliteDatabase } from 'drizzle-orm/pglite';
+
+import { PGlite } from '@electric-sql/pglite';
+import { getTableConfig } from 'drizzle-orm/pg-core';
+import { drizzle } from 'drizzle-orm/pglite';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { vi } from 'vitest';
+
+// ── PGlite test database ──
+//
+// A fresh, fully-migrated in-memory Postgres for one test file -- real Postgres (PGlite is the
+// actual Postgres engine compiled to WASM, not a mock/emulator), no Docker, no DATABASE_URL,
+// isolated per call so tests using this don't need to serialize with each other the way a
+// DATABASE_URL-gated integration suite does.
+
+function isAddConstraint(statement: string): boolean {
+	return /^ALTER TABLE\b/i.test(statement) && /\bADD CONSTRAINT\b/i.test(statement);
+}
+
+// GRANT/REVOKE reference real production Postgres roles provisioned by infra outside migrations --
+// irrelevant here, PGlite's default connection already has full privileges.
+function isGrantOrRevoke(statement: string): boolean {
+	return /^(GRANT|REVOKE)\b/i.test(statement);
+}
+
+function collectStatements(migrationsDir: string): string[] {
+	const files = readdirSync(migrationsDir).filter((f) => f.endsWith('.sql'));
+	return files
+		.flatMap((file) =>
+			readFileSync(path.join(migrationsDir, file), 'utf8')
+				.split('--> statement-breakpoint')
+				.map((s) => s.trim())
+				.filter(Boolean)
+		)
+		.filter((s) => !isGrantOrRevoke(s));
+}
+
+// A schema's hand-written `functions.sql` (drizzle can't model functions), as one script with its GRANTs dropped.
+function collectFunctions(schemaDir: string): string | undefined {
+	const file = path.join(schemaDir, 'functions.sql');
+	if (!existsSync(file)) return undefined;
+	return readFileSync(file, 'utf8').replace(/^(GRANT|REVOKE)\b.*;$/gim, '');
+}
+
+// Every immediate subdirectory of `schemasDir` that ships a `migrations` folder -- so a package
+// gaining a new Postgres schema doesn't also need a second, hand-maintained list of schema names
+// kept in sync by hand.
+function discoverSchemaNames(schemasDir: string): string[] {
+	return readdirSync(schemasDir, { withFileTypes: true })
+		.filter(
+			(entry) => entry.isDirectory() && existsSync(path.join(schemasDir, entry.name, 'migrations'))
+		)
+		.map((entry) => entry.name);
+}
+
+/**
+ * A fresh, fully-migrated in-memory Postgres for one test file, wrapped in drizzle over `schema`.
+ * `schemasDir` is the package's `schemas/` directory (e.g. `.../db-schemas-postgres/schemas`) --
+ * every schema under it gets migrated, not just the ones `schema` imports types from, since a
+ * cross-schema FK needs its target table to exist even when nothing here queries it through
+ * Drizzle directly.
+ *
+ * Migrations are applied in two passes across every schema -- everything except `ADD CONSTRAINT`
+ * first, then every `ADD CONSTRAINT` after -- rather than schema-by-schema in list order: a
+ * circular FK between two schemas (each referencing a table in the other) means no ordering of
+ * whole schemas can work; every table has to exist before any FK constraint is added, no matter
+ * which schema it's in.
+ *
+ * `frozenTime`, if given, freezes the clock for the lifetime of the returned client (restored on
+ * `close()`) -- PGlite's SQL `now()` is backed by the host JS Date (runs in-process WASM), so any
+ * fixture data computed relative to "now" needs the clock already frozen before it's inserted.
+ */
+export async function createPgliteTestDb<TSchema extends Record<string, unknown>>(
+	schema: TSchema,
+	schemasDir: string,
+	frozenTime?: Date
+): Promise<{ close: () => Promise<void>; db: PgliteDatabase<TSchema> }> {
+	if (frozenTime) {
+		vi.useFakeTimers();
+		vi.setSystemTime(frozenTime);
+	}
+
+	const pg = new PGlite();
+	const schemaNames = discoverSchemaNames(schemasDir);
+
+	for (const name of schemaNames) {
+		await pg.exec(`CREATE SCHEMA IF NOT EXISTS ${name};`);
+	}
+
+	const allStatements = schemaNames.flatMap((name) =>
+		collectStatements(path.join(schemasDir, name, 'migrations'))
+	);
+	const constraints = allStatements.filter(isAddConstraint);
+	const everythingElse = allStatements.filter((s) => !isAddConstraint(s));
+
+	for (const stmt of everythingElse) await pg.exec(stmt);
+	for (const stmt of constraints) await pg.exec(stmt);
+	for (const name of schemaNames) {
+		const functions = collectFunctions(path.join(schemasDir, name));
+		if (functions) await pg.exec(functions);
+	}
+
+	return {
+		close: async () => {
+			await pg.close();
+			if (frozenTime) vi.useRealTimers();
+		},
+		db: drizzle(pg, { schema }),
+	};
+}
+
+// ── JSON fixtures ──
+//
+// A master fixture file (plus override files merged on top) seeds rows into a table by
+// fixture-id -- a local alias, never written to any column -- so other rows can reference one
+// another before either has a real DB-assigned id (e.g. a list's `accountId: "a"`), and so a test
+// can look the real id back up after seeding by the same name. A row's shape (which fields are
+// foreign keys, to which other collection, and whether its primary key needs the fixture-id as a
+// fallback value) is read off the table's own drizzle definition via `getTableConfig`, not
+// hand-maintained.
+
+export type FixtureFile = Record<string, Record<string, FixtureRow>>;
+export type FixtureIdMap = Record<string, Record<string, number | string>>;
+export type FixtureRow = Record<string, unknown>;
+
+export type FixtureCollection = {
+	/** Boilerplate field values a fixture row can omit -- for a NOT NULL column with no
+	 *  meaningful DB-side default (e.g. a jsonb config column), not something schema
+	 *  introspection can supply. */
+	defaults?: FixtureRow;
+	/** A field that references another collection WITHOUT a real DB foreign key constraint --
+	 *  schema introspection can only see actual FK constraints, so a denormalized reference has
+	 *  to be named here by hand. */
+	extraFkFields?: Record<string, string>;
+	/** The JSON key fixture files address this collection by. */
+	name: string;
+	table: PgTable;
+};
+
+function qualifiedName(table: PgTable): string {
+	const { name, schema } = getTableConfig(table);
+	return schema ? `${schema}.${name}` : name;
+}
+
+// Finds which JS property name (e.g. "accountId") a column is exposed under on its own table --
+// foreign-key/primary-key metadata only gives us DB column names ("account_id"), not the
+// camelCase ones fixture rows and `.values()` calls use. Matched by DB name, not object identity:
+// a table-level `foreignKey({ columns: [t.accountId], ... })` constraint (as opposed to an inline
+// `.references()`) captures a different column object than the one exposed as `table.accountId`,
+// even though they're the same column -- verified empirically against a real schema.
+function columnPropertyName(table: PgTable, column: PgColumn): string {
+	const entry = Object.entries(table).find(
+		([, value]) => (value as PgColumn | undefined)?.name === column.name
+	);
+	if (!entry) throw new Error(`Column ${column.name} not found as a property of its own table`);
+	return entry[0];
+}
+
+type TableShape = {
+	fkFields: Record<string, string>;
+	idField: string | undefined;
+	idNeedsFixtureKey: boolean;
+};
+
+function introspectTable(
+	table: PgTable,
+	collectionByTableName: Map<string, string>,
+	extraFkFields: Record<string, string> = {}
+): TableShape {
+	const config = getTableConfig(table);
+	// A single-column `.primaryKey()` builder marks the column itself (`.primary === true`); a
+	// table-level `primaryKey({ columns: [...] })` constraint (e.g. auth.method) doesn't -- it only
+	// shows up in `primaryKeys`, verified empirically against a real schema.
+	const pk = config.columns.find((c) => c.primary) ?? config.primaryKeys[0]?.columns[0];
+	const fkFields: Record<string, string> = { ...extraFkFields };
+	for (const fk of config.foreignKeys) {
+		const ref = fk.reference();
+		const targetCollection = collectionByTableName.get(qualifiedName(ref.foreignTable));
+		if (!targetCollection) continue;
+		for (const column of ref.columns)
+			fkFields[columnPropertyName(table, column)] = targetCollection;
+	}
+	return {
+		fkFields,
+		idField: pk && columnPropertyName(table, pk),
+		idNeedsFixtureKey: pk ? !pk.hasDefault : false,
+	};
+}
+
+// A relative-time field written as data instead of code, e.g. `{ "daysAgo": 365 }` or
+// `{ "minutesAgo": 5 }` -- resolved against `nowFn()` at seed time rather than baked into the JSON
+// as an absolute timestamp, so it stays meaningful regardless of when the suite runs.
+function isRelativeTime(value: unknown): value is { daysAgo: number } | { minutesAgo: number } {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		('daysAgo' in value || 'minutesAgo' in value) &&
+		Object.keys(value).length === 1
+	);
+}
+
+/** Deep-merges override files onto the master fixture, per collection per fixture-id: fields on
+ *  an existing fixture-id are overridden, new fixture-ids are added, nothing in master is dropped. */
+export function mergeFixtures(master: FixtureFile, overrides: FixtureFile[]): FixtureFile {
+	const merged: FixtureFile = structuredClone(master);
+	for (const override of overrides) {
+		for (const [collection, rows] of Object.entries(override)) {
+			merged[collection] ??= {};
+			for (const [fixtureId, row] of Object.entries(rows)) {
+				merged[collection][fixtureId] = { ...merged[collection][fixtureId], ...row };
+			}
+		}
+	}
+	return merged;
+}
+
+/**
+ * Seeds `master` (plus any override files, merged on top) into a PGlite instance, resolving
+ * cross-collection references (e.g. a job's `fromInboxId: "sender"`) to the real id Postgres
+ * assigned on insert. Returns the fixture-id -> real-id map so a test can look up rows by the same
+ * name they're defined under in the JSON.
+ */
+export async function seedFixtures(
+	pglite: PgliteDatabase<Record<string, unknown>>,
+	collections: FixtureCollection[],
+	master: FixtureFile,
+	overrides: FixtureFile[] = [],
+	// A caller freezing the clock for relative fixture dates wants those dates resolved against
+	// its own frozen "now" -- passed in rather than imported, so this module doesn't depend on any
+	// one app's datetime library. Only required if a fixture actually uses `daysAgo`/`minutesAgo`.
+	nowFn?: () => { subtract: (unit: Record<string, number>) => unknown }
+): Promise<{ ids: FixtureIdMap }> {
+	const collectionByTableName = new Map(collections.map((c) => [qualifiedName(c.table), c.name]));
+	const fixtures = mergeFixtures(master, overrides);
+	const ids: FixtureIdMap = {};
+
+	for (const { defaults, extraFkFields, name, table } of collections) {
+		const { fkFields, idField, idNeedsFixtureKey } = introspectTable(
+			table,
+			collectionByTableName,
+			extraFkFields
+		);
+		ids[name] = {};
+		for (const [fixtureId, row] of Object.entries(fixtures[name] ?? {})) {
+			const resolved: FixtureRow = { ...defaults, ...row };
+			if (idNeedsFixtureKey && idField) resolved[idField] ??= fixtureId;
+			for (const [field, refCollection] of Object.entries(fkFields)) {
+				const ref = resolved[field];
+				if (typeof ref === 'string') resolved[field] = ids[refCollection][ref];
+			}
+			for (const [field, value] of Object.entries(resolved)) {
+				if (!isRelativeTime(value)) continue;
+				if (!nowFn) {
+					throw new Error(
+						`Fixture "${name}.${fixtureId}.${field}" uses a relative time but no nowFn was passed to seedFixtures()`
+					);
+				}
+				resolved[field] =
+					'daysAgo' in value
+						? nowFn().subtract({ days: value.daysAgo })
+						: nowFn().subtract({ minutes: value.minutesAgo });
+			}
+			const [inserted] = await pglite
+				.insert(table)
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any -- each table's own insert shape, fixtures are untyped JSON by design
+				.values(resolved as any)
+				.returning({ id: table[idField as keyof PgTable] as PgColumn });
+			ids[name][fixtureId] = inserted.id as number | string;
+		}
+	}
+
+	return { ids };
+}