@shivaedev/test-sql 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.15.0 - 2026-10-30
+
+### Added
+
+- `observeUntil(read, settled, waitingFor, options?)` from `@shivaedev/test-sql/server/observeUntil.ts` waits for PostgreSQL state that sends no notification, such as sessions in `pg_stat_activity` or lock waiters. It repeats one read on live time, even under a paused test clock, and returns the value once `settled` holds for `stableReads` reads in a row (default 2), so a value that flips back is not accepted. When `within` (default 5 seconds) runs out it fails with a typed `NeverSettled` whose message names what it waited for, the read count and the last value.
+
+### Breaking
+
+- `raceWithLock` waits for its contenders to block through `observeUntil`, so that wait runs on live time. Its `timeout` now bounds each phase on its own: taking the lock and the contenders' finish after release still fail with `TimeoutError`, while contenders that never all block fail with `NeverSettled` naming how many blocked. Handle `NeverSettled` wherever you handled the `TimeoutError` of contenders that never queued on the lock.
+
 ## 0.14.0 - 2026-10-30
 
 ### Added

package/README.md

@@ -169,7 +169,21 @@ expect(results.filter(Result.isSuccess)).toHaveLength(1);
 expect(results.filter(Result.isFailure).map((result) => result.failure)).toEqual(["full", "full"]);
 ```
 
-`claimLastPlace` is the application's guarded write, failing with the typed `"full"` value when no place remains; `Result` is Effect's native `Result` module. Results stay in input order, including each call's typed failure. The holder rolls back by default, discarding any writes in `lock`; set `release: "commit"` when a contender must observe the holder's committed write. The default timeout is five seconds; `timeout` accepts an Effect duration. Defects and interruption retain their native failure kind, and the helper's scope owns the holder and competing fibers.
+`claimLastPlace` is the application's guarded write, failing with the typed `"full"` value when no place remains; `Result` is Effect's native `Result` module. Results stay in input order, including each call's typed failure. The holder rolls back by default, discarding any writes in `lock`; set `release: "commit"` when a contender must observe the holder's committed write. `timeout` accepts an Effect duration, five seconds by default, and bounds each phase on its own: taking the lock and the contenders' finish after release fail with `TimeoutError`, and contenders that never all block fail with `NeverSettled` from `observeUntil`, naming how many blocked at the last read. The wait for blocked contenders runs on live time. Defects and interruption retain their native failure kind, and the helper's scope owns the holder and competing fibers.
+
+### Wait for PostgreSQL state that sends no notification
+
+PostgreSQL announces no change to its catalog views: a session leaving `pg_stat_activity` or a backend starting to wait on a lock happens without a signal. `observeUntil` is the one poll for such state. It repeats one read, returns the value once `settled` holds for `stableReads` reads in a row, and sleeps on live time, so a story's paused test clock does not stall it:
+
+```ts
+import { observeUntil } from "@shivaedev/test-sql/server/observeUntil.ts";
+
+const sessions = sql<{ count: number }>`select count(*)::int as count from pg_stat_activity
+	where application_name = ${applicationName}`.pipe(Effect.map(([row]) => row?.count ?? 0));
+yield* observeUntil(sessions, (count) => count === 0, "the app's sessions to close");
+```
+
+Options are `every` (default 25 milliseconds between reads), `within` (default 5 seconds) and `stableReads` (default 2). A count that reaches zero and rises again restarts the run of agreeing reads instead of being accepted. When `within` runs out the Effect fails with a typed `NeverSettled`, whose `last` holds the last value as an `Option` and whose message reads like `Timed out after 1s waiting for the app's sessions to close: 40 reads, last value 1`. Use it only for state PostgreSQL does not announce; wait on the engine's own signals everywhere else.
 
 ### Choose an empty database per story or trait
 
