@kici-dev/shared 0.0.0 → 0.1.0

package/dist/db-admin.d.ts

@@ -0,0 +1,1422 @@
+import pg from 'pg';
+import type { MigrationProvider } from 'kysely/migration';
+/**
+ * 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.
+ */
+export declare const MIGRATION_HASH_TABLE = "_migration_content_hash";
+interface ParsedDatabaseUrl {
+    adminUrl: string;
+    dbName: string;
+    dbOwner: string;
+}
+/**
+ * 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.
+ */
+export declare function parseDatabaseUrl(databaseUrl: string): ParsedDatabaseUrl;
+/**
+ * Redact the password from a libpq URL for safe logging.
+ */
+export declare function maskDatabaseUrl(databaseUrl: string): string;
+/**
+ * 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.
+ */
+export declare function dropDatabaseDirect(databaseUrl: string): Promise<void>;
+/**
+ * Drop `dbName` (if it exists), then recreate it owned by `owner`. Terminates
+ * existing backend connections so the DROP doesn't block.
+ */
+export declare function dropAndCreateDatabase(databaseUrl: string): Promise<void>;
+/**
+ * CREATE DATABASE IF NOT EXISTS (idempotent). Uses the URL's username as owner.
+ */
+export declare function ensureDatabase(databaseUrl: string): Promise<'created' | 'exists'>;
+/**
+ * CREATE ROLE ... LOGIN [CREATEDB] (idempotent — updates password if role
+ * already exists).
+ */
+export declare function createDbRole(adminUrl: string, opts: {
+    username: string;
+    password: string;
+    createDb?: boolean;
+}): Promise<'created' | '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.
+ */
+export declare function createReadOnlyDbUser(databaseUrl: string, opts: {
+    username: string;
+    password: string;
+}): Promise<'created' | 'updated'>;
+/**
+ * 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.
+ */
+export declare function computeMigrationsHash(provider: MigrationProvider): Promise<string>;
+/**
+ * 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.
+ */
+export declare 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`.
+ */
+export declare function storeMigrationContentHash(pool: pg.Pool, hash: string): Promise<void>;
+/**
+ * Read the provider-based content hash, or `null` if the marker table / row
+ * doesn't exist.
+ */
+export declare function readStoredMigrationContentHash(pool: pg.Pool): Promise<string | null>;
+export interface PurgeStaleExecutionResult {
+    runsDeleted: number;
+    jobsDeleted: number;
+    concurrencyGroupsDeleted: number;
+}
+/**
+ * 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).
+ */
+export declare function clearDispatchQueueDirect(databaseUrl: string): Promise<void>;
+/**
+ * DELETE orphan execution_runs + execution_jobs for routing keys other than
+ * `routingKey` (and rows with NULL routing_key). Returns row counts.
+ */
+export declare function purgeStaleExecutionDirect(databaseUrl: string, routingKey: string): Promise<PurgeStaleExecutionResult>;
+export interface PurgeStaleSourcesResult {
+    dryRun: boolean;
+    secretsDeleted?: number;
+    sourcesDeleted?: number;
+    genericDeleted?: number;
+    registrationsDeleted?: number;
+    staleSecrets?: number;
+    staleSources?: number;
+    genericSources?: number;
+    orphanRegistrations?: number;
+}
+/**
+ * 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).
+ */
+export declare function purgeStaleSourcesDirect(databaseUrl: string, routingKey: string, dryRun: boolean): Promise<PurgeStaleSourcesResult>;
+/**
+ * Bulk-delete scoped_secrets. Scoped to one org when `orgId` is provided,
+ * else all orgs. Returns the number of rows deleted.
+ */
+export declare function purgeScopedSecretsDirect(databaseUrl: string, orgId?: string): Promise<{
+    deleted: number;
+}>;
+export interface SeedEnvironmentOpts {
+    orgId: string;
+    name: string;
+    type?: string;
+    enabled?: boolean;
+    branchRestrictions?: unknown;
+    requiredReviewers?: unknown;
+    waitTimerSeconds?: number | null;
+    holdExpirySeconds?: number | null;
+    minimumTrust?: string | null;
+}
+export interface SeedEnvironmentResult {
+    envId: string;
+    created: boolean;
+}
+/**
+ * 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.
+ */
+export declare function seedEnvironmentDirect(databaseUrl: string, opts: SeedEnvironmentOpts): Promise<SeedEnvironmentResult>;
+export interface SeedEnvironmentBindingOpts {
+    orgId: string;
+    envName: string;
+    scopePattern: string;
+}
+/**
+ * Upsert an `environment_bindings` row connecting `envName` to `scopePattern`.
+ * Throws if the environment does not exist.
+ */
+export declare function seedEnvironmentBindingDirect(databaseUrl: string, opts: SeedEnvironmentBindingOpts): Promise<{
+    created: boolean;
+}>;
+export interface SetEnvironmentPolicyOpts {
+    orgId: string;
+    envName: string;
+    branchRestrictions?: unknown;
+    requiredReviewers?: unknown;
+    waitTimerSeconds?: number | null;
+    holdExpirySeconds?: number | null;
+    minimumTrust?: string | null;
+    enabled?: boolean;
+}
+/**
+ * UPDATE only the policy fields that were explicitly provided. Columns that
+ * were NOT in `opts` are left untouched. Throws if the environment is missing.
+ */
+export declare function setEnvironmentPolicyDirect(databaseUrl: string, opts: SetEnvironmentPolicyOpts): Promise<void>;
+export interface EnvironmentRow {
+    id: string;
+    org_id: string;
+    name: string;
+    type: string;
+    enabled: boolean;
+    branch_restrictions: unknown;
+    required_reviewers: unknown;
+    wait_timer_seconds: number | null;
+    hold_expiry_seconds: number | null;
+    minimum_trust: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * SELECT * FROM environments WHERE org_id = $1, ordered by name.
+ */
+export declare function listEnvironmentsDirect(databaseUrl: string, opts: {
+    orgId: string;
+}): Promise<{
+    environments: EnvironmentRow[];
+}>;
+export interface EnvironmentVariableRow {
+    key: string;
+    value: string;
+    locked: boolean;
+    updated_at: string;
+}
+export interface EnvironmentBindingRow {
+    scope_pattern: string;
+    created_at: string;
+}
+export interface ShowEnvironmentResult {
+    environment: EnvironmentRow;
+    variables: EnvironmentVariableRow[];
+    bindings: EnvironmentBindingRow[];
+}
+/**
+ * Fetch a single environment row joined with its variables and bindings.
+ * Throws if the environment does not exist.
+ */
+export declare function showEnvironmentDirect(databaseUrl: string, opts: {
+    orgId: string;
+    name: string;
+}): Promise<ShowEnvironmentResult>;
+export interface CreateEnvironmentTemplateOpts {
+    orgId: string;
+    templateName: string;
+    type?: string;
+    branchRestrictions?: unknown;
+    requiredReviewers?: unknown;
+    waitTimerSeconds?: number | null;
+    holdExpirySeconds?: number | null;
+    minimumTrust?: string | null;
+    variables?: Record<string, string>;
+}
+/**
+ * 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 }`.
+ */
+export declare function createEnvironmentTemplateDirect(databaseUrl: string, opts: CreateEnvironmentTemplateOpts): Promise<{
+    envId: string;
+    created: boolean;
+    variablesSet: number;
+}>;
+export interface SetEnvironmentSecretOpts {
+    orgId: string;
+    environment: string;
+    key: string;
+    encryptedValue: string;
+}
+/**
+ * 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).
+ */
+export declare function setEnvironmentSecretDirect(databaseUrl: string, opts: SetEnvironmentSecretOpts): Promise<{
+    inserted: boolean;
+}>;
+export interface DispatchQueueRow {
+    id: string;
+    run_id: string;
+    workflow_name: string;
+    job_name: string;
+    status: string;
+    routing_key: string;
+    provider: string;
+    created_at: string;
+    expires_at: string | null;
+    delivery_id: string;
+    source_tar_url: string | null;
+    deps_url: string | null;
+    job_config: string | null;
+}
+export interface ListQueueOpts {
+    status?: string;
+    /** Status NOT IN list (e.g., to find non-terminal rows). */
+    statusNotIn?: readonly string[];
+    jobNamePrefix?: string;
+    /** Exact job_name match (e.g., `__build__e2e-test`). */
+    jobName?: string;
+    /** job_name NOT LIKE (e.g., `__build__%` to exclude build jobs). */
+    jobNameNotLike?: string;
+    workflowName?: string;
+    /** ISO timestamp or Date; matches rows with created_at > this. */
+    createdAfter?: string | Date;
+    limit?: number;
+}
+/**
+ * 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.
+ */
+export declare function listQueueDirect(databaseUrl: string, opts?: ListQueueOpts): Promise<{
+    entries: DispatchQueueRow[];
+}>;
+/**
+ * READ-ONLY: SELECT a single dispatch_queue row by id. Throws with a
+ * clear message when no row matches.
+ */
+export declare function showQueueEntryDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<DispatchQueueRow>;
+export interface ExecutionRunRow {
+    id: string;
+    run_id: string;
+    workflow_name: string;
+    status: string;
+    provider: string;
+    repo_identifier: string;
+    ref: string;
+    sha: string;
+    routing_key: string | null;
+    environment: string | null;
+    trust_tier: string | null;
+    created_at: string;
+    started_at: string;
+    completed_at: string | null;
+    duration_ms: number | null;
+}
+export interface ExecutionJobRow {
+    id: string;
+    run_id: string;
+    job_id: string;
+    job_name: string;
+    status: string;
+    agent_id: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    duration_ms: number | null;
+    created_at: string;
+    error_message: string | null;
+}
+export interface ListExecutionRunsOpts {
+    routingKey?: string;
+    status?: string;
+    workflowName?: string;
+    limit?: number;
+}
+/**
+ * READ-ONLY: SELECT execution_runs with optional filters. Ordered by
+ * created_at DESC, capped at a sensible limit.
+ */
+export declare function listExecutionRunsDirect(databaseUrl: string, opts?: ListExecutionRunsOpts): Promise<{
+    runs: ExecutionRunRow[];
+}>;
+/**
+ * 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.
+ */
+export declare function showExecutionRunDirect(databaseUrl: string, opts: {
+    runId: string;
+}): Promise<{
+    run: ExecutionRunRow;
+    jobs: ExecutionJobRow[];
+}>;
+/**
+ * READ-ONLY: list execution_jobs for a given execution_runs.id. Ordered by
+ * created_at ASC so downstream diffs show timeline order.
+ */
+export declare function listExecutionJobsDirect(databaseUrl: string, opts: {
+    runId: string;
+}): Promise<{
+    jobs: ExecutionJobRow[];
+}>;
+export interface WorkflowRegistrationRow {
+    id: string;
+    repo_identifier: string;
+    workflow_name: string;
+    routing_key: string;
+    customer_id: string;
+    trigger_types: string[];
+    disabled: boolean;
+    is_global: boolean;
+    commit_sha: string | null;
+    source_file: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ListRegistrationsOpts {
+    customerId?: string;
+    routingKey?: string;
+    repoIdentifier?: string;
+    /** Include rows where this trigger type is in trigger_types[]. */
+    triggerType?: string;
+    limit?: number;
+}
+export interface ListRegistrationsResult {
+    registrations: WorkflowRegistrationRow[];
+    /** Latest `registry_versions.version`, or null if the table has no row. */
+    registryVersion: number | null;
+}
+/**
+ * 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.
+ */
+export declare function listRegistrationsDirect(databaseUrl: string, opts?: ListRegistrationsOpts): Promise<ListRegistrationsResult>;
+export interface ShowRegistrationResult {
+    registration: WorkflowRegistrationRow & {
+        lock_entry: unknown;
+        provider_context: unknown;
+    };
+    registryVersion: number | null;
+}
+/**
+ * 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.
+ */
+export declare function showRegistrationDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<ShowRegistrationResult>;
+/**
+ * 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.
+ */
+export declare const REGISTERABLE_TRIGGER_TYPES: ReadonlySet<string>;
+interface MinimalLockEntry {
+    name: string;
+    triggers: ReadonlyArray<{
+        _type: string;
+        repos?: unknown[];
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+interface MinimalLockFileShape {
+    workflows: readonly MinimalLockEntry[];
+}
+export interface RegisterWorkflowManualOpts {
+    /** Either `lockFileContents` (raw JSON string) OR `lockFile` (parsed object). */
+    lockFileContents?: string;
+    lockFile?: MinimalLockFileShape;
+    repoIdentifier: string;
+    routingKey: string;
+    customerId: string;
+    providerContext: Record<string, unknown>;
+    commitSha?: string;
+}
+export interface RegisterWorkflowManualResult {
+    workflowCount: number;
+    registryVersion: number;
+}
+/**
+ * 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.
+ */
+export declare function registerWorkflowManualDirect(databaseUrl: string, opts: RegisterWorkflowManualOpts): Promise<RegisterWorkflowManualResult>;
+/**
+ * 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.
+ */
+export declare function resetRaftStateDirect(databaseUrl: string): Promise<{
+    rowsDeleted: number;
+}>;
+export interface EmitKiciEventOpts {
+    eventName: string;
+    payload: Record<string, unknown>;
+    sourceRoutingKey?: string;
+    sourceRepo?: string;
+}
+/**
+ * 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.
+ */
+export declare function emitKiciEventDirect(databaseUrl: string, opts: EmitKiciEventOpts): Promise<{
+    eventId: string;
+}>;
+export interface SeedGenericWebhookSourceOpts {
+    orgId: string;
+    name: string;
+    /** Pre-computed deterministic UUID (caller derives via sha256(orgId:name)) */
+    sourceId: string;
+    /** Pre-computed routing key (caller uses `generic:${orgId}:${name}`) */
+    routingKey: string;
+    verificationMethod?: string;
+    /** 'generic' (Stripe-shaped) or 'internal' (github-shaped via InternalWebhookNormalizer) */
+    providerType?: 'generic' | 'internal';
+}
+/**
+ * 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.
+ */
+export declare function seedGenericWebhookSourceDirect(databaseUrl: string, opts: SeedGenericWebhookSourceOpts): Promise<void>;
+/**
+ * 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`).
+ */
+export declare function isSchemaCurrent(pool: pg.Pool, provider: MigrationProvider): Promise<{
+    current: boolean;
+    reason?: string;
+}>;
+/**
+ * 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.
+ */
+export declare function purgeSecretBackendsDirect(databaseUrl: string): Promise<{
+    deleted: number;
+}>;
+/**
+ * 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.
+ */
+export declare function apiKeyExistsDirect(databaseUrl: string, apiKey: string): Promise<boolean>;
+/**
+ * Insert an api_keys row (Platform-side orchestrator credential). Used by
+ * e2e setup to seed an orchestrator authentication token. Returns the id.
+ */
+export declare function seedApiKeyInlineDirect(databaseUrl: string, opts: {
+    keyName: string;
+    orgId: string;
+    fullKey: string;
+}): Promise<{
+    keyId: string;
+}>;
+/**
+ * Lookup a `platform_connections` row by connection_id. Returns true when
+ * present. Used by the orphan-sweeper e2e test.
+ */
+export declare function platformConnectionExistsDirect(databaseUrl: string, connectionId: string): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function countWebhookSourcesByConnectionIdDirect(databaseUrl: string, connectionId: string): Promise<number>;
+/**
+ * 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.
+ */
+export declare function findAnyUserApiKeyIdDirect(databaseUrl: string, preferredOrgId: string): Promise<string | null>;
+/**
+ * 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.
+ */
+export declare function seedSyntheticGithubSourceDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    orgId: string;
+}): Promise<void>;
+/**
+ * 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.
+ */
+export declare function seedWebhookSecretDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    webhookSecret: string;
+    encryptFn: (plaintext: string, aad: string) => string | Buffer;
+}): Promise<{
+    sourceId: string;
+}>;
+/**
+ * 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).
+ */
+export declare function seedSourcePrivateKeyDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    privateKey: string;
+    encryptFn: (plaintext: string, aad: string) => string | Buffer;
+}): Promise<{
+    sourceId: string;
+} | null>;
+/**
+ * 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.
+ */
+export declare function bumpRegistryVersionDirect(databaseUrl: string): Promise<number>;
+/**
+ * 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.
+ */
+export declare function pollKiciEventsDirect(databaseUrl: string, opts: {
+    eventName: string;
+    since: Date;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    payloadFilter?: {
+        key: string;
+        value: string;
+    };
+}): Promise<Record<string, unknown>>;
+/**
+ * Ping a PostgreSQL database; retries until `SELECT 1` succeeds or the
+ * timeout expires. Used by e2e startup to wait for Postgres readiness.
+ */
+export declare function waitForPostgresDirect(databaseUrl: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<void>;
+/**
+ * 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.
+ */
+export declare function waitForRunCompletionDirect(databaseUrl: string, runId: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<{
+    status: string;
+}>;
+/**
+ * DELETE from execution_jobs + execution_runs where started_at > since.
+ * Used by e2e cleanup for tests that want explicit post-test row cleanup.
+ */
+export declare function cleanupExecutionRowsDirect(databaseUrl: string, since: Date): Promise<{
+    runs: number;
+    jobs: number;
+}>;
+/**
+ * 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.
+ */
+export declare function isSchemaCurrentFromFilesDirect(databaseUrl: string, opts: {
+    tableName?: string;
+    expectedCount: number;
+    expectedContentHash: string;
+}): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function storeMigrationContentHashInTableDirect(databaseUrl: string, opts: {
+    tableName?: string;
+    contentHash: string;
+}): Promise<void>;
+/**
+ * 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.
+ */
+export declare function createJoinTokenDirect(databaseUrl: string, opts: {
+    id: string;
+    tokenHash: string;
+    routingInfo: Record<string, unknown>;
+    role: string;
+    createdBy: string;
+    expiresAt: Date;
+}): Promise<void>;
+/**
+ * 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).
+ */
+export declare function updateSourceRoutingKeyDirect(databaseUrl: string, opts: {
+    provider: string;
+    newRoutingKey: string;
+    whereRoutingKey?: string;
+}): Promise<{
+    updated: number;
+}>;
+/**
+ * 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.
+ */
+export declare function prunePeerCredentialsDirect(databaseUrl: string, opts: {
+    keepInstanceIdPattern: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * 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.
+ */
+export declare function waitForPlatformRegistrationsDirect(platformDbUrl: string, routingKey: string, opts?: {
+    minRegistrations?: number;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<void>;
+/**
+ * Seed a generic_webhook_sources row with a custom `event_type_header` and
+ * `git_config` payload. Used by universal-git e2e (Forgejo) to register
+ * an ingest endpoint that extracts the event type from Gitea-style headers.
+ */
+export interface SeedUniversalGitSourceOpts {
+    orgId: string;
+    sourceId: string;
+    sourceName: string;
+    routingKey: string;
+    gitConfig: Record<string, unknown>;
+    eventTypeHeader?: string;
+}
+export declare function seedUniversalGitSourceDirect(databaseUrl: string, opts: SeedUniversalGitSourceOpts): Promise<void>;
+/**
+ * Seed the ci-security orchestrator fixtures expected by the security
+ * pipeline e2e: sources row for dashboard orgId resolution, environment,
+ * two execution_runs (unknown + trusted), two execution_jobs, and a
+ * security held_run for the unknown contributor.
+ *
+ * Returns the ids so the caller can assert downstream.
+ */
+export interface SeedCiSecurityFixturesOpts {
+    orgId: string;
+    envName?: string;
+    sourceName?: string;
+    sourceRoutingKey?: string;
+    runsRoutingKey: string;
+    unknownRunId: string;
+    unknownDeliveryId: string;
+    unknownJobId: string;
+    trustedRunId: string;
+    trustedDeliveryId: string;
+    trustedJobId: string;
+}
+export interface SeedCiSecurityFixturesResult {
+    envId: string;
+    heldRunId: string;
+}
+export declare function seedCiSecurityFixturesDirect(databaseUrl: string, opts: SeedCiSecurityFixturesOpts): Promise<SeedCiSecurityFixturesResult>;
+/**
+ * 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.
+ */
+export declare function waitForExecutionRunStatusSinceDirect(databaseUrl: string, opts: {
+    status: string;
+    since: Date;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<{
+    found: boolean;
+}>;
+/**
+ * Fetch the most recent `execution_runs` row matching `status`, plus its
+ * `execution_jobs`. Used by cluster reroute tests to confirm the run +
+ * its jobs completed successfully.
+ */
+export interface LatestExecutionRunResult {
+    run: {
+        run_id: string;
+        workflow_name: string;
+        status: string;
+    };
+    jobs: Array<{
+        job_id: string;
+        job_name: string;
+        status: string;
+    }>;
+}
+export declare function latestExecutionRunByStatusDirect(databaseUrl: string, opts: {
+    status: string;
+}): Promise<LatestExecutionRunResult | null>;
+/**
+ * Wait for a `execution_jobs` row joined against the most recent
+ * `execution_runs` for a given workflow name with started_at >= since,
+ * returning the job's status + error + run_id. Used by secrets-pipeline
+ * to gate on terminal job status.
+ */
+export interface WaitForLatestJobResult {
+    status: string | null;
+    errorMessage: string | null;
+    runId: string | null;
+}
+export declare function waitForLatestExecutionJobStatusDirect(databaseUrl: string, opts: {
+    workflowName: string;
+    since: Date;
+    terminalStatuses?: readonly string[];
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<WaitForLatestJobResult>;
+/**
+ * READ-ONLY: return information_schema column names for `tableName`,
+ * ordered by ordinal_position. Used by e2e tests to verify migrations
+ * produced expected schema shape. Returns empty array if the table
+ * doesn't exist.
+ */
+export interface ColumnInfo {
+    name: string;
+    dataType: string;
+}
+export declare function describeTableColumnsDirect(databaseUrl: string, opts: {
+    tableName: string;
+}): Promise<ColumnInfo[]>;
+/**
+ * READ-ONLY: return true if a table exists in the public schema.
+ */
+export declare function tableExistsDirect(databaseUrl: string, opts: {
+    tableName: string;
+    schema?: string;
+}): Promise<boolean>;
+/**
+ * Raw INSERT into kici_events with custom chain_depth + expiry window.
+ * Used by event-routing e2e to test circuit-breaker + TTL behavior
+ * beyond what `emitKiciEventDirect` exposes (which hardcodes depth=0
+ * and 1h expiry). Returns the inserted id.
+ */
+export interface InsertKiciEventRawOpts {
+    eventName: string;
+    payload: Record<string, unknown>;
+    sourceRoutingKey?: string;
+    chainDepth?: number;
+    /** ISO string or relative '1 hour' / '-1 hour'. Use negative for expired. */
+    expiresIn?: string;
+}
+export declare function insertKiciEventRawDirect(databaseUrl: string, opts: InsertKiciEventRawOpts): Promise<{
+    id: string;
+}>;
+/**
+ * READ-ONLY: return a kici_events row by id, or null. Callers decode
+ * `payload` as they need. Used by event-routing e2e after an INSERT.
+ */
+export interface KiciEventRow {
+    id: string;
+    event_name: string;
+    payload: Record<string, unknown>;
+    chain_depth: number;
+    source_routing_key: string | null;
+    source_repo: string | null;
+    processed: boolean | null;
+    expires_at: string;
+    created_at: string;
+}
+export declare function showKiciEventDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<KiciEventRow | null>;
+/**
+ * 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.
+ */
+export declare function listKiciEventsDirect(databaseUrl: string, opts?: {
+    eventName?: string;
+    minChainDepth?: number;
+    /** When true, return only rows past their expires_at. */
+    onlyExpired?: boolean;
+    /** When set, cap to this many rows. */
+    limit?: number;
+}): Promise<KiciEventRow[]>;
+/**
+ * DELETE kici_events by id or event_name. Returns the number of rows
+ * deleted. Used by event-routing teardown.
+ */
+export declare function deleteKiciEventsDirect(databaseUrl: string, opts: {
+    id?: string;
+    eventName?: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * 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.
+ */
+export declare function verifyKiciEventNotifyDirect(databaseUrl: string, opts: {
+    payload: string;
+    waitMs?: number;
+}): Promise<{
+    received: string[];
+}>;
+export interface CrossRepoTrustRow {
+    id: string;
+    source_repo: string;
+    source_routing_key: string;
+    target_repo: string;
+    target_routing_key: string;
+    allowed_events: string[] | null;
+}
+/**
+ * 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.
+ */
+export declare function seedCrossRepoTrustDirect(databaseUrl: string, opts: {
+    sourceRepo: string;
+    sourceRoutingKey: string;
+    targetRepo: string;
+    targetRoutingKey: string;
+    allowedEvents?: string[];
+}): Promise<{
+    id: string;
+    allowedEvents: string[] | null;
+}>;
+/**
+ * READ-ONLY: list cross_repo_trust rows by source_routing_key. Used by
+ * generic-webhook e2e to find a trust row it just inserted.
+ */
+export declare function listCrossRepoTrustBySourceRoutingKeyDirect(databaseUrl: string, opts: {
+    sourceRoutingKey: string;
+}): Promise<CrossRepoTrustRow[]>;
+/**
+ * DELETE cross_repo_trust rows. Deletes by id, or asserts uniqueness
+ * check error on duplicate INSERT (handled by caller). Returns row count.
+ */
+export declare function deleteCrossRepoTrustDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * 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.
+ */
+export declare function insertCrossRepoTrustStrictDirect(databaseUrl: string, opts: {
+    sourceRepo: string;
+    sourceRoutingKey: string;
+    targetRepo: string;
+    targetRoutingKey: string;
+}): Promise<void>;
+/**
+ * Cleanup helper for workflow_registrations. Accepts id, routingKey,
+ * or repoIdentifier filter (exactly one). Returns delete count.
+ */
+export declare function deleteWorkflowRegistrationsDirect(databaseUrl: string, opts: {
+    id?: string;
+    routingKey?: string;
+    repoIdentifier?: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * READ-ONLY: workflow_registrations by id — returns null when missing.
+ * Pulls the full row so tests can assert lock_entry contents + trigger_types.
+ */
+export interface WorkflowRegistrationFullRow extends WorkflowRegistrationRow {
+    lock_entry: unknown;
+}
+export declare function getWorkflowRegistrationByIdDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<WorkflowRegistrationFullRow | null>;
+/**
+ * READ-ONLY: return the count + optional rows + latest updated_at for
+ * workflow_registrations scoped to a routing key. Used by forgejo e2e
+ * to wait for extraction + verify re-extraction bumped updated_at.
+ */
+export interface RegistrationsScopedResult {
+    count: number;
+    latestUpdatedAt: Date | null;
+    rows: Array<{
+        workflow_name: string;
+        is_global: boolean;
+    }>;
+}
+export declare function listRegistrationsByRoutingKeyDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    onlyGlobal?: boolean;
+}): Promise<RegistrationsScopedResult>;
+/**
+ * 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).
+ */
+export declare function waitForRegistrationsByRoutingKeyDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    minCount?: number;
+    onlyGlobal?: boolean;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<Array<{
+    workflow_name: string;
+    is_global: boolean;
+}>>;
+/**
+ * Wait for `workflow_registrations.updated_at` for a routing key to
+ * exceed `baselineUpdatedAt`. Used by forgejo rotated-PAT e2e.
+ */
+export declare function waitForRegistrationsUpdatedAtAdvanceDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    baselineUpdatedAt: Date | null;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<{
+    advanced: boolean;
+    latestUpdatedAt: Date | null;
+}>;
+/**
+ * UPDATE a workflow_registrations row's commit_sha. Used by cron-scheduler
+ * e2e where the manual-schedule handler rejects null commit SHAs.
+ */
+export declare function updateWorkflowRegistrationCommitShaDirect(databaseUrl: string, opts: {
+    id: string;
+    commitSha: string;
+}): Promise<void>;
+/**
+ * Lock-entry seeding for the admin-API e2e, which uses a custom
+ * shape (cron schedule). Returns the inserted id.
+ */
+export declare function insertWorkflowRegistrationRawDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    repoIdentifier: string;
+    workflowName: string;
+    lockEntry: Record<string, unknown>;
+    triggerTypes: string[];
+    customerId: string;
+    isGlobal?: boolean;
+    disabled?: boolean;
+    commitSha?: string;
+    id?: string;
+}): Promise<{
+    id: string;
+}>;
+/**
+ * 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).
+ */
+export declare function insertWorkflowRegistrationStrictDirect(databaseUrl: string, opts: {
+    routingKey: string;
+    repoIdentifier: string;
+    workflowName: string;
+    lockEntryJson?: string;
+    triggerTypes: readonly string[];
+    customerId: string;
+}): Promise<{
+    id: string | null;
+}>;
+/**
+ * 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.
+ */
+export declare function getRegistryVersionDirect(databaseUrl: string, opts?: {
+    id?: string;
+}): Promise<number | null>;
+/**
+ * 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.
+ */
+export declare function bumpRegistryVersionSimpleDirect(databaseUrl: string, opts?: {
+    id?: string;
+}): Promise<void>;
+/**
+ * Seed cron_last_fired for a registration with an `-INTERVAL` offset so
+ * the scheduler fires on the next evaluation. Upsert via ON CONFLICT.
+ */
+export declare function upsertCronLastFiredDirect(databaseUrl: string, opts: {
+    registrationId: string;
+    agoInterval: string;
+}): Promise<void>;
+/**
+ * READ-ONLY: count cron_last_fired rows for a registration. Used by
+ * registration-schema e2e to assert the FK cascade deletes the row.
+ */
+export declare function countCronLastFiredDirect(databaseUrl: string, opts: {
+    registrationId: string;
+}): Promise<number>;
+/**
+ * INSERT a cron_last_fired row with an explicit timestamp. Used by
+ * registration-schema e2e to set up the FK cascade test.
+ */
+export declare function insertCronLastFiredNowDirect(databaseUrl: string, opts: {
+    registrationId: string;
+}): Promise<void>;
+/**
+ * DELETE cron_last_fired rows for a registration. Teardown helper.
+ */
+export declare function deleteCronLastFiredDirect(databaseUrl: string, opts: {
+    registrationId: string;
+}): Promise<void>;
+/**
+ * DELETE execution_runs by workflow_name. Teardown helper for
+ * manual-schedule e2e.
+ */
+export declare function deleteExecutionRunsByWorkflowNameDirect(databaseUrl: string, opts: {
+    workflowName: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * READ-ONLY: SELECT generic_webhook_sources by routing_key.
+ * Used by forgejo e2e to assert the source exists with correct git_config.
+ */
+export declare function getGenericWebhookSourceByRoutingKeyDirect(databaseUrl: string, opts: {
+    routingKey: string;
+}): Promise<{
+    id: string;
+    git_config: unknown;
+    customer_id: string | null;
+} | null>;
+/**
+ * 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.
+ */
+export declare function listActiveGenericWebhookSourcesDirect(databaseUrl: string): Promise<Array<{
+    id: string;
+    customer_id: string | null;
+    routing_key: string;
+}>>;
+/**
+ * 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.
+ */
+export declare function updateGenericWebhookVerificationConfigDirect(databaseUrl: string, opts: {
+    name: string;
+    customerId: string;
+    verificationConfig: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * DELETE generic_webhook_sources by name list. Teardown for the auth
+ * e2e, which seeded 3 sources by name.
+ */
+export declare function deleteGenericWebhookSourcesByNameDirect(databaseUrl: string, opts: {
+    names: readonly string[];
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * 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.
+ */
+export declare function restoreSoftDeletedGenericWebhookSourceDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<void>;
+/**
+ * One entry in any of the three repo-pattern lists stored on `org_settings`.
+ * `routingKey` is the source-qualifier; when absent, the entry applies to
+ * any source in the org.
+ */
+export interface OrgSettingsRepoPatternEntry {
+    routingKey?: string;
+    pattern: string;
+}
+/**
+ * UPSERT org_settings for a customer/org id. `globalWorkflowsEnabled` is
+ * required; the three list fields are each optional. Each list is a jsonb
+ * array of `{routingKey?, pattern}` entries. Pass `null` to clear a list.
+ */
+export interface UpsertOrgSettingsOpts {
+    customerId: string;
+    globalWorkflowsEnabled: boolean;
+    allowedRepos?: OrgSettingsRepoPatternEntry[] | null;
+    deniedRepos?: OrgSettingsRepoPatternEntry[] | null;
+    elevatedRepos?: OrgSettingsRepoPatternEntry[] | null;
+}
+export declare function upsertOrgSettingsGlobalWorkflowsDirect(databaseUrl: string, opts: UpsertOrgSettingsOpts): Promise<void>;
+/**
+ * UPDATE org_settings.global_workflow_denied_repos for a customer/org id.
+ * Assumes the row exists (upsertOrgSettingsGlobalWorkflowsDirect was
+ * called earlier in the test).
+ */
+export declare function updateOrgSettingsDeniedReposDirect(databaseUrl: string, opts: {
+    customerId: string;
+    deniedRepos: OrgSettingsRepoPatternEntry[] | null;
+}): Promise<void>;
+/**
+ * DELETE org_settings by customer/org id. Teardown helper.
+ */
+export declare function deleteOrgSettingsByCustomerIdDirect(databaseUrl: string, opts: {
+    customerId: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * READ-ONLY: fetch an execution_runs row by run_id, returning the
+ * security-relevant columns the ci-security e2e asserts on. Throws
+ * when the row is missing.
+ */
+export interface ExecutionRunSecurityRow {
+    run_id: string;
+    trust_tier: string | null;
+    lock_file_source: string | null;
+    contributor_username: string | null;
+    status: string;
+}
+export declare function getExecutionRunSecurityDirect(databaseUrl: string, opts: {
+    runId: string;
+}): Promise<ExecutionRunSecurityRow>;
+/**
+ * READ-ONLY: fetch a held_runs row by id (with the security columns).
+ * Returns null if missing.
+ */
+export interface HeldRunSecurityRow {
+    id: string;
+    run_id: string;
+    hold_type: string;
+    queue_type: string;
+    status: string;
+    reason: string | null;
+    expires_at: string | null;
+    approved_by: string | null;
+    resolved_at: string | null;
+}
+export declare function getHeldRunByIdDirect(databaseUrl: string, opts: {
+    id: string;
+}): Promise<HeldRunSecurityRow | null>;
+/**
+ * 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.
+ */
+export declare function countHeldRunsByRunIdDirect(databaseUrl: string, opts: {
+    runId: string;
+    queueType?: string;
+}): Promise<number>;
+/**
+ * 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).
+ */
+export declare function waitForPlatformExecutionRunStatusDirect(databaseUrl: string, opts: {
+    status: string;
+    since: Date;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<{
+    status: string;
+    failure_reason: string | null;
+} | null>;
+/**
+ * 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).
+ */
+export declare function waitForPlatformEventLogDistinctRoutedDirect(databaseUrl: string, opts: {
+    since: Date;
+    minDistinctRouted: number;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<{
+    distinctRouted: number;
+}>;
+/**
+ * Wait for an orchestrator `event_log` row keyed by `delivery_id`.
+ * Returns the full row (the webhook-pipeline e2e asserts many
+ * columns) or null on timeout.
+ */
+export interface EventLogRow {
+    org_id: string;
+    delivery_id: string;
+    status: string;
+    source: string;
+    event: string;
+    provider: string;
+    payload_hash: string;
+    payload_omitted: boolean;
+    payload_key: string | null;
+    payload_size_bytes: number;
+    matched_count: number;
+    run_id: string | null;
+}
+export declare function waitForEventLogRowByDeliveryIdDirect(databaseUrl: string, opts: {
+    deliveryId: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<EventLogRow | null>;
+/**
+ * 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.
+ */
+export declare function resolvePlatformWebhookSourceRoutingKeyDirect(platformDbUrl: string, opts: {
+    orgId: string;
+    routingKeyLikePrefix: string;
+    orchDbUrl?: string;
+    nameInOrchDb?: string;
+}): Promise<string | null>;
+/**
+ * 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.
+ */
+export declare function ensureOrgOwnerMemberDirect(platformDbUrl: string, opts: {
+    orgId: string;
+    zitadelSub: string;
+    email: string;
+    displayName: string;
+}): Promise<{
+    ownerRoleId: string;
+}>;
+/**
+ * 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.
+ */
+export declare function deletePeerCredentialsByInstanceIdLikeDirect(databaseUrl: string, opts: {
+    pattern: string;
+}): Promise<{
+    deleted: number;
+}>;
+/**
+ * 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.
+ */
+export declare function insertPeerCredentialExpiredDirect(databaseUrl: string, opts: {
+    instanceId: string;
+    credentialHash: string;
+    role: string;
+    routingKeys: readonly string[];
+    expiresAt: Date;
+}): Promise<void>;
+/**
+ * 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").
+ */
+export declare function getPeerCredentialRevokedAtDirect(databaseUrl: string, opts: {
+    credentialHash: string;
+}): Promise<{
+    present: boolean;
+    revokedAt: Date | null;
+}>;
+/**
+ * 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.
+ */
+export declare function listActivePeerCredentialsExcludingDirect(databaseUrl: string, opts: {
+    excludeInstanceIdPattern: string;
+}): Promise<{
+    ids: string[];
+}>;
+/**
+ * Clear revoked_at on a set of peer_credentials ids. Used by revokeAll
+ * e2e to restore real cluster credentials after the destructive test.
+ */
+export declare function clearPeerCredentialsRevokedAtByIdsDirect(databaseUrl: string, opts: {
+    ids: readonly string[];
+}): Promise<{
+    updated: number;
+}>;
+/**
+ * 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.
+ */
+export declare function countActivePeerCredentialsByInstanceDirect(databaseUrl: string, opts: {
+    instanceId: string;
+}): Promise<number>;
+export {};
+//# sourceMappingURL=db-admin.d.ts.map