@kici-dev/shared 0.0.0 → 0.1.0

package/dist/db-admin.js

@@ -0,0 +1,2525 @@
+import "./chunk-gOLHoazu.js";
+import { createPool } from "./db.js";
+import { createHash } from "node:crypto";
+import pg from "pg";
+//#region src/db-admin.ts
+/**
+* Admin/DB-operations helpers shared between `kici-admin` (orchestrator DB)
+* and `kici-platform-admin` (Platform DB). Each CLI wraps these with its own
+* bundled migration provider and audit-log pattern.
+*
+* All destructive ops require the caller to pass a fully-formed database URL
+* — no parsing of environment variables here. The CLI layer handles that.
+*/
+const MIGRATION_HASH_TABLE = "_migration_content_hash";
+/**
+* Parse a libpq-style URL into (adminUrl, dbName, dbOwner).
+*
+* `adminUrl` connects to the `postgres` maintenance DB so callers can run
+* `CREATE DATABASE` / `DROP DATABASE` on `dbName`. `dbOwner` is the URL's
+* username, which becomes the new DB owner when we create it.
+*/
+function parseDatabaseUrl(databaseUrl) {
+	const url = new URL(databaseUrl);
+	const dbName = url.pathname.replace(/^\//, "");
+	if (!dbName) throw new Error(`Database URL missing /dbname path component: ${maskDatabaseUrl(databaseUrl)}`);
+	const dbOwner = decodeURIComponent(url.username);
+	if (!dbOwner) throw new Error(`Database URL missing username: ${maskDatabaseUrl(databaseUrl)}`);
+	url.pathname = "/postgres";
+	return {
+		adminUrl: url.toString(),
+		dbName,
+		dbOwner
+	};
+}
+/**
+* Redact the password from a libpq URL for safe logging.
+*/
+function maskDatabaseUrl(databaseUrl) {
+	try {
+		const url = new URL(databaseUrl);
+		if (url.password) url.password = "***";
+		return url.toString();
+	} catch {
+		return "<unparseable database-url>";
+	}
+}
+function escapeSqlLiteral(value) {
+	return value.replace(/'/g, "''");
+}
+function assertValidIdentifier(name, label) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`Invalid ${label} identifier: ${name}`);
+}
+async function withAdminPool(adminUrl, fn) {
+	const pool = new pg.Pool({
+		connectionString: adminUrl,
+		max: 1
+	});
+	try {
+		return await fn(pool);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DROP `dbName` (if it exists). Terminates existing backend connections
+* so the DROP doesn't block. Idempotent — drops are IF EXISTS.
+*
+* Used by e2e cleanup after a full-lifecycle service-deploy test tears
+* down its isolated database. Shares the same admin-URL + identifier-
+* validation + backend-termination scaffolding as dropAndCreateDatabase
+* so the two helpers cannot drift.
+*/
+async function dropDatabaseDirect(databaseUrl) {
+	const { adminUrl, dbName } = parseDatabaseUrl(databaseUrl);
+	assertValidIdentifier(dbName, "database name");
+	await withAdminPool(adminUrl, async (pool) => {
+		await pool.query("SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()", [dbName]);
+		await pool.query(`DROP DATABASE IF EXISTS "${dbName}"`);
+	});
+}
+/**
+* Drop `dbName` (if it exists), then recreate it owned by `owner`. Terminates
+* existing backend connections so the DROP doesn't block.
+*/
+async function dropAndCreateDatabase(databaseUrl) {
+	const { adminUrl, dbName, dbOwner } = parseDatabaseUrl(databaseUrl);
+	assertValidIdentifier(dbName, "database name");
+	assertValidIdentifier(dbOwner, "database owner");
+	await withAdminPool(adminUrl, async (pool) => {
+		await pool.query("SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()", [dbName]);
+		await pool.query(`DROP DATABASE IF EXISTS "${dbName}"`);
+		await pool.query(`CREATE DATABASE "${dbName}" OWNER "${dbOwner}"`);
+	});
+}
+/**
+* CREATE DATABASE IF NOT EXISTS (idempotent). Uses the URL's username as owner.
+*/
+async function ensureDatabase(databaseUrl) {
+	const { adminUrl, dbName, dbOwner } = parseDatabaseUrl(databaseUrl);
+	assertValidIdentifier(dbName, "database name");
+	assertValidIdentifier(dbOwner, "database owner");
+	return withAdminPool(adminUrl, async (pool) => {
+		if ((await pool.query("SELECT 1 FROM pg_database WHERE datname = $1", [dbName])).rows.length > 0) return "exists";
+		await pool.query(`CREATE DATABASE "${dbName}" OWNER "${dbOwner}"`);
+		return "created";
+	});
+}
+/**
+* CREATE ROLE ... LOGIN [CREATEDB] (idempotent — updates password if role
+* already exists).
+*/
+async function createDbRole(adminUrl, opts) {
+	assertValidIdentifier(opts.username, "role name");
+	return withAdminPool(adminUrl, async (pool) => {
+		const exists = await pool.query("SELECT 1 FROM pg_roles WHERE rolname = $1", [opts.username]);
+		const pw = escapeSqlLiteral(opts.password);
+		if (exists.rows.length === 0) {
+			const createDbClause = opts.createDb ? " CREATEDB" : "";
+			await pool.query(`CREATE ROLE "${opts.username}" LOGIN${createDbClause} PASSWORD '${pw}'`);
+			return "created";
+		}
+		await pool.query(`ALTER ROLE "${opts.username}" PASSWORD '${pw}'`);
+		return "updated";
+	});
+}
+/**
+* Create a read-only role and grant SELECT on all tables in the public schema
+* (plus default privileges for tables created later).
+*
+* `databaseUrl` must connect as the DB owner (or superuser) since we need to
+* ALTER DEFAULT PRIVILEGES.
+*/
+async function createReadOnlyDbUser(databaseUrl, opts) {
+	assertValidIdentifier(opts.username, "role name");
+	const { dbName } = parseDatabaseUrl(databaseUrl);
+	assertValidIdentifier(dbName, "database name");
+	const pool = createPool(databaseUrl);
+	try {
+		const exists = await pool.query("SELECT 1 FROM pg_roles WHERE rolname = $1", [opts.username]);
+		const pw = escapeSqlLiteral(opts.password);
+		let outcome;
+		if (exists.rows.length === 0) {
+			await pool.query(`CREATE ROLE "${opts.username}" LOGIN PASSWORD '${pw}'`);
+			outcome = "created";
+		} else {
+			await pool.query(`ALTER ROLE "${opts.username}" PASSWORD '${pw}'`);
+			outcome = "updated";
+		}
+		await pool.query(`GRANT CONNECT ON DATABASE "${dbName}" TO "${opts.username}"`);
+		await pool.query(`GRANT USAGE ON SCHEMA public TO "${opts.username}"`);
+		await pool.query(`GRANT SELECT ON ALL TABLES IN SCHEMA public TO "${opts.username}"`);
+		await pool.query(`ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO "${opts.username}"`);
+		return outcome;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Compute a stable content hash over all migrations the provider exposes.
+* Uses migration name + the string representation of `up`/`down` (via
+* `Function.toString()`), so brute-force rewrites of a migration body invalidate
+* the hash even when the filename stays the same.
+*
+* Works with any `MigrationProvider` — file-based or the orchestrator /
+* Platform bundled ones.
+*/
+async function computeMigrationsHash(provider) {
+	const migrations = await provider.getMigrations();
+	const names = Object.keys(migrations).sort();
+	const hash = createHash("sha256");
+	for (const name of names) {
+		const migration = migrations[name];
+		hash.update(name);
+		hash.update("\0");
+		hash.update(migration.up.toString());
+		hash.update("\0");
+		if (migration.down) hash.update(migration.down.toString());
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+/**
+* Marker row key used by the bundled-provider hash (`computeMigrationsHash`).
+*
+* Kept distinct from the legacy e2e file-based hash (which still writes to
+* the row keyed `'kysely_migration'`) so the two algorithms can coexist in
+* the same `_migration_content_hash` table without clobbering each other.
+* `kici-admin db check-schema` / `kici-platform-admin db check-schema` read
+* this row; the e2e `isSchemaCurrent` helper reads the other.
+*/
+const PROVIDER_HASH_KEY = "kysely_migration_provider";
+/**
+* Ensure the content-hash marker table exists, then upsert `hash` keyed by
+* `PROVIDER_HASH_KEY`. Paired with `readStoredMigrationContentHash` +
+* `isSchemaCurrent`.
+*/
+async function storeMigrationContentHash(pool, hash) {
+	await pool.query(`
+    CREATE TABLE IF NOT EXISTS ${MIGRATION_HASH_TABLE} (
+      table_name text PRIMARY KEY,
+      hash text NOT NULL
+    )
+  `);
+	await pool.query(`INSERT INTO ${MIGRATION_HASH_TABLE} (table_name, hash) VALUES ($1, $2) ON CONFLICT (table_name) DO UPDATE SET hash = EXCLUDED.hash`, [PROVIDER_HASH_KEY, hash]);
+}
+/**
+* Read the provider-based content hash, or `null` if the marker table / row
+* doesn't exist.
+*/
+async function readStoredMigrationContentHash(pool) {
+	try {
+		return (await pool.query(`SELECT hash FROM ${MIGRATION_HASH_TABLE} WHERE table_name = $1`, [PROVIDER_HASH_KEY])).rows[0]?.hash ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* TRUNCATE dispatch_queue on the orchestrator DB (direct SQL). Used by the
+* `kici-admin queue clear --database-url ...` direct-DB fallback when the
+* orchestrator isn't reachable over HTTP (e.g. warm-start cleanup before the
+* service restarts).
+*/
+async function clearDispatchQueueDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query("TRUNCATE dispatch_queue");
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE orphan execution_runs + execution_jobs for routing keys other than
+* `routingKey` (and rows with NULL routing_key). Returns row counts.
+*/
+async function purgeStaleExecutionDirect(databaseUrl, routingKey) {
+	const pool = createPool(databaseUrl);
+	try {
+		const concurrencyGroupsResult = await pool.query(`DELETE FROM concurrency_groups
+        WHERE routing_key != $1
+           OR routing_key IS NULL
+           OR run_id NOT IN (
+             SELECT run_id FROM execution_runs
+              WHERE status IN ('pending', 'running', 'cancelling')
+           )`, [routingKey]);
+		const jobs = await pool.query(`DELETE FROM execution_jobs
+        WHERE run_id IN (
+          SELECT run_id FROM execution_runs
+           WHERE routing_key != $1 OR routing_key IS NULL
+        )`, [routingKey]);
+		const runs = await pool.query(`DELETE FROM execution_runs WHERE routing_key != $1 OR routing_key IS NULL`, [routingKey]);
+		return {
+			jobsDeleted: jobs.rowCount ?? 0,
+			runsDeleted: runs.rowCount ?? 0,
+			concurrencyGroupsDeleted: concurrencyGroupsResult.rowCount ?? 0
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE orphan sources + their `__system__`-scoped webhook/private-key
+* secrets, all `generic_webhook_sources` (the table is single-tenant per
+* deployment), and any `workflow_registrations` rows whose routing_key no
+* longer points at an existing source. When `dryRun` is true, only count
+* the rows that would be deleted.
+*
+* Orphan registration cleanup is critical: generic_webhook_sources is wiped
+* wholesale, but workflow_registrations rows previously persisted under those
+* routing keys would otherwise survive and pollute the cross-source dispatch
+* fan-out on the next test run (causing clone attempts against long-dead
+* repo identifiers from earlier tests).
+*/
+async function purgeStaleSourcesDirect(databaseUrl, routingKey, dryRun) {
+	const pool = createPool(databaseUrl);
+	try {
+		if (dryRun) {
+			const staleSources = await pool.query(`SELECT COUNT(*)::int AS count FROM sources WHERE routing_key != $1`, [routingKey]);
+			const staleSecrets = await pool.query(`SELECT COUNT(*)::int AS count FROM scoped_secrets
+          WHERE org_id = '__system__'
+            AND scope LIKE '__source__/%'
+            AND scope NOT IN (
+              SELECT '__source__/' || id::text FROM sources WHERE routing_key = $1
+            )`, [routingKey]);
+			const genericSources = await pool.query(`SELECT COUNT(*)::int AS count FROM generic_webhook_sources`);
+			const orphanRegistrations = await pool.query(`SELECT COUNT(*)::int AS count FROM workflow_registrations
+          WHERE routing_key != $1
+            AND routing_key NOT IN (SELECT routing_key FROM generic_webhook_sources)`, [routingKey]);
+			return {
+				dryRun: true,
+				staleSecrets: staleSecrets.rows[0]?.count ?? 0,
+				staleSources: staleSources.rows[0]?.count ?? 0,
+				genericSources: genericSources.rows[0]?.count ?? 0,
+				orphanRegistrations: orphanRegistrations.rows[0]?.count ?? 0
+			};
+		}
+		const secrets = await pool.query(`DELETE FROM scoped_secrets
+        WHERE org_id = '__system__'
+          AND scope LIKE '__source__/%'
+          AND scope NOT IN (
+            SELECT '__source__/' || id::text FROM sources WHERE routing_key = $1
+          )`, [routingKey]);
+		const sources = await pool.query(`DELETE FROM sources WHERE routing_key != $1`, [routingKey]);
+		const generic = await pool.query(`DELETE FROM generic_webhook_sources`);
+		const registrations = await pool.query(`DELETE FROM workflow_registrations
+        WHERE routing_key != $1
+          AND routing_key NOT IN (SELECT routing_key FROM sources)`, [routingKey]);
+		return {
+			dryRun: false,
+			secretsDeleted: secrets.rowCount ?? 0,
+			sourcesDeleted: sources.rowCount ?? 0,
+			genericDeleted: generic.rowCount ?? 0,
+			registrationsDeleted: registrations.rowCount ?? 0
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Bulk-delete scoped_secrets. Scoped to one org when `orgId` is provided,
+* else all orgs. Returns the number of rows deleted.
+*/
+async function purgeScopedSecretsDirect(databaseUrl, orgId) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (orgId ? await pool.query(`DELETE FROM scoped_secrets WHERE org_id = $1`, [orgId]) : await pool.query(`DELETE FROM scoped_secrets`)).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Allowed policy field names for `setEnvironmentPolicyDirect`. Kept as an
+* explicit allowlist so the column-name interpolation in the UPDATE string
+* can never be driven by unsanitised caller input.
+*/
+const ENV_POLICY_COLUMNS = new Set([
+	"branch_restrictions",
+	"required_reviewers",
+	"wait_timer_seconds",
+	"hold_expiry_seconds",
+	"minimum_trust",
+	"enabled"
+]);
+/**
+* Upsert an environment row keyed by (org_id, name). Returns the env id and
+* whether the row was newly inserted. `branchRestrictions` / `requiredReviewers`
+* are JSON-serialised server-side; pass them as plain arrays or objects.
+*/
+async function seedEnvironmentDirect(databaseUrl, opts) {
+	if (opts.waitTimerSeconds != null && opts.waitTimerSeconds < 0) throw new Error(`environment: waitTimerSeconds must be >= 0 (got ${opts.waitTimerSeconds})`);
+	if (opts.holdExpirySeconds != null && opts.holdExpirySeconds < 0) throw new Error(`environment: holdExpirySeconds must be >= 0 (got ${opts.holdExpirySeconds})`);
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		const branchJson = JSON.stringify(opts.branchRestrictions ?? []);
+		const reviewersJson = opts.requiredReviewers === void 0 ? null : JSON.stringify(opts.requiredReviewers);
+		const row = (await pool.query(`INSERT INTO environments
+          (org_id, name, type, enabled, branch_restrictions, required_reviewers,
+           wait_timer_seconds, hold_expiry_seconds, minimum_trust)
+        VALUES ($1, $2, COALESCE($3, 'fixed'), COALESCE($4, true), $5::jsonb, $6::jsonb,
+                $7, COALESCE($8, 86400), $9)
+        ON CONFLICT (org_id, name) DO UPDATE SET
+          type = COALESCE(EXCLUDED.type, environments.type),
+          enabled = EXCLUDED.enabled,
+          branch_restrictions = EXCLUDED.branch_restrictions,
+          required_reviewers = EXCLUDED.required_reviewers,
+          wait_timer_seconds = EXCLUDED.wait_timer_seconds,
+          hold_expiry_seconds = EXCLUDED.hold_expiry_seconds,
+          minimum_trust = EXCLUDED.minimum_trust,
+          updated_at = now()
+        RETURNING id, (xmax = 0) AS inserted`, [
+			opts.orgId,
+			opts.name,
+			opts.type ?? null,
+			opts.enabled ?? null,
+			branchJson,
+			reviewersJson,
+			opts.waitTimerSeconds ?? null,
+			opts.holdExpirySeconds ?? null,
+			opts.minimumTrust ?? null
+		])).rows[0];
+		if (!row) throw new Error(`environment: upsert returned no row for ${opts.name}`);
+		return {
+			envId: row.id,
+			created: row.inserted
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Upsert an `environment_bindings` row connecting `envName` to `scopePattern`.
+* Throws if the environment does not exist.
+*/
+async function seedEnvironmentBindingDirect(databaseUrl, opts) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		const envRow = await pool.query(`SELECT id FROM environments WHERE org_id = $1 AND name = $2`, [opts.orgId, opts.envName]);
+		if (envRow.rows.length === 0) throw new Error(`environment: not found (org=${opts.orgId}, name=${opts.envName})`);
+		const envId = envRow.rows[0].id;
+		return { created: (await pool.query(`INSERT INTO environment_bindings (org_id, environment_id, scope_pattern)
+         VALUES ($1, $2, $3)
+         ON CONFLICT DO NOTHING
+         RETURNING (xmax = 0) AS inserted`, [
+			opts.orgId,
+			envId,
+			opts.scopePattern
+		])).rows[0]?.inserted ?? false };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* UPDATE only the policy fields that were explicitly provided. Columns that
+* were NOT in `opts` are left untouched. Throws if the environment is missing.
+*/
+async function setEnvironmentPolicyDirect(databaseUrl, opts) {
+	if (opts.waitTimerSeconds != null && opts.waitTimerSeconds < 0) throw new Error(`environment: waitTimerSeconds must be >= 0 (got ${opts.waitTimerSeconds})`);
+	if (opts.holdExpirySeconds != null && opts.holdExpirySeconds < 0) throw new Error(`environment: holdExpirySeconds must be >= 0 (got ${opts.holdExpirySeconds})`);
+	const setClauses = [];
+	const params = [];
+	let idx = 1;
+	const addSet = (column, value, cast) => {
+		if (!ENV_POLICY_COLUMNS.has(column)) throw new Error(`environment: unknown policy column ${column}`);
+		setClauses.push(`${column} = $${idx}${cast ? `::${cast}` : ""}`);
+		params.push(value);
+		idx += 1;
+	};
+	if (opts.branchRestrictions !== void 0) addSet("branch_restrictions", JSON.stringify(opts.branchRestrictions), "jsonb");
+	if (opts.requiredReviewers !== void 0) addSet("required_reviewers", opts.requiredReviewers === null ? null : JSON.stringify(opts.requiredReviewers), "jsonb");
+	if (opts.waitTimerSeconds !== void 0) addSet("wait_timer_seconds", opts.waitTimerSeconds);
+	if (opts.holdExpirySeconds !== void 0) addSet("hold_expiry_seconds", opts.holdExpirySeconds);
+	if (opts.minimumTrust !== void 0) addSet("minimum_trust", opts.minimumTrust);
+	if (opts.enabled !== void 0) addSet("enabled", opts.enabled);
+	if (setClauses.length === 0) throw new Error("environment: setEnvironmentPolicy requires at least one policy field");
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		params.push(opts.orgId, opts.envName);
+		const orgParam = `$${idx}`;
+		const nameParam = `$${idx + 1}`;
+		const sql = `UPDATE environments
+                    SET ${setClauses.join(", ")}, updated_at = now()
+                    WHERE org_id = ${orgParam} AND name = ${nameParam}`;
+		if (((await pool.query(sql, params)).rowCount ?? 0) === 0) throw new Error(`environment: not found (org=${opts.orgId}, name=${opts.envName})`);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* SELECT * FROM environments WHERE org_id = $1, ordered by name.
+*/
+async function listEnvironmentsDirect(databaseUrl, opts) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		return { environments: (await pool.query(`SELECT id, org_id, name, type, enabled, branch_restrictions, required_reviewers,
+              wait_timer_seconds, hold_expiry_seconds, minimum_trust,
+              created_at, updated_at
+         FROM environments
+        WHERE org_id = $1
+        ORDER BY name`, [opts.orgId])).rows };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Fetch a single environment row joined with its variables and bindings.
+* Throws if the environment does not exist.
+*/
+async function showEnvironmentDirect(databaseUrl, opts) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		const envResult = await pool.query(`SELECT id, org_id, name, type, enabled, branch_restrictions, required_reviewers,
+              wait_timer_seconds, hold_expiry_seconds, minimum_trust,
+              created_at, updated_at
+         FROM environments
+        WHERE org_id = $1 AND name = $2`, [opts.orgId, opts.name]);
+		if (envResult.rows.length === 0) throw new Error(`environment: not found (org=${opts.orgId}, name=${opts.name})`);
+		const env = envResult.rows[0];
+		const variables = await pool.query(`SELECT key, value, locked, updated_at
+         FROM environment_variables
+        WHERE environment_id = $1
+        ORDER BY key`, [env.id]);
+		const bindings = await pool.query(`SELECT scope_pattern, created_at
+         FROM environment_bindings
+        WHERE environment_id = $1
+        ORDER BY scope_pattern`, [env.id]);
+		return {
+			environment: env,
+			variables: variables.rows,
+			bindings: bindings.rows
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Create (or update) an environment template + its seed variables in one
+* transaction. Templates are represented as environments with `type='template'`
+* by convention. Returns `{ envId, variablesSet }`.
+*/
+async function createEnvironmentTemplateDirect(databaseUrl, opts) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	const client = await pool.connect();
+	try {
+		await client.query("BEGIN");
+		const row = (await client.query(`INSERT INTO environments
+          (org_id, name, type, enabled, branch_restrictions, required_reviewers,
+           wait_timer_seconds, hold_expiry_seconds, minimum_trust)
+        VALUES ($1, $2, COALESCE($3, 'template'), true, $4::jsonb, $5::jsonb, $6, COALESCE($7, 86400), $8)
+        ON CONFLICT (org_id, name) DO UPDATE SET
+          type = COALESCE(EXCLUDED.type, environments.type),
+          branch_restrictions = EXCLUDED.branch_restrictions,
+          required_reviewers = EXCLUDED.required_reviewers,
+          wait_timer_seconds = EXCLUDED.wait_timer_seconds,
+          hold_expiry_seconds = EXCLUDED.hold_expiry_seconds,
+          minimum_trust = EXCLUDED.minimum_trust,
+          updated_at = now()
+        RETURNING id, (xmax = 0) AS inserted`, [
+			opts.orgId,
+			opts.templateName,
+			opts.type ?? null,
+			JSON.stringify(opts.branchRestrictions ?? []),
+			opts.requiredReviewers === void 0 ? null : JSON.stringify(opts.requiredReviewers),
+			opts.waitTimerSeconds ?? null,
+			opts.holdExpirySeconds ?? null,
+			opts.minimumTrust ?? null
+		])).rows[0];
+		if (!row) throw new Error(`environment: template upsert returned no row`);
+		let variablesSet = 0;
+		if (opts.variables) for (const [key, value] of Object.entries(opts.variables)) {
+			await client.query(`INSERT INTO environment_variables (org_id, environment_id, key, value, locked)
+             VALUES ($1, $2, $3, $4, false)
+             ON CONFLICT (org_id, environment_id, key) DO UPDATE SET
+               value = EXCLUDED.value,
+               updated_at = now()`, [
+				opts.orgId,
+				row.id,
+				key,
+				value
+			]);
+			variablesSet += 1;
+		}
+		await client.query("COMMIT");
+		return {
+			envId: row.id,
+			created: row.inserted,
+			variablesSet
+		};
+	} catch (err) {
+		await client.query("ROLLBACK").catch(() => void 0);
+		throw err;
+	} finally {
+		client.release();
+		await pool.end();
+	}
+}
+/**
+* UPSERT a scoped_secrets row keyed by (org_id, scope=environment, key).
+* Writes the value verbatim — the caller is responsible for encryption
+* (matches the stage-4 deferral noted in the plan).
+*/
+async function setEnvironmentSecretDirect(databaseUrl, opts) {
+	if (!opts.orgId) throw new Error("environment: orgId required");
+	if (!opts.environment) throw new Error("environment: environment name required");
+	if (!opts.key) throw new Error("environment: key required");
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		return { inserted: (await pool.query(`INSERT INTO scoped_secrets (org_id, scope, key, encrypted_value)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (org_id, scope, key) DO UPDATE SET
+           encrypted_value = EXCLUDED.encrypted_value,
+           updated_at = now()
+         RETURNING (xmax = 0) AS inserted`, [
+			opts.orgId,
+			opts.environment,
+			opts.key,
+			opts.encryptedValue
+		])).rows[0]?.inserted ?? false };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: SELECT from `dispatch_queue` with optional status + job-name
+* filters and a bounded limit (defaults to 100). Includes source_tar_url,
+* deps_url, and job_config so E2E tests can assert on cache metadata
+* without a second round-trip.
+*/
+async function listQueueDirect(databaseUrl, opts = {}) {
+	const pool = createPool(databaseUrl);
+	try {
+		const clauses = [];
+		const params = [];
+		let idx = 1;
+		if (opts.status !== void 0) {
+			clauses.push(`status = $${idx}`);
+			params.push(opts.status);
+			idx += 1;
+		}
+		if (opts.statusNotIn !== void 0 && opts.statusNotIn.length > 0) {
+			const placeholders = opts.statusNotIn.map(() => {
+				const p = `$${idx}`;
+				idx += 1;
+				return p;
+			});
+			clauses.push(`status NOT IN (${placeholders.join(",")})`);
+			params.push(...opts.statusNotIn);
+		}
+		if (opts.jobNamePrefix !== void 0) {
+			clauses.push(`job_name LIKE $${idx}`);
+			params.push(`${opts.jobNamePrefix}%`);
+			idx += 1;
+		}
+		if (opts.jobName !== void 0) {
+			clauses.push(`job_name = $${idx}`);
+			params.push(opts.jobName);
+			idx += 1;
+		}
+		if (opts.jobNameNotLike !== void 0) {
+			clauses.push(`job_name NOT LIKE $${idx}`);
+			params.push(opts.jobNameNotLike);
+			idx += 1;
+		}
+		if (opts.workflowName !== void 0) {
+			clauses.push(`workflow_name = $${idx}`);
+			params.push(opts.workflowName);
+			idx += 1;
+		}
+		if (opts.createdAfter !== void 0) {
+			clauses.push(`created_at > $${idx}`);
+			params.push(opts.createdAfter instanceof Date ? opts.createdAfter : new Date(opts.createdAfter));
+			idx += 1;
+		}
+		const limit = Math.max(1, Math.min(1e3, opts.limit ?? 100));
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+		return { entries: (await pool.query(`SELECT id, run_id, workflow_name, job_name, status, routing_key,
+              provider, created_at, expires_at, delivery_id,
+              source_tar_url, deps_url, job_config
+         FROM dispatch_queue
+         ${where}
+         ORDER BY created_at DESC
+         LIMIT ${limit}`, params)).rows };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: SELECT a single dispatch_queue row by id. Throws with a
+* clear message when no row matches.
+*/
+async function showQueueEntryDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const result = await pool.query(`SELECT id, run_id, workflow_name, job_name, status, routing_key,
+              provider, created_at, expires_at, delivery_id,
+              source_tar_url, deps_url, job_config
+         FROM dispatch_queue
+        WHERE id = $1`, [opts.id]);
+		if (result.rows.length === 0) throw new Error(`queue: entry not found (id=${opts.id})`);
+		return result.rows[0];
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: SELECT execution_runs with optional filters. Ordered by
+* created_at DESC, capped at a sensible limit.
+*/
+async function listExecutionRunsDirect(databaseUrl, opts = {}) {
+	const pool = createPool(databaseUrl);
+	try {
+		const clauses = [];
+		const params = [];
+		let idx = 1;
+		if (opts.routingKey !== void 0) {
+			clauses.push(`routing_key = $${idx}`);
+			params.push(opts.routingKey);
+			idx += 1;
+		}
+		if (opts.status !== void 0) {
+			clauses.push(`status = $${idx}`);
+			params.push(opts.status);
+			idx += 1;
+		}
+		if (opts.workflowName !== void 0) {
+			clauses.push(`workflow_name = $${idx}`);
+			params.push(opts.workflowName);
+			idx += 1;
+		}
+		const limit = Math.max(1, Math.min(1e3, opts.limit ?? 100));
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+		return { runs: (await pool.query(`SELECT id, run_id, workflow_name, status, provider, repo_identifier,
+              ref, sha, routing_key, environment, trust_tier, created_at,
+              started_at, completed_at, duration_ms
+         FROM execution_runs
+         ${where}
+         ORDER BY created_at DESC
+         LIMIT ${limit}`, params)).rows };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: fetch a single run by run_id AND its jobs. Throws if no run
+* matches the run_id. Jobs list may be empty for pending runs.
+*/
+async function showExecutionRunDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const runResult = await pool.query(`SELECT id, run_id, workflow_name, status, provider, repo_identifier,
+              ref, sha, routing_key, environment, trust_tier, created_at,
+              started_at, completed_at, duration_ms
+         FROM execution_runs
+        WHERE run_id = $1`, [opts.runId]);
+		if (runResult.rows.length === 0) throw new Error(`execution: run not found (run_id=${opts.runId})`);
+		const run = runResult.rows[0];
+		return {
+			run,
+			jobs: (await pool.query(`SELECT id, run_id, job_id, job_name, status, agent_id,
+              started_at, completed_at, duration_ms, created_at, error_message
+         FROM execution_jobs
+        WHERE run_id = $1
+        ORDER BY created_at ASC`, [run.run_id])).rows
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: list execution_jobs for a given execution_runs.id. Ordered by
+* created_at ASC so downstream diffs show timeline order.
+*/
+async function listExecutionJobsDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { jobs: (await pool.query(`SELECT j.id, j.run_id, j.job_id, j.job_name, j.status, j.agent_id,
+              j.started_at, j.completed_at, j.duration_ms, j.created_at, j.error_message
+         FROM execution_jobs j
+         INNER JOIN execution_runs r ON r.run_id = j.run_id
+        WHERE r.run_id::text = $1 OR r.id::text = $1
+        ORDER BY j.created_at ASC`, [opts.runId])).rows };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: list workflow_registrations with optional filters. Also returns
+* the latest registry_versions.version so callers can assert registry bumps
+* without a second round trip.
+*/
+async function listRegistrationsDirect(databaseUrl, opts = {}) {
+	const pool = createPool(databaseUrl);
+	try {
+		const clauses = [];
+		const params = [];
+		let idx = 1;
+		if (opts.customerId !== void 0) {
+			clauses.push(`customer_id = $${idx}`);
+			params.push(opts.customerId);
+			idx += 1;
+		}
+		if (opts.routingKey !== void 0) {
+			clauses.push(`routing_key = $${idx}`);
+			params.push(opts.routingKey);
+			idx += 1;
+		}
+		if (opts.repoIdentifier !== void 0) {
+			clauses.push(`repo_identifier = $${idx}`);
+			params.push(opts.repoIdentifier);
+			idx += 1;
+		}
+		if (opts.triggerType !== void 0) {
+			clauses.push(`$${idx} = ANY(trigger_types)`);
+			params.push(opts.triggerType);
+			idx += 1;
+		}
+		const limit = Math.max(1, Math.min(1e3, opts.limit ?? 100));
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+		const result = await pool.query(`SELECT id, repo_identifier, workflow_name, routing_key, customer_id,
+              trigger_types, disabled, is_global, commit_sha, source_file,
+              created_at, updated_at
+         FROM workflow_registrations
+         ${where}
+         ORDER BY updated_at DESC
+         LIMIT ${limit}`, params);
+		const versionResult = await pool.query(`SELECT version FROM registry_versions ORDER BY version DESC LIMIT 1`);
+		return {
+			registrations: result.rows,
+			registryVersion: versionResult.rows[0]?.version ?? null
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: show one workflow_registrations row by id, plus the latest
+* registry_versions row (the monotonic version bumped on every registration
+* insert/delete). Throws if the registration id is unknown.
+*/
+async function showRegistrationDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const result = await pool.query(`SELECT id, repo_identifier, workflow_name, routing_key, customer_id,
+              trigger_types, disabled, is_global, commit_sha, source_file,
+              created_at, updated_at, lock_entry, provider_context
+         FROM workflow_registrations
+        WHERE id = $1`, [opts.id]);
+		if (result.rows.length === 0) throw new Error(`registration: not found (id=${opts.id})`);
+		const registryVersion = (await pool.query(`SELECT version FROM registry_versions ORDER BY version DESC LIMIT 1`)).rows[0]?.version ?? null;
+		return {
+			registration: result.rows[0],
+			registryVersion
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Registerable trigger types. Kept in sync with
+* packages/orchestrator/src/registration/extractor.ts — any trigger whose type
+* is in this set (or which pins `repos: [...]` patterns) produces a
+* workflow_registrations row on default-branch push extraction.
+*
+* Duplicated here intentionally so the helper has no runtime dependency on
+* the engine package.
+*/
+const REGISTERABLE_TRIGGER_TYPES = new Set([
+	"push",
+	"pr",
+	"pull_request",
+	"tag",
+	"release",
+	"schedule",
+	"kici_event",
+	"webhook",
+	"repository_dispatch",
+	"issue_comment",
+	"pull_request_review"
+]);
+/**
+* Transactionally upsert `workflow_registrations` rows from a lock file and
+* bump `registry_versions.version`. Mirrors the orchestrator's
+* RegistrationStore.replaceAll() path but runs offline — the E2E test helpers
+* `seedWorkflowRegistrationsFromLockFile` called this pattern via raw pg.Pool
+* before this helper existed.
+*
+* Writes one row per registerable workflow (UPSERT by
+* (routing_key, repo_identifier, workflow_name)), then bumps
+* `registry_versions` in the same transaction so orchestrator processes
+* watching that row refresh their in-memory index.
+*/
+async function registerWorkflowManualDirect(databaseUrl, opts) {
+	let lockFile;
+	if (opts.lockFile !== void 0) lockFile = opts.lockFile;
+	else if (opts.lockFileContents !== void 0) try {
+		lockFile = JSON.parse(opts.lockFileContents);
+	} catch (err) {
+		throw new Error(`registration: lockFileContents is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	else throw new Error("registration: either lockFileContents or lockFile must be provided");
+	if (!Array.isArray(lockFile.workflows)) throw new Error("registration: lock file missing workflows[] array");
+	const hasRepoPatterns = (t) => Array.isArray(t.repos) && t.repos.length > 0;
+	const registerable = lockFile.workflows.filter((w) => w.triggers.some((t) => REGISTERABLE_TRIGGER_TYPES.has(t._type) || hasRepoPatterns(t)));
+	const pool = createPool(databaseUrl);
+	const client = await pool.connect();
+	try {
+		await client.query("BEGIN");
+		for (const workflow of registerable) {
+			const triggerTypes = [...new Set(workflow.triggers.map((t) => t._type))];
+			await client.query(`INSERT INTO workflow_registrations (
+          repo_identifier, workflow_name, lock_entry, trigger_types,
+          routing_key, provider_context, customer_id, commit_sha, source_file
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+        ON CONFLICT (routing_key, repo_identifier, workflow_name) DO UPDATE SET
+          lock_entry = EXCLUDED.lock_entry,
+          trigger_types = EXCLUDED.trigger_types,
+          provider_context = EXCLUDED.provider_context,
+          customer_id = EXCLUDED.customer_id,
+          commit_sha = EXCLUDED.commit_sha,
+          source_file = EXCLUDED.source_file,
+          updated_at = NOW()`, [
+				opts.repoIdentifier,
+				workflow.name,
+				JSON.stringify(workflow),
+				triggerTypes,
+				opts.routingKey,
+				JSON.stringify(opts.providerContext),
+				opts.customerId,
+				opts.commitSha ?? null,
+				`.kici/workflows/${workflow.name}.ts`
+			]);
+		}
+		const registryVersion = (await client.query(`INSERT INTO registry_versions (id, version) VALUES ('default', 1)
+       ON CONFLICT (id) DO UPDATE SET version = registry_versions.version + 1, updated_at = NOW()
+       RETURNING version`)).rows[0].version;
+		await client.query("COMMIT");
+		return {
+			workflowCount: registerable.length,
+			registryVersion
+		};
+	} catch (err) {
+		await client.query("ROLLBACK").catch(() => {});
+		throw err;
+	} finally {
+		client.release();
+		await pool.end();
+	}
+}
+/**
+* DELETE all rows from `raft_state` so a freshly-started orchestrator
+* self-elects with a clean term. Used after swapping the running
+* orchestrator process (warm-mode deploys) — without this, the new
+* process loads a high term and takes 60+ seconds cycling through
+* failed election rounds. Returns the number of rows deleted.
+*
+* Safe for repeated calls — if the table is empty, returns 0.
+*/
+async function resetRaftStateDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { rowsDeleted: (await pool.query("DELETE FROM raft_state")).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* INSERT a row into `kici_events` and fire `pg_notify('kici_event_channel', <id>)`
+* so the orchestrator EventRouter picks it up immediately. Used by Bucket B/C
+* e2e helpers to simulate what `agent ctx.emit()` does from inside a step
+* execution — but without needing an actual running step. Returns the event id.
+*
+* Fixed `chain_depth=0` and `expires_at=NOW() + 1h` match emitInternalEvent()
+* in e2e/helpers/internal-webhook.ts, which this helper supersedes.
+*/
+async function emitKiciEventDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const eventId = (await pool.query(`INSERT INTO kici_events (
+        event_name, payload, source_routing_key, source_repo,
+        chain_depth, expires_at
+      )
+      VALUES ($1, $2, $3, $4, 0, NOW() + INTERVAL '1 hour')
+      RETURNING id`, [
+			opts.eventName,
+			JSON.stringify(opts.payload),
+			opts.sourceRoutingKey ?? "",
+			opts.sourceRepo ?? ""
+		])).rows[0].id;
+		await pool.query(`SELECT pg_notify('kici_event_channel', $1)`, [eventId]);
+		return { eventId };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Upsert a row into `generic_webhook_sources` for internal E2E tests. Uses
+* `ON CONFLICT (routing_key) DO UPDATE` so warm-start mode (where the source
+* may already exist from a prior run) is idempotent.
+*
+* IMPORTANT: callers must invoke this BEFORE the orchestrator starts, because
+* GenericSourceManager caches sources at boot and does not reload them later.
+* This helper supersedes seedGenericWebhookSource() in
+* e2e/helpers/internal-webhook.ts.
+*/
+async function seedGenericWebhookSourceDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO generic_webhook_sources (
+        id, customer_id, name, routing_key,
+        verification_method, verification_config,
+        event_type_header, dedup_window_seconds,
+        max_payload_bytes, rate_limit_rpm, enabled,
+        provider_type
+      ) VALUES ($1, $2, $3, $4, $5, '{}', 'x-event-type', 300, 10485760, 600, true, $6)
+      ON CONFLICT (routing_key) DO UPDATE SET
+        customer_id = EXCLUDED.customer_id,
+        name = EXCLUDED.name,
+        verification_method = EXCLUDED.verification_method,
+        verification_config = EXCLUDED.verification_config,
+        provider_type = EXCLUDED.provider_type,
+        enabled = true,
+        deleted_at = NULL,
+        updated_at = NOW()`, [
+			opts.sourceId,
+			opts.orgId,
+			opts.name,
+			opts.routingKey,
+			opts.verificationMethod ?? "none",
+			opts.providerType ?? "generic"
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Return `{ current: true }` if the applied migration count matches the
+* provider's migration count AND the content hash in `_migration_content_hash`
+* matches the provider's current hash. Otherwise return `{ current: false,
+* reason }` with a human-readable reason.
+*
+* Callers use this as a warm-start freshness gate — if not current, do a cold
+* start (`db fresh`).
+*/
+async function isSchemaCurrent(pool, provider) {
+	const migrations = await provider.getMigrations();
+	const expectedCount = Object.keys(migrations).length;
+	let appliedCount;
+	try {
+		appliedCount = (await pool.query("SELECT COUNT(*)::int AS count FROM \"kysely_migration\"")).rows[0]?.count ?? 0;
+	} catch {
+		return {
+			current: false,
+			reason: "kysely_migration table missing"
+		};
+	}
+	if (appliedCount !== expectedCount) return {
+		current: false,
+		reason: `migration count mismatch (applied=${appliedCount}, expected=${expectedCount})`
+	};
+	const expectedHash = await computeMigrationsHash(provider);
+	const storedHash = await readStoredMigrationContentHash(pool);
+	if (storedHash !== expectedHash) return {
+		current: false,
+		reason: storedHash === null ? "content hash missing" : "content hash mismatch"
+	};
+	return { current: true };
+}
+/**
+* Purge backends whose encrypted `config` column can no longer be decrypted
+* (e.g. warm-start E2E where KICI_SECRET_KEY rotated between categories).
+*
+* Only rows with a non-empty `config_encrypted` are affected — the default
+* `pg` backend is seeded by the initial migration with `config_encrypted = ''`
+* as a sentinel (loadAllStores() skips decryption for it), so it is never the
+* source of the decryption failure and must be preserved. Deleting it breaks
+* downstream tests that rely on the default backend being registered.
+*/
+async function purgeSecretBackendsDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query("DELETE FROM secret_backends WHERE config_encrypted IS NOT NULL AND config_encrypted <> ''")).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Check if an API key exists in the Platform DB (api_keys table — orchestrator-
+* managed, NOT user_api_keys). Returns true when a row matches the hashed key.
+*/
+async function apiKeyExistsDirect(databaseUrl, apiKey) {
+	const keyHash = createHash("sha256").update(apiKey).digest("hex");
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query("SELECT 1 FROM api_keys WHERE key_hash = $1", [keyHash])).rows.length > 0;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Insert an api_keys row (Platform-side orchestrator credential). Used by
+* e2e setup to seed an orchestrator authentication token. Returns the id.
+*/
+async function seedApiKeyInlineDirect(databaseUrl, opts) {
+	const keyHash = createHash("sha256").update(opts.fullKey).digest("hex");
+	const keyPrefix = opts.fullKey.slice(0, 16);
+	const pool = createPool(databaseUrl);
+	try {
+		return { keyId: (await pool.query(`INSERT INTO api_keys (key_hash, key_prefix, name, org_id)
+       VALUES ($1, $2, $3, $4)
+       RETURNING id`, [
+			keyHash,
+			keyPrefix,
+			opts.keyName,
+			opts.orgId
+		])).rows[0].id };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Lookup a `platform_connections` row by connection_id. Returns true when
+* present. Used by the orphan-sweeper e2e test.
+*/
+async function platformConnectionExistsDirect(databaseUrl, connectionId) {
+	const pool = createPool(databaseUrl);
+	try {
+		const res = await pool.query(`SELECT 1 FROM platform_connections WHERE connection_id = $1 LIMIT 1`, [connectionId]);
+		return res.rowCount !== null && res.rowCount > 0;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Count `webhook_sources` rows for a given orchestrator_connection_id.
+* Used by the orphan-sweeper e2e test to assert the FK CASCADE introduced
+* by Platform migration 017 actually fires when the parent
+* `platform_connections` row is deleted.
+*/
+async function countWebhookSourcesByConnectionIdDirect(databaseUrl, connectionId) {
+	const pool = createPool(databaseUrl);
+	try {
+		const res = await pool.query(`SELECT COUNT(*)::int AS cnt
+         FROM webhook_sources
+         WHERE orchestrator_connection_id = $1`, [connectionId]);
+		return Number(res.rows[0]?.cnt ?? 0);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Find a `user_api_keys.id` preferring rows scoped to `preferredOrgId`, else
+* any row in the table. Used by orphan-sweeper test to get a realistic
+* `key_id` for platform_connections seeding.
+*/
+async function findAnyUserApiKeyIdDirect(databaseUrl, preferredOrgId) {
+	const pool = createPool(databaseUrl);
+	try {
+		const scoped = await pool.query(`SELECT id FROM user_api_keys WHERE org_id = $1 LIMIT 1`, [preferredOrgId]);
+		if (scoped.rows.length > 0) return String(scoped.rows[0].id);
+		const any = await pool.query(`SELECT id FROM user_api_keys LIMIT 1`);
+		return any.rows.length > 0 ? String(any.rows[0].id) : null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Seed or refresh a synthetic GitHub webhook source on the Platform DB.
+* Used by HMAC E2E tests that post to `/webhook/:orgId/github`.
+* Idempotent — refreshes the secret/org_id via ON CONFLICT DO UPDATE,
+* and clears stale rows with a different routing_key under the same
+* (org_id, provider, connection_id) triple.
+*/
+async function seedSyntheticGithubSourceDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO platform_connections (
+         org_id, instance_id, connection_id, key_id, routing_keys
+       )
+       VALUES ($1, 'e2e-synthetic-instance', 'e2e-synthetic',
+               '00000000-0000-4000-8000-000000000000', $2::text)
+       ON CONFLICT (connection_id) DO UPDATE
+         SET org_id = $1,
+             routing_keys = $2::text,
+             last_heartbeat_at = NOW()`, [opts.orgId, JSON.stringify([opts.routingKey])]);
+		await pool.query(`DELETE FROM webhook_sources
+       WHERE org_id = $1 AND provider = 'github'
+         AND orchestrator_connection_id = 'e2e-synthetic'
+         AND routing_key != $2`, [opts.orgId, opts.routingKey]);
+		await pool.query(`INSERT INTO webhook_sources (routing_key, provider, orchestrator_connection_id, org_id)
+       VALUES ($1, 'github', 'e2e-synthetic', $2)
+       ON CONFLICT (routing_key, orchestrator_connection_id) DO UPDATE SET org_id = $2`, [opts.routingKey, opts.orgId]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Seed a webhook secret into the orchestrator's `scoped_secrets` table,
+* encrypted with the caller-supplied key. Ensures a `sources` row exists
+* for the routing_key. Used by e2e setup on the orchestrator DB side.
+*
+* encryptFn takes plaintext + AAD and returns ciphertext bytes. The
+* caller owns the crypto primitive so this helper stays decoupled from
+* the orchestrator's PgSecretStore crypto module.
+*/
+async function seedWebhookSecretDirect(databaseUrl, opts) {
+	const { randomBytes } = await import("node:crypto");
+	const pool = createPool(databaseUrl);
+	try {
+		let sourceId;
+		const sourceResult = await pool.query("SELECT id FROM sources WHERE routing_key = $1", [opts.routingKey]);
+		if (sourceResult.rows.length > 0) sourceId = sourceResult.rows[0].id;
+		else {
+			sourceId = randomBytes(16).toString("hex");
+			const [provider, appId] = opts.routingKey.split(":");
+			await pool.query(`INSERT INTO sources (id, provider, name, routing_key, config)
+         VALUES ($1, $2, $3, $4, $5)
+         ON CONFLICT (routing_key) DO NOTHING`, [
+				sourceId,
+				provider || "github",
+				`e2e-${appId}`,
+				opts.routingKey,
+				JSON.stringify({ appId: appId || "" })
+			]);
+			sourceId = (await pool.query("SELECT id FROM sources WHERE routing_key = $1", [opts.routingKey])).rows[0].id;
+		}
+		const scope = `__source__/${sourceId}`;
+		const orgId = "__system__";
+		const aad = `${orgId}:${scope}:webhookSecret`;
+		const encrypted = opts.encryptFn(opts.webhookSecret, aad);
+		await pool.query(`INSERT INTO scoped_secrets (org_id, scope, key, encrypted_value, backend_type, key_version)
+       VALUES ($1, $2, 'webhookSecret', $3, 'pg', 1)
+       ON CONFLICT (org_id, scope, key) DO UPDATE SET encrypted_value = $3, updated_at = now()`, [
+			orgId,
+			scope,
+			encrypted
+		]);
+		return { sourceId };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Seed a source private key into the orchestrator's `scoped_secrets` table.
+* encryptFn signature matches seedWebhookSecretDirect. Returns null if the
+* sources row is missing (matches legacy warning-and-skip behaviour).
+*/
+async function seedSourcePrivateKeyDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const sourceResult = await pool.query("SELECT id FROM sources WHERE routing_key = $1", [opts.routingKey]);
+		if (sourceResult.rows.length === 0) return null;
+		const sourceId = sourceResult.rows[0].id;
+		const scope = `__source__/${sourceId}`;
+		const orgId = "__system__";
+		const aad = `${orgId}:${scope}:privateKey`;
+		const encrypted = opts.encryptFn(opts.privateKey, aad);
+		await pool.query(`INSERT INTO scoped_secrets (org_id, scope, key, encrypted_value, backend_type, key_version)
+       VALUES ($1, $2, 'privateKey', $3, 'pg', 1)
+       ON CONFLICT (org_id, scope, key) DO UPDATE SET encrypted_value = $3, updated_at = now()`, [
+			orgId,
+			scope,
+			encrypted
+		]);
+		return { sourceId };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Bump `registry_versions.version` for the default registry and return the
+* new value. Used by cron-scheduler e2e to retrigger index after a manual
+* workflow change.
+*/
+async function bumpRegistryVersionDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`UPDATE registry_versions
+       SET version = version + 1, updated_at = NOW()
+       WHERE id = 'default'
+       RETURNING version`)).rows[0].version;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Poll `kici_events` for an event matching `eventName` created after `since`.
+* Returns the newest match, or throws on timeout. Used by e2e event-routing tests.
+*/
+async function pollKiciEventsDirect(databaseUrl, opts) {
+	const timeoutMs = opts.timeoutMs ?? 6e4;
+	const pollInterval = opts.pollIntervalMs ?? 2e3;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		while (Date.now() < deadline) {
+			const filter = opts.payloadFilter;
+			const result = filter ? await pool.query(`SELECT * FROM kici_events
+             WHERE event_name = $1 AND created_at > $2 AND payload->>$3 = $4
+             ORDER BY created_at DESC
+             LIMIT 1`, [
+				opts.eventName,
+				opts.since.toISOString(),
+				filter.key,
+				filter.value
+			]) : await pool.query(`SELECT * FROM kici_events
+             WHERE event_name = $1 AND created_at > $2
+             ORDER BY created_at DESC
+             LIMIT 1`, [opts.eventName, opts.since.toISOString()]);
+			if (result.rows.length > 0) return result.rows[0];
+			await new Promise((r) => setTimeout(r, pollInterval));
+		}
+		throw new Error(`Timed out after ${timeoutMs}ms waiting for kici_event '${opts.eventName}' since ${opts.since.toISOString()}`);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Ping a PostgreSQL database; retries until `SELECT 1` succeeds or the
+* timeout expires. Used by e2e startup to wait for Postgres readiness.
+*/
+async function waitForPostgresDirect(databaseUrl, opts) {
+	const timeout = opts?.timeoutMs ?? 3e4;
+	const interval = opts?.intervalMs ?? 2e3;
+	const deadline = Date.now() + timeout;
+	while (Date.now() < deadline) {
+		const pool = createPool(databaseUrl);
+		try {
+			await pool.query("SELECT 1");
+			await pool.end();
+			return;
+		} catch {
+			await pool.end();
+		}
+		await new Promise((r) => setTimeout(r, interval));
+	}
+	throw new Error(`PostgreSQL at ${databaseUrl} did not become available within ${timeout}ms`);
+}
+/**
+* Wait for a specific execution_runs row to reach a terminal status.
+* Used by test-pipeline e2e to gate on run completion. Terminal statuses
+* are success / failed / cancelled / timed_out_stale.
+*/
+async function waitForRunCompletionDirect(databaseUrl, runId, opts) {
+	const timeoutMs = opts?.timeoutMs ?? 12e4;
+	const intervalMs = opts?.intervalMs ?? 2e3;
+	const terminalStatuses = [
+		"success",
+		"failed",
+		"cancelled",
+		"timed_out_stale"
+	];
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		while (Date.now() < deadline) {
+			const result = await pool.query(`SELECT status FROM execution_runs WHERE run_id = $1 LIMIT 1`, [runId]);
+			if (result.rows.length > 0) {
+				const status = result.rows[0].status;
+				if (terminalStatuses.includes(status)) return { status };
+			}
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		throw new Error(`Run ${runId} did not complete within ${timeoutMs}ms`);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE from execution_jobs + execution_runs where started_at > since.
+* Used by e2e cleanup for tests that want explicit post-test row cleanup.
+*/
+async function cleanupExecutionRowsDirect(databaseUrl, since) {
+	const pool = createPool(databaseUrl);
+	try {
+		const jobsResult = await pool.query(`DELETE FROM execution_jobs WHERE run_id IN (
+        SELECT run_id FROM execution_runs WHERE started_at > $1
+      )`, [since]);
+		return {
+			runs: (await pool.query(`DELETE FROM execution_runs WHERE started_at > $1`, [since])).rowCount ?? 0,
+			jobs: jobsResult.rowCount ?? 0
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Check whether the schema is "current" by comparing applied migration count
+* and content hash against a caller-supplied set of migration files.
+* Returns false if the migration table is missing, counts mismatch, or the
+* stored hash differs from the caller-supplied hash. Used by e2e warm-start.
+*/
+async function isSchemaCurrentFromFilesDirect(databaseUrl, opts) {
+	const tableName = opts.tableName ?? "kysely_migration";
+	const pool = createPool(databaseUrl);
+	try {
+		try {
+			if (((await pool.query(`SELECT COUNT(*)::int AS count FROM "${tableName}"`)).rows[0]?.count ?? 0) !== opts.expectedCount) return false;
+			const hashResult = await pool.query(`SELECT hash FROM ${MIGRATION_HASH_TABLE} WHERE table_name = $1`, [tableName]);
+			if (hashResult.rows.length === 0 || hashResult.rows[0].hash !== opts.expectedContentHash) return false;
+			return true;
+		} catch {
+			return false;
+		}
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Store a migration content hash in the `_migration_content_hash` marker
+* table. Creates the table if missing. Used by e2e freshDatabase() after
+* migrations run so warm-start detection can compare on next run.
+*/
+async function storeMigrationContentHashInTableDirect(databaseUrl, opts) {
+	const tableName = opts.tableName ?? "kysely_migration";
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`
+      CREATE TABLE IF NOT EXISTS ${MIGRATION_HASH_TABLE} (
+        table_name text PRIMARY KEY,
+        hash text NOT NULL
+      )
+    `);
+		await pool.query(`INSERT INTO ${MIGRATION_HASH_TABLE} (table_name, hash) VALUES ($1, $2)
+       ON CONFLICT (table_name) DO UPDATE SET hash = $2`, [tableName, opts.contentHash]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Insert a join_tokens row (orchestrator DB) for cluster peer auth.
+* Used by cluster e2e helpers to provision a shared secret the second
+* orchestrator will use when joining the cluster.
+*/
+async function createJoinTokenDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO join_tokens (id, token_hash, routing_info, role, created_by, expires_at)
+       VALUES ($1, $2, $3, $4, $5, $6)`, [
+			opts.id,
+			opts.tokenHash,
+			JSON.stringify(opts.routingInfo),
+			opts.role,
+			opts.createdBy,
+			opts.expiresAt
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Update the routing_key on `sources` rows for a given provider. Used by
+* cluster e2e to swap the staging routing key for an isolated test key
+* (and to restore it on teardown).
+*
+* `whereRoutingKey`: optional filter on the current routing_key. When
+* present only rows matching it are updated; when absent the provider
+* filter alone is used (with an implicit `!= newRoutingKey` guard so the
+* update is idempotent).
+*/
+async function updateSourceRoutingKeyDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { updated: (opts.whereRoutingKey ? await pool.query(`UPDATE sources SET routing_key = $1 WHERE provider = $2 AND routing_key = $3`, [
+			opts.newRoutingKey,
+			opts.provider,
+			opts.whereRoutingKey
+		]) : await pool.query(`UPDATE sources SET routing_key = $1 WHERE provider = $2 AND routing_key != $1`, [opts.newRoutingKey, opts.provider])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Delete peer_credentials rows whose instance_id does NOT match a pattern.
+* Used by cluster e2e to wipe stale staging peer credentials while leaving
+* e2e-* peers intact.
+*/
+async function prunePeerCredentialsDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query(`DELETE FROM peer_credentials WHERE instance_id NOT LIKE $1`, [opts.keepInstanceIdPattern])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Poll Platform until at least `minRegistrations` distinct orchestrator
+* connections are BOTH registered for the routing key (row in webhook_sources)
+* AND live (row in platform_connections with status='connected'). The live-
+* connection join is critical — Platform's webhook_sources rows persist after
+* a connection disconnects (the orphan sweeper eventually reaps them), so a
+* naive COUNT(DISTINCT) on webhook_sources alone would inflate the number
+* and mask a missing coordinator registration.
+*/
+async function waitForPlatformRegistrationsDirect(platformDbUrl, routingKey, opts) {
+	const minRegistrations = opts?.minRegistrations ?? 1;
+	const timeoutMs = opts?.timeoutMs ?? 3e4;
+	const intervalMs = opts?.intervalMs ?? 2e3;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(platformDbUrl);
+	try {
+		while (Date.now() < deadline) {
+			if (((await pool.query(`SELECT COUNT(DISTINCT ws.orchestrator_connection_id)::int AS cnt
+           FROM webhook_sources ws
+           JOIN platform_connections pc
+             ON pc.connection_id = ws.orchestrator_connection_id
+            AND pc.status = 'connected'
+          WHERE ws.routing_key = $1
+            AND ws.orchestrator_connection_id != 'e2e-synthetic'`, [routingKey])).rows[0]?.cnt ?? 0) >= minRegistrations) return;
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		throw new Error(`Timed out waiting for ${minRegistrations} orchestrator registration(s) for routing key ${routingKey} (waited ${timeoutMs}ms)`);
+	} finally {
+		await pool.end();
+	}
+}
+async function seedUniversalGitSourceDirect(databaseUrl, opts) {
+	const eventTypeHeader = opts.eventTypeHeader ?? "x-gitea-event";
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO generic_webhook_sources (
+        id, customer_id, name, routing_key,
+        verification_method, verification_config,
+        event_type_header, dedup_window_seconds,
+        max_payload_bytes, rate_limit_rpm, enabled,
+        provider_type, git_config
+      ) VALUES ($1, $2, $3, $4, 'none', '{}', $6, 300, 10485760, 600, true,
+                'generic', $5::jsonb)
+      ON CONFLICT (routing_key) DO UPDATE SET
+        customer_id = EXCLUDED.customer_id,
+        name = EXCLUDED.name,
+        event_type_header = EXCLUDED.event_type_header,
+        git_config = EXCLUDED.git_config,
+        enabled = true,
+        deleted_at = NULL,
+        updated_at = NOW()`, [
+			opts.sourceId,
+			opts.orgId,
+			opts.sourceName,
+			opts.routingKey,
+			JSON.stringify(opts.gitConfig),
+			eventTypeHeader
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+async function seedCiSecurityFixturesDirect(databaseUrl, opts) {
+	const envName = opts.envName ?? "ci-security-env";
+	const sourceName = opts.sourceName ?? "ci-security-dashboard-resolver";
+	const sourceRoutingKey = opts.sourceRoutingKey ?? `generic:${opts.orgId}:ci-security-dashboard`;
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO sources (id, provider, name, routing_key, config, customer_id)
+       VALUES (gen_random_uuid(), \'generic\', $1, $2, \'{}\', $3)
+       ON CONFLICT (routing_key) DO UPDATE SET customer_id = EXCLUDED.customer_id`, [
+			sourceName,
+			sourceRoutingKey,
+			opts.orgId
+		]);
+		const envId = (await pool.query(`INSERT INTO environments (org_id, name, type, enabled)
+       VALUES ($1, $2, \'fixed\', true)
+       ON CONFLICT (org_id, name) DO UPDATE SET enabled = true
+       RETURNING id`, [opts.orgId, envName])).rows[0].id;
+		await pool.query(`INSERT INTO execution_runs (
+        run_id, workflow_name, provider, repo_identifier,
+        ref, sha, delivery_id, status, trust_tier, lock_file_source,
+        contributor_username, routing_key
+      ) VALUES ($1, \'e2e-security-wf\', \'internal\', \'.\', \'refs/heads/feature\',
+        \'abc123\', $2, \'pending\', \'unknown\', \'base\', \'unknown-dev\', $3)`, [
+			opts.unknownRunId,
+			opts.unknownDeliveryId,
+			opts.runsRoutingKey
+		]);
+		await pool.query(`INSERT INTO execution_jobs (job_id, run_id, job_name, status)
+       VALUES ($1, $2, \'security-test-job\', \'pending\')`, [opts.unknownJobId, opts.unknownRunId]);
+		const heldRunId = (await pool.query(`INSERT INTO held_runs (org_id, run_id, job_id, environment_id, hold_type, queue_type, reason, expires_at)
+       VALUES ($1, $2, $3, $4, \'unknown_contributor\', \'security\',
+        \'Unknown contributor requires approval\', NOW() + INTERVAL \'72 hours\')
+       RETURNING id`, [
+			opts.orgId,
+			opts.unknownRunId,
+			opts.unknownJobId,
+			envId
+		])).rows[0].id;
+		await pool.query(`INSERT INTO execution_runs (
+        run_id, workflow_name, provider, repo_identifier,
+        ref, sha, delivery_id, status, trust_tier, lock_file_source,
+        contributor_username, routing_key
+      ) VALUES ($1, \'e2e-security-wf\', \'internal\', \'.\', \'refs/heads/feature\',
+        \'def456\', $2, \'running\', \'trusted\', \'head\', \'trusted-dev\', $3)`, [
+			opts.trustedRunId,
+			opts.trustedDeliveryId,
+			opts.runsRoutingKey
+		]);
+		await pool.query(`INSERT INTO execution_jobs (job_id, run_id, job_name, status)
+       VALUES ($1, $2, \'security-test-job\', \'running\')`, [opts.trustedJobId, opts.trustedRunId]);
+		return {
+			envId,
+			heldRunId
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Poll `execution_runs` for at least one row matching `status` whose
+* `started_at > since`. Used by cluster/job-reroute tests to gate on
+* a workflow reaching the terminal state after a webhook trigger.
+*/
+async function waitForExecutionRunStatusSinceDirect(databaseUrl, opts) {
+	const timeoutMs = opts.timeoutMs ?? 12e4;
+	const intervalMs = opts.intervalMs ?? 5e3;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		while (Date.now() < deadline) {
+			if ((await pool.query(`SELECT 1 FROM execution_runs
+         WHERE started_at > $1 AND status = $2
+         LIMIT 1`, [opts.since, opts.status])).rows.length > 0) return { found: true };
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		return { found: false };
+	} finally {
+		await pool.end();
+	}
+}
+async function latestExecutionRunByStatusDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const runResult = await pool.query(`SELECT run_id, workflow_name, status FROM execution_runs
+       WHERE status = $1
+       ORDER BY started_at DESC LIMIT 1`, [opts.status]);
+		if (runResult.rows.length === 0) return null;
+		const run = runResult.rows[0];
+		return {
+			run,
+			jobs: (await pool.query(`SELECT job_id, job_name, status FROM execution_jobs WHERE run_id = $1`, [run.run_id])).rows
+		};
+	} finally {
+		await pool.end();
+	}
+}
+async function waitForLatestExecutionJobStatusDirect(databaseUrl, opts) {
+	const terminal = opts.terminalStatuses ?? [
+		"success",
+		"completed",
+		"failed"
+	];
+	const timeoutMs = opts.timeoutMs ?? 18e4;
+	const intervalMs = opts.intervalMs ?? 3e3;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		let status = null;
+		let errorMessage = null;
+		let runId = null;
+		while (Date.now() < deadline) {
+			const result = await pool.query(`SELECT j.status, j.error_message, r.run_id
+           FROM execution_jobs j
+           JOIN execution_runs r ON r.run_id = j.run_id
+          WHERE r.workflow_name = $1
+            AND r.started_at >= $2
+          ORDER BY r.started_at DESC
+          LIMIT 1`, [opts.workflowName, opts.since]);
+			if (result.rows.length > 0) {
+				status = result.rows[0].status;
+				errorMessage = result.rows[0].error_message;
+				runId = result.rows[0].run_id;
+				if (status && terminal.includes(status)) break;
+			}
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		return {
+			status,
+			errorMessage,
+			runId
+		};
+	} finally {
+		await pool.end();
+	}
+}
+async function describeTableColumnsDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT column_name, data_type FROM information_schema.columns
+        WHERE table_name = $1
+        ORDER BY ordinal_position`, [opts.tableName])).rows.map((r) => ({
+			name: r.column_name,
+			dataType: r.data_type
+		}));
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: return true if a table exists in the public schema.
+*/
+async function tableExistsDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT 1 FROM information_schema.tables
+        WHERE table_schema = $1 AND table_name = $2`, [opts.schema ?? "public", opts.tableName])).rows.length > 0;
+	} finally {
+		await pool.end();
+	}
+}
+async function insertKiciEventRawDirect(databaseUrl, opts) {
+	const expiresIn = opts.expiresIn ?? "1 hour";
+	const pool = createPool(databaseUrl);
+	try {
+		return { id: (await pool.query(`INSERT INTO kici_events (event_name, payload, source_routing_key, chain_depth, expires_at)
+       VALUES ($1, $2, $3, $4, NOW() + ($5)::interval)
+       RETURNING id`, [
+			opts.eventName,
+			JSON.stringify(opts.payload),
+			opts.sourceRoutingKey ?? null,
+			opts.chainDepth ?? 0,
+			expiresIn
+		])).rows[0].id };
+	} finally {
+		await pool.end();
+	}
+}
+async function showKiciEventDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT id, event_name, payload, chain_depth, source_routing_key,
+              source_repo, processed, expires_at, created_at
+         FROM kici_events WHERE id = $1`, [opts.id])).rows[0] ?? null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: list kici_events with filter hooks used by e2e tests:
+* by `event_name`, minimum `chain_depth`, expiry window. Returns the
+* rows with chain_depth ordered ascending. Callers apply assertions.
+*/
+async function listKiciEventsDirect(databaseUrl, opts = {}) {
+	const pool = createPool(databaseUrl);
+	try {
+		const clauses = [];
+		const params = [];
+		let idx = 1;
+		if (opts.eventName !== void 0) {
+			clauses.push(`event_name = $${idx}`);
+			params.push(opts.eventName);
+			idx += 1;
+		}
+		if (opts.minChainDepth !== void 0) {
+			clauses.push(`chain_depth > $${idx}`);
+			params.push(opts.minChainDepth);
+			idx += 1;
+		}
+		if (opts.onlyExpired) clauses.push(`expires_at < NOW()`);
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+		const limit = Math.max(1, Math.min(1e4, opts.limit ?? 1e3));
+		return (await pool.query(`SELECT id, event_name, payload, chain_depth, source_routing_key,
+              source_repo, processed, expires_at, created_at
+         FROM kici_events
+         ${where}
+         ORDER BY chain_depth ASC, created_at ASC
+         LIMIT ${limit}`, params)).rows;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE kici_events by id or event_name. Returns the number of rows
+* deleted. Used by event-routing teardown.
+*/
+async function deleteKiciEventsDirect(databaseUrl, opts) {
+	if (!opts.id && !opts.eventName) throw new Error("deleteKiciEventsDirect: one of {id, eventName} is required");
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (opts.id ? await pool.query(`DELETE FROM kici_events WHERE id = $1`, [opts.id]) : await pool.query(`DELETE FROM kici_events WHERE event_name = $1`, [opts.eventName])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Simulate a NOTIFY on `kici_event_channel` and verify a LISTEN client
+* receives it. Used by event-routing e2e to prove the infrastructure
+* the EventRouter uses for real-time delivery is functional. Owns the
+* pool for the full test to keep the listen/notify correlated.
+*/
+async function verifyKiciEventNotifyDirect(databaseUrl, opts) {
+	const waitMs = opts.waitMs ?? 1e3;
+	const pool = createPool(databaseUrl);
+	const client = await pool.connect();
+	try {
+		const notifications = [];
+		client.on("notification", (msg) => {
+			if (msg.channel === "kici_event_channel") notifications.push(msg.payload ?? "");
+		});
+		await client.query("LISTEN kici_event_channel");
+		await pool.query(`SELECT pg_notify('kici_event_channel', $1)`, [opts.payload]);
+		await new Promise((r) => setTimeout(r, waitMs));
+		await client.query("UNLISTEN kici_event_channel");
+		return { received: notifications };
+	} finally {
+		client.release();
+		await pool.end();
+	}
+}
+/**
+* INSERT a cross_repo_trust row. Returns the new id and allowed_events
+* array. Used by generic-webhook + event-routing e2e until a proper
+* `kici-admin trust` CLI ships.
+*/
+async function seedCrossRepoTrustDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const result = await pool.query(`INSERT INTO cross_repo_trust
+         (source_repo, source_routing_key, target_repo, target_routing_key, allowed_events)
+       VALUES ($1, $2, $3, $4, $5)
+       RETURNING id, allowed_events`, [
+			opts.sourceRepo,
+			opts.sourceRoutingKey,
+			opts.targetRepo,
+			opts.targetRoutingKey,
+			opts.allowedEvents ? JSON.stringify(opts.allowedEvents) : null
+		]);
+		return {
+			id: result.rows[0].id,
+			allowedEvents: result.rows[0].allowed_events
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: list cross_repo_trust rows by source_routing_key. Used by
+* generic-webhook e2e to find a trust row it just inserted.
+*/
+async function listCrossRepoTrustBySourceRoutingKeyDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT id, source_repo, source_routing_key, target_repo, target_routing_key, allowed_events
+         FROM cross_repo_trust WHERE source_routing_key = $1`, [opts.sourceRoutingKey])).rows;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE cross_repo_trust rows. Deletes by id, or asserts uniqueness
+* check error on duplicate INSERT (handled by caller). Returns row count.
+*/
+async function deleteCrossRepoTrustDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query(`DELETE FROM cross_repo_trust WHERE id = $1`, [opts.id])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Direct INSERT with duplicate-key detection. Used by event-routing
+* e2e to verify the unique constraint enforces. Throws on duplicate;
+* caller asserts the error message matches /unique/i.
+*/
+async function insertCrossRepoTrustStrictDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO cross_repo_trust (source_repo, source_routing_key, target_repo, target_routing_key)
+       VALUES ($1, $2, $3, $4)`, [
+			opts.sourceRepo,
+			opts.sourceRoutingKey,
+			opts.targetRepo,
+			opts.targetRoutingKey
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Cleanup helper for workflow_registrations. Accepts id, routingKey,
+* or repoIdentifier filter (exactly one). Returns delete count.
+*/
+async function deleteWorkflowRegistrationsDirect(databaseUrl, opts) {
+	if ([
+		opts.id,
+		opts.routingKey,
+		opts.repoIdentifier
+	].filter((v) => v !== void 0).length !== 1) throw new Error("deleteWorkflowRegistrationsDirect: exactly one of {id, routingKey, repoIdentifier} required");
+	const pool = createPool(databaseUrl);
+	try {
+		let result;
+		if (opts.id) result = await pool.query(`DELETE FROM workflow_registrations WHERE id = $1`, [opts.id]);
+		else if (opts.routingKey) result = await pool.query(`DELETE FROM workflow_registrations WHERE routing_key = $1`, [opts.routingKey]);
+		else result = await pool.query(`DELETE FROM workflow_registrations WHERE repo_identifier = $1`, [opts.repoIdentifier]);
+		return { deleted: result.rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+async function getWorkflowRegistrationByIdDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT id, repo_identifier, workflow_name, routing_key, customer_id,
+              trigger_types, disabled, is_global, commit_sha, source_file,
+              created_at, updated_at, lock_entry
+         FROM workflow_registrations
+        WHERE id = $1`, [opts.id])).rows[0] ?? null;
+	} finally {
+		await pool.end();
+	}
+}
+async function listRegistrationsByRoutingKeyDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const globalFilter = opts.onlyGlobal ? `AND is_global = TRUE` : "";
+		const result = await pool.query(`SELECT workflow_name, is_global, updated_at
+         FROM workflow_registrations
+        WHERE routing_key = $1 ${globalFilter}`, [opts.routingKey]);
+		let latest = null;
+		for (const r of result.rows) {
+			const d = r.updated_at ? new Date(r.updated_at) : null;
+			if (d && (!latest || d.getTime() > latest.getTime())) latest = d;
+		}
+		return {
+			count: result.rows.length,
+			latestUpdatedAt: latest,
+			rows: result.rows.map((r) => ({
+				workflow_name: r.workflow_name,
+				is_global: r.is_global
+			}))
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Poll `workflow_registrations` for at least `minCount` rows for a
+* routing key. Returns the rows or throws on timeout (keeps parity with
+* the forgejo helper pattern it replaces).
+*/
+async function waitForRegistrationsByRoutingKeyDirect(databaseUrl, opts) {
+	const minCount = opts.minCount ?? 1;
+	const timeoutMs = opts.timeoutMs ?? 3e4;
+	const intervalMs = opts.intervalMs ?? 1e3;
+	const deadline = Date.now() + timeoutMs;
+	let rows = [];
+	while (Date.now() < deadline) {
+		rows = (await listRegistrationsByRoutingKeyDirect(databaseUrl, {
+			routingKey: opts.routingKey,
+			onlyGlobal: opts.onlyGlobal
+		})).rows;
+		if (rows.length >= minCount) return rows;
+		await new Promise((r) => setTimeout(r, intervalMs));
+	}
+	return rows;
+}
+/**
+* Wait for `workflow_registrations.updated_at` for a routing key to
+* exceed `baselineUpdatedAt`. Used by forgejo rotated-PAT e2e.
+*/
+async function waitForRegistrationsUpdatedAtAdvanceDirect(databaseUrl, opts) {
+	const timeoutMs = opts.timeoutMs ?? 3e4;
+	const intervalMs = opts.intervalMs ?? 1e3;
+	const deadline = Date.now() + timeoutMs;
+	let latest = null;
+	while (Date.now() < deadline) {
+		latest = (await listRegistrationsByRoutingKeyDirect(databaseUrl, { routingKey: opts.routingKey })).latestUpdatedAt;
+		if (latest && (!opts.baselineUpdatedAt || latest.getTime() > opts.baselineUpdatedAt.getTime())) return {
+			advanced: true,
+			latestUpdatedAt: latest
+		};
+		await new Promise((r) => setTimeout(r, intervalMs));
+	}
+	return {
+		advanced: false,
+		latestUpdatedAt: latest
+	};
+}
+/**
+* UPDATE a workflow_registrations row's commit_sha. Used by cron-scheduler
+* e2e where the manual-schedule handler rejects null commit SHAs.
+*/
+async function updateWorkflowRegistrationCommitShaDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`UPDATE workflow_registrations SET commit_sha = $1 WHERE id = $2`, [opts.commitSha, opts.id]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Lock-entry seeding for the admin-API e2e, which uses a custom
+* shape (cron schedule). Returns the inserted id.
+*/
+async function insertWorkflowRegistrationRawDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const idClause = opts.id ? "$7" : "gen_random_uuid()";
+		const extras = [];
+		if (opts.id) extras.push(opts.id);
+		const columns = [];
+		const placeholders = [];
+		if (opts.isGlobal !== void 0) {
+			columns.push("is_global");
+			placeholders.push(`$${7 + extras.length}`);
+			extras.push(opts.isGlobal);
+		}
+		if (opts.disabled !== void 0) {
+			columns.push("disabled");
+			placeholders.push(`$${7 + extras.length}`);
+			extras.push(opts.disabled);
+		}
+		if (opts.commitSha !== void 0) {
+			columns.push("commit_sha");
+			placeholders.push(`$${7 + extras.length}`);
+			extras.push(opts.commitSha);
+		}
+		const extraColumns = columns.length > 0 ? `, ${columns.join(", ")}` : "";
+		const extraPlaceholders = placeholders.length > 0 ? `, ${placeholders.join(", ")}` : "";
+		const sql = `INSERT INTO workflow_registrations
+      (routing_key, repo_identifier, workflow_name, lock_entry, trigger_types, customer_id${opts.id ? ", id" : ""}${extraColumns})
+      VALUES ($1, $2, $3, $4, $5, $6${opts.id ? `, ${idClause}` : ""}${extraPlaceholders})
+      ON CONFLICT (routing_key, repo_identifier, workflow_name) DO UPDATE SET
+        lock_entry = EXCLUDED.lock_entry,
+        trigger_types = EXCLUDED.trigger_types,
+        customer_id = EXCLUDED.customer_id
+      RETURNING id`;
+		return { id: (await pool.query(sql, [
+			opts.routingKey,
+			opts.repoIdentifier,
+			opts.workflowName,
+			JSON.stringify(opts.lockEntry),
+			opts.triggerTypes,
+			opts.customerId,
+			...extras
+		])).rows[0].id };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* INSERT with a STRICT shape (no ON CONFLICT). Used by registration-schema
+* e2e to prove the unique constraint rejects duplicates. Throws the raw
+* DB error (caller matches /unique/i).
+*/
+async function insertWorkflowRegistrationStrictDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { id: (await pool.query(`INSERT INTO workflow_registrations
+         (routing_key, repo_identifier, workflow_name, lock_entry, trigger_types, customer_id)
+       VALUES ($1, $2, $3, $4::jsonb, $5, $6)
+       RETURNING id`, [
+			opts.routingKey,
+			opts.repoIdentifier,
+			opts.workflowName,
+			opts.lockEntryJson ?? "{}",
+			opts.triggerTypes,
+			opts.customerId
+		])).rows[0]?.id ?? null };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: latest registry_versions.version, or null if the default
+* row is missing. Used by registration-admin-api e2e to bracket a
+* refresh call.
+*/
+async function getRegistryVersionDirect(databaseUrl, opts = {}) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT version FROM registry_versions WHERE id = $1`, [opts.id ?? "default"])).rows[0]?.version ?? null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* UPDATE `registry_versions.version = version + 1` WHERE id (default).
+* Simpler than `bumpRegistryVersionDirect` — used by global-workflow
+* e2e which wants the side-effect (force index refresh) without the
+* return value.
+*/
+async function bumpRegistryVersionSimpleDirect(databaseUrl, opts = {}) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`UPDATE registry_versions SET version = version + 1 WHERE id = $1`, [opts.id ?? "default"]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Seed cron_last_fired for a registration with an `-INTERVAL` offset so
+* the scheduler fires on the next evaluation. Upsert via ON CONFLICT.
+*/
+async function upsertCronLastFiredDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO cron_last_fired (registration_id, last_fired_at)
+         VALUES ($1, NOW() - ($2)::interval)
+         ON CONFLICT (registration_id) DO UPDATE SET
+           last_fired_at = NOW() - ($2)::interval,
+           updated_at = NOW()`, [opts.registrationId, opts.agoInterval]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: count cron_last_fired rows for a registration. Used by
+* registration-schema e2e to assert the FK cascade deletes the row.
+*/
+async function countCronLastFiredDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT COUNT(*)::int AS cnt FROM cron_last_fired WHERE registration_id = $1`, [opts.registrationId])).rows[0]?.cnt ?? 0;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* INSERT a cron_last_fired row with an explicit timestamp. Used by
+* registration-schema e2e to set up the FK cascade test.
+*/
+async function insertCronLastFiredNowDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO cron_last_fired (registration_id, last_fired_at) VALUES ($1, NOW())`, [opts.registrationId]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE cron_last_fired rows for a registration. Teardown helper.
+*/
+async function deleteCronLastFiredDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`DELETE FROM cron_last_fired WHERE registration_id = $1`, [opts.registrationId]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE execution_runs by workflow_name. Teardown helper for
+* manual-schedule e2e.
+*/
+async function deleteExecutionRunsByWorkflowNameDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query(`DELETE FROM execution_runs WHERE workflow_name = $1`, [opts.workflowName])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: SELECT generic_webhook_sources by routing_key.
+* Used by forgejo e2e to assert the source exists with correct git_config.
+*/
+async function getGenericWebhookSourceByRoutingKeyDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT id, git_config, customer_id FROM generic_webhook_sources WHERE routing_key = $1`, [opts.routingKey])).rows[0] ?? null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: list active (enabled=true) generic_webhook_sources.
+* Used by cluster-leader-failover e2e to prove the seeded source exists
+* before a leader crash.
+*/
+async function listActiveGenericWebhookSourcesDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT id, customer_id, routing_key FROM generic_webhook_sources WHERE enabled = true`)).rows;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* UPDATE generic_webhook_sources.verification_config for a source by
+* name + customer_id. Used by the generic-webhook-auth e2e which seeds
+* sources and then writes custom auth configs.
+*/
+async function updateGenericWebhookVerificationConfigDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`UPDATE generic_webhook_sources
+         SET verification_config = $1
+        WHERE name = $2 AND customer_id = $3`, [
+			JSON.stringify(opts.verificationConfig),
+			opts.name,
+			opts.customerId
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE generic_webhook_sources by name list. Teardown for the auth
+* e2e, which seeded 3 sources by name.
+*/
+async function deleteGenericWebhookSourcesByNameDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query(`DELETE FROM generic_webhook_sources WHERE name = ANY($1::text[])`, [opts.names])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* UPDATE generic_webhook_sources.deleted_at = NULL for a row by id.
+* Used by the generic-webhook e2e to restore a soft-deleted source
+* after the soft-delete test ran — there is no CLI-level undelete.
+*/
+async function restoreSoftDeletedGenericWebhookSourceDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`UPDATE generic_webhook_sources SET deleted_at = NULL WHERE id = $1`, [opts.id]);
+	} finally {
+		await pool.end();
+	}
+}
+async function upsertOrgSettingsGlobalWorkflowsDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO org_settings (
+         customer_id, global_workflows_enabled,
+         global_workflow_allowed_repos,
+         global_workflow_denied_repos,
+         global_workflow_elevated_repos
+       ) VALUES ($1, $2, $3::jsonb, $4::jsonb, $5::jsonb)
+       ON CONFLICT (customer_id) DO UPDATE SET
+         global_workflows_enabled = EXCLUDED.global_workflows_enabled,
+         global_workflow_allowed_repos = EXCLUDED.global_workflow_allowed_repos,
+         global_workflow_denied_repos = EXCLUDED.global_workflow_denied_repos,
+         global_workflow_elevated_repos = EXCLUDED.global_workflow_elevated_repos,
+         updated_at = NOW()`, [
+			opts.customerId,
+			opts.globalWorkflowsEnabled,
+			opts.allowedRepos == null ? null : JSON.stringify(opts.allowedRepos),
+			opts.deniedRepos == null ? null : JSON.stringify(opts.deniedRepos),
+			opts.elevatedRepos == null ? null : JSON.stringify(opts.elevatedRepos)
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* UPDATE org_settings.global_workflow_denied_repos for a customer/org id.
+* Assumes the row exists (upsertOrgSettingsGlobalWorkflowsDirect was
+* called earlier in the test).
+*/
+async function updateOrgSettingsDeniedReposDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`UPDATE org_settings
+         SET global_workflow_denied_repos = $2::jsonb,
+             updated_at = NOW()
+        WHERE customer_id = $1`, [opts.customerId, opts.deniedRepos == null ? null : JSON.stringify(opts.deniedRepos)]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* DELETE org_settings by customer/org id. Teardown helper.
+*/
+async function deleteOrgSettingsByCustomerIdDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query(`DELETE FROM org_settings WHERE customer_id = $1`, [opts.customerId])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+async function getExecutionRunSecurityDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const result = await pool.query(`SELECT run_id, trust_tier, lock_file_source, contributor_username, status
+         FROM execution_runs WHERE run_id = $1`, [opts.runId]);
+		if (result.rows.length === 0) throw new Error(`execution_runs: row not found (run_id=${opts.runId})`);
+		return result.rows[0];
+	} finally {
+		await pool.end();
+	}
+}
+async function getHeldRunByIdDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT id, run_id, hold_type, queue_type, status, reason,
+              expires_at, approved_by, resolved_at
+         FROM held_runs WHERE id = $1`, [opts.id])).rows[0] ?? null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: count held_runs rows matching run_id + queue_type.
+* Used by ci-security e2e to prove no security hold exists for a
+* trusted contributor PR.
+*/
+async function countHeldRunsByRunIdDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (opts.queueType ? await pool.query(`SELECT COUNT(*)::int AS cnt FROM held_runs WHERE run_id = $1 AND queue_type = $2`, [opts.runId, opts.queueType]) : await pool.query(`SELECT COUNT(*)::int AS cnt FROM held_runs WHERE run_id = $1`, [opts.runId])).rows[0]?.cnt ?? 0;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Wait for Platform-side `execution_runs.status = <status>` where
+* `created_at > since`. Returns the final status + failure_reason or
+* null if the timeout elapsed. Used by webhook-pipeline (failed) and
+* orchestrator-never-reconnects (timed_out_stale).
+*/
+async function waitForPlatformExecutionRunStatusDirect(databaseUrl, opts) {
+	const timeoutMs = opts.timeoutMs ?? 3e4;
+	const intervalMs = opts.intervalMs ?? 2e3;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		while (Date.now() < deadline) {
+			const result = await pool.query(`SELECT status, failure_reason FROM execution_runs
+          WHERE created_at > $1 AND status = $2
+          ORDER BY created_at DESC LIMIT 1`, [opts.since, opts.status]);
+			if (result.rows.length > 0) return result.rows[0];
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		return null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Wait for Platform `event_log` to show at least `minDistinctRouted`
+* distinct `routed_to` values since a given timestamp. Used by
+* cluster-round-robin to prove at least 2 orchestrators received
+* deliveries. Returns the observed count (0 if timed out).
+*/
+async function waitForPlatformEventLogDistinctRoutedDirect(databaseUrl, opts) {
+	const timeoutMs = opts.timeoutMs ?? 6e4;
+	const intervalMs = opts.intervalMs ?? 3e3;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		let distinct = 0;
+		while (Date.now() < deadline) {
+			distinct = (await pool.query(`SELECT COUNT(DISTINCT routed_to)::int AS cnt FROM event_log WHERE received_at > $1`, [opts.since])).rows[0]?.cnt ?? 0;
+			if (distinct >= opts.minDistinctRouted) return { distinctRouted: distinct };
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		return { distinctRouted: distinct };
+	} finally {
+		await pool.end();
+	}
+}
+async function waitForEventLogRowByDeliveryIdDirect(databaseUrl, opts) {
+	const timeoutMs = opts.timeoutMs ?? 1e4;
+	const intervalMs = opts.intervalMs ?? 200;
+	const deadline = Date.now() + timeoutMs;
+	const pool = createPool(databaseUrl);
+	try {
+		while (Date.now() < deadline) {
+			const res = await pool.query(`SELECT org_id, delivery_id, status, source, event, provider, payload_hash,
+                payload_omitted, payload_key, payload_size_bytes, matched_count, run_id
+           FROM event_log WHERE delivery_id = $1`, [opts.deliveryId]);
+			if (res.rowCount && res.rowCount > 0) return res.rows[0];
+			await new Promise((r) => setTimeout(r, intervalMs));
+		}
+		return null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Resolve a Platform `webhook_sources.routing_key` for an org.
+*
+* - With `routingKeyLikePrefix` only: returns the newest match. Note that
+*   this picks whichever generic source was registered most recently — if
+*   tests have created additional generic sources (e.g. universal-git-forgejo
+*   creating `stg-universal-git-forgejo`), the newest may NOT be the
+*   `stg-generic` default seeded by `pnpm deploy:stg`.
+* - With `orchDbUrl` + `nameInOrchDb`: looks up the source by name in the
+*   orchestrator's `generic_webhook_sources` table, then verifies the
+*   resulting routing key is registered in Platform's `webhook_sources`.
+*   This is the disambiguating path Bucket-B tests should use when other
+*   generic sources may exist alongside the default.
+*/
+async function resolvePlatformWebhookSourceRoutingKeyDirect(platformDbUrl, opts) {
+	if (opts.orchDbUrl && opts.nameInOrchDb) {
+		const orchPool = createPool(opts.orchDbUrl);
+		let candidateRoutingKey = null;
+		try {
+			const id = (await orchPool.query(`SELECT id FROM generic_webhook_sources
+          WHERE customer_id = $1 AND name = $2 AND deleted_at IS NULL
+          LIMIT 1`, [opts.orgId, opts.nameInOrchDb])).rows[0]?.id;
+			if (!id) return null;
+			candidateRoutingKey = `generic:${opts.orgId}:${id}`;
+		} finally {
+			await orchPool.end();
+		}
+		const platformPool = createPool(platformDbUrl);
+		try {
+			return (await platformPool.query(`SELECT routing_key FROM webhook_sources
+          WHERE org_id = $1 AND routing_key = $2 LIMIT 1`, [opts.orgId, candidateRoutingKey])).rows[0]?.routing_key ?? null;
+		} finally {
+			await platformPool.end();
+		}
+	}
+	const pool = createPool(platformDbUrl);
+	try {
+		return (await pool.query(`SELECT routing_key FROM webhook_sources
+        WHERE org_id = $1 AND routing_key LIKE $2
+        ORDER BY registered_at DESC LIMIT 1`, [opts.orgId, `${opts.routingKeyLikePrefix}%`])).rows[0]?.routing_key ?? null;
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Idempotent seeding of an E2E regular user + org membership + owner
+* role on the Platform DB. Used by stg-ha-smoke before seeding a user
+* API key. Requires the org to already have an owner role.
+*/
+async function ensureOrgOwnerMemberDirect(platformDbUrl, opts) {
+	const pool = createPool(platformDbUrl);
+	try {
+		const ownerRole = await pool.query(`SELECT id FROM roles WHERE org_id = $1 AND is_owner = true LIMIT 1`, [opts.orgId]);
+		if (ownerRole.rows.length === 0) throw new Error(`ensureOrgOwnerMemberDirect: no owner role found for org ${opts.orgId}`);
+		const ownerRoleId = ownerRole.rows[0].id;
+		await pool.query(`INSERT INTO users (zitadel_sub, email, display_name)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (zitadel_sub) DO NOTHING`, [
+			opts.zitadelSub,
+			opts.email,
+			opts.displayName
+		]);
+		await pool.query(`INSERT INTO org_members (org_id, user_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`, [opts.orgId, opts.zitadelSub]);
+		await pool.query(`INSERT INTO role_assignments (org_id, user_id, role_id, assigned_by)
+         VALUES ($1, $2, $3, $2)
+         ON CONFLICT (org_id, user_id, role_id) DO NOTHING`, [
+			opts.orgId,
+			opts.zitadelSub,
+			ownerRoleId
+		]);
+		return { ownerRoleId };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Cleanup peer_credentials by instance_id LIKE pattern. Used by the
+* cluster-peer-credentials e2e before/after each test to wipe its
+* own seeded rows without touching real cluster credentials.
+*/
+async function deletePeerCredentialsByInstanceIdLikeDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { deleted: (await pool.query(`DELETE FROM peer_credentials WHERE instance_id LIKE $1`, [opts.pattern])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Insert a peer_credentials row with an explicit expires_at. Used by
+* the "expired credential is not returned" e2e — the store's save()
+* always computes a future expiry, so tests that need a pre-expired
+* row must bypass it.
+*/
+async function insertPeerCredentialExpiredDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		await pool.query(`INSERT INTO peer_credentials (instance_id, credential_hash, role, routing_keys, expires_at)
+       VALUES ($1, $2, $3, $4::text[], $5)`, [
+			opts.instanceId,
+			opts.credentialHash,
+			opts.role,
+			Array.from(opts.routingKeys),
+			opts.expiresAt
+		]);
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: `revoked_at` for a peer_credentials row by hash. Used
+* by the "save revokes old credential" e2e to assert revocation.
+* Returns null when the row is missing entirely (distinct from
+* "present but not revoked").
+*/
+async function getPeerCredentialRevokedAtDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		const result = await pool.query(`SELECT revoked_at FROM peer_credentials WHERE credential_hash = $1`, [opts.credentialHash]);
+		if (result.rows.length === 0) return {
+			present: false,
+			revokedAt: null
+		};
+		return {
+			present: true,
+			revokedAt: result.rows[0].revoked_at
+		};
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: list active peer_credentials ids EXCLUDING a
+* `instance_id LIKE` pattern. Used by revokeAll e2e to snapshot
+* real cluster credentials it will restore later.
+*/
+async function listActivePeerCredentialsExcludingDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return { ids: (await pool.query(`SELECT id FROM peer_credentials
+        WHERE revoked_at IS NULL AND instance_id NOT LIKE $1`, [opts.excludeInstanceIdPattern])).rows.map((r) => r.id) };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* Clear revoked_at on a set of peer_credentials ids. Used by revokeAll
+* e2e to restore real cluster credentials after the destructive test.
+*/
+async function clearPeerCredentialsRevokedAtByIdsDirect(databaseUrl, opts) {
+	if (opts.ids.length === 0) return { updated: 0 };
+	const pool = createPool(databaseUrl);
+	try {
+		return { updated: (await pool.query(`UPDATE peer_credentials SET revoked_at = NULL WHERE id = ANY($1::uuid[])`, [opts.ids])).rowCount ?? 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
+* READ-ONLY: count currently-active (non-revoked, non-expired)
+* peer_credentials rows for a given instance_id. Used by the
+* concurrent-save e2e to assert 1 <= count <= 2.
+*/
+async function countActivePeerCredentialsByInstanceDirect(databaseUrl, opts) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT count(*)::int AS cnt FROM peer_credentials
+        WHERE instance_id = $1 AND revoked_at IS NULL AND expires_at > now()`, [opts.instanceId])).rows[0]?.cnt ?? 0;
+	} finally {
+		await pool.end();
+	}
+}
+//#endregion
+export { MIGRATION_HASH_TABLE, PROVIDER_HASH_KEY, REGISTERABLE_TRIGGER_TYPES, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDbRole, createEnvironmentTemplateDirect, createJoinTokenDirect, createReadOnlyDbUser, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getRegistryVersionDirect, getWorkflowRegistrationByIdDirect, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };
+
+//# sourceMappingURL=db-admin.js.map