@@ -270,6 +284,7 @@ Import each name from the module that defines it. The package has no root entry.
 | `@shivaedev/test-sql/server/migrationSteps.ts`       | `migrationSteps(appMigrations)` returning `{ migrateTo(name), migrateToLatest }`                                                                                                           |
 | `@shivaedev/test-sql/server/migrationUpgrade.ts`     | `migrationUpgrade({ migrations, upTo, table })`, `MigrationUpgradeOptions`, `PostgresColumn`                                                                                               |
 | `@shivaedev/test-sql/server/assertModelColumns.ts`   | `assertModelColumns(columns, model, types)`, `ModelColumnMismatch`                                                                                                                         |
+| `@shivaedev/test-sql/server/observeUntil.ts`         | `observeUntil(read, settled, waitingFor, { every?, within?, stableReads? }?)`, `NeverSettled`, `ObserveOptions`                                                                            |
 
 `url` is a redacted PostgreSQL URL for an existing administrative database. `PostgresTestDatabase` supplies the current database's redacted `url`, an `awaitCleanup: Effect<void>` drain, a scoped `isolated` Effect that acquires a migrated clone's service Context, and `clone(template)` for an explicit `"empty"` or `"migrated"` choice. With `prepare: false`, both choices are empty. Prefer `withIsolatedDatabase` to acquire and release that Context around a test. Wrappers retain the body's result, failures and unmet service requirements, with native `SqlError` added for acquisition or transaction failures. Cleanup failures surface as SQL defects when the Layer closes. Drops that fail with connection exhaustion (SQLSTATE `53300`) retry every 100 ms of live time for up to 300 retries, even while a test clock is paused; if capacity does not return, the SQL defect remains visible. Startup sweeps databases left by dead processes on the same host and databases from the older unowned naming format. Databases owned by live processes or another host are retained, so local parallel workers keep their databases. Use the same host to reclaim its abandoned databases.
 

package/dist/server/observeUntil.d.ts

@@ -0,0 +1,26 @@
+import { Duration, Effect, Option } from "effect";
+export interface ObserveOptions {
+    readonly every?: Duration.Input;
+    readonly stableReads?: number;
+    readonly within?: Duration.Input;
+}
+declare const NeverSettled_base: new <A_1 extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A_1 as P extends "_tag" ? never : P]: A_1[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NeverSettled";
+} & Readonly<A_1>;
+export declare class NeverSettled<A> extends NeverSettled_base<{
+    readonly reads: number;
+    readonly waitingFor: string;
+    readonly within: Duration.Duration;
+}> {
+    readonly last: Option.Option<A>;
+    constructor({ last, ...fields }: {
+        readonly last: Option.Option<A>;
+        readonly reads: number;
+        readonly waitingFor: string;
+        readonly within: Duration.Duration;
+    });
+    get message(): string;
+}
+export declare const observeUntil: <A, E, R>(read: Effect.Effect<A, E, R>, settled: (value: A) => boolean, waitingFor: string, options?: ObserveOptions | undefined) => Effect.Effect<A, E | NeverSettled<A>, R>;
+export {};
+//# sourceMappingURL=observeUntil.d.ts.map

package/dist/server/observeUntil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeUntil.d.ts","sourceRoot":"","sources":["../../src/server/observeUntil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,QAAQ,EAAE,MAAM,EAAa,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE1E,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CACjC;;;;AAED,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,kBAAiC;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;CACnC,CAAC;IACD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAEhC,YAAY,EACX,IAAI,EACJ,GAAG,MAAM,EACT,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAA;KAAE,EAG9H;IAED,IAAa,OAAO,WAMnB;CACD;AAGD,eAAO,MAAM,YAAY,GAAqD,CAAC,EAAE,CAAC,EAAE,CAAC,iDAEnE,CAAC,KAAK,OAAO,uGAuB7B,CAAC"}

package/dist/server/observeUntil.js

