@evolu/common 8.6.2 → 8.8.0

package/src/Resource.test.ts

@@ -0,0 +1,4623 @@
+import { describe, it } from "node:test";
+import {
+  assertConditionAfterMicrotasks,
+  assertEqual,
+  assertErr,
+  assertFalse,
+  assertInstanceOf,
+  assertLength,
+  assertNotUndefined,
+  assertOk,
+  assertRejects,
+  assertSame,
+  assertTrue,
+} from "./Assert.ts";
+
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.ts";
+import { constVoid } from "./Function.ts";
+import { installPolyfills } from "./Polyfills.ts";
+import {
+  createSharedResourceByKeyWithClaims,
+  createSharedResource,
+  createSharedResourceByKey,
+  type BorrowedResource,
+  type ClaimLease,
+  type Lease,
+  type SharedResource,
+  type SharedResourceByKey,
+  type SharedResourceByKeyWithClaims,
+} from "./Resource.ts";
+import { err, ok } from "./Result.ts";
+import {
+  AbortError,
+  createGate,
+  runDisposedAbortReason,
+  testAbortReason,
+  testCreateRun,
+  type Task,
+} from "./Task.ts";
+import { assertType } from "./Type.ts";
+
+installPolyfills();
+
+/** Creates a fresh Disposable per create call and records lifecycle counts. */
+const createTestResources = () => {
+  let createCount = 0;
+  let disposeCount = 0;
+  const disposedWaiters: Array<() => void> = [];
+
+  const create: Task<Disposable> = () => {
+    createCount++;
+    return ok({
+      [Symbol.dispose]: () => {
+        disposeCount++;
+        for (const resolve of disposedWaiters.splice(0)) resolve();
+      },
+    });
+  };
+
+  return {
+    create,
+    getCreateCount: () => createCount,
+    getDisposeCount: () => disposeCount,
+    nextDisposed: () =>
+      new Promise<void>((resolve) => {
+        disposedWaiters.push(resolve);
+      }),
+  };
+};
+
+const idleMutexSnapshot = {
+  policy: "fifo",
+  permits: 1,
+  taken: 0,
+  waiters: [],
+  available: 1,
+  isIdle: true,
+};
+
+describe("BorrowedResource", () => {
+  it("preserves resource unions", () => {
+    interface SyncResource extends Disposable {
+      readonly type: "sync";
+      readonly sync: () => void;
+    }
+    interface AsyncResource extends AsyncDisposable {
+      readonly type: "async";
+      readonly async: () => void;
+    }
+
+    assertType<
+      BorrowedResource<SyncResource | AsyncResource>,
+      | { readonly type: "sync"; readonly sync: () => void }
+      | { readonly type: "async"; readonly async: () => void }
+    >();
+  });
+});
+
+describe("SharedResource", () => {
+  describe("acquire", () => {
+    it("lazily creates the resource", async () => {
+      await using run = testCreateRun();
+
+      let createCount = 0;
+      const resource: Disposable = { [Symbol.dispose]: constVoid };
+
+      await using sharedResource = await run.ok(
+        createSharedResource(() => {
+          createCount++;
+          return ok(resource);
+        }),
+      );
+
+      assertEqual(createCount, 0);
+
+      const lease = await run.ok(sharedResource.acquire);
+
+      assertEqual(createCount, 1);
+      assertSame(lease.resource, resource);
+    });
+
+    it("reuses the current resource while a lease is held", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      const second = await run.ok(sharedResource.acquire);
+
+      assertEqual(resources.getCreateCount(), 1);
+      assertSame(second.resource, first.resource);
+    });
+
+    it("reports whether acquire created the resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      const second = await run.ok(sharedResource.acquire);
+
+      assertTrue(first.created);
+      assertFalse(second.created);
+    });
+
+    it("creates a fresh resource after disposal", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      const firstResource = first.resource;
+      const disposed = resources.nextDisposed();
+      first.release();
+      await disposed;
+
+      const second = await run.ok(sharedResource.acquire);
+
+      assertEqual(resources.getCreateCount(), 2);
+      assertFalse(Object.is(second.resource, firstResource));
+    });
+
+    it("waits for async resource disposal", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      let createCount = 0;
+      const create: Task<AsyncDisposable> = () => {
+        createCount++;
+        return ok({
+          [Symbol.asyncDispose]: async () => {
+            disposalStarted.resolve();
+            await continueDisposal.promise;
+          },
+        });
+      };
+
+      await using sharedResource = await run.ok(createSharedResource(create));
+
+      const first = await run.ok(sharedResource.acquire);
+      first.release();
+      await disposalStarted.promise;
+
+      const second = run.ok(sharedResource.acquire);
+
+      assertEqual(createCount, 1);
+
+      continueDisposal.resolve();
+      await second;
+
+      assertEqual(createCount, 2);
+    });
+
+    it("serializes concurrent first calls so create runs once", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+
+      let createCount = 0;
+      const resource: Disposable = { [Symbol.dispose]: constVoid };
+      const create: Task<Disposable> = async (run) => {
+        createCount++;
+        await run.ok(gate.wait);
+        return ok(resource);
+      };
+
+      await using sharedResource = await run.ok(createSharedResource(create));
+
+      const first = run.ok(sharedResource.acquire);
+      const second = run.ok(sharedResource.acquire);
+      gate.open();
+      const [firstLease, secondLease] = await Promise.all([first, second]);
+
+      assertEqual(createCount, 1);
+      assertSame(firstLease.resource, resource);
+      assertSame(secondLease.resource, resource);
+    });
+
+    it("runs to completion when the caller aborts its Fiber", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+
+      const resource: Disposable = { [Symbol.dispose]: constVoid };
+      const create: Task<Disposable> = async (run) => {
+        await run.ok(gate.wait);
+        return ok(resource);
+      };
+
+      await using sharedResource = await run.ok(createSharedResource(create));
+
+      const fiber = run.abortable(sharedResource.acquire);
+      fiber.abort(testAbortReason);
+      gate.open();
+
+      const result = await fiber;
+
+      assertOk(result);
+      assertSame(result.value.resource, resource);
+      assertEqual(sharedResource.snapshot().leaseCount, 1);
+    });
+
+    it("overprovided acquire deps do not replace deps captured for create", async () => {
+      await using run = testCreateRun();
+
+      interface TestResource extends Disposable {
+        readonly value: string;
+      }
+      interface TestDep {
+        readonly value: string;
+      }
+
+      await using sharedResource = await run.ok(
+        createSharedResource<TestResource, TestDep>(({ deps }) =>
+          ok({ value: deps.value, [Symbol.dispose]: constVoid }),
+        ),
+        { value: "captured" },
+      );
+
+      const lease = await run.ok(sharedResource.acquire, {
+        value: "replacement",
+      });
+
+      assertEqual(lease.resource.value, "captured");
+    });
+  });
+
+  describe("acquireCurrent", () => {
+    it("returns undefined without creating a resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const lease = await run.ok(sharedResource.acquireCurrent);
+
+      assertSame(lease, undefined);
+      assertEqual(resources.getCreateCount(), 0);
+    });
+
+    it("waits for in-flight creation and acquires the new resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const gate = createGate();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(async (run) => {
+          await run.ok(gate.wait);
+          return run(resources.create);
+        }),
+      );
+
+      const first = run.ok(sharedResource.acquire);
+      const current = run.ok(sharedResource.acquireCurrent);
+      gate.open();
+
+      const firstLease = await first;
+      const currentLease = await current;
+
+      assertSame(currentLease?.resource, firstLease.resource);
+      assertFalse(currentLease?.created);
+      assertEqual(resources.getCreateCount(), 1);
+    });
+
+    it("waits for in-flight disposal and returns undefined", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(() =>
+          ok({
+            [Symbol.asyncDispose]: async () => {
+              disposalStarted.resolve();
+              await continueDisposal.promise;
+            },
+          }),
+        ),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      lease.release();
+      await disposalStarted.promise;
+
+      const current = run.ok(sharedResource.acquireCurrent);
+      assertEqual(sharedResource.snapshot().mutex.waiters, [{ permits: 1 }]);
+      continueDisposal.resolve();
+
+      assertSame(await current, undefined);
+    });
+
+    it("acquires the current resource without creating another", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      const current = await run.ok(sharedResource.acquireCurrent);
+
+      assertSame(current?.resource, first.resource);
+      assertFalse(current?.created);
+      assertEqual(resources.getCreateCount(), 1);
+    });
+
+    it("cancels pending idle disposal and acquires the current resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, { idleDisposeAfter: "3s" }),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      first.release();
+
+      const current = await run.ok(sharedResource.acquireCurrent);
+
+      assertSame(current?.resource, first.resource);
+      assertFalse(sharedResource.snapshot().idleDisposePending);
+
+      run.deps.time.advance("3s");
+      assertEqual(resources.getDisposeCount(), 0);
+    });
+  });
+
+  describe("use", () => {
+    it("creates the resource and releases its lease after the Task settles", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      let leaseCountDuringUse: number | undefined;
+      let createdDuringUse: boolean | undefined;
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const value = await run.ok(
+        sharedResource.use((_resource, created) => () => {
+          leaseCountDuringUse = sharedResource.snapshot().leaseCount;
+          createdDuringUse = created;
+          return ok("used" as const);
+        }),
+      );
+
+      assertEqual(value, "used");
+      assertTrue(createdDuringUse);
+      assertEqual(leaseCountDuringUse, 1);
+      assertEqual(sharedResource.snapshot().leaseCount, 0);
+    });
+
+    it("reports created false while reusing a held resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      let createdDuringUse: boolean | undefined;
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      using _lease = await run.ok(sharedResource.acquire);
+
+      await run.ok(
+        sharedResource.use((_resource, created) => () => {
+          createdDuringUse = created;
+          return ok();
+        }),
+      );
+
+      assertFalse(createdDuringUse);
+      assertEqual(resources.getCreateCount(), 1);
+      assertEqual(sharedResource.snapshot().leaseCount, 1);
+    });
+
+    it("releases its lease when the callback Task aborts", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const callbackStarted = Promise.withResolvers<void>();
+      const gate = createGate();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      const disposed = resources.nextDisposed();
+
+      const fiber = run.abortable(
+        sharedResource.use(() => async (run) => {
+          callbackStarted.resolve();
+          await run.ok(gate.wait);
+          return ok();
+        }),
+      );
+      await callbackStarted.promise;
+
+      assertEqual(sharedResource.snapshot().leaseCount, 1);
+
+      fiber.abort(testAbortReason);
+      const result = await fiber;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, testAbortReason);
+
+      await disposed;
+      assertEqual(sharedResource.snapshot().leaseCount, 0);
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+  });
+
+  describe("Lease", () => {
+    it("release disposes the resource after the last lease", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      const disposed = resources.nextDisposed();
+
+      assertTrue(lease.release());
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(sharedResource.snapshot().hasResource);
+      assertFalse(sharedResource.snapshot().idleDisposePending);
+    });
+
+    it("release keeps the resource while other leases remain", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      await run.ok(sharedResource.acquire);
+
+      assertTrue(first.release());
+
+      assertEqual(resources.getDisposeCount(), 0);
+      assertTrue(sharedResource.snapshot().hasResource);
+      assertEqual(sharedResource.snapshot().leaseCount, 1);
+    });
+
+    it("release is idempotent and returns false after the first call", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      await run.ok(sharedResource.acquire);
+
+      assertTrue(first.release());
+      assertFalse(first.release());
+
+      // Double release must not release the remaining lease's hold.
+      assertEqual(sharedResource.snapshot().leaseCount, 1);
+      assertEqual(resources.getDisposeCount(), 0);
+    });
+
+    it("release remains safe after root Run disposal", async () => {
+      const run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      const lease = await run.ok(sharedResource.acquire);
+
+      await run[Symbol.asyncDispose]();
+
+      assertFalse(lease.release());
+      assertFalse(lease.release());
+    });
+
+    it("Symbol.dispose releases it", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const disposed = resources.nextDisposed();
+
+      {
+        using _ = await run.ok(sharedResource.acquire);
+        assertEqual(sharedResource.snapshot().leaseCount, 1);
+      }
+
+      await disposed;
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+  });
+
+  describe("idleDisposeAfter", () => {
+    it("delays disposal after the last release", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, { idleDisposeAfter: "3s" }),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+
+      assertTrue(lease.release());
+      assertEqual(resources.getDisposeCount(), 0);
+      assertTrue(sharedResource.snapshot().idleDisposePending);
+
+      const disposed = resources.nextDisposed();
+      run.deps.time.advance("3s");
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(sharedResource.snapshot().hasResource);
+    });
+
+    it("reuses the current resource when acquired before disposal", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, { idleDisposeAfter: "3s" }),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      first.release();
+      assertTrue(sharedResource.snapshot().idleDisposePending);
+
+      const second = await run.ok(sharedResource.acquire);
+
+      assertFalse(sharedResource.snapshot().idleDisposePending);
+      assertEqual(resources.getCreateCount(), 1);
+      assertSame(second.resource, first.resource);
+
+      run.deps.time.advance("3s");
+      assertEqual(resources.getDisposeCount(), 0);
+    });
+
+    it("restarts the idle delay after reacquisition and release", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, { idleDisposeAfter: "3s" }),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      first.release();
+      run.deps.time.advance("2s");
+
+      const second = await run.ok(sharedResource.acquire);
+      second.release();
+      run.deps.time.advance("1s");
+
+      assertEqual(resources.getDisposeCount(), 0);
+      assertTrue(sharedResource.snapshot().idleDisposePending);
+
+      const disposed = resources.nextDisposed();
+      run.deps.time.advance("2s");
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("creates a fresh resource when acquired after the timer elapses", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      let createCount = 0;
+      const create: Task<AsyncDisposable & { readonly id: number }> = () => {
+        const id = ++createCount;
+        return ok({
+          id,
+          [Symbol.asyncDispose]: async () => {
+            if (id !== 1) return;
+            disposalStarted.resolve();
+            await continueDisposal.promise;
+          },
+        });
+      };
+
+      await using sharedResource = await run.ok(
+        createSharedResource(create, { idleDisposeAfter: "3s" }),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+      first.release();
+      run.deps.time.advance("3s");
+      await disposalStarted.promise;
+
+      const second = run.ok(sharedResource.acquire);
+      assertEqual(createCount, 1);
+
+      continueDisposal.resolve();
+      const secondLease = await second;
+
+      assertEqual(createCount, 2);
+      assertFalse(Object.is(secondLease.resource, first.resource));
+    });
+  });
+
+  describe("snapshot", () => {
+    it("reports shared resource state", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, { idleDisposeAfter: "3s" }),
+      );
+
+      assertEqual(sharedResource.snapshot(), {
+        isIdle: true,
+        leaseCount: 0,
+        hasResource: false,
+        idleDisposePending: false,
+        mutex: idleMutexSnapshot,
+      });
+
+      const lease = await run.ok(sharedResource.acquire);
+
+      assertEqual(sharedResource.snapshot(), {
+        isIdle: false,
+        leaseCount: 1,
+        hasResource: true,
+        idleDisposePending: false,
+        mutex: idleMutexSnapshot,
+      });
+
+      lease.release();
+
+      assertEqual(sharedResource.snapshot(), {
+        isIdle: false,
+        leaseCount: 0,
+        hasResource: true,
+        idleDisposePending: true,
+        mutex: idleMutexSnapshot,
+      });
+    });
+
+    it("reports immediate disposal in progress", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      const disposed = resources.nextDisposed();
+      lease.release();
+
+      assertEqual(sharedResource.snapshot(), {
+        isIdle: false,
+        leaseCount: 0,
+        hasResource: true,
+        idleDisposePending: false,
+        mutex: {
+          policy: "fifo",
+          permits: 1,
+          taken: 1,
+          waiters: [],
+          available: 0,
+          isIdle: false,
+        },
+      });
+
+      await disposed;
+    });
+
+    it("reports not idle while creating the first resource", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(async (run) => {
+          await run.ok(gate.wait);
+          return ok({ [Symbol.dispose]: constVoid });
+        }),
+      );
+
+      const acquire = run.ok(sharedResource.acquire);
+      const isIdleWhileCreating = sharedResource.snapshot().isIdle;
+      gate.open();
+      await acquire;
+
+      assertFalse(isIdleWhileCreating);
+    });
+
+    it("reports mutex waiters during a contended acquire", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(async (run) => {
+          await run.ok(gate.wait);
+          return ok({ [Symbol.dispose]: constVoid });
+        }),
+      );
+
+      const first = run.ok(sharedResource.acquire);
+      const second = run.ok(sharedResource.acquire);
+      const mutexWhileContended = sharedResource.snapshot().mutex;
+      gate.open();
+      await Promise.all([first, second]);
+
+      assertEqual(mutexWhileContended.waiters, [{ permits: 1 }]);
+    });
+  });
+
+  describe("onDisposed", () => {
+    it("does not call onDisposed when disposed before resource creation", async () => {
+      await using run = testCreateRun();
+      let onDisposedCallCount = 0;
+
+      const sharedResource = await run.ok(
+        createSharedResource(createTestResources().create, {
+          onDisposed: () => {
+            onDisposedCallCount++;
+          },
+        }),
+      );
+
+      await sharedResource[Symbol.asyncDispose]();
+
+      assertEqual(onDisposedCallCount, 0);
+    });
+
+    it("calls onDisposed during owner disposal", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      let disposeCountAtCallback: number | undefined;
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create, {
+          onDisposed: () => {
+            disposeCountAtCallback = resources.getDisposeCount();
+          },
+        }),
+      );
+      await run.ok(sharedResource.acquire);
+
+      await sharedResource[Symbol.asyncDispose]();
+
+      assertEqual(disposeCountAtCallback, 1);
+    });
+
+    it("runs after the resource is disposed and cleared", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const onDisposedCalled = Promise.withResolvers<void>();
+
+      let stateAtCallback:
+        { disposeCount: number; hasResource: boolean } | undefined;
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, {
+          onDisposed: () => {
+            stateAtCallback = {
+              disposeCount: resources.getDisposeCount(),
+              hasResource: sharedResource.snapshot().hasResource,
+            };
+            onDisposedCalled.resolve();
+          },
+        }),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      lease.release();
+      await onDisposedCalled.promise;
+
+      assertEqual(stateAtCallback, { disposeCount: 1, hasResource: false });
+    });
+
+    it("runs after delayed idle disposal", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const onDisposedCalled = Promise.withResolvers<void>();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, {
+          idleDisposeAfter: "3s",
+          onDisposed: onDisposedCalled.resolve,
+        }),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      lease.release();
+
+      assertEqual(resources.getDisposeCount(), 0);
+
+      run.deps.time.advance("3s");
+      await onDisposedCalled.promise;
+
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(sharedResource.snapshot().hasResource);
+    });
+  });
+
+  describe("disposal", () => {
+    it("aborts acquire queued on the mutex when the owner is disposed", async () => {
+      await using run = testCreateRun();
+      const createStarted = Promise.withResolvers<void>();
+      const gate = createGate();
+
+      const sharedResource = await run.ok(
+        createSharedResource(async (run) => {
+          createStarted.resolve();
+          await run.ok(gate.wait);
+          return ok({ [Symbol.dispose]: constVoid });
+        }),
+      );
+
+      const first = run.abortable(sharedResource.acquire);
+      await createStarted.promise;
+
+      const queued = run.abortable(sharedResource.acquire);
+      assertEqual(sharedResource.snapshot().mutex.waiters, [{ permits: 1 }]);
+
+      const disposal = sharedResource[Symbol.asyncDispose]();
+      const result = await queued;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, runDisposedAbortReason);
+
+      gate.open();
+      await first;
+      await disposal;
+    });
+
+    it("aborts acquire when the owner is disposed during creation", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const createStarted = Promise.withResolvers<void>();
+      const continueCreate = Promise.withResolvers<void>();
+
+      const sharedResource = await run.ok(
+        createSharedResource(async (run) => {
+          const resource = await run.ok(resources.create);
+          createStarted.resolve();
+          await continueCreate.promise;
+          return ok(resource);
+        }),
+      );
+
+      const acquire = run.abortable(sharedResource.acquire);
+      await createStarted.promise;
+
+      const disposal = sharedResource[Symbol.asyncDispose]();
+      continueCreate.resolve();
+
+      const result = await acquire;
+      await disposal;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, runDisposedAbortReason);
+      assertEqual(resources.getCreateCount(), 1);
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("disposes the current resource and releases held leases", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      const lease = await run.ok(sharedResource.acquire);
+
+      await sharedResource[Symbol.asyncDispose]();
+
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(lease.release());
+      assertFalse(sharedResource.snapshot().hasResource);
+    });
+
+    it("clears pending idle disposal state", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create, { idleDisposeAfter: "3s" }),
+      );
+      const lease = await run.ok(sharedResource.acquire);
+      lease.release();
+
+      assertTrue(sharedResource.snapshot().idleDisposePending);
+
+      await sharedResource[Symbol.asyncDispose]();
+
+      assertEqual(resources.getDisposeCount(), 1);
+      const snapshot = sharedResource.snapshot();
+      assertTrue(snapshot.isIdle);
+      assertFalse(snapshot.idleDisposePending);
+    });
+
+    it("awaits async resource disposal", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      const sharedResource = await run.ok(
+        createSharedResource(() =>
+          ok({
+            [Symbol.asyncDispose]: async () => {
+              disposalStarted.resolve();
+              await continueDisposal.promise;
+            },
+          }),
+        ),
+      );
+      await run.ok(sharedResource.acquire);
+
+      let disposalSettled = false;
+      const disposal = sharedResource[Symbol.asyncDispose]().then(() => {
+        disposalSettled = true;
+      });
+      await disposalStarted.promise;
+
+      assertFalse(disposalSettled);
+
+      continueDisposal.resolve();
+      await disposal;
+
+      assertTrue(disposalSettled);
+    });
+
+    it("root Run disposal awaits current resource disposal", async () => {
+      const run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      const sharedResource = await run.ok(
+        createSharedResource(() =>
+          ok({
+            [Symbol.asyncDispose]: async () => {
+              disposalStarted.resolve();
+              await continueDisposal.promise;
+            },
+          }),
+        ),
+      );
+      await run.ok(sharedResource.acquire);
+
+      let rootDisposalSettled = false;
+      const rootDisposal = run[Symbol.asyncDispose]().then(() => {
+        rootDisposalSettled = true;
+      });
+
+      try {
+        const firstSettled = await Promise.race([
+          disposalStarted.promise.then(() => "resourceDisposalStarted"),
+          rootDisposal.then(() => "rootDisposalSettled"),
+        ]);
+
+        assertEqual(firstSettled, "resourceDisposalStarted");
+        assertFalse(rootDisposalSettled);
+
+        continueDisposal.resolve();
+        await rootDisposal;
+
+        assertFalse(sharedResource.snapshot().hasResource);
+        assertEqual(run.deps.reportDefect.getDefectsSnapshot(), []);
+      } finally {
+        continueDisposal.resolve();
+        await sharedResource[Symbol.asyncDispose]();
+        await rootDisposal;
+      }
+    });
+
+    it("allows late lease release as a safe no-op", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      const lease = await run.ok(sharedResource.acquire);
+
+      const disposal = sharedResource[Symbol.asyncDispose]();
+      assertTrue(lease.release());
+      await disposal;
+
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(lease.release());
+    });
+
+    it("owner disposal can drain a transferred lease before the caller awaits it", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      const acquire = run.ok(sharedResource.acquire);
+
+      await assertConditionAfterMicrotasks(
+        () => sharedResource.snapshot().leaseCount === 1,
+        10,
+      );
+      await sharedResource[Symbol.asyncDispose]();
+
+      const lease = await acquire;
+
+      assertEqual(sharedResource.snapshot().leaseCount, 0);
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(lease.release());
+    });
+
+    it("skips scheduled disposal when a new lease arrives", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const first = await run.ok(sharedResource.acquire);
+
+      // Take the mutex before release so the scheduled disposal queues behind
+      // the second acquire.
+      const second = run.ok(sharedResource.acquire);
+      first.release();
+      const secondLease = await second;
+
+      // The mutex is FIFO, so a third acquire completes only after the queued
+      // disposal task ran.
+      await run.ok(sharedResource.acquire);
+
+      assertEqual(resources.getDisposeCount(), 0);
+      assertSame(secondLease.resource, first.resource);
+    });
+  });
+
+  describe("leak detection", () => {
+    it("warns when an undisposed SharedResource is garbage-collected", async () => {
+      await using run = testCreateRun();
+
+      await run.ok(createSharedResource(createTestResources().create));
+
+      assertEqual(run.deps.leakDetector.collect(), 1);
+
+      const entries = run.deps.console.getEntriesSnapshot();
+      assertLength(entries, 1);
+      assertEqual(entries[0].method, "warn");
+      assertEqual(
+        entries[0].args[0],
+        "SharedResource was garbage-collected without cleanup. Tracked at:",
+      );
+    });
+
+    it("warns when a leaked lease is garbage-collected", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      // Acquired but never released — a leak.
+      await run.ok(sharedResource.acquire);
+
+      assertEqual(run.deps.leakDetector.collect(), 2);
+
+      const entries = run.deps.console.getEntriesSnapshot();
+      assertLength(entries, 2);
+      assertTrue(
+        entries.some(
+          (entry) =>
+            entry.method === "warn" &&
+            entry.args.includes(
+              "Lease was garbage-collected without cleanup. Tracked at:",
+            ),
+        ),
+      );
+    });
+
+    it("release untracks the lease", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+
+      assertEqual(run.deps.leakDetector.getTrackedCount({ name: "Lease" }), 1);
+
+      lease.release();
+
+      assertEqual(run.deps.leakDetector.getTrackedCount({ name: "Lease" }), 0);
+    });
+
+    it("disposal untracks held leases", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+
+      await run.ok(sharedResource.acquire);
+      assertEqual(run.deps.leakDetector.getTrackedCount({ name: "Lease" }), 1);
+
+      await sharedResource[Symbol.asyncDispose]();
+
+      assertEqual(run.deps.leakDetector.getTrackedCount({ name: "Lease" }), 0);
+      assertEqual(run.deps.console.getEntriesSnapshot(), []);
+    });
+  });
+
+  describe("defects", () => {
+    it("acquire after disposal is a programmer error", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create),
+      );
+      await sharedResource[Symbol.asyncDispose]();
+
+      const result = await run.abortable(sharedResource.acquire);
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertInstanceOf(result.error.reason.defect, Error);
+      assertEqual(
+        result.error.reason.defect.message,
+        "Cannot use a disposed object.",
+      );
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing create Task panics the Run tree", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("create failed");
+
+      await using sharedResource = await run.ok(
+        createSharedResource(() => {
+          throw defect;
+        }),
+      );
+
+      const result = await run.abortable(sharedResource.acquire);
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing onDisposed after the last release panics the Run tree", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const defect = new Error("onDisposed failed");
+
+      await using sharedResource = await run.ok(
+        createSharedResource(resources.create, {
+          onDisposed: () => {
+            throw defect;
+          },
+        }),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      lease.release();
+
+      // Disposal runs on a fire-and-forget Fiber, so the defect is observable
+      // only via panic reporting.
+      const abortError = await run.deps.reportDefect.next();
+      assertType(AbortError, abortError);
+      assertSame(abortError.reason.type, "PanicAbortReason");
+      assertSame(abortError.reason.defect, defect);
+    });
+
+    it("throwing onDisposed during disposal reports once and rejects with AbortError", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const defect = new Error("onDisposed failed");
+
+      const sharedResource = await run.ok(
+        createSharedResource(resources.create, {
+          onDisposed: () => {
+            throw defect;
+          },
+        }),
+      );
+
+      await run.ok(sharedResource.acquire);
+
+      await assertRejects(
+        sharedResource[Symbol.asyncDispose](),
+        (disposalError) => {
+          assertType(AbortError, disposalError);
+          assertSame(disposalError.reason.type, "PanicAbortReason");
+          assertSame(disposalError.reason.defect, defect);
+          assertEqual(run.deps.reportDefect.getDefectsSnapshot(), [
+            disposalError,
+          ]);
+        },
+      );
+    });
+
+    it("throwing resource disposer panics the Run tree", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("dispose failed");
+
+      await using sharedResource = await run.ok(
+        createSharedResource(() =>
+          ok({
+            [Symbol.dispose]: () => {
+              throw defect;
+            },
+          }),
+        ),
+      );
+
+      const lease = await run.ok(sharedResource.acquire);
+      lease.release();
+
+      const abortError = await run.deps.reportDefect.next();
+      assertType(AbortError, abortError);
+      assertSame(abortError.reason.type, "PanicAbortReason");
+      assertSame(abortError.reason.defect, defect);
+    });
+  });
+
+  describe("types", () => {
+    it("keyed acquire does not require captured deps", () => {
+      interface TestDb extends Disposable {
+        readonly query: () => string;
+      }
+      interface TestDep {
+        readonly value: string;
+      }
+
+      assertType<SharedResource<TestDb>["acquire"], Task<Lease<TestDb>>>();
+
+      const _sharedResource = createSharedResource((() =>
+        ok({ [Symbol.dispose]: constVoid })) as Task<
+        Disposable,
+        never,
+        TestDep
+      >);
+      assertType<
+        typeof _sharedResource,
+        Task<SharedResource<Disposable>, never, TestDep>
+      >();
+
+      // @ts-expect-error - create Task must not fail.
+      createSharedResource(() => err({ type: "CreateError" }));
+    });
+
+    it("acquireCurrent and use preserve their Task types", async () => {
+      await using run = testCreateRun();
+
+      interface TestDb extends Disposable {
+        readonly query: () => string;
+      }
+      interface TestError {
+        readonly type: "TestError";
+      }
+      interface TestDep {
+        readonly value: string;
+      }
+
+      const create: Task<TestDb> = () =>
+        ok({ query: () => "result", [Symbol.dispose]: constVoid });
+
+      await using sharedResource = await run.ok(createSharedResource(create));
+
+      assertType<
+        typeof sharedResource.acquireCurrent,
+        Task<Lease<TestDb> | undefined>
+      >();
+
+      const use = sharedResource.use(
+        (): Task<"used", TestError, TestDep> => () =>
+          err({ type: "TestError" }),
+      );
+      assertType<typeof use, Task<"used", TestError, TestDep>>();
+    });
+  });
+});
+
+describe("SharedResourceByKey", () => {
+  describe("acquire", () => {
+    it("lazily creates a resource per key", async () => {
+      await using run = testCreateRun();
+
+      const createCountsByKey = new Map<string, number>();
+      const create =
+        (key: string): Task<Disposable> =>
+        () => {
+          createCountsByKey.set(key, (createCountsByKey.get(key) ?? 0) + 1);
+          return ok({ [Symbol.dispose]: constVoid });
+        };
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(create),
+      );
+
+      assertEqual(createCountsByKey.size, 0);
+
+      const first = await run.ok(sharedResourceByKey.acquire("a"));
+      const second = await run.ok(sharedResourceByKey.acquire("a"));
+
+      assertEqual(createCountsByKey.get("a"), 1);
+      assertSame(second.resource, first.resource);
+    });
+
+    it("serializes concurrent first acquires for the same key", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+
+      let createCount = 0;
+      const create = (): Task<Disposable> => async (run) => {
+        createCount++;
+        await run.ok(gate.wait);
+        return ok({ [Symbol.dispose]: constVoid });
+      };
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(create),
+      );
+
+      const first = run.ok(sharedResourceByKey.acquire("a"));
+      const second = run.ok(sharedResourceByKey.acquire("a"));
+      gate.open();
+      const [firstLease, secondLease] = await Promise.all([first, second]);
+
+      assertEqual(createCount, 1);
+      assertSame(secondLease.resource, firstLease.resource);
+    });
+
+    it("creates independent resources for different keys", async () => {
+      await using run = testCreateRun();
+
+      const resourcesByKey = new Map<
+        string,
+        ReturnType<typeof createTestResources>
+      >();
+      const create = (key: string): Task<Disposable> => {
+        const resources = createTestResources();
+        resourcesByKey.set(key, resources);
+        return resources.create;
+      };
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(create),
+      );
+
+      const a = await run.ok(sharedResourceByKey.acquire("a"));
+      const b = await run.ok(sharedResourceByKey.acquire("b"));
+
+      assertFalse(Object.is(b.resource, a.resource));
+
+      // Releasing "a" disposes only "a".
+      const aDisposed = resourcesByKey.get("a")!.nextDisposed();
+      a.release();
+      await aDisposed;
+
+      assertEqual(resourcesByKey.get("a")!.getDisposeCount(), 1);
+      assertEqual(resourcesByKey.get("b")!.getDisposeCount(), 0);
+      assertTrue(
+        sharedResourceByKey.snapshot().resourcesByKey.get("b")?.hasResource,
+      );
+    });
+
+    it("allows different keys to progress concurrently", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+
+      const create =
+        (key: string): Task<Disposable> =>
+        async (run) => {
+          if (key === "a") await run.ok(gate.wait);
+          return ok({ [Symbol.dispose]: constVoid });
+        };
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(create),
+      );
+
+      const a = run.ok(sharedResourceByKey.acquire("a"));
+      await run.ok(sharedResourceByKey.acquire("b"));
+
+      assertTrue(
+        sharedResourceByKey.snapshot().resourcesByKey.get("b")?.hasResource,
+      );
+      assertFalse(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.hasResource,
+      );
+
+      gate.open();
+      await a;
+    });
+
+    it("runs to completion after caller abort while waiting for a key", async () => {
+      await using run = testCreateRun();
+      const gate = createGate();
+      const resources = createTestResources();
+
+      const create: Task<Disposable> = async (run) => {
+        await run.ok(gate.wait);
+        return run(resources.create);
+      };
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => create),
+      );
+
+      const first = run.ok(sharedResourceByKey.acquire("a"));
+      const second = run.abortable(sharedResourceByKey.acquire("a"));
+      second.abort(testAbortReason);
+      gate.open();
+
+      const firstLease = await first;
+      const result = await second;
+
+      assertOk(result);
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount,
+        2,
+      );
+
+      assertTrue(firstLease.release());
+      assertEqual(resources.getDisposeCount(), 0);
+
+      const disposed = resources.nextDisposed();
+      assertTrue(result.value.release());
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+  });
+
+  describe("key removal", () => {
+    it("disposes the resource and removes the key after the last lease", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const onDisposedCalled = Promise.withResolvers<void>();
+      let hasKeyWhenDisposed: boolean | undefined;
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create, {
+          onDisposed: () => {
+            hasKeyWhenDisposed = sharedResourceByKey
+              .snapshot()
+              .resourcesByKey.has("a");
+            onDisposedCalled.resolve();
+          },
+        }),
+      );
+
+      const lease = await run.ok(sharedResourceByKey.acquire("a"));
+      lease.release();
+      await onDisposedCalled.promise;
+
+      assertFalse(hasKeyWhenDisposed);
+      assertEqual(resources.getDisposeCount(), 1);
+
+      // The key was removed before onDisposed, so this acquire creates a fresh
+      // resource.
+      const again = await run.ok(sharedResourceByKey.acquire("a"));
+
+      assertEqual(resources.getCreateCount(), 2);
+      assertFalse(Object.is(again.resource, lease.resource));
+      assertEqual(sharedResourceByKey.snapshot().resourcesByKey.size, 1);
+    });
+
+    it("removes the key when acquireCurrent waits for its resource disposal", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(
+          () => () =>
+            ok({
+              [Symbol.asyncDispose]: async () => {
+                disposalStarted.resolve();
+                await continueDisposal.promise;
+              },
+            }),
+        ),
+      );
+
+      const lease = await run.ok(sharedResourceByKey.acquire("a"));
+      lease.release();
+      await disposalStarted.promise;
+
+      const current = run.ok(sharedResourceByKey.acquireCurrent("a"));
+      await assertConditionAfterMicrotasks(
+        () =>
+          sharedResourceByKey.snapshot().resourcesByKey.get("a")?.mutex.waiters
+            .length === 1,
+        5,
+      );
+      continueDisposal.resolve();
+
+      assertSame(await current, undefined);
+      assertFalse(sharedResourceByKey.snapshot().resourcesByKey.has("a"));
+    });
+
+    it("keeps the key when its resource is reacquired before removal", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+
+      const first = await run.ok(sharedResourceByKey.acquire("a"));
+
+      // Take the outer key mutex before release so synchronous key removal
+      // leaves the SharedResource registered for this acquire.
+      const second = run.ok(sharedResourceByKey.acquire("a"));
+      first.release();
+      const secondLease = await second;
+
+      // Later acquires reuse the same keyed SharedResource.
+      const thirdLease = await run.ok(sharedResourceByKey.acquire("a"));
+
+      assertEqual(resources.getCreateCount(), 2);
+      assertEqual(resources.getDisposeCount(), 1);
+      assertSame(thirdLease.resource, secondLease.resource);
+    });
+  });
+
+  describe("lookup", () => {
+    it("derives logical key identity", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create, {
+          lookup: (key: { readonly id: string }) => key.id,
+        }),
+      );
+
+      const first = await run.ok(sharedResourceByKey.acquire({ id: "a" }));
+      const second = await run.ok(sharedResourceByKey.acquire({ id: "a" }));
+      await run.ok(sharedResourceByKey.acquire({ id: "b" }));
+
+      assertEqual(resources.getCreateCount(), 2);
+      assertSame(second.resource, first.resource);
+    });
+  });
+
+  describe("acquireCurrent", () => {
+    it("returns undefined for an absent key without creating or registering it", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+
+      const lease = await run.ok(sharedResourceByKey.acquireCurrent("a"));
+
+      assertSame(lease, undefined);
+      assertEqual(resources.getCreateCount(), 0);
+      assertEqual(sharedResourceByKey.snapshot().resourcesByKey.size, 0);
+    });
+
+    it("acquires the current resource for an existing key without creating another", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+
+      const first = await run.ok(sharedResourceByKey.acquire("a"));
+      const current = await run.ok(sharedResourceByKey.acquireCurrent("a"));
+
+      assertSame(current?.resource, first.resource);
+      assertFalse(current?.created);
+      assertEqual(resources.getCreateCount(), 1);
+    });
+  });
+
+  describe("use", () => {
+    it("creates the keyed resource and releases its lease after the Task settles", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      let leaseCountDuringUse: number | undefined;
+      let createdDuringUse: boolean | undefined;
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+      const disposed = resources.nextDisposed();
+
+      const value = await run.ok(
+        sharedResourceByKey.use("a", (_resource, created) => () => {
+          leaseCountDuringUse = sharedResourceByKey
+            .snapshot()
+            .resourcesByKey.get("a")?.leaseCount;
+          createdDuringUse = created;
+          return ok("used" as const);
+        }),
+      );
+
+      assertEqual(value, "used");
+      assertTrue(createdDuringUse);
+      assertEqual(leaseCountDuringUse, 1);
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount,
+        0,
+      );
+      await disposed;
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("reports created false while reusing a held keyed resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      let createdDuringUse: boolean | undefined;
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+      using _lease = await run.ok(sharedResourceByKey.acquire("a"));
+
+      await run.ok(
+        sharedResourceByKey.use("a", (_resource, created) => () => {
+          createdDuringUse = created;
+          return ok();
+        }),
+      );
+
+      assertFalse(createdDuringUse);
+      assertEqual(resources.getCreateCount(), 1);
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount,
+        1,
+      );
+    });
+
+    it("releases its keyed lease when the callback Task aborts", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const callbackStarted = Promise.withResolvers<void>();
+      const gate = createGate();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+      const disposed = resources.nextDisposed();
+
+      const fiber = run.abortable(
+        sharedResourceByKey.use("a", () => async (run) => {
+          callbackStarted.resolve();
+          await run.ok(gate.wait);
+          return ok();
+        }),
+      );
+      await callbackStarted.promise;
+
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount,
+        1,
+      );
+
+      fiber.abort(testAbortReason);
+      const result = await fiber;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, testAbortReason);
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount ?? 0,
+        0,
+      );
+
+      await disposed;
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+  });
+
+  describe("forEachCurrent", () => {
+    it("delegates to every current resource while holding temporary leases", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey((_key: string) => resources.create),
+      );
+
+      const first = await run.ok(sharedResourceByKey.acquire("a"));
+      const second = await run.ok(sharedResourceByKey.acquire("b"));
+      const entries: Array<readonly [typeof first.resource, string]> = [];
+      const leaseCountsDuringUse = new Map<string, number>();
+
+      await run.ok(
+        sharedResourceByKey.forEachCurrent((resource, key) => {
+          entries.push([resource, key]);
+          leaseCountsDuringUse.set(
+            key,
+            sharedResourceByKey.snapshot().resourcesByKey.get(key)!.leaseCount,
+          );
+        }),
+      );
+
+      assertEqual(entries, [
+        [first.resource, "a"],
+        [second.resource, "b"],
+      ]);
+      assertEqual(
+        leaseCountsDuringUse,
+        new Map([
+          ["a", 2],
+          ["b", 2],
+        ]),
+      );
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount,
+        1,
+      );
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("b")?.leaseCount,
+        1,
+      );
+    });
+
+    it("releases collected leases when the caller aborts while acquiring a later key", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const bCreateStarted = Promise.withResolvers<void>();
+      const continueBCreate = Promise.withResolvers<void>();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey((key: string) => async (run) => {
+          if (key === "b") {
+            bCreateStarted.resolve();
+            await continueBCreate.promise;
+          }
+          return run(resources.create);
+        }),
+      );
+
+      using _a = await run.ok(sharedResourceByKey.acquire("a"));
+      const b = run.ok(sharedResourceByKey.acquire("b"));
+      await bCreateStarted.promise;
+
+      const keys: Array<string> = [];
+      const forEach = run.abortable(
+        sharedResourceByKey.forEachCurrent((_resource, key) => {
+          keys.push(key);
+        }),
+      );
+      const firstAcquireRunSnapshot = forEach.run.snapshot().children.at(0);
+      assertNotUndefined(firstAcquireRunSnapshot);
+      // forEachCurrent acquires keys sequentially. Replacing this child means
+      // the first lease is held and acquisition of the blocked second key has
+      // started. The exact count intentionally pins that settlement pipeline.
+      await assertConditionAfterMicrotasks(() => {
+        const { children } = forEach.run.snapshot();
+        return (
+          children.length === 1 &&
+          !Object.is(children[0].id, firstAcquireRunSnapshot.id)
+        );
+      }, 34);
+
+      forEach.abort(testAbortReason);
+      continueBCreate.resolve();
+      using _b = await b;
+
+      const result = await forEach;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, testAbortReason);
+      assertEqual(keys, []);
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.leaseCount,
+        1,
+      );
+      assertEqual(
+        sharedResourceByKey.snapshot().resourcesByKey.get("b")?.leaseCount,
+        1,
+      );
+    });
+
+    it("skips a resource disposed before its temporary lease is acquired", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+      const keys: Array<string> = [];
+
+      const create: Task<AsyncDisposable> = () =>
+        ok({
+          [Symbol.asyncDispose]: async () => {
+            disposalStarted.resolve();
+            await continueDisposal.promise;
+          },
+        });
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey((_key: string) => create),
+      );
+
+      const first = await run.ok(sharedResourceByKey.acquire("a"));
+      await run.ok(sharedResourceByKey.acquire("b"));
+
+      first.release();
+      await disposalStarted.promise;
+
+      const forEach = run.ok(
+        sharedResourceByKey.forEachCurrent((_resource, key) => {
+          keys.push(key);
+        }),
+      );
+      continueDisposal.resolve();
+      await forEach;
+
+      assertEqual(keys, ["b"]);
+    });
+  });
+
+  describe("idleDisposeAfter", () => {
+    it("keeps a resource across release/acquire churn", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create, {
+          idleDisposeAfter: "3s",
+        }),
+      );
+
+      const first = await run.ok(sharedResourceByKey.acquire("a"));
+      first.release();
+
+      const second = await run.ok(sharedResourceByKey.acquire("a"));
+
+      assertEqual(resources.getCreateCount(), 1);
+      assertSame(second.resource, first.resource);
+
+      // After the last release, the idle delay elapses and the key is disposed.
+      const disposed = resources.nextDisposed();
+      second.release();
+      run.deps.time.advance("3s");
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+      assertFalse(
+        sharedResourceByKey.snapshot().resourcesByKey.get("a")?.hasResource,
+      );
+    });
+  });
+
+  describe("snapshot", () => {
+    it("returns current states by key", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+
+      assertEqual(sharedResourceByKey.snapshot(), {
+        resourcesByKey: new Map(),
+      });
+
+      await run.ok(sharedResourceByKey.acquire("a"));
+      await run.ok(sharedResourceByKey.acquire("a"));
+      await run.ok(sharedResourceByKey.acquire("b"));
+
+      assertEqual(sharedResourceByKey.snapshot(), {
+        resourcesByKey: new Map([
+          [
+            "a",
+            {
+              isIdle: false,
+              leaseCount: 2,
+              hasResource: true,
+              idleDisposePending: false,
+              mutex: idleMutexSnapshot,
+            },
+          ],
+          [
+            "b",
+            {
+              isIdle: false,
+              leaseCount: 1,
+              hasResource: true,
+              idleDisposePending: false,
+              mutex: idleMutexSnapshot,
+            },
+          ],
+        ]),
+      });
+    });
+  });
+
+  describe("onDisposed", () => {
+    it("does not call onDisposed when registry is disposed before resource creation", async () => {
+      await using run = testCreateRun();
+      const disposedKeys: Array<string> = [];
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(
+          (_key: string) => createTestResources().create,
+          {
+            onDisposed: (key) => {
+              disposedKeys.push(key);
+            },
+          },
+        ),
+      );
+
+      await sharedResourceByKey[Symbol.asyncDispose]();
+
+      assertEqual(disposedKeys, []);
+    });
+
+    it("calls onDisposed for every key during owner disposal", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const disposedKeys: Array<string> = [];
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey((_key: string) => resources.create, {
+          onDisposed: (key) => {
+            disposedKeys.push(key);
+          },
+        }),
+      );
+      await run.ok(sharedResourceByKey.acquire("a"));
+      await run.ok(sharedResourceByKey.acquire("b"));
+
+      await sharedResourceByKey[Symbol.asyncDispose]();
+
+      assertLength(disposedKeys, 2);
+      assertEqual(new Set(disposedKeys), new Set(["a", "b"]));
+    });
+
+    it("receives the key", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const disposedKeys: Array<string> = [];
+      const onDisposedCalled = Promise.withResolvers<void>();
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey((_key: string) => resources.create, {
+          onDisposed: (key) => {
+            disposedKeys.push(key);
+            onDisposedCalled.resolve();
+          },
+        }),
+      );
+
+      const lease = await run.ok(sharedResourceByKey.acquire("a"));
+
+      assertEqual(disposedKeys, []);
+
+      lease.release();
+      await onDisposedCalled.promise;
+
+      assertEqual(disposedKeys, ["a"]);
+    });
+  });
+
+  describe("disposal", () => {
+    it("aborts acquire when the registry is disposed during creation", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const createStarted = Promise.withResolvers<void>();
+      const continueCreate = Promise.withResolvers<void>();
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => async (run) => {
+          const resource = await run.ok(resources.create);
+          createStarted.resolve();
+          await continueCreate.promise;
+          return ok(resource);
+        }),
+      );
+
+      const acquire = run.abortable(sharedResourceByKey.acquire("a"));
+      await createStarted.promise;
+
+      const disposal = sharedResourceByKey[Symbol.asyncDispose]();
+      continueCreate.resolve();
+
+      const result = await acquire;
+      await disposal;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, runDisposedAbortReason);
+      assertEqual(resources.getCreateCount(), 1);
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("aborts acquireCurrent when the registry is disposed while it waits", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(
+          () => () =>
+            ok({
+              [Symbol.asyncDispose]: async () => {
+                disposalStarted.resolve();
+                await continueDisposal.promise;
+              },
+            }),
+        ),
+      );
+
+      const lease = await run.ok(sharedResourceByKey.acquire("a"));
+      lease.release();
+      await disposalStarted.promise;
+
+      const acquireCurrent = run.abortable(
+        sharedResourceByKey.acquireCurrent("a"),
+      );
+      await assertConditionAfterMicrotasks(
+        () =>
+          sharedResourceByKey.snapshot().resourcesByKey.get("a")?.mutex.waiters
+            .length === 1,
+        5,
+      );
+
+      const disposal = sharedResourceByKey[Symbol.asyncDispose]();
+      continueDisposal.resolve();
+
+      const result = await acquireCurrent;
+      await disposal;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, runDisposedAbortReason);
+    });
+
+    it("disposes all keyed resources", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create),
+      );
+
+      const leaseA = await run.ok(sharedResourceByKey.acquire("a"));
+      const leaseB = await run.ok(sharedResourceByKey.acquire("b"));
+
+      await sharedResourceByKey[Symbol.asyncDispose]();
+
+      assertEqual(resources.getDisposeCount(), 2);
+      assertFalse(leaseA.release());
+      assertFalse(leaseB.release());
+      assertEqual(sharedResourceByKey.snapshot().resourcesByKey.size, 0);
+    });
+
+    it("registry disposal owns concurrently removed keys", async () => {
+      await using run = testCreateRun();
+      const aDisposalStarted = Promise.withResolvers<void>();
+      const continueADisposal = Promise.withResolvers<void>();
+      const aDisposed = Promise.withResolvers<void>();
+      const bCreateStarted = Promise.withResolvers<void>();
+      const bCreateGate = createGate();
+
+      const create =
+        (key: string): Task<AsyncDisposable> =>
+        async (run) => {
+          if (key === "b") {
+            bCreateStarted.resolve();
+            await run.ok(bCreateGate.wait);
+          }
+
+          return ok({
+            [Symbol.asyncDispose]: async () => {
+              if (key !== "a") return;
+              aDisposalStarted.resolve();
+              await continueADisposal.promise;
+            },
+          });
+        };
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(create, {
+          onDisposed: (key) => {
+            if (key === "a") aDisposed.resolve();
+          },
+        }),
+      );
+
+      const a = await run.ok(sharedResourceByKey.acquire("a"));
+      a.release();
+      await aDisposalStarted.promise;
+
+      const b = run.abortable(sharedResourceByKey.acquire("b"));
+      await bCreateStarted.promise;
+
+      const registryDisposal = sharedResourceByKey[Symbol.asyncDispose]();
+      continueADisposal.resolve();
+      await aDisposed.promise;
+
+      bCreateGate.open();
+      const bResult = await b;
+      await registryDisposal;
+
+      assertErr(bResult);
+      assertType(AbortError, bResult.error);
+      assertSame(bResult.error.reason, runDisposedAbortReason);
+      assertEqual(run.snapshot().children, []);
+    });
+
+    it("root Run disposal awaits keyed resource disposal", async () => {
+      const run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(
+          (_key: string) => () =>
+            ok({
+              [Symbol.asyncDispose]: async () => {
+                disposalStarted.resolve();
+                await continueDisposal.promise;
+              },
+            }),
+        ),
+      );
+      await run.ok(sharedResourceByKey.acquire("a"));
+
+      let rootDisposalSettled = false;
+      const rootDisposal = run[Symbol.asyncDispose]().then(() => {
+        rootDisposalSettled = true;
+      });
+
+      try {
+        const firstSettled = await Promise.race([
+          disposalStarted.promise.then(() => "resourceDisposalStarted"),
+          rootDisposal.then(() => "rootDisposalSettled"),
+        ]);
+
+        assertEqual(firstSettled, "resourceDisposalStarted");
+        assertFalse(rootDisposalSettled);
+
+        continueDisposal.resolve();
+        await rootDisposal;
+
+        assertEqual(sharedResourceByKey.snapshot().resourcesByKey.size, 0);
+        assertEqual(run.deps.reportDefect.getDefectsSnapshot(), []);
+      } finally {
+        continueDisposal.resolve();
+        await sharedResourceByKey[Symbol.asyncDispose]();
+        await rootDisposal;
+      }
+    });
+  });
+
+  describe("leak detection", () => {
+    it("warns when an undisposed SharedResourceByKey is garbage-collected", async () => {
+      await using run = testCreateRun();
+
+      await run.ok(
+        createSharedResourceByKey(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+
+      assertEqual(run.deps.leakDetector.collect(), 1);
+
+      const entries = run.deps.console.getEntriesSnapshot();
+      assertLength(entries, 1);
+      assertEqual(entries[0].method, "warn");
+      assertEqual(
+        entries[0].args[0],
+        "SharedResourceByKey was garbage-collected without cleanup. Tracked at:",
+      );
+    });
+  });
+
+  describe("defects", () => {
+    it("acquire after registry disposal is a programmer error", async () => {
+      await using run = testCreateRun();
+
+      const sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      await sharedResourceByKey[Symbol.asyncDispose]();
+
+      const result = await run.abortable(sharedResourceByKey.acquire("a"));
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertInstanceOf(result.error.reason.defect, Error);
+      assertEqual(
+        result.error.reason.defect.message,
+        "Cannot use a disposed object.",
+      );
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing create factory panics the Run tree", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("create failed");
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey((_key: string) => {
+          throw defect;
+        }),
+      );
+
+      const result = await run.abortable(sharedResourceByKey.acquire("a"));
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing lookup panics the Run tree", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const defect = new Error("lookup failed");
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create, {
+          lookup: (_key: string): string => {
+            throw defect;
+          },
+        }),
+      );
+
+      const result = await run.abortable(sharedResourceByKey.acquire("a"));
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing onDisposed panics the Run tree", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const defect = new Error("onDisposed failed");
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(() => resources.create, {
+          onDisposed: () => {
+            throw defect;
+          },
+        }),
+      );
+
+      const lease = await run.ok(sharedResourceByKey.acquire("a"));
+      lease.release();
+
+      // Disposal runs on a fire-and-forget Fiber, so the defect is observable
+      // only via panic reporting.
+      const abortError = await run.deps.reportDefect.next();
+      assertType(AbortError, abortError);
+      assertSame(abortError.reason.type, "PanicAbortReason");
+      assertSame(abortError.reason.defect, defect);
+      assertFalse(sharedResourceByKey.snapshot().resourcesByKey.has("a"));
+    });
+  });
+
+  describe("types", () => {
+    it("acquire does not require captured deps", () => {
+      interface TestDb extends Disposable {
+        readonly query: () => string;
+      }
+      interface TestDep {
+        readonly value: string;
+      }
+
+      assertType<
+        SharedResourceByKey<string, TestDb>["acquire"],
+        (key: string) => Task<Lease<TestDb>>
+      >();
+
+      const create = ((_key: string) => () =>
+        ok({ [Symbol.dispose]: constVoid })) as (
+        key: string,
+      ) => Task<Disposable, never, TestDep>;
+
+      {
+        const actual = createSharedResourceByKey(create);
+        assertType<
+          typeof actual,
+          Task<SharedResourceByKey<string, Disposable>, never, TestDep>
+        >();
+      }
+      {
+        const actual = createSharedResourceByKey(create, {
+          lookup: (key) => key,
+        });
+        assertType<
+          typeof actual,
+          Task<SharedResourceByKey<string, Disposable>, never, TestDep>
+        >();
+      }
+
+      const failingCreate = (_key: string) => () =>
+        err({ type: "CreateError" });
+
+      // @ts-expect-error - create Task must not fail.
+      createSharedResourceByKey(failingCreate);
+    });
+
+    it("keyed acquireCurrent and use preserve their Task types", async () => {
+      await using run = testCreateRun();
+
+      interface TestDb extends Disposable {
+        readonly query: () => string;
+      }
+      interface TestError {
+        readonly type: "TestError";
+      }
+      interface TestDep {
+        readonly value: string;
+      }
+
+      const create =
+        (_key: string): Task<TestDb> =>
+        () =>
+          ok({ query: () => "result", [Symbol.dispose]: constVoid });
+
+      await using sharedResourceByKey = await run.ok(
+        createSharedResourceByKey(create),
+      );
+
+      assertType<
+        typeof sharedResourceByKey.acquireCurrent,
+        (key: string) => Task<Lease<TestDb> | undefined>
+      >();
+
+      const use = sharedResourceByKey.use(
+        "a",
+        (): Task<"used", TestError, TestDep> => () =>
+          err({ type: "TestError" }),
+      );
+      assertType<typeof use, Task<"used", TestError, TestDep>>();
+    });
+  });
+});
+
+describe("SharedResourceByKeyWithClaims", () => {
+  describe("types", () => {
+    it("types expose claim as a non-failing Task returning ClaimLease", () => {
+      assertType<ClaimLease extends Disposable ? true : false, true>();
+      assertType<
+        SharedResourceByKeyWithClaims<string, number, Disposable>["claim"],
+        (
+          claim: number,
+          resourceKeys: NonEmptyReadonlyArray<string>,
+        ) => Task<ClaimLease>
+      >();
+
+      createSharedResourceByKeyWithClaims(
+        (_key: string): Task<Disposable> =>
+          () =>
+            ok({ [Symbol.dispose]: constVoid }),
+      );
+    });
+
+    it("types expose scoped use with borrowed resources and callback Task errors and dependencies", () => {
+      assertType<
+        SharedResourceByKeyWithClaims<string, number, Disposable>["use"],
+        <R, E, D>(
+          claim: number,
+          resourceKeys: NonEmptyReadonlyArray<string>,
+          callback: (
+            resources: NonEmptyReadonlyArray<
+              readonly [BorrowedResource<Disposable>, string]
+            >,
+          ) => Task<R, E, D>,
+        ) => Task<R, E, D>
+      >();
+    });
+
+    it("types reject empty claim and use resource keys", () => {
+      type Claims = SharedResourceByKeyWithClaims<string, number, Disposable>;
+
+      // @ts-expect-error - a claim must retain at least one resource.
+      const _invalidClaimResourceKeys: Parameters<Claims["claim"]>[1] = [];
+      // @ts-expect-error - scoped use must retain at least one resource.
+      const _invalidUseResourceKeys: Parameters<Claims["use"]>[1] = [];
+    });
+
+    it("types do not expose command-based removeClaim", () => {
+      assertType<
+        "removeClaim" extends keyof SharedResourceByKeyWithClaims<
+          string,
+          number,
+          Disposable
+        >
+          ? true
+          : false,
+        false
+      >();
+    });
+
+    it("types accept interface-shaped keys and claims with lookup functions", () => {
+      interface ResourceKey {
+        readonly id: string;
+      }
+
+      interface Claim {
+        readonly id: number;
+      }
+
+      const task = createSharedResourceByKeyWithClaims(
+        (_key: ResourceKey): Task<Disposable> =>
+          () =>
+            ok({ [Symbol.dispose]: constVoid }),
+        {
+          resourceLookup: (key) => key.id,
+          claimLookup: (claim: Claim) => claim.id,
+        },
+      );
+
+      assertType<
+        typeof task,
+        Task<SharedResourceByKeyWithClaims<ResourceKey, Claim, Disposable>>
+      >();
+    });
+  });
+
+  describe("use", () => {
+    it("provides only its resources in input order and releases them after the callback settles", async () => {
+      await using run = testCreateRun();
+      const callbackStarted = Promise.withResolvers<void>();
+      const continueCallback = createGate();
+      const scopedResourcesDisposed = Promise.withResolvers<void>();
+      const disposedKeys = new Set<string>();
+
+      interface TestResource extends Disposable {
+        readonly key: string;
+        readonly isDisposed: () => boolean;
+      }
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<TestResource> =>
+            () =>
+              ok({
+                key,
+                isDisposed: () => disposedKeys.has(key),
+                [Symbol.dispose]: () => {
+                  disposedKeys.add(key);
+                  if (disposedKeys.has("a") && disposedKeys.has("b")) {
+                    scopedResourcesDisposed.resolve();
+                  }
+                },
+              }),
+        ),
+      );
+      using _existingClaimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["existing"]),
+      );
+
+      const use = run.ok(
+        sharedResourceByKeyWithClaims.use(
+          "claim",
+          ["b", "a"],
+          (resources) => async (run) => {
+            callbackStarted.resolve();
+            await run.ok(continueCallback.wait);
+            return ok(
+              resources.map(([resource, resourceKey]) => {
+                assertFalse(resource.isDisposed());
+                return [resource.key, resourceKey] as const;
+              }),
+            );
+          },
+        ),
+      );
+      await callbackStarted.promise;
+
+      assertEqual(disposedKeys, new Set());
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["existing", "b", "a"]),
+      );
+
+      continueCallback.open();
+
+      assertEqual(await use, [
+        ["b", "b"],
+        ["a", "a"],
+      ]);
+      await scopedResourcesDisposed.promise;
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["existing"]),
+      );
+    });
+
+    it("releases its ClaimLease when the callback Task aborts", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const callbackStarted = Promise.withResolvers<void>();
+      const gate = createGate();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => resources.create),
+      );
+      const disposed = resources.nextDisposed();
+
+      const fiber = run.abortable(
+        sharedResourceByKeyWithClaims.use(
+          "claim",
+          ["resource"],
+          () => async (run) => {
+            callbackStarted.resolve();
+            await run.ok(gate.wait);
+            return ok();
+          },
+        ),
+      );
+      await callbackStarted.promise;
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["resource"]),
+      );
+
+      fiber.abort(testAbortReason);
+      const result = await fiber;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, testAbortReason);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+
+      await disposed;
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+  });
+
+  describe("claim lifecycle", () => {
+    it("claim lazily creates and retains every keyed resource until its claim lease is released", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => resources.create),
+      );
+
+      assertEqual(resources.getCreateCount(), 0);
+
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertEqual(resources.getCreateCount(), 1);
+      assertEqual(resources.getDisposeCount(), 0);
+
+      const disposed = resources.nextDisposed();
+      assertTrue(claimLease.release());
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("claim lease release is idempotent", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => resources.create),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      const disposed = resources.nextDisposed();
+      assertTrue(claimLease.release());
+      assertFalse(claimLease.release());
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("claim lease Symbol.dispose releases it", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => resources.create),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      const disposed = resources.nextDisposed();
+      claimLease[Symbol.dispose]();
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("repeated claims for the same logical pair retain independently without duplicating the relation", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: { readonly id: string }) => resources.create,
+          {
+            resourceLookup: (key) => key.id,
+            claimLookup: (claim: { readonly id: string }) => claim.id,
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim({ id: "claim" }, [
+          { id: "resource" },
+        ]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim({ id: "claim" }, [
+          { id: "resource" },
+        ]),
+      );
+
+      assertEqual(resources.getCreateCount(), 1);
+
+      const disposed = resources.nextDisposed();
+      assertTrue(first.release());
+      assertEqual(resources.getDisposeCount(), 0);
+      assertTrue(second.release());
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("multiple claims share one keyed resource until the last claim lease is released", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => resources.create),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+
+      assertEqual(resources.getCreateCount(), 1);
+
+      const disposed = resources.nextDisposed();
+      assertTrue(first.release());
+      assertEqual(resources.getDisposeCount(), 0);
+      assertTrue(second.release());
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("one claim lease retains and releases multiple resource keys together", async () => {
+      await using run = testCreateRun();
+      const createdKeys: Array<string> = [];
+      const disposedKeys: Array<string> = [];
+      const allDisposed = Promise.withResolvers<void>();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<Disposable> =>
+            () => {
+              createdKeys.push(key);
+              return ok({
+                [Symbol.dispose]: () => {
+                  disposedKeys.push(key);
+                  if (disposedKeys.length === 2) allDisposed.resolve();
+                },
+              });
+            },
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+
+      assertEqual(createdKeys, ["a", "b"]);
+
+      assertTrue(claimLease.release());
+      await allDisposed.promise;
+
+      assertEqual(new Set(disposedKeys), new Set(["a", "b"]));
+    });
+
+    it("claim rejects lookup-duplicate resource keys as a programmer defect", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: { readonly id: string }) => resources.create,
+          { resourceLookup: (key) => key.id },
+        ),
+      );
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", [
+          { id: "resource" },
+          { id: "resource" },
+        ]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertInstanceOf(result.error.reason.defect, Error);
+      assertEqual(
+        result.error.reason.defect.message,
+        "resourceKeys must not contain lookup duplicates.",
+      );
+      assertEqual(resources.getCreateCount(), 0);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("claim snapshots resource keys before awaiting acquisition", async () => {
+      await using run = testCreateRun();
+      const createStarted = Promise.withResolvers<void>();
+      const continueCreate = Promise.withResolvers<void>();
+      const createdKeys: Array<string> = [];
+      const resourceKeys: NonEmptyArray<string> = ["a"];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<Disposable> =>
+            async () => {
+              createdKeys.push(key);
+              if (key === "a") {
+                createStarted.resolve();
+                await continueCreate.promise;
+              }
+              return ok({ [Symbol.dispose]: constVoid });
+            },
+        ),
+      );
+
+      const claim = run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", resourceKeys),
+      );
+      await createStarted.promise;
+      resourceKeys.push("b");
+      continueCreate.resolve();
+      using _claimLease = await claim;
+
+      assertEqual(createdKeys, ["a"]);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["a"]),
+      );
+    });
+
+    it("later claim deps do not replace deps captured for resource creation", async () => {
+      await using run = testCreateRun();
+
+      interface TestDep {
+        readonly value: string;
+      }
+
+      const createValues: Array<string> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string): Task<Disposable, never, TestDep> =>
+            ({ deps }) => {
+              createValues.push(deps.value);
+              return ok({ [Symbol.dispose]: constVoid });
+            },
+        ),
+        { value: "captured" },
+      );
+
+      using _claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+        { value: "replacement" },
+      );
+
+      assertEqual(createValues, ["captured"]);
+    });
+  });
+
+  describe("relations", () => {
+    it("gets unique canonical claims retaining a resource key", async () => {
+      await using run = testCreateRun();
+
+      interface ResourceKey {
+        readonly id: string;
+        readonly label: string;
+      }
+
+      interface Claim {
+        readonly id: string;
+        readonly label: string;
+      }
+
+      const resourceKey = { id: "resource", label: "first" };
+      const firstClaim = { id: "first", label: "first" };
+      const equivalentFirstClaim = { id: "first", label: "equivalent" };
+      const secondClaim = { id: "second", label: "second" };
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: ResourceKey) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            resourceLookup: (key) => key.id,
+            claimLookup: (claim: Claim) => claim.id,
+          },
+        ),
+      );
+      using _first = await run.ok(
+        sharedResourceByKeyWithClaims.claim(firstClaim, [resourceKey]),
+      );
+      using _equivalentFirst = await run.ok(
+        sharedResourceByKeyWithClaims.claim(equivalentFirstClaim, [
+          { id: "resource", label: "equivalent" },
+        ]),
+      );
+      using _second = await run.ok(
+        sharedResourceByKeyWithClaims.claim(secondClaim, [resourceKey]),
+      );
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource({
+          id: "resource",
+          label: "query",
+        }),
+        new Set([firstClaim, secondClaim]),
+      );
+
+      const snapshot = sharedResourceByKeyWithClaims.snapshot();
+      assertSame(
+        [...snapshot.retainCountsByResourceKeyByClaim.keys()][0],
+        firstClaim,
+      );
+      const firstClaimRetainCounts =
+        snapshot.retainCountsByResourceKeyByClaim.get(firstClaim);
+      assertNotUndefined(firstClaimRetainCounts);
+      assertSame([...firstClaimRetainCounts.keys()][0], resourceKey);
+      assertSame([...snapshot.resourcesByKey.keys()][0], resourceKey);
+    });
+
+    it("gets unique canonical resource keys retained by a claim", async () => {
+      await using run = testCreateRun();
+
+      interface ResourceKey {
+        readonly id: string;
+        readonly label: string;
+      }
+
+      interface Claim {
+        readonly id: string;
+        readonly label: string;
+      }
+
+      const claim = { id: "claim", label: "first" };
+      const firstResourceKey = { id: "first", label: "first" };
+      const secondResourceKey = { id: "second", label: "second" };
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: ResourceKey) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            resourceLookup: (key) => key.id,
+            claimLookup: (claim: Claim) => claim.id,
+          },
+        ),
+      );
+      using _first = await run.ok(
+        sharedResourceByKeyWithClaims.claim(claim, [firstResourceKey]),
+      );
+      using _second = await run.ok(
+        sharedResourceByKeyWithClaims.claim(
+          { id: "claim", label: "equivalent" },
+          [{ id: "first", label: "equivalent" }, secondResourceKey],
+        ),
+      );
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim({
+          id: "claim",
+          label: "query",
+        }),
+        new Set([firstResourceKey, secondResourceKey]),
+      );
+    });
+
+    it("keeps canonical representatives until their logical relations end", async () => {
+      await using run = testCreateRun();
+
+      interface ResourceKey {
+        readonly id: string;
+        readonly label: string;
+      }
+
+      interface Claim {
+        readonly id: string;
+        readonly label: string;
+      }
+
+      const firstClaim = { id: "claim", label: "first" };
+      const equivalentClaim = { id: "claim", label: "equivalent" };
+      const firstResourceKey = { id: "resource", label: "first" };
+      const equivalentResourceKey = {
+        id: "resource",
+        label: "equivalent",
+      };
+      const lastClaimRemoved: Array<readonly [Claim, ResourceKey]> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: ResourceKey) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            resourceLookup: (key) => key.id,
+            claimLookup: (claim: Claim) => claim.id,
+            onLastClaimRemoved: (claim, _resource, resourceKey) => {
+              lastClaimRemoved.push([claim, resourceKey]);
+            },
+          },
+        ),
+      );
+      const firstClaimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim(firstClaim, [firstResourceKey]),
+      );
+      const equivalentClaimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim(equivalentClaim, [
+          equivalentResourceKey,
+        ]),
+      );
+
+      firstClaimLease.release();
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource(
+          equivalentResourceKey,
+        ),
+        new Set([firstClaim]),
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim(equivalentClaim),
+        new Set([firstResourceKey]),
+      );
+
+      const snapshot = sharedResourceByKeyWithClaims.snapshot();
+      assertEqual(
+        [...snapshot.retainCountsByResourceKeyByClaim.keys()],
+        [firstClaim],
+      );
+      assertEqual(
+        [...snapshot.retainCountsByResourceKeyByClaim.get(firstClaim)!.keys()],
+        [firstResourceKey],
+      );
+      assertEqual([...snapshot.resourcesByKey.keys()], [firstResourceKey]);
+
+      equivalentClaimLease.release();
+
+      assertEqual(lastClaimRemoved, [[firstClaim, firstResourceKey]]);
+    });
+
+    it("iterates current resources for a claim while pair leases keep them alive", async () => {
+      await using run = testCreateRun();
+
+      interface TestResource extends Disposable {
+        readonly id: string;
+        readonly isDisposed: () => boolean;
+      }
+
+      const disposedIds = new Set<string>();
+      const visited: Array<readonly [string, string]> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: { readonly id: string }): Task<TestResource> =>
+            () =>
+              ok({
+                id: key.id,
+                isDisposed: () => disposedIds.has(key.id),
+                [Symbol.dispose]: () => {
+                  disposedIds.add(key.id);
+                },
+              }),
+          {
+            resourceLookup: (key) => key.id,
+            claimLookup: (claim: { readonly id: string }) => claim.id,
+          },
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim({ id: "claim" }, [
+          { id: "a" },
+          { id: "b" },
+        ]),
+      );
+
+      sharedResourceByKeyWithClaims.forEachResourceForClaim(
+        { id: "claim" },
+        (resource, resourceKey) => {
+          assertFalse(resource.isDisposed());
+          visited.push([resource.id, resourceKey.id]);
+        },
+      );
+
+      assertEqual(visited, [
+        ["a", "a"],
+        ["b", "b"],
+      ]);
+      assertEqual(disposedIds.size, 0);
+
+      claimLease.release();
+    });
+
+    it("relation queries are empty after the final claim lease is released", async () => {
+      await using run = testCreateRun();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(["claim"]),
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["resource"]),
+      );
+
+      claimLease.release();
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(),
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+
+      const visited: Array<string> = [];
+      sharedResourceByKeyWithClaims.forEachResourceForClaim("claim", () => {
+        visited.push("visited");
+      });
+      assertEqual(visited, []);
+    });
+
+    it("iteration is stable when a callback releases the claim lease", async () => {
+      await using run = testCreateRun();
+      const disposedKeys = new Set<string>();
+      const allDisposed = Promise.withResolvers<void>();
+
+      interface TestResource extends Disposable {
+        readonly isDisposed: () => boolean;
+      }
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<TestResource> =>
+            () =>
+              ok({
+                isDisposed: () => disposedKeys.has(key),
+                [Symbol.dispose]: () => {
+                  disposedKeys.add(key);
+                  if (disposedKeys.size === 2) allDisposed.resolve();
+                },
+              }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+      const visited: Array<string> = [];
+
+      sharedResourceByKeyWithClaims.forEachResourceForClaim(
+        "claim",
+        (resource, resourceKey) => {
+          assertFalse(resource.isDisposed());
+          visited.push(resourceKey);
+          if (resourceKey === "a") assertTrue(claimLease.release());
+        },
+      );
+
+      assertEqual(visited, ["a", "b"]);
+      assertEqual(disposedKeys.size, 0);
+      await allDisposed.promise;
+      assertEqual(disposedKeys, new Set(["a", "b"]));
+      assertFalse(claimLease.release());
+    });
+  });
+
+  describe("transitions", () => {
+    it("calls onFirstClaimAdded for each claim-resource pair's first retain", async () => {
+      await using run = testCreateRun();
+      const calls: Array<readonly [string, string, string]> = [];
+
+      interface TestResource extends Disposable {
+        readonly id: string;
+      }
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<TestResource> =>
+            () =>
+              ok({ id: key, [Symbol.dispose]: constVoid }),
+          {
+            onFirstClaimAdded: (claim: string, resource, resourceKey) => {
+              calls.push([claim, resource.id, resourceKey]);
+            },
+          },
+        ),
+      );
+
+      using _first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      using _second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+
+      assertEqual(calls, [
+        ["first", "resource", "resource"],
+        ["second", "resource", "resource"],
+      ]);
+    });
+
+    it("onFirstClaimAdded can iterate all resources retained by the claim", async () => {
+      await using run = testCreateRun();
+      const visitedKeys: Array<string> = [];
+      let forEachResourceForClaim = (
+        _claim: string,
+        _callback: (
+          resource: BorrowedResource<Disposable>,
+          resourceKey: string,
+        ) => void,
+      ): void => {
+        throw new Error("forEachResourceForClaim is not initialized.");
+      };
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            onFirstClaimAdded: (claim: string, _resource, resourceKey) => {
+              if (resourceKey !== "a") return;
+              forEachResourceForClaim(claim, (_resource, resourceKey) => {
+                visitedKeys.push(resourceKey);
+              });
+            },
+          },
+        ),
+      );
+      forEachResourceForClaim = (claim, callback) => {
+        sharedResourceByKeyWithClaims.forEachResourceForClaim(claim, callback);
+      };
+
+      using _claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+
+      assertEqual(visitedKeys, ["a", "b"]);
+    });
+
+    it("calls onLastClaimRemoved before a key loses its final lease", async () => {
+      await using run = testCreateRun();
+      let resourceDisposed = false;
+      let callbackState:
+        | {
+            readonly claim: string;
+            readonly key: string;
+            readonly disposed: boolean;
+          }
+        | undefined;
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () =>
+            ok({
+              isDisposed: () => resourceDisposed,
+              [Symbol.dispose]: () => {
+                resourceDisposed = true;
+              },
+            }),
+          {
+            onLastClaimRemoved: (claim: string, resource, resourceKey) => {
+              callbackState = {
+                claim,
+                key: resourceKey,
+                disposed: resource.isDisposed(),
+              };
+            },
+          },
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      claimLease.release();
+
+      assertEqual(callbackState, {
+        claim: "claim",
+        key: "resource",
+        disposed: false,
+      });
+    });
+
+    it("onLastClaimRemoved observes the current pair removed and later lease keys retained", async () => {
+      await using run = testCreateRun();
+      const relationStates: Array<
+        readonly [string, ReadonlySet<string>, ReadonlySet<string>]
+      > = [];
+      let getClaimsForResource = (_resourceKey: string): ReadonlySet<string> =>
+        new Set();
+      let getResourceKeysForClaim = (_claim: string): ReadonlySet<string> =>
+        new Set();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            onLastClaimRemoved: (claim: string, _resource, resourceKey) => {
+              if (claim !== "claim") return;
+              relationStates.push([
+                resourceKey,
+                getClaimsForResource(resourceKey),
+                getResourceKeysForClaim(claim),
+              ]);
+            },
+          },
+        ),
+      );
+      getClaimsForResource = (resourceKey) =>
+        sharedResourceByKeyWithClaims.getClaimsForResource(resourceKey);
+      getResourceKeysForClaim = (claim) =>
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim(claim);
+
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+      using _otherClaimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("other", ["a"]),
+      );
+
+      claimLease.release();
+
+      assertEqual(relationStates, [
+        ["a", new Set(["other"]), new Set(["b"])],
+        ["b", new Set(), new Set()],
+      ]);
+    });
+
+    it("calls onLastClaimRemoved for each claim-resource pair's final release", async () => {
+      await using run = testCreateRun();
+      const calls: Array<string> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            onLastClaimRemoved: (claim: string) => {
+              calls.push(claim);
+            },
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+
+      first.release();
+      assertEqual(calls, ["first"]);
+
+      second.release();
+      assertEqual(calls, ["first", "second"]);
+    });
+
+    it("pair transitions ignore intermediate retains and releases", async () => {
+      await using run = testCreateRun();
+      const firstCalls: Array<string> = [];
+      const lastCalls: Array<string> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            onFirstClaimAdded: (claim: string) => {
+              firstCalls.push(claim);
+            },
+            onLastClaimRemoved: (claim: string) => {
+              lastCalls.push(claim);
+            },
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertEqual(firstCalls, ["claim"]);
+
+      first.release();
+      assertEqual(lastCalls, []);
+
+      second.release();
+      assertEqual(lastCalls, ["claim"]);
+    });
+
+    it("calls onFirstClaimAdded again after zero claims is reached while the resource idles", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const resourcesAtFirstClaim: Array<object> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          {
+            idleDisposeAfter: "3s",
+            onFirstClaimAdded: (_claim, resource) => {
+              resourcesAtFirstClaim.push(resource);
+            },
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      first.release();
+
+      using _second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+
+      assertEqual(resources.getCreateCount(), 1);
+      assertLength(resourcesAtFirstClaim, 2);
+      assertSame(resourcesAtFirstClaim[1], resourcesAtFirstClaim[0]);
+    });
+
+    it("registry disposal drains claims without calling transition callbacks because disposal is not semantic claim removal", async () => {
+      await using run = testCreateRun();
+      const lastClaimRemoved: Array<string> = [];
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            onLastClaimRemoved: (claim: string) => {
+              lastClaimRemoved.push(claim);
+            },
+          },
+        ),
+      );
+      await run.ok(sharedResourceByKeyWithClaims.claim("claim", ["resource"]));
+
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      assertEqual(lastClaimRemoved, []);
+    });
+
+    it("onFirstClaimAdded defects compensate completed transitions in reverse order and clean up resources", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("onFirstClaimAdded failed");
+      const firstTransitions: Array<string> = [];
+      const lastTransitions: Array<string> = [];
+      const resourceKeysDuringTransitions: Array<ReadonlySet<string>> = [];
+      const allDisposed = Promise.withResolvers<void>();
+      let disposeCount = 0;
+      let getResourceKeysForClaim = (): ReadonlySet<string> => new Set();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () =>
+            ok({
+              [Symbol.dispose]: () => {
+                disposeCount++;
+                if (disposeCount === 3) allDisposed.resolve();
+              },
+            }),
+          {
+            onFirstClaimAdded: (_claim, _resource, resourceKey) => {
+              resourceKeysDuringTransitions.push(getResourceKeysForClaim());
+              if (resourceKey === "c") throw defect;
+              firstTransitions.push(resourceKey);
+            },
+            onLastClaimRemoved: (_claim, _resource, resourceKey) => {
+              resourceKeysDuringTransitions.push(getResourceKeysForClaim());
+              lastTransitions.push(resourceKey);
+            },
+          },
+        ),
+      );
+      getResourceKeysForClaim = () =>
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim");
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b", "c"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      await allDisposed.promise;
+      assertEqual(firstTransitions, ["a", "b"]);
+      assertEqual(lastTransitions, ["b", "a"]);
+      assertEqual(resourceKeysDuringTransitions, [
+        new Set(["a", "b", "c"]),
+        new Set(["a", "b", "c"]),
+        new Set(["a", "b", "c"]),
+        new Set(["a", "b", "c"]),
+        new Set(["a", "b", "c"]),
+      ]);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("compensation callback defects also panic while cleanup completes", async () => {
+      await using run = testCreateRun();
+      const firstDefect = new Error("onFirstClaimAdded failed");
+      const compensationDefect = new Error("compensation failed");
+      const allDisposed = Promise.withResolvers<void>();
+      let disposeCount = 0;
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () =>
+            ok({
+              [Symbol.dispose]: () => {
+                disposeCount++;
+                if (disposeCount === 2) allDisposed.resolve();
+              },
+            }),
+          {
+            onFirstClaimAdded: (_claim, _resource, resourceKey) => {
+              if (resourceKey === "b") throw firstDefect;
+            },
+            onLastClaimRemoved: () => {
+              throw compensationDefect;
+            },
+          },
+        ),
+      );
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, firstDefect);
+      await allDisposed.promise;
+      assertEqual(
+        run.deps.reportDefect.getDefectsSnapshot().map((reported) => {
+          assertType(AbortError, reported);
+          assertSame(reported.reason.type, "PanicAbortReason");
+          return reported.reason.defect;
+        }),
+        [compensationDefect, firstDefect],
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+    });
+
+    it("onLastClaimRemoved defects panic the owner Run and resources are cleaned up", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const defect = new Error("onLastClaimRemoved failed");
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          {
+            onLastClaimRemoved: () => {
+              throw defect;
+            },
+          },
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+      const disposed = resources.nextDisposed();
+
+      assertTrue(claimLease.release());
+
+      const abortError = await run.deps.reportDefect.next();
+      assertType(AbortError, abortError);
+      assertSame(abortError.reason.type, "PanicAbortReason");
+      assertSame(abortError.reason.defect, defect);
+      await disposed;
+      assertEqual(resources.getDisposeCount(), 1);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(),
+      );
+    });
+  });
+
+  describe("idle disposal", () => {
+    it("the final claim release keeps the resource alive until idleDisposeAfter elapses", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          { idleDisposeAfter: "3s" },
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertTrue(claimLease.release());
+      run.deps.time.advance("2s");
+
+      assertEqual(resources.getDisposeCount(), 0);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(),
+      );
+
+      const disposed = resources.nextDisposed();
+      run.deps.time.advance("1s");
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+
+    it("a claim acquired during idle delay reuses the current resource", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const resourcesAtFirstClaim: Array<object> = [];
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          {
+            idleDisposeAfter: "3s",
+            onFirstClaimAdded: (_claim, resource) => {
+              resourcesAtFirstClaim.push(resource);
+            },
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      first.release();
+      run.deps.time.advance("2s");
+
+      using _second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+
+      assertEqual(resources.getCreateCount(), 1);
+      assertLength(resourcesAtFirstClaim, 2);
+      assertSame(resourcesAtFirstClaim[1], resourcesAtFirstClaim[0]);
+
+      run.deps.time.advance("1s");
+      assertEqual(resources.getDisposeCount(), 0);
+    });
+
+    it("a claim acquired after disposal starts creates a fresh resource generation", async () => {
+      await using run = testCreateRun();
+      const firstDisposalStarted = Promise.withResolvers<void>();
+      const continueFirstDisposal = Promise.withResolvers<void>();
+      const resourcesAtFirstClaim: Array<{ readonly id: number }> = [];
+      let createCount = 0;
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string): Task<AsyncDisposable & { readonly id: number }> =>
+            () => {
+              const id = ++createCount;
+              return ok({
+                id,
+                [Symbol.asyncDispose]: async () => {
+                  if (id !== 1) return;
+                  firstDisposalStarted.resolve();
+                  await continueFirstDisposal.promise;
+                },
+              });
+            },
+          {
+            idleDisposeAfter: "3s",
+            onFirstClaimAdded: (_claim, resource) => {
+              resourcesAtFirstClaim.push(resource);
+            },
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      first.release();
+      run.deps.time.advance("3s");
+      await firstDisposalStarted.promise;
+
+      const second = run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+      const createCountWhileDisposing = createCount;
+      continueFirstDisposal.resolve();
+      using _second = await second;
+
+      assertEqual(createCountWhileDisposing, 1);
+      assertEqual(createCount, 2);
+      assertEqual(
+        resourcesAtFirstClaim.map((resource) => resource.id),
+        [1, 2],
+      );
+    });
+
+    it("a stale disposal callback does not hide a reacquired resource", async () => {
+      await using run = testCreateRun();
+      const firstDisposalStarted = Promise.withResolvers<void>();
+      const continueFirstDisposal = Promise.withResolvers<void>();
+      let createCount = 0;
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string): Task<AsyncDisposable> =>
+            () => {
+              const id = ++createCount;
+              return ok({
+                [Symbol.asyncDispose]: async () => {
+                  if (id !== 1) return;
+                  firstDisposalStarted.resolve();
+                  await continueFirstDisposal.promise;
+                },
+              });
+            },
+          { idleDisposeAfter: "3s" },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      first.release();
+      run.deps.time.advance("3s");
+      await firstDisposalStarted.promise;
+
+      const second = run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+      continueFirstDisposal.resolve();
+      using _second = await second;
+      using _third = await run.ok(
+        sharedResourceByKeyWithClaims.claim("third", ["resource"]),
+      );
+
+      assertEqual(createCount, 2);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(["second", "third"]),
+      );
+    });
+
+    it("reacquisition and release restart the idle disposal delay", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          { idleDisposeAfter: "3s" },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      first.release();
+      run.deps.time.advance("2s");
+
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+      second.release();
+      run.deps.time.advance("1s");
+
+      assertEqual(resources.getDisposeCount(), 0);
+
+      const disposed = resources.nextDisposed();
+      run.deps.time.advance("2s");
+      await disposed;
+
+      assertEqual(resources.getDisposeCount(), 1);
+    });
+  });
+
+  describe("concurrency and abort", () => {
+    it("concurrent first claims for one key share one resource creation", async () => {
+      await using run = testCreateRun();
+      const createStarted = Promise.withResolvers<void>();
+      const continueCreate = createGate();
+      let createCount = 0;
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string): Task<Disposable> =>
+            async (run) => {
+              createCount++;
+              createStarted.resolve();
+              await run.ok(continueCreate.wait);
+              return ok({ [Symbol.dispose]: constVoid });
+            },
+        ),
+      );
+
+      const first = run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["resource"]),
+      );
+      await createStarted.promise;
+      const second = run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["resource"]),
+      );
+      continueCreate.open();
+
+      using _first = await first;
+      using _second = await second;
+
+      assertEqual(createCount, 1);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(["first", "second"]),
+      );
+    });
+
+    it("claim completes despite caller abort once acquisition starts", async () => {
+      await using run = testCreateRun();
+      const createStarted = Promise.withResolvers<void>();
+      const continueCreate = createGate();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string): Task<Disposable> =>
+            async (run) => {
+              createStarted.resolve();
+              await run.ok(continueCreate.wait);
+              return ok({ [Symbol.dispose]: constVoid });
+            },
+        ),
+      );
+      const claim = run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+      await createStarted.promise;
+
+      claim.abort(testAbortReason);
+      continueCreate.open();
+
+      const result = await claim;
+
+      assertOk(result);
+      using _claimLease = result.value;
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["resource"]),
+      );
+    });
+
+    it("overlapping claims acquired in different key orders complete without deadlock", async () => {
+      await using run = testCreateRun();
+      const bothCreatesStarted = createGate();
+      const startedKeys = new Set<string>();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<Disposable> =>
+            async (run) => {
+              startedKeys.add(key);
+              if (startedKeys.size === 2) bothCreatesStarted.open();
+              await run.ok(bothCreatesStarted.wait);
+              return ok({ [Symbol.dispose]: constVoid });
+            },
+        ),
+      );
+
+      const first = run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["a", "b"]),
+      );
+      const second = run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["b", "a"]),
+      );
+
+      using _first = await first;
+      using _second = await second;
+
+      assertEqual(startedKeys, new Set(["a", "b"]));
+    });
+
+    it("a claim waiting for one key does not block claims for disjoint keys", async () => {
+      await using run = testCreateRun();
+      const blockedCreateStarted = Promise.withResolvers<void>();
+      const continueBlockedCreate = createGate();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<Disposable> =>
+            async (run) => {
+              if (key === "blocked") {
+                blockedCreateStarted.resolve();
+                await run.ok(continueBlockedCreate.wait);
+              }
+              return ok({ [Symbol.dispose]: constVoid });
+            },
+        ),
+      );
+      const blocked = run.ok(
+        sharedResourceByKeyWithClaims.claim("blocked", ["blocked"]),
+      );
+      await blockedCreateStarted.promise;
+
+      using _disjoint = await run.ok(
+        sharedResourceByKeyWithClaims.claim("disjoint", ["disjoint"]),
+      );
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("disjoint"),
+        new Set(["disjoint"]),
+      );
+
+      continueBlockedCreate.open();
+      using _blocked = await blocked;
+    });
+
+    it("claim re-inserts a resource generation pinned before another claim removes its relation", async () => {
+      await using run = testCreateRun();
+      const trailingCreateStarted = Promise.withResolvers<void>();
+      const continueTrailingCreate = createGate();
+      const createCountsByKey = new Map<string, number>();
+
+      interface TestResource extends Disposable {
+        readonly key: string;
+      }
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<TestResource> =>
+            async (run) => {
+              if (key === "trailing") {
+                trailingCreateStarted.resolve();
+                await run.ok(continueTrailingCreate.wait);
+              }
+              createCountsByKey.set(key, (createCountsByKey.get(key) ?? 0) + 1);
+              return ok({ key, [Symbol.dispose]: constVoid });
+            },
+        ),
+      );
+      const firstClaimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["shared"]),
+      );
+      let firstResource: BorrowedResource<TestResource> | undefined;
+      sharedResourceByKeyWithClaims.forEachResourceForClaim(
+        "first",
+        (resource) => {
+          firstResource = resource;
+        },
+      );
+
+      const secondClaim = run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["shared", "trailing"]),
+      );
+      await trailingCreateStarted.promise;
+
+      firstClaimLease.release();
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("shared"),
+        new Set(),
+      );
+
+      continueTrailingCreate.open();
+      using _secondClaimLease = await secondClaim;
+
+      let secondResource: BorrowedResource<TestResource> | undefined;
+      sharedResourceByKeyWithClaims.forEachResourceForClaim(
+        "second",
+        (resource, resourceKey) => {
+          if (resourceKey === "shared") secondResource = resource;
+        },
+      );
+      assertSame(secondResource, firstResource);
+      assertEqual(createCountsByKey.get("shared"), 1);
+    });
+
+    it("registry disposal before claim transfer aborts acquisition and releases partial leases", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const secondCreateStarted = Promise.withResolvers<void>();
+      const secondCreateGate = createGate();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (key: string): Task<Disposable> =>
+            async (run) => {
+              if (key === "b") {
+                secondCreateStarted.resolve();
+                await run.ok(secondCreateGate.wait);
+              }
+              return run(resources.create);
+            },
+        ),
+      );
+      const claim = run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+      await secondCreateStarted.promise;
+
+      const disposal = sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+      secondCreateGate.open();
+      const result = await claim;
+      await disposal;
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason, runDisposedAbortReason);
+      assertEqual(resources.getCreateCount(), 2);
+      assertEqual(resources.getDisposeCount(), 2);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+    });
+
+    it("registry disposal after claim transfer can drain the lease before the caller awaits it", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const claimTransferred = Promise.withResolvers<void>();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          { onFirstClaimAdded: () => claimTransferred.resolve() },
+        ),
+      );
+      const claim = run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      await claimTransferred.promise;
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(["resource"]),
+      );
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      const claimLease = await claim;
+
+      assertFalse(claimLease.release());
+      assertEqual(resources.getDisposeCount(), 1);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+    });
+  });
+
+  describe("disposal", () => {
+    it("disposal drains claim leases, claim indexes, and keyed resources", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => resources.create),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a"]),
+      );
+
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      assertFalse(first.release());
+      assertFalse(second.release());
+      assertEqual(resources.getDisposeCount(), 2);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("a"),
+        new Set(),
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        0,
+      );
+      assertEqual(run.deps.reportDefect.getDefectsSnapshot(), []);
+    });
+
+    it("disposal continues draining claim leases after one release defects", async () => {
+      await using run = testCreateRun();
+      const resources = createTestResources();
+      const defect = new Error("claim lookup failed during drain");
+      let throwForFirst = false;
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => resources.create,
+          {
+            claimLookup: (claim: string) => {
+              if (throwForFirst && claim === "first") throw defect;
+              return claim;
+            },
+          },
+        ),
+      );
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("first", ["a"]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("second", ["b"]),
+      );
+
+      throwForFirst = true;
+      await assertRejects(
+        sharedResourceByKeyWithClaims[Symbol.asyncDispose](),
+        (disposalError) => {
+          assertType(AbortError, disposalError);
+          assertSame(disposalError.reason.type, "PanicAbortReason");
+          assertSame(disposalError.reason.defect, defect);
+        },
+      );
+      throwForFirst = false;
+      assertFalse(first.release());
+      assertFalse(second.release());
+      assertEqual(resources.getDisposeCount(), 2);
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("a"),
+        new Set(),
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("second"),
+        new Set(),
+      );
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        0,
+      );
+      const reportedDefects = run.deps.reportDefect.getDefectsSnapshot();
+      assertLength(reportedDefects, 1);
+      const reportedDefect = reportedDefects[0];
+      assertType(AbortError, reportedDefect);
+      assertSame(reportedDefect.reason.type, "PanicAbortReason");
+      assertSame(reportedDefect.reason.defect, defect);
+    });
+
+    it("a claim lease reports false after the registry drains it", async () => {
+      await using run = testCreateRun();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      assertFalse(claimLease.release());
+    });
+
+    it("claim lease release remains safe after root Run disposal", async () => {
+      const run = testCreateRun();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      await run[Symbol.asyncDispose]();
+
+      assertFalse(claimLease.release());
+      assertFalse(claimLease.release());
+      run.deps.leakDetector.collect();
+      assertEqual(run.deps.console.getEntriesSnapshot(), []);
+    });
+
+    it("relation queries are empty after root Run disposal", async () => {
+      const run = testCreateRun();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      await run.ok(sharedResourceByKeyWithClaims.claim("claim", ["resource"]));
+
+      await run[Symbol.asyncDispose]();
+
+      assertEqual(
+        sharedResourceByKeyWithClaims.getClaimsForResource("resource"),
+        new Set(),
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims.getResourceKeysForClaim("claim"),
+        new Set(),
+      );
+      const visited: Array<string> = [];
+      sharedResourceByKeyWithClaims.forEachResourceForClaim(
+        "claim",
+        (_resource, resourceKey) => {
+          visited.push(resourceKey);
+        },
+      );
+      assertEqual(visited, []);
+    });
+
+    it("late claim lease release during registry disposal is a safe no-op", async () => {
+      await using run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () =>
+            ok({
+              [Symbol.asyncDispose]: async () => {
+                disposalStarted.resolve();
+                await continueDisposal.promise;
+              },
+            }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      const disposal = sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      try {
+        await disposalStarted.promise;
+
+        // Resource disposal starts only after the metadata drain releases the
+        // final inner lease, so the ClaimLease is already drained here.
+        assertFalse(claimLease.release());
+
+        continueDisposal.resolve();
+        await disposal;
+
+        assertEqual(run.deps.reportDefect.getDefectsSnapshot(), []);
+      } finally {
+        continueDisposal.resolve();
+        await disposal;
+      }
+    });
+
+    it("root Run disposal awaits keyed resource disposal", async () => {
+      const run = testCreateRun();
+      const disposalStarted = Promise.withResolvers<void>();
+      const continueDisposal = Promise.withResolvers<void>();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () =>
+            ok({
+              [Symbol.asyncDispose]: async () => {
+                disposalStarted.resolve();
+                await continueDisposal.promise;
+              },
+            }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      let rootDisposalSettled = false;
+      const rootDisposal = run[Symbol.asyncDispose]().then(() => {
+        rootDisposalSettled = true;
+      });
+
+      try {
+        const firstSettled = await Promise.race([
+          disposalStarted.promise.then(() => "resourceDisposalStarted"),
+          rootDisposal.then(() => "rootDisposalSettled"),
+        ]);
+
+        assertEqual(firstSettled, "resourceDisposalStarted");
+        assertFalse(rootDisposalSettled);
+
+        continueDisposal.resolve();
+        await rootDisposal;
+
+        assertEqual(run.deps.reportDefect.getDefectsSnapshot(), []);
+      } finally {
+        continueDisposal.resolve();
+        claimLease.release();
+        await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+        await rootDisposal;
+      }
+    });
+
+    it("claiming after registry disposal is a programmer error", async () => {
+      await using run = testCreateRun();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertInstanceOf(result.error.reason.defect, Error);
+      assertEqual(
+        result.error.reason.defect.message,
+        "Cannot use a disposed object.",
+      );
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("claiming after root Run disposal is a programmer error", async () => {
+      const ownerRun = testCreateRun();
+      const sharedResourceByKeyWithClaims = await ownerRun.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      await ownerRun[Symbol.asyncDispose]();
+      await using callerRun = testCreateRun();
+
+      const result = await callerRun.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertInstanceOf(result.error.reason.defect, Error);
+      assertEqual(
+        result.error.reason.defect.message,
+        "Cannot use a disposed object.",
+      );
+      assertSame(await callerRun.deps.reportDefect.next(), result.error);
+    });
+  });
+
+  describe("leak detection", () => {
+    it("warns when an undisposed claims registry is garbage-collected", async () => {
+      await using run = testCreateRun();
+
+      await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({
+          name: "SharedResourceByKeyWithClaims",
+        }),
+        1,
+      );
+
+      run.deps.leakDetector.collect();
+
+      assertTrue(
+        run.deps.console
+          .getEntriesSnapshot()
+          .some(
+            (entry) =>
+              entry.method === "warn" &&
+              entry.args.includes(
+                "SharedResourceByKeyWithClaims was garbage-collected without cleanup. Tracked at:",
+              ),
+          ),
+      );
+    });
+
+    it("warns when a leaked claim lease is garbage-collected", async () => {
+      await using run = testCreateRun();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+
+      await run.ok(sharedResourceByKeyWithClaims.claim("claim", ["resource"]));
+
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        1,
+      );
+
+      run.deps.leakDetector.collect();
+
+      assertTrue(
+        run.deps.console
+          .getEntriesSnapshot()
+          .some(
+            (entry) =>
+              entry.method === "warn" &&
+              entry.args.includes(
+                "ClaimLease was garbage-collected without cleanup. Tracked at:",
+              ),
+          ),
+      );
+    });
+
+    it("claim lease release untracks it", async () => {
+      await using run = testCreateRun();
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      const claimLease = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        1,
+      );
+
+      claimLease.release();
+
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        0,
+      );
+    });
+
+    it("registry disposal untracks held claim leases", async () => {
+      await using run = testCreateRun();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+      await run.ok(sharedResourceByKeyWithClaims.claim("claim", ["resource"]));
+
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        1,
+      );
+
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      assertEqual(
+        run.deps.leakDetector.getTrackedCount({ name: "ClaimLease" }),
+        0,
+      );
+      assertEqual(run.deps.console.getEntriesSnapshot(), []);
+    });
+  });
+
+  describe("defects", () => {
+    it("throwing create Task panics the owner Run", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("create failed");
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims((_key: string) => () => {
+          throw defect;
+        }),
+      );
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing resource lookup panics the owner Run", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("resource lookup failed");
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            resourceLookup: (_key): string => {
+              throw defect;
+            },
+          },
+        ),
+      );
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+
+    it("throwing claim lookup panics the owner Run", async () => {
+      await using run = testCreateRun();
+      const defect = new Error("claim lookup failed");
+
+      await using sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+          {
+            claimLookup: (_claim): string => {
+              throw defect;
+            },
+          },
+        ),
+      );
+
+      const result = await run.abortable(
+        sharedResourceByKeyWithClaims.claim("claim", ["resource"]),
+      );
+
+      assertErr(result);
+      assertType(AbortError, result.error);
+      assertSame(result.error.reason.type, "PanicAbortReason");
+      assertSame(result.error.reason.defect, defect);
+      assertSame(await run.deps.reportDefect.next(), result.error);
+    });
+  });
+
+  describe("snapshot", () => {
+    it("snapshot exposes pair retain counts and keyed resource states", async () => {
+      await using run = testCreateRun();
+
+      const sharedResourceByKeyWithClaims = await run.ok(
+        createSharedResourceByKeyWithClaims(
+          (_key: string) => () => ok({ [Symbol.dispose]: constVoid }),
+        ),
+      );
+
+      assertEqual(sharedResourceByKeyWithClaims.snapshot(), {
+        claimLeaseCount: 0,
+        retainCountsByResourceKeyByClaim: new Map(),
+        resourcesByKey: new Map(),
+      });
+
+      const first = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a", "b"]),
+      );
+      const second = await run.ok(
+        sharedResourceByKeyWithClaims.claim("claim", ["a"]),
+      );
+      const other = await run.ok(
+        sharedResourceByKeyWithClaims.claim("other", ["a"]),
+      );
+
+      const snapshot = sharedResourceByKeyWithClaims.snapshot();
+      assertEqual(snapshot, {
+        claimLeaseCount: 3,
+        retainCountsByResourceKeyByClaim: new Map([
+          [
+            "claim",
+            new Map([
+              ["a", 2],
+              ["b", 1],
+            ]),
+          ],
+          ["other", new Map([["a", 1]])],
+        ]),
+        resourcesByKey: new Map([
+          [
+            "a",
+            {
+              isIdle: false,
+              leaseCount: 3,
+              hasResource: true,
+              idleDisposePending: false,
+              mutex: idleMutexSnapshot,
+            },
+          ],
+          [
+            "b",
+            {
+              isIdle: false,
+              leaseCount: 1,
+              hasResource: true,
+              idleDisposePending: false,
+              mutex: idleMutexSnapshot,
+            },
+          ],
+        ]),
+      });
+
+      assertTrue(second.release());
+      assertEqual(
+        snapshot.retainCountsByResourceKeyByClaim.get("claim")?.get("a"),
+        2,
+      );
+      assertEqual(
+        sharedResourceByKeyWithClaims
+          .snapshot()
+          .retainCountsByResourceKeyByClaim.get("claim")
+          ?.get("a"),
+        1,
+      );
+
+      await sharedResourceByKeyWithClaims[Symbol.asyncDispose]();
+
+      assertEqual(sharedResourceByKeyWithClaims.snapshot(), {
+        claimLeaseCount: 0,
+        retainCountsByResourceKeyByClaim: new Map(),
+        resourcesByKey: new Map(),
+      });
+      assertFalse(first.release());
+      assertFalse(second.release());
+      assertFalse(other.release());
+    });
+  });
+});