bunsane 0.5.5 → 0.5.7

package/core/scheduler/locks/AdvisoryLockBackend.ts

@@ -0,0 +1,276 @@
+/**
+ * AdvisoryLockBackend — PostgreSQL session advisory locks (`pg_advisory_lock`).
+ *
+ * The framework's historical lock primitive, preserved as an OPT-IN backend.
+ *
+ * ⚠️  Advisory locks are bound to the PostgreSQL *session* that took them. This
+ * backend pins one connection via `sql.reserve()` and routes every lock/unlock
+ * through it, so a process's locks all live in one session and unlock always
+ * hits the acquiring session. If the process crashes, PostgreSQL drops the
+ * session and releases every lock automatically.
+ *
+ * This is ONLY safe when the client→server path preserves session affinity,
+ * i.e. a direct PostgreSQL connection or pgbouncer in `session`/`statement`
+ * mode. Behind pgbouncer `pool_mode = transaction` the reserved connection
+ * pins client→pgbouncer but NOT pgbouncer→backend, so lock and unlock land on
+ * different backends and the lock strands silently (BUNSANE-1). Prefer
+ * {@link PostgresLeaseLockBackend} unless you control a session-pinned lane.
+ *
+ * @see https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS
+ */
+
+import { randomUUID } from "crypto";
+import type { ReservedSQL, SQL } from "bun";
+import db from "../../../database";
+import { logger } from "../../Logger";
+import type { AcquireOptions, LockBackend, LockHandle } from "./LockBackend";
+
+const loggerInstance = logger.child({ scope: "AdvisoryLockBackend" });
+
+/**
+ * Thrown on first use when the advisory backend detects it is NOT on a
+ * session-pinned connection (i.e. behind a transaction-pooling pooler), where
+ * advisory locks strand silently (BUNSANE-1/-7). This is a configuration error,
+ * not a transient lock failure — {@link DistributedLock} re-throws it so the
+ * misconfiguration fails loudly instead of silently skipping critical sections.
+ * Acknowledge and bypass with `BUNSANE_ALLOW_UNSAFE_ADVISORY_LOCK=true`.
+ */
+export class UnsafeAdvisoryPoolingError extends Error {
+    constructor() {
+        super(
+            "Advisory lock backend is running on a connection without session affinity " +
+                "(transaction-pooling pooler detected). Session advisory locks strand silently here. " +
+                "Use the default 'postgres' lease backend, point this app at a session-pinned lane, " +
+                "or set BUNSANE_ALLOW_UNSAFE_ADVISORY_LOCK=true to override at your own risk."
+        );
+        this.name = "UnsafeAdvisoryPoolingError";
+    }
+}
+
+export interface AdvisoryBackendConfig {
+    /** Namespace prefix occupying the high 32 bits of the advisory key. */
+    lockKeyPrefix: number;
+    enableLogging: boolean;
+}
+
+const DEFAULT_PREFIX = 0x42554e53; // "BUNS"
+
+interface AdvisoryInternal {
+    bigintKey: bigint;
+}
+
+export class AdvisoryLockBackend implements LockBackend {
+    readonly name = "advisory";
+    private config: AdvisoryBackendConfig;
+    private readonly sql: SQL;
+
+    private reservedConn: ReservedSQL | null = null;
+    private reservePromise: Promise<ReservedSQL> | null = null;
+    /** Outstanding handles; the reserved session is freed when this hits 0. */
+    private outstanding = 0;
+    /** Session-affinity probe runs once per reserved session. */
+    private safetyChecked = false;
+
+    constructor(config: Partial<AdvisoryBackendConfig> = {}, sql: SQL = db) {
+        this.config = {
+            lockKeyPrefix: config.lockKeyPrefix ?? DEFAULT_PREFIX,
+            enableLogging: config.enableLogging ?? false,
+        };
+        this.sql = sql;
+    }
+
+    /**
+     * 32-bit string hash folded into the low half of the advisory key under a
+     * fixed 32-bit prefix. NOTE (BUNSANE-4): effective key space is ~2^32, so
+     * distinct keys can hash-collide onto the same advisory id → false
+     * contention. Acceptable for the opt-in advisory path; lease backends key
+     * on the raw text and have no such collision.
+     */
+    private generateLockKey(key: string): bigint {
+        let hash = 0;
+        for (let i = 0; i < key.length; i++) {
+            const char = key.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash;
+        }
+        hash = Math.abs(hash);
+        const prefix = BigInt(this.config.lockKeyPrefix);
+        const hashBigInt = BigInt(hash >>> 0);
+        return (prefix << 32n) | hashBigInt;
+    }
+
+    private async ensureReserved(): Promise<ReservedSQL> {
+        if (this.reservedConn) return this.reservedConn;
+        if (!this.reservePromise) {
+            // On reject (pool exhausted / shutdown mid-reserve), null the
+            // promise so the next caller retries a fresh reserve rather than
+            // re-awaiting the same rejected one forever (H-DB-2).
+            this.reservePromise = this.sql.reserve().then(
+                (conn) => {
+                    this.reservedConn = conn;
+                    this.reservePromise = null;
+                    return conn;
+                },
+                (err) => {
+                    this.reservePromise = null;
+                    throw err;
+                }
+            );
+        }
+        return this.reservePromise;
+    }
+
+    private releaseReservationIfIdle(): void {
+        if (this.outstanding > 0 || !this.reservedConn) return;
+        try {
+            this.reservedConn.release();
+        } catch (error) {
+            loggerInstance.warn(
+                `Failed to release reserved connection: ${error instanceof Error ? error.message : String(error)}`
+            );
+        }
+        this.reservedConn = null;
+    }
+
+    /**
+     * Verify the reserved connection has session affinity. Sets a session GUC
+     * then reads it back on a SEPARATE query: under a transaction pooler the two
+     * queries land on different backends so the value is lost, exposing the
+     * silently-unsafe config (BUNSANE-1/-7). Runs once per session. A probe that
+     * errors out (e.g. an engine that disallows the GUC) is treated as
+     * inconclusive → assume safe rather than block. Throws
+     * {@link UnsafeAdvisoryPoolingError} on an affirmative "not pinned" unless
+     * acknowledged via `BUNSANE_ALLOW_UNSAFE_ADVISORY_LOCK=true`.
+     */
+    private async checkSessionAffinity(conn: ReservedSQL): Promise<void> {
+        if (this.safetyChecked) return;
+
+        if (process.env.BUNSANE_ALLOW_UNSAFE_ADVISORY_LOCK === "true") {
+            this.safetyChecked = true;
+            return;
+        }
+
+        const token = randomUUID();
+        let readBack: string | null = null;
+        try {
+            await conn`SELECT set_config('bunsane.lock_affinity_probe', ${token}, false)`;
+            const rows = await conn`
+                SELECT current_setting('bunsane.lock_affinity_probe', true) AS v
+            `;
+            readBack = rows[0]?.v ?? null;
+        } catch (error) {
+            // Inconclusive (engine rejected the GUC, etc.) — don't block.
+            loggerInstance.debug(
+                `Session-affinity probe inconclusive, assuming safe: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.safetyChecked = true;
+            return;
+        }
+
+        if (readBack !== token) {
+            loggerInstance.error(
+                "Advisory lock backend has NO session affinity — a transaction-pooling pooler is " +
+                    "multiplexing queries across backends. Session advisory locks WILL strand silently " +
+                    "(see BUNSANE-1). Switch to the 'postgres' lease backend or a session-pinned lane."
+            );
+            throw new UnsafeAdvisoryPoolingError();
+        }
+        this.safetyChecked = true;
+    }
+
+    async acquire(key: string, _opts?: AcquireOptions): Promise<LockHandle | null> {
+        const bigintKey = this.generateLockKey(key);
+
+        // Reserve the session (transient failures → null, retried next call).
+        let conn: ReservedSQL;
+        try {
+            conn = await this.ensureReserved();
+        } catch (error) {
+            loggerInstance.error(
+                `Error reserving connection for advisory lock ${key}: ${error instanceof Error ? error.message : String(error)}`
+            );
+            return null;
+        }
+
+        // Fail LOUD on an unsafe pooling config (throws past the catch below).
+        await this.checkSessionAffinity(conn);
+
+        try {
+            const result = await conn`
+                SELECT pg_try_advisory_lock(${bigintKey}::bigint) as locked
+            `;
+            const acquired = result[0]?.locked ?? false;
+            if (!acquired) {
+                this.releaseReservationIfIdle();
+                return null;
+            }
+            this.outstanding++;
+            if (this.config.enableLogging) {
+                loggerInstance.debug(`Acquired advisory lock ${key} (${bigintKey})`);
+            }
+            const internal: AdvisoryInternal = { bigintKey };
+            return { key, token: bigintKey.toString(), expiresAt: null, _internal: internal };
+        } catch (error) {
+            loggerInstance.error(
+                `Error acquiring advisory lock ${key}: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.releaseReservationIfIdle();
+            return null;
+        }
+    }
+
+    async release(handle: LockHandle): Promise<boolean> {
+        const { bigintKey } = (handle._internal as AdvisoryInternal) ?? {
+            bigintKey: this.generateLockKey(handle.key),
+        };
+        if (!this.reservedConn) {
+            loggerInstance.warn(
+                `No reserved connection to release advisory lock ${handle.key}`
+            );
+            return false;
+        }
+        try {
+            const result = await this.reservedConn`
+                SELECT pg_advisory_unlock(${bigintKey}::bigint) as unlocked
+            `;
+            const released = result[0]?.unlocked ?? false;
+            this.outstanding = Math.max(0, this.outstanding - 1);
+            // A false unlock is the canonical stranded-lock signal (BUNSANE-1/2);
+            // the DistributedLock facade promotes it to a loud ERROR + counter,
+            // so keep the backend log at debug to avoid double-logging.
+            if (this.config.enableLogging) {
+                loggerInstance.debug(
+                    released
+                        ? `Released advisory lock ${handle.key} (${bigintKey})`
+                        : `pg_advisory_unlock returned false for ${handle.key} (${bigintKey}) — may be stranded on another backend`
+                );
+            }
+            this.releaseReservationIfIdle();
+            return released;
+        } catch (error) {
+            loggerInstance.error(
+                `Error releasing advisory lock ${handle.key}: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.outstanding = Math.max(0, this.outstanding - 1);
+            this.releaseReservationIfIdle();
+            return false;
+        }
+    }
+
+    async dispose(): Promise<void> {
+        this.outstanding = 0;
+        this.safetyChecked = false; // new session must re-probe affinity
+        if (this.reservedConn) {
+            try {
+                this.reservedConn.release();
+            } catch {
+                /* best-effort on shutdown */
+            }
+            this.reservedConn = null;
+        }
+    }
+
+    updateConfig(config: Partial<AdvisoryBackendConfig>): void {
+        this.config = { ...this.config, ...config };
+    }
+}

package/core/scheduler/locks/InProcessLockBackend.ts

@@ -0,0 +1,85 @@
+/**
+ * InProcessLockBackend — single-process mutual exclusion via an in-memory Map.
+ *
+ * Correct for single-instance deployments and as a faithful test double:
+ * unlike the old `enabled:false` no-op (which pretended every acquire
+ * succeeded and so never exercised contention), this backend genuinely refuses
+ * a second holder of the same key and honours lease expiry. Two backend
+ * *instances* sharing one process do NOT share state — construct one per
+ * process and share it (this is what the singleton wiring does).
+ *
+ * It provides no cross-process exclusion. Use {@link PostgresLeaseLockBackend}
+ * or {@link RedisLockBackend} for multi-instance deployments.
+ */
+
+import { randomUUID } from "crypto";
+import type { AcquireOptions, LockBackend, LockHandle } from "./LockBackend";
+
+const DEFAULT_TTL_MS = 30_000;
+
+interface Lease {
+    token: string;
+    expiresAt: number; // Date.now() scale
+}
+
+export class InProcessLockBackend implements LockBackend {
+    readonly name = "in-process";
+    private readonly leases = new Map<string, Lease>();
+
+    private now(): number {
+        // Date.now is fine in normal runtime code (forbidden only in workflow
+        // scripts). Centralised so tests can stub if needed.
+        return Date.now();
+    }
+
+    private isLive(lease: Lease | undefined): lease is Lease {
+        return !!lease && lease.expiresAt > this.now();
+    }
+
+    async acquire(key: string, opts?: AcquireOptions): Promise<LockHandle | null> {
+        const existing = this.leases.get(key);
+        if (this.isLive(existing)) {
+            return null; // someone else holds a live lease
+        }
+        // No live holder (free, or the prior lease lapsed → steal it).
+        const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+        const token = randomUUID();
+        const expiresAt = this.now() + ttlMs;
+        this.leases.set(key, { token, expiresAt });
+        return { key, token, expiresAt };
+    }
+
+    async renew(handle: LockHandle, ttlMs: number): Promise<boolean> {
+        const lease = this.leases.get(handle.key);
+        // Only the current owner may renew; a lapsed-and-stolen lease fails.
+        if (!this.isLive(lease) || lease.token !== handle.token) {
+            return false;
+        }
+        lease.expiresAt = this.now() + ttlMs;
+        return true;
+    }
+
+    async release(handle: LockHandle): Promise<boolean> {
+        const lease = this.leases.get(handle.key);
+        if (!lease || lease.token !== handle.token) {
+            // Already gone, or we lost ownership (lapsed + restolen). The latter
+            // is the "stranded lease" signal.
+            return false;
+        }
+        this.leases.delete(handle.key);
+        return true;
+    }
+
+    async dispose(): Promise<void> {
+        this.leases.clear();
+    }
+
+    /** Test helper: number of live leases currently held. */
+    liveCount(): number {
+        let n = 0;
+        for (const lease of this.leases.values()) {
+            if (this.isLive(lease)) n++;
+        }
+        return n;
+    }
+}

package/core/scheduler/locks/LockBackend.ts

@@ -0,0 +1,91 @@
+/**
+ * LockBackend — pluggable mutual-exclusion primitive behind {@link DistributedLock}.
+ *
+ * Three concrete backends ship with the framework:
+ *  - {@link InProcessLockBackend}    — single-instance, in-memory. No infra.
+ *  - {@link PostgresLeaseLockBackend} — lease-row table, pooler-safe. Default
+ *    distributed backend (each acquire/renew/release is one short transaction,
+ *    so it works behind pgbouncer `pool_mode = transaction`).
+ *  - {@link AdvisoryLockBackend}     — PostgreSQL session advisory locks. The
+ *    historical default; opt-in only because it REQUIRES a session-pinned
+ *    connection lane (breaks silently behind a transaction pooler — see
+ *    docs/TICKETS_LOCK_POOLING_DATALOADER_2026-06-22.md, BUNSANE-1).
+ *
+ * The unifying model is a *lease*: a holder owns `key` until it releases it or
+ * `expiresAt` passes. Advisory locks have no TTL (they live for the session),
+ * so `ttlMs`/`renew` are best-effort: a backend that cannot honour a lease
+ * simply ignores `ttlMs` and omits `renew`.
+ */
+
+/**
+ * Opaque proof of ownership returned by {@link LockBackend.acquire}. Must be
+ * passed back to `renew`/`release` so a backend can verify the caller still
+ * owns the lease (fencing) before mutating shared state.
+ */
+export interface LockHandle {
+    /** The logical lock key the caller asked for. */
+    key: string;
+    /**
+     * Unique-per-acquisition owner token. Lease backends compare-and-act on
+     * this so a holder whose lease already expired and was stolen cannot
+     * release/renew the new holder's lease.
+     */
+    token: string;
+    /**
+     * Wall-clock ms (Date.now scale) at which the lease lapses, or `null` for
+     * session-bound backends (advisory) that have no TTL.
+     */
+    expiresAt: number | null;
+    /**
+     * Backend-private scratch space (e.g. the bigint advisory key). Not part of
+     * the public contract — never read it outside the backend that set it.
+     */
+    readonly _internal?: unknown;
+}
+
+export interface AcquireOptions {
+    /**
+     * Desired lease lifetime in ms. Lease backends use this as the TTL;
+     * session-bound backends ignore it. Renew before this elapses for work
+     * that outlives the lease.
+     */
+    ttlMs?: number;
+}
+
+/**
+ * A pluggable lock primitive. Implementations MUST be safe to call
+ * concurrently and MUST treat `acquire` as atomic: at most one live handle
+ * exists per `key` across every process sharing the backend's store.
+ */
+export interface LockBackend {
+    /** Stable identifier for logs/metrics (e.g. "postgres-lease"). */
+    readonly name: string;
+
+    /**
+     * Try once to acquire `key`. Resolves to a {@link LockHandle} on success or
+     * `null` if another holder owns it. Never blocks/retries — the caller
+     * ({@link DistributedLock}) owns the wait loop.
+     */
+    acquire(key: string, opts?: AcquireOptions): Promise<LockHandle | null>;
+
+    /**
+     * Extend an owned lease by `ttlMs`. Returns `false` if the handle no longer
+     * owns the lock (expired and stolen, or already released). Optional:
+     * session-bound backends omit it (their lock never lapses while held).
+     */
+    renew?(handle: LockHandle, ttlMs: number): Promise<boolean>;
+
+    /**
+     * Release an owned lock. Returns `true` if this handle released a lock it
+     * genuinely held, `false` if the lock was already gone / owned by someone
+     * else (a `false` here is the canonical "stranded/lost lease" signal —
+     * callers should surface it loudly, see BUNSANE-2).
+     */
+    release(handle: LockHandle): Promise<boolean>;
+
+    /**
+     * Release any backend-held resources (pooled connection, redis client
+     * subscription). Called on shutdown. Idempotent.
+     */
+    dispose?(): Promise<void>;
+}

package/core/scheduler/locks/PostgresLeaseLockBackend.ts

@@ -0,0 +1,159 @@
+/**
+ * PostgresLeaseLockBackend — pooler-safe distributed lock via a lease-row table.
+ *
+ * Each operation (acquire / renew / release) is a SINGLE autocommit statement,
+ * so it runs in exactly one transaction on one backend. That makes it correct
+ * behind pgbouncer `pool_mode = transaction` — unlike session advisory locks,
+ * which strand when lock and unlock land on different backends (BUNSANE-1). It
+ * also keys on the raw text `key`, so distinct keys never collide (no 32-bit
+ * hash folding — BUNSANE-4).
+ *
+ * Crash safety: a holder owns `key` until it deletes its row OR `expires_at`
+ * passes. A crashed holder's lease lapses after `ttlMs` and the next acquirer
+ * steals it. Long-running work must `renew` before the lease elapses (the
+ * DistributedLock/withLock layer drives a heartbeat).
+ *
+ * Fencing: `owner` is a per-acquisition random token. renew/release act only on
+ * `key = $key AND owner = $token`, so a holder whose lease expired and was
+ * stolen cannot renew or release the new holder's lease (returns false — the
+ * canonical lost-lease signal).
+ *
+ * The table is created lazily and idempotently on first use, so `withLock`
+ * works even without a full `App.init()` migration pass.
+ */
+
+import { randomUUID } from "crypto";
+import type { SQL } from "bun";
+import db from "../../../database";
+import { logger } from "../../Logger";
+import type { AcquireOptions, LockBackend, LockHandle } from "./LockBackend";
+
+const loggerInstance = logger.child({ scope: "PostgresLeaseLockBackend" });
+
+const TABLE = "bunsane_locks";
+const DEFAULT_TTL_MS = 30_000;
+
+export interface PostgresLeaseBackendConfig {
+    enableLogging: boolean;
+}
+
+export class PostgresLeaseLockBackend implements LockBackend {
+    readonly name = "postgres-lease";
+    private config: PostgresLeaseBackendConfig;
+    private readonly sql: SQL;
+    /** Runs the idempotent table create exactly once per backend instance. */
+    private tableReady: Promise<void> | null = null;
+
+    constructor(config: Partial<PostgresLeaseBackendConfig> = {}, sql: SQL = db) {
+        this.config = { enableLogging: config.enableLogging ?? false };
+        this.sql = sql;
+    }
+
+    private ensureTable(): Promise<void> {
+        if (!this.tableReady) {
+            this.tableReady = this.sql
+                .unsafe(
+                    `CREATE TABLE IF NOT EXISTS ${TABLE} (
+                        key text PRIMARY KEY,
+                        owner text NOT NULL,
+                        expires_at timestamptz NOT NULL
+                    )`
+                )
+                .then(() => undefined)
+                .catch((err) => {
+                    // Reset so a transient failure (pool exhausted at boot)
+                    // retries on the next call rather than caching the reject.
+                    this.tableReady = null;
+                    throw err;
+                });
+        }
+        return this.tableReady;
+    }
+
+    async acquire(key: string, opts?: AcquireOptions): Promise<LockHandle | null> {
+        const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+        const token = randomUUID();
+        try {
+            await this.ensureTable();
+            // Fresh insert OR steal of an expired lease both RETURN a row whose
+            // owner is us. A live foreign lease fails the conditional UPDATE and
+            // RETURNING yields zero rows.
+            const rows = await this.sql.unsafe(
+                `INSERT INTO ${TABLE} (key, owner, expires_at)
+                 VALUES ($1, $2, now() + ($3::bigint * interval '1 millisecond'))
+                 ON CONFLICT (key) DO UPDATE
+                     SET owner = excluded.owner, expires_at = excluded.expires_at
+                     WHERE ${TABLE}.expires_at < now()
+                 RETURNING (owner = $2) AS acquired`,
+                [key, token, ttlMs]
+            );
+            const acquired = rows.length > 0 && rows[0]?.acquired === true;
+            if (!acquired) return null;
+
+            if (this.config.enableLogging) {
+                loggerInstance.debug(`Acquired lease ${key} (ttl ${ttlMs}ms)`);
+            }
+            return { key, token, expiresAt: Date.now() + ttlMs };
+        } catch (error) {
+            loggerInstance.error(
+                `Error acquiring lease ${key}: ${error instanceof Error ? error.message : String(error)}`
+            );
+            return null;
+        }
+    }
+
+    async renew(handle: LockHandle, ttlMs: number): Promise<boolean> {
+        try {
+            const rows = await this.sql.unsafe(
+                `UPDATE ${TABLE}
+                 SET expires_at = now() + ($3::bigint * interval '1 millisecond')
+                 WHERE key = $1 AND owner = $2 AND expires_at > now()
+                 RETURNING 1 AS renewed`,
+                [handle.key, handle.token, ttlMs]
+            );
+            return rows.length > 0;
+        } catch (error) {
+            loggerInstance.error(
+                `Error renewing lease ${handle.key}: ${error instanceof Error ? error.message : String(error)}`
+            );
+            return false;
+        }
+    }
+
+    async release(handle: LockHandle): Promise<boolean> {
+        try {
+            // Delete only our own row. A row stolen after our lease lapsed has a
+            // different owner → 0 rows → false (lost-lease signal).
+            const rows = await this.sql.unsafe(
+                `DELETE FROM ${TABLE}
+                 WHERE key = $1 AND owner = $2
+                 RETURNING 1 AS released`,
+                [handle.key, handle.token]
+            );
+            const released = rows.length > 0;
+            // A 0-row release (lease stolen / already gone) is surfaced loudly
+            // by the DistributedLock facade; keep the backend log at debug to
+            // avoid double-logging.
+            if (this.config.enableLogging) {
+                loggerInstance.debug(
+                    released
+                        ? `Released lease ${handle.key}`
+                        : `Lease release for ${handle.key} affected 0 rows (stolen or already released)`
+                );
+            }
+            return released;
+        } catch (error) {
+            loggerInstance.error(
+                `Error releasing lease ${handle.key}: ${error instanceof Error ? error.message : String(error)}`
+            );
+            return false;
+        }
+    }
+
+    async dispose(): Promise<void> {
+        // Stateless aside from the table-ready cache; nothing to release. Rows
+        // self-expire via TTL; an explicit releaseAll() at the DistributedLock
+        // layer deletes still-held leases on graceful shutdown.
+        this.tableReady = null;
+    }
+}

package/core/scheduler/locks/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Lock backend selection + factory.
+ *
+ * Resolution order: explicit `config.kind` → `BUNSANE_LOCK_BACKEND` env →
+ * `'auto'`. `'auto'` resolves to the safest correct default for the deployment.
+ *
+ * `'auto'` resolves to `'postgres'` (pooler-safe lease): the default lock
+ * primitive is now correct behind pgbouncer transaction pooling. The old
+ * advisory primitive (silently broken behind a pooler — BUNSANE-1) is opt-in
+ * via `'advisory'`, and only safe on a session-pinned connection lane.
+ */
+
+import { logger } from "../../Logger";
+import type { LockBackend } from "./LockBackend";
+import { InProcessLockBackend } from "./InProcessLockBackend";
+import { AdvisoryLockBackend } from "./AdvisoryLockBackend";
+import { PostgresLeaseLockBackend } from "./PostgresLeaseLockBackend";
+
+const loggerInstance = logger.child({ scope: "LockBackend" });
+
+export type LockBackendKind =
+    | "auto"
+    | "in-process"
+    | "postgres"
+    | "redis"
+    | "advisory";
+
+export interface LockBackendConfig {
+    /** Which backend to use. Default resolves via env then `'auto'`. */
+    kind?: LockBackendKind;
+    /** Advisory backend only: 32-bit namespace prefix for the advisory key. */
+    lockKeyPrefix?: number;
+    enableLogging?: boolean;
+}
+
+function resolveKind(kind: LockBackendKind | undefined): Exclude<LockBackendKind, "auto"> {
+    const requested =
+        kind ?? (process.env.BUNSANE_LOCK_BACKEND as LockBackendKind | undefined) ?? "auto";
+
+    if (requested === "auto") {
+        // Pooler-safe lease is the correct default behind PgBouncer transaction
+        // pooling. Single-instance deploys may opt down to 'in-process'.
+        return "postgres";
+    }
+    return requested;
+}
+
+export function createLockBackend(config: LockBackendConfig = {}): LockBackend {
+    const kind = resolveKind(config.kind);
+
+    switch (kind) {
+        case "in-process":
+            return new InProcessLockBackend();
+        case "advisory":
+            return new AdvisoryLockBackend({
+                lockKeyPrefix: config.lockKeyPrefix,
+                enableLogging: config.enableLogging,
+            });
+        case "postgres":
+            return new PostgresLeaseLockBackend({
+                enableLogging: config.enableLogging,
+            });
+        case "redis":
+            // Implemented in Phase 4.
+            loggerInstance.error(
+                `Lock backend 'redis' is not implemented yet; falling back to postgres-lease.`
+            );
+            return new PostgresLeaseLockBackend({
+                enableLogging: config.enableLogging,
+            });
+        default: {
+            const exhaustive: never = kind;
+            throw new Error(`Unknown lock backend: ${String(exhaustive)}`);
+        }
+    }
+}
+
+export type { LockBackend, LockHandle, AcquireOptions } from "./LockBackend";
+export { InProcessLockBackend } from "./InProcessLockBackend";
+export { AdvisoryLockBackend, UnsafeAdvisoryPoolingError } from "./AdvisoryLockBackend";
+export { PostgresLeaseLockBackend } from "./PostgresLeaseLockBackend";