@@ -0,0 +1,35 @@
+import { Clock, Data, Duration, Effect, Formatter, Option } from "effect";
+export class NeverSettled extends Data.TaggedError("NeverSettled") {
+    last;
+    constructor({ last, ...fields }) {
+        super(fields);
+        this.last = last;
+    }
+    get message() {
+        const seen = Option.match(this.last, {
+            onNone: () => "no read finished",
+            onSome: (value) => `${this.reads} ${this.reads === 1 ? "read" : "reads"}, last value ${Formatter.format(value)}`,
+        });
+        return `Timed out after ${Duration.format(this.within)} waiting for ${this.waitingFor}: ${seen}`;
+    }
+}
+// PostgreSQL announces no change to its catalog views, so this poll is the sanctioned wait for them. It sleeps on live time because a story's test clock cannot move PostgreSQL.
+export const observeUntil = Effect.fn("PostgresTest.observeUntil")(function* (read, settled, waitingFor, options) {
+    const within = Duration.fromInputUnsafe(options?.within ?? "5 seconds");
+    const stableReads = options?.stableReads ?? 2;
+    const live = Clock.Clock.defaultValue();
+    const pause = Effect.sleep(options?.every ?? "25 millis").pipe(Effect.provideService(Clock.Clock, live));
+    let last = Option.none();
+    let reads = 0;
+    function observe(streak) {
+        return Effect.flatMap(read, (value) => {
+            last = Option.some(value);
+            reads += 1;
+            const agreeing = settled(value) ? streak + 1 : 0;
+            return agreeing >= stableReads ? Effect.succeed(value) : Effect.andThen(pause, observe(agreeing));
+        });
+    }
+    const deadline = Effect.sleep(within).pipe(Effect.provideService(Clock.Clock, live), Effect.andThen(Effect.suspend(() => Effect.fail(new NeverSettled({ last, reads, waitingFor, within })))));
+    return yield* Effect.raceFirst(observe(0), deadline);
+});
+//# sourceMappingURL=observeUntil.js.map

package/dist/server/observeUntil.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeUntil.js","sourceRoot":"","sources":["../../src/server/observeUntil.ts"],"names":[],"mappings":"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"}

package/dist/server/raceWithLock.d.ts

@@ -6,5 +6,5 @@ export declare function raceWithLock<A, E, R, TLockError, TLockServices>(options
     readonly timeout?: Duration.Input;
     readonly release?: "commit" | "rollback";
     readonly count?: "contenders" | "every blocked session";
-}): Effect.Effect<import("effect/Result").Result<A, E>[], TLockError | import("effect/sql/SqlError").SqlError | import("effect/Cause").TimeoutError, import("effect/reactivity/Reactivity").Reactivity | SqlClient.SqlClient | Exclude<R, import("effect/Scope").Scope> | Exclude<Exclude<TLockServices, import("effect/Scope").Scope>, import("effect/Scope").Scope>>;
+}): Effect.Effect<import("effect/Result").Result<A, E>[], TLockError | import("#observeUntil.ts").NeverSettled<number> | import("effect/sql/SqlError").SqlError | import("effect/Cause").TimeoutError, import("effect/reactivity/Reactivity").Reactivity | SqlClient.SqlClient | Exclude<R, import("effect/Scope").Scope> | Exclude<Exclude<TLockServices, import("effect/Scope").Scope>, import("effect/Scope").Scope>>;
 //# sourceMappingURL=raceWithLock.d.ts.map

package/dist/server/raceWithLock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raceWithLock.d.ts","sourceRoot":"","sources":["../../src/server/raceWithLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,EAAmB,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAUlD,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,uBAAuB,CAAC;CACxD,sWAyCA"}
+{"version":3,"file":"raceWithLock.d.ts","sourceRoot":"","sources":["../../src/server/raceWithLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,EAAS,MAAM,QAAQ,CAAC;AAChE,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAWlD,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,uBAAuB,CAAC;CACxD,wZAyCA"}

package/dist/server/raceWithLock.js

@@ -1,39 +1,40 @@
-import { Deferred, Effect, Fiber, Schedule } from "effect";
+import { Deferred, Effect, Fiber } from "effect";
 import { SqlClient, Statement } from "effect/sql";
 import { transact } from "@shivaedev/sql/transact.ts";
+import { observeUntil } from "#observeUntil.ts";
 import { withTestTransaction } from "#withTestTransaction.ts";
 function tagged(effect, tag) {
     return Effect.provideService(effect, Statement.CurrentTransformer, (statement, sql) => Effect.succeed(sql `${sql.literal(`/* ${tag} */`)} ${statement}`));
 }
 export function raceWithLock(options) {
     const everyBlockedSession = options.count === "every blocked session";
+    const timeout = options.timeout ?? "5 seconds";
+    const contenders = `${options.effects.length} ${everyBlockedSession ? "sessions" : "contenders"} to block on the lock`;
     return Effect.scoped(Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const ready = yield* Deferred.make();
         const started = yield* Deferred.make();
         const hold = Effect.gen(function* () {
-            yield* options.lock;
+            yield* Effect.timeout(options.lock, timeout);
             const [holder] = yield* sql `select pg_backend_pid() as pid`;
             const race = `raceWithLock ${holder?.pid}.`;
             yield* Deferred.succeed(ready, race);
             yield* Deferred.await(started);
-            // PostgreSQL signals nothing when a session starts waiting on a lock, so the holder polls its blocker graph.
-            yield* sql `select pg_stat_clear_snapshot()`.pipe(Effect.andThen(sql `with recursive blocked(pid) as (
+            const waiting = sql `select pg_stat_clear_snapshot()`.pipe(Effect.andThen(sql `with recursive blocked(pid) as (
 						select pid from pg_stat_activity where pg_backend_pid() = any(pg_blocking_pids(pid))
 						union
 						select activity.pid from pg_stat_activity activity join blocked on blocked.pid = any(pg_blocking_pids(activity.pid))
 					) select ${everyBlockedSession ? sql `count(*)` : sql `count(distinct split_part(activity.query, ' */', 1))`}::integer as waiting
 					from pg_stat_activity activity join blocked using (pid)
-					where ${everyBlockedSession ? sql `true` : sql `starts_with(activity.query, ${`/* ${race}`})`}`), Effect.repeat({ schedule: Schedule.spaced("10 millis"), while: ([row]) => (row?.waiting ?? 0) < options.effects.length }));
+					where ${everyBlockedSession ? sql `true` : sql `starts_with(activity.query, ${`/* ${race}`})`}`), Effect.map(([row]) => row?.waiting ?? 0));
+            yield* observeUntil(waiting, (count) => count >= options.effects.length, contenders, { within: timeout });
         });
         const holder = yield* (options.release === "commit" ? transact(Effect.scoped(hold), { onSqlError: (error) => error }) : withTestTransaction(hold)).pipe(Effect.forkScoped);
         const race = yield* Effect.raceFirst(Deferred.await(ready), Fiber.join(holder).pipe(Effect.andThen(Effect.never)));
-        const contenders = yield* Effect.forEach(options.effects, (effect, index) => Effect.result(everyBlockedSession ? effect : tagged(effect, `${race}${index}`)), {
-            concurrency: "unbounded",
-        }).pipe(Effect.forkScoped);
+        const racing = yield* Effect.forEach(options.effects, (effect, index) => Effect.result(everyBlockedSession ? effect : tagged(effect, `${race}${index}`)), { concurrency: "unbounded" }).pipe(Effect.forkScoped);
         yield* Deferred.succeed(started, undefined);
-        yield* Effect.raceFirst(Fiber.join(holder), Fiber.join(contenders).pipe(Effect.andThen(Effect.never)));
-        return yield* Fiber.join(contenders);
-    })).pipe(Effect.timeout(options.timeout ?? "5 seconds"));
+        yield* Effect.raceFirst(Fiber.join(holder), Fiber.join(racing).pipe(Effect.andThen(Effect.never)));
+        return yield* Effect.timeout(Fiber.join(racing), timeout);
+    }));
 }
 //# sourceMappingURL=raceWithLock.js.map

package/dist/server/raceWithLock.js.map

@@ -1 +1 @@
-{"version":3,"file":"raceWithLock.js","sourceRoot":"","sources":["../../src/server/raceWithLock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"raceWithLock.js","sourceRoot":"","sources":["../../src/server/raceWithLock.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-sql",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "PostgreSQL rollback and real-commit test isolation for Effect",
   "keywords": [
     "effect"
@@ -43,16 +43,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/sql": "0.26.1"
+    "@shivaedev/sql": "0.27.0"
   },
   "devDependencies": {
     "@effect/sql-pg": "4.0.6",
     "@effect/vitest": "4.0.6",
-    "@shivaedev/jobs": "0.23.1",
-    "@shivaedev/quality": "0.47.0",
+    "@shivaedev/jobs": "0.23.2",
+    "@shivaedev/quality": "0.48.0",
     "@shivaedev/service": "0.6.0",
     "@shivaedev/test": "0.12.0",
-    "@shivaedev/test-story": "0.26.0",
+    "@shivaedev/test-story": "0.26.2",
     "@types/node": "24.19.2",
     "effect": "4.0.6",
     "pg-boss": "12.38.0",

package/src/server/observeUntil.ts

@@ -0,0 +1,59 @@
+import { Clock, Data, Duration, Effect, Formatter, Option } from "effect";
+
+export interface ObserveOptions {
+	readonly every?: Duration.Input;
+	readonly stableReads?: number;
+	readonly within?: Duration.Input;
+}
+
+export class NeverSettled<A> extends Data.TaggedError("NeverSettled")<{
+	readonly reads: number;
+	readonly waitingFor: string;
+	readonly within: Duration.Duration;
+}> {
+	readonly last: Option.Option<A>;
+
+	constructor({
+		last,
+		...fields
+	}: { readonly last: Option.Option<A>; readonly reads: number; readonly waitingFor: string; readonly within: Duration.Duration }) {
+		super(fields);
+		this.last = last;
+	}
+
+	override get message() {
+		const seen = Option.match(this.last, {
+			onNone: () => "no read finished",
+			onSome: (value) => `${this.reads} ${this.reads === 1 ? "read" : "reads"}, last value ${Formatter.format(value)}`,
+		});
+		return `Timed out after ${Duration.format(this.within)} waiting for ${this.waitingFor}: ${seen}`;
+	}
+}
+
+// PostgreSQL announces no change to its catalog views, so this poll is the sanctioned wait for them. It sleeps on live time because a story's test clock cannot move PostgreSQL.
+export const observeUntil = Effect.fn("PostgresTest.observeUntil")(function* <A, E, R>(
+	read: Effect.Effect<A, E, R>,
+	settled: (value: A) => boolean,
+	waitingFor: string,
+	options?: ObserveOptions,
+) {
+	const within = Duration.fromInputUnsafe(options?.within ?? "5 seconds");
+	const stableReads = options?.stableReads ?? 2;
+	const live = Clock.Clock.defaultValue();
+	const pause = Effect.sleep(options?.every ?? "25 millis").pipe(Effect.provideService(Clock.Clock, live));
+	let last = Option.none<A>();
+	let reads = 0;
+	function observe(streak: number): Effect.Effect<A, E, R> {
+		return Effect.flatMap(read, (value) => {
+			last = Option.some(value);
+			reads += 1;
+			const agreeing = settled(value) ? streak + 1 : 0;
+			return agreeing >= stableReads ? Effect.succeed(value) : Effect.andThen(pause, observe(agreeing));
+		});
+	}
+	const deadline = Effect.sleep(within).pipe(
+		Effect.provideService(Clock.Clock, live),
+		Effect.andThen(Effect.suspend(() => Effect.fail(new NeverSettled({ last, reads, waitingFor, within })))),
+	);
+	return yield* Effect.raceFirst(observe(0), deadline);
+});

package/src/server/raceWithLock.ts

@@ -1,6 +1,7 @@
-import { Deferred, type Duration, Effect, Fiber, Schedule } from "effect";
+import { Deferred, type Duration, Effect, Fiber } from "effect";
 import { SqlClient, Statement } from "effect/sql";
 import { transact } from "@shivaedev/sql/transact.ts";
+import { observeUntil } from "#observeUntil.ts";
 import { withTestTransaction } from "#withTestTransaction.ts";
 
 function tagged<A, E, R>(effect: Effect.Effect<A, E, R>, tag: string) {
@@ -17,19 +18,20 @@ export function raceWithLock<A, E, R, TLockError, TLockServices>(options: {
 	readonly count?: "contenders" | "every blocked session";
 }) {
 	const everyBlockedSession = options.count === "every blocked session";
+	const timeout = options.timeout ?? "5 seconds";
+	const contenders = `${options.effects.length} ${everyBlockedSession ? "sessions" : "contenders"} to block on the lock`;
 	return Effect.scoped(
 		Effect.gen(function* () {
 			const sql = yield* SqlClient.SqlClient;
 			const ready = yield* Deferred.make<string>();
 			const started = yield* Deferred.make<void>();
 			const hold = Effect.gen(function* () {
-				yield* options.lock;
+				yield* Effect.timeout(options.lock, timeout);
 				const [holder] = yield* sql<{ pid: number }>`select pg_backend_pid() as pid`;
 				const race = `raceWithLock ${holder?.pid}.`;
 				yield* Deferred.succeed(ready, race);
 				yield* Deferred.await(started);
-				// PostgreSQL signals nothing when a session starts waiting on a lock, so the holder polls its blocker graph.
-				yield* sql`select pg_stat_clear_snapshot()`.pipe(
+				const waiting = sql`select pg_stat_clear_snapshot()`.pipe(
 					Effect.andThen(sql<{ waiting: number }>`with recursive blocked(pid) as (
 						select pid from pg_stat_activity where pg_backend_pid() = any(pg_blocking_pids(pid))
 						union
@@ -37,23 +39,22 @@ export function raceWithLock<A, E, R, TLockError, TLockServices>(options: {
 					) select ${everyBlockedSession ? sql`count(*)` : sql`count(distinct split_part(activity.query, ' */', 1))`}::integer as waiting
 					from pg_stat_activity activity join blocked using (pid)
 					where ${everyBlockedSession ? sql`true` : sql`starts_with(activity.query, ${`/* ${race}`})`}`),
-					Effect.repeat({ schedule: Schedule.spaced("10 millis"), while: ([row]) => (row?.waiting ?? 0) < options.effects.length }),
+					Effect.map(([row]) => row?.waiting ?? 0),
 				);
+				yield* observeUntil(waiting, (count) => count >= options.effects.length, contenders, { within: timeout });
 			});
 			const holder = yield* (
 				options.release === "commit" ? transact(Effect.scoped(hold), { onSqlError: (error) => error }) : withTestTransaction(hold)
 			).pipe(Effect.forkScoped);
 			const race = yield* Effect.raceFirst(Deferred.await(ready), Fiber.join(holder).pipe(Effect.andThen(Effect.never)));
-			const contenders = yield* Effect.forEach(
+			const racing = yield* Effect.forEach(
 				options.effects,
 				(effect, index) => Effect.result(everyBlockedSession ? effect : tagged(effect, `${race}${index}`)),
-				{
-					concurrency: "unbounded",
-				},
+				{ concurrency: "unbounded" },
 			).pipe(Effect.forkScoped);
 			yield* Deferred.succeed(started, undefined);
-			yield* Effect.raceFirst(Fiber.join(holder), Fiber.join(contenders).pipe(Effect.andThen(Effect.never)));
-			return yield* Fiber.join(contenders);
+			yield* Effect.raceFirst(Fiber.join(holder), Fiber.join(racing).pipe(Effect.andThen(Effect.never)));
+			return yield* Effect.timeout(Fiber.join(racing), timeout);
 		}),
-	).pipe(Effect.timeout(options.timeout ?? "5 seconds"));
+	);
 }