@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Resource.js

@@ -55,384 +55,633 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { assert, assertNotAborted } from "./Assert.js";
+import { assert, assertNonNullable } from "./Assert.js";
 import { identity } from "./Function.js";
 import { createLookupMap, createLookupSet, } from "./Lookup.js";
-import { createRefCount, createRefCountByKey, } from "./RefCount.js";
-import { createRelation } from "./Relation.js";
+import { createRefCountedRelation } from "./Relation.js";
 import { ok } from "./Result.js";
-import { createMutex, createMutexByKey, sleep, unabortable, } from "./Task.js";
+import { createMutex, createMutexByKey, sleep, } from "./Task.js";
 import {} from "./Time.js";
-import { NonNegativeInt, zeroNonNegativeInt } from "./Type.js";
-export { createRefCount, createRefCountByKey, } from "./RefCount.js";
-/** Creates {@link ResourceRef}. */
-export const createResourceRef = (create) => unabortable(async (run) => {
-    const env_1 = { stack: [], error: void 0, hasError: false };
-    try {
-        const resourceRefRun = run.create();
-        const disposer = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
-        disposer.use(resourceRefRun);
-        const initial = await resourceRefRun(create);
-        if (!initial.ok)
-            return initial;
-        let current = createOwnedResource(initial.value);
-        const mutex = disposer.use(createMutex());
-        disposer.defer(() => current.stack.disposeAsync());
-        // Register as the last so disposal aborts further calls first.
-        // Repeated registration is safe because disposal is idempotent.
-        disposer.use(resourceRefRun);
-        const disposables = disposer.move();
-        return ok({
-            get: () => resourceRefRun(mutex.withLock(() => ok(current.resource))),
-            set: (create) => unabortable(() => resourceRefRun(mutex.withLock(async (run) => {
-                await current.stack.disposeAsync();
-                const next = await run(create);
-                if (!next.ok)
-                    return next;
-                current = createOwnedResource(next.value);
-                return ok();
-            }))),
-            [Symbol.asyncDispose]: () => disposables.disposeAsync(),
+import { NonNegativeInt } from "./Type.js";
+import {} from "./Types.js";
+/**
+ * Creates {@link SharedResource}.
+ *
+ * The `create` Task must not fail. Creation establishes shared resource state
+ * and may serve multiple concurrent acquirers, so a recoverable failure does
+ * not belong to one lease. Handle recoverable failures inside `create`: retry
+ * until creation succeeds (for example with a Schedule), or return a resource
+ * whose state models connection and reconnection failures.
+ *
+ * A successfully returned resource must be live and independently owned. The
+ * `create` Task must not bind its disposal to that Task's {@link DisposableRun}
+ * with `defer`.
+ *
+ * Create resources with {@link disposable} when their shape supports it. Its
+ * disposal guard makes calls through a lease fail eagerly after resource
+ * disposal instead of operating on disposed state.
+ *
+ * The `create` Task runs while acquisition is locked and must not directly or
+ * transitively acquire from the same SharedResource. The lock is non-reentrant,
+ * so doing so deadlocks.
+ *
+ * Internal work runs on a Run created from the Run that executes this Task, so
+ * dependencies are captured at creation time. Deps provided to later acquire
+ * calls do not change what `create` observes.
+ *
+ * Lifecycle callbacks must not throw. A throwing
+ * {@link SharedResourceOptions.onDisposed | onDisposed} is a defect that panics
+ * the Run tree.
+ */
+export const createSharedResource = (create, { idleDisposeAfter, onDisposed } = {}) => (run) => {
+    const sharedResourceRun = run.create();
+    const { leakDetector } = run.deps;
+    let current;
+    let idleDisposeFiber;
+    const heldLeases = new Set();
+    const mutex = createMutex();
+    const sharedResourceHandle = {};
+    // Idle disposal calls this under the mutex. Owner finalization calls it only
+    // after child Tasks, including idle disposal, settle, so calls cannot
+    // overlap.
+    const disposeCurrent = async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (!current)
+                return;
+            const resourceDisposer = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+            if (onDisposed)
+                resourceDisposer.defer(onDisposed);
+            resourceDisposer.use(current);
+            current = undefined;
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    };
+    /** Disposes the current resource unless a new lease arrived meanwhile. */
+    const disposeCurrentWhenUnused = mutex.withLock(async () => {
+        // For delayed disposal, this is safe to clear unconditionally: a newer
+        // idle-dispose fiber would require a release after a completed acquire,
+        // but FIFO orders that acquire behind this task. Therefore this is the
+        // current fiber or already undefined, never newer. An acquire that got
+        // the mutex before this task queued aborted this fiber while it was
+        // still sleeping. If this fiber was already queued on the mutex, abort
+        // removes its semaphore waiter before grant, so this body cannot run
+        // stale.
+        idleDisposeFiber = undefined;
+        if (heldLeases.size === 0)
+            await disposeCurrent();
+        return ok();
+    });
+    // Execution order is LIFO: clear idle state, drain leases, dispose current,
+    // then untrack the owner. Separate entries preserve later cleanup when an
+    // earlier finalizer defects.
+    sharedResourceRun.defer(() => {
+        leakDetector.untrack(sharedResourceHandle);
+    });
+    sharedResourceRun.defer(disposeCurrent);
+    sharedResourceRun.defer(() => {
+        for (const handle of heldLeases)
+            leakDetector.untrack(handle);
+        heldLeases.clear();
+    });
+    sharedResourceRun.defer(() => {
+        idleDisposeFiber = undefined;
+    });
+    const createLease = (created) => {
+        const handle = {};
+        heldLeases.add(handle);
+        const release = () => {
+            if (!heldLeases.delete(handle))
+                return false;
+            leakDetector.untrack(handle);
+            if (heldLeases.size > 0)
+                return true;
+            // During shutdown, disposal owns the resource; release is accounting
+            // only.
+            if (sharedResourceRun.getState().type !== "Running")
+                return true;
+            if (idleDisposeAfter) {
+                idleDisposeFiber = sharedResourceRun.abortable(async (run) => {
+                    await run.ok(sleep(idleDisposeAfter));
+                    return run(disposeCurrentWhenUnused);
+                });
+            }
+            else {
+                // Immediate disposal is not retained for acquire to cancel. Starting
+                // it synchronously queues or acquires the mutex before release
+                // returns. The mutex orders it against acquires, and disposal
+                // rechecks the lease count under the lock.
+                void sharedResourceRun.abortable(disposeCurrentWhenUnused);
+            }
+            return true;
+        };
+        const lease = {
+            resource: current,
+            created,
+            release,
+            [Symbol.dispose]: release,
+        };
+        leakDetector.track(lease, { name: "Lease", isLeaked: () => heldLeases.has(handle) }, handle);
+        return lease;
+    };
+    const sharedResource = {
+        // Run on the resource-owned tree so caller abort cannot interrupt acquire
+        // and later acquire deps cannot replace the owner's captured deps.
+        acquire: () => sharedResourceRun(mutex.withLock(async (run) => {
+            if (idleDisposeFiber) {
+                idleDisposeFiber.abort();
+                idleDisposeFiber = undefined;
+            }
+            const created = current === undefined;
+            current ??= await run.ok(create);
+            // Publish ownership before the checkpoint so owner finalization
+            // disposes a resource returned after shutdown started.
+            run.signal.throwIfAborted();
+            return ok(createLease(created));
+        })),
+        acquireCurrent: () => sharedResourceRun(
+        // This body must stay synchronous so owner disposal cannot start
+        // between checking current and transferring its lease.
+        mutex.withLock(() => {
+            if (!current)
+                return ok(undefined);
+            if (idleDisposeFiber) {
+                idleDisposeFiber.abort();
+                idleDisposeFiber = undefined;
+            }
+            return ok(createLease(false));
+        })),
+        use: (callback) => async (run) => {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const lease = __addDisposableResource(env_2, await run.ok(sharedResource.acquire), false);
+                return await run(callback(lease.resource, lease.created));
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
+            }
+        },
+        snapshot: () => {
+            const mutexSnapshot = mutex.snapshot();
+            return {
+                isIdle: heldLeases.size === 0 &&
+                    !current &&
+                    !idleDisposeFiber &&
+                    mutexSnapshot.isIdle,
+                leaseCount: NonNegativeInt.orThrow(heldLeases.size),
+                hasResource: current !== undefined,
+                idleDisposePending: idleDisposeFiber !== undefined,
+                mutex: mutexSnapshot,
+            };
+        },
+        [Symbol.asyncDispose]: () => sharedResourceRun[Symbol.asyncDispose](),
+    };
+    leakDetector.track(sharedResource, {
+        name: "SharedResource",
+        isLeaked: () => sharedResourceRun.getState().type === "Running",
+    }, sharedResourceHandle);
+    return ok(sharedResource);
+};
+export function createSharedResourceByKey(create, { idleDisposeAfter, lookup = identity, onDisposed, } = {}) {
+    return (run) => {
+        const sharedResourceByKeyRun = run.create();
+        const { leakDetector } = run.deps;
+        const sharedResourcesByKey = createLookupMap({
+            lookup,
         });
-    }
-    catch (e_1) {
-        env_1.error = e_1;
-        env_1.hasError = true;
-    }
-    finally {
-        const result_1 = __disposeResources(env_1);
-        if (result_1)
-            await result_1;
-    }
-});
-/** Creates {@link SharedResource}. */
-export const createSharedResource = (create, { idleDisposeAfter, onDisposed } = {}) => unabortable(async (run) => {
-    const env_2 = { stack: [], error: void 0, hasError: false };
-    try {
-        const sharedResourceRun = run.create();
-        let current;
-        let idleDisposeFiber;
-        const disposer = __addDisposableResource(env_2, new AsyncDisposableStack(), true);
-        const refCount = disposer.use(createRefCount());
-        const mutex = disposer.use(createMutex());
-        const disposeCurrent = async () => {
+        const mutexByKey = createMutexByKey({ lookup });
+        const disposer = new AsyncDisposableStack();
+        const sharedResourceByKeyHandle = {};
+        const removeKey = (key, sharedResource) => {
+            // Callers must ensure no same-key operation can still use sharedResource.
+            // onDisposed checks that the key mutex is idle; acquireCurrent holds the
+            // key mutex after observing that the inner resource is empty.
+            // Explicit registry disposal owns every registered SharedResource. Keep
+            // the key visible until keyDisposer captures it.
+            if (disposer.disposed)
+                return;
+            sharedResourcesByKey.delete(key);
+            // During root shutdown, the inner Run is already being disposed.
+            if (sharedResourceByKeyRun.getState().type !== "Running")
+                return;
+            void sharedResourceByKeyRun.abortable(async () => {
+                await sharedResource[Symbol.asyncDispose]();
+                return ok();
+            });
+        };
+        // Disposed in reverse order: the Run first, so pending acquires and removed
+        // SharedResource disposals are aborted and awaited before the registered
+        // SharedResources are disposed.
+        disposer.defer(async () => {
             const env_3 = { stack: [], error: void 0, hasError: false };
             try {
-                if (!current)
-                    return;
-                const disposer = __addDisposableResource(env_3, new AsyncDisposableStack(), true);
-                if (onDisposed)
-                    disposer.defer(onDisposed);
-                disposer.use(current.stack);
-                current = undefined;
+                const keyDisposer = __addDisposableResource(env_3, new AsyncDisposableStack(), true);
+                for (const sharedResource of sharedResourcesByKey.values())
+                    keyDisposer.use(sharedResource);
+                sharedResourcesByKey.clear();
             }
             catch (e_3) {
                 env_3.error = e_3;
                 env_3.hasError = true;
             }
             finally {
-                const result_3 = __disposeResources(env_3);
-                if (result_3)
-                    await result_3;
+                const result_2 = __disposeResources(env_3);
+                if (result_2)
+                    await result_2;
             }
+        });
+        disposer.use(sharedResourceByKeyRun);
+        sharedResourceByKeyRun.defer(() => {
+            leakDetector.untrack(sharedResourceByKeyHandle);
+        });
+        const releaseLeaseIfAborted = (signal, lease) => {
+            if (!signal.aborted)
+                return;
+            lease?.release();
+            signal.throwIfAborted();
         };
-        disposer.defer(disposeCurrent);
-        // Register as the last so disposal aborts further calls first.
-        disposer.use(sharedResourceRun);
-        const disposables = disposer.move();
-        return ok({
-            acquire: unabortable(() => sharedResourceRun(mutex.withLock(async (run) => {
-                if (idleDisposeFiber) {
-                    idleDisposeFiber.abort();
-                    idleDisposeFiber = undefined;
+        const sharedResourceByKey = {
+            acquire: (key) => () => sharedResourceByKeyRun(mutexByKey.withLock(key, async (run) => {
+                // The outer key mutex spans registration and the inner acquire so
+                // key removal cannot race resource creation or lease transfer.
+                let sharedResource = sharedResourcesByKey.get(key);
+                if (!sharedResource) {
+                    sharedResource = await run.ok(createSharedResource(create(key), {
+                        idleDisposeAfter,
+                        onDisposed: () => {
+                            assertNonNullable(sharedResource, "SharedResource must be assigned before its resource is disposed.");
+                            if (mutexByKey.isIdle(key))
+                                removeKey(key, sharedResource);
+                            onDisposed?.(key);
+                        },
+                    }));
+                    sharedResourcesByKey.set(key, sharedResource);
                 }
-                if (!current) {
-                    const resource = await run(create);
-                    if (!resource.ok)
-                        return resource;
-                    current = createOwnedResource(resource.value);
+                const lease = await run.ok(sharedResource.acquire);
+                releaseLeaseIfAborted(run.signal, lease);
+                return ok(lease);
+            })),
+            acquireCurrent: (key) => () => sharedResourceByKeyRun(mutexByKey.withLock(key, async (run) => {
+                const sharedResource = sharedResourcesByKey.get(key);
+                if (!sharedResource)
+                    return ok(undefined);
+                const lease = await run.ok(sharedResource.acquireCurrent);
+                releaseLeaseIfAborted(run.signal, lease);
+                if (!lease)
+                    removeKey(key, sharedResource);
+                return ok(lease);
+            })),
+            use: (key, callback) => async (run) => {
+                const env_4 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const lease = __addDisposableResource(env_4, await run.ok(sharedResourceByKey.acquire(key)), false);
+                    return await run(callback(lease.resource, lease.created));
                 }
-                refCount.increment();
-                return ok(current.resource);
-            }))),
-            release: unabortable(() => sharedResourceRun(mutex.withLock(async () => {
-                if (refCount.decrement() > 0)
-                    return ok();
-                if (!idleDisposeAfter) {
-                    await disposeCurrent();
-                    return ok();
+                catch (e_4) {
+                    env_4.error = e_4;
+                    env_4.hasError = true;
                 }
-                idleDisposeFiber = sharedResourceRun(async (run) => {
-                    const slept = await run(sleep(idleDisposeAfter));
-                    if (!slept.ok)
-                        return slept;
-                    return run(mutex.withLock(async () => {
-                        idleDisposeFiber = undefined;
-                        await disposeCurrent();
-                        return ok();
-                    }));
-                });
-                return ok();
-            }))),
-            getCount: () => sharedResourceRun(mutex.withLock(() => ok(refCount.getCount()))),
-            get: () => current?.resource,
-            snapshot: () => ({
-                isIdle: refCount.getCount() === 0 && !current && !idleDisposeFiber,
-                mutex: mutex.snapshot(),
-            }),
-            [Symbol.asyncDispose]: () => disposables.disposeAsync(),
-        });
-    }
-    catch (e_2) {
-        env_2.error = e_2;
-        env_2.hasError = true;
-    }
-    finally {
-        const result_2 = __disposeResources(env_2);
-        if (result_2)
-            await result_2;
-    }
-});
-export function createSharedResourceByKey(create, { idleDisposeAfter, lookup = identity, onDisposed, } = {}) {
-    return unabortable(async (run) => {
-        const env_4 = { stack: [], error: void 0, hasError: false };
-        try {
-            const sharedResourceByKeyRun = run.create();
-            const sharedResourcesByKey = createLookupMap({
-                lookup,
-            });
-            const disposer = __addDisposableResource(env_4, new AsyncDisposableStack(), true);
-            const mutexByKey = disposer.use(createMutexByKey({ lookup }));
-            disposer.defer(async () => {
+                finally {
+                    __disposeResources(env_4);
+                }
+            },
+            forEachCurrent: (callback) => async (run) => {
                 const env_5 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const disposer = __addDisposableResource(env_5, new AsyncDisposableStack(), true);
-                    for (const resource of sharedResourcesByKey.values())
-                        disposer.use(resource);
-                    await disposer.disposeAsync();
-                    sharedResourcesByKey.clear();
+                    const leaseDisposer = __addDisposableResource(env_5, new DisposableStack(), false);
+                    const leasesByKey = [];
+                    for (const [key] of [...sharedResourcesByKey]) {
+                        const lease = await run.ok(sharedResourceByKey.acquireCurrent(key));
+                        if (lease)
+                            leasesByKey.push([leaseDisposer.use(lease), key]);
+                        run.signal.throwIfAborted();
+                    }
+                    for (const [lease, key] of leasesByKey)
+                        callback(lease.resource, key);
+                    return ok();
                 }
                 catch (e_5) {
                     env_5.error = e_5;
                     env_5.hasError = true;
                 }
                 finally {
-                    const result_5 = __disposeResources(env_5);
-                    if (result_5)
-                        await result_5;
+                    __disposeResources(env_5);
                 }
-            });
-            // Register as the last so disposal aborts further calls first.
-            disposer.use(sharedResourceByKeyRun);
-            const disposables = disposer.move();
-            return ok({
-                acquire: (key) => unabortable(() => sharedResourceByKeyRun(mutexByKey.withLock(key, async (run) => {
-                    let sharedResource = sharedResourcesByKey.get(key);
-                    if (!sharedResource) {
-                        const sharedResourceResult = await run(createSharedResource(create(key), {
-                            idleDisposeAfter,
-                            onDisposed: () => {
-                                onDisposed?.(key);
-                                void sharedResourceByKeyRun(mutexByKey.withLock(key, async () => {
-                                    if (sharedResource &&
-                                        sharedResourcesByKey.get(key) === sharedResource &&
-                                        sharedResource.snapshot().isIdle) {
-                                        sharedResourcesByKey.delete(key);
-                                        await sharedResource[Symbol.asyncDispose]();
-                                    }
-                                    return ok();
-                                }));
-                            },
-                        }));
-                        assertNotAborted(sharedResourceResult);
-                        sharedResource = sharedResourceResult.value;
-                        sharedResourcesByKey.set(key, sharedResource);
+            },
+            snapshot: () => {
+                const resourcesByKey = new Map();
+                for (const [key, sharedResource] of sharedResourcesByKey)
+                    resourcesByKey.set(key, sharedResource.snapshot());
+                return { resourcesByKey };
+            },
+            [Symbol.asyncDispose]: () => disposer.disposeAsync(),
+        };
+        leakDetector.track(sharedResourceByKey, {
+            name: "SharedResourceByKey",
+            isLeaked: () => sharedResourceByKeyRun.getState().type === "Running",
+        }, sharedResourceByKeyHandle);
+        return ok(sharedResourceByKey);
+    };
+}
+/**
+ * Creates {@link SharedResourceByKeyWithClaims}.
+ *
+ * The `create` callback is called with a resource key when that resource must
+ * be created. The returned Task must not fail. Its dependencies are captured
+ * when the registry is created; later claim calls do not require or replace
+ * them.
+ *
+ * Transition callbacks represent semantic claim-resource pair changes and are
+ * not called when this registry or its Run tree drains claims during disposal.
+ * They must not throw. If a first-claim callback defects after earlier
+ * callbacks in the same claim completed, matching last-claim callbacks
+ * compensate those completed transitions in reverse order before cleanup.
+ * Relation reads during compensation still include the failed claim. Callback
+ * defects panic the owner Run after claim metadata and resource ownership are
+ * cleaned up.
+ *
+ * Transition callbacks may synchronously read relation state. They must not
+ * call `claim`, release a {@link ClaimLease} owned by this registry, or dispose
+ * this registry.
+ *
+ * Transition callbacks do not report actual resource disposal. Disposal can
+ * happen later when `idleDisposeAfter` is configured.
+ */
+export const createSharedResourceByKeyWithClaims = (create, { idleDisposeAfter, resourceLookup = identity, claimLookup = identity, onFirstClaimAdded, onLastClaimRemoved, } = {}) => async (run) => {
+    const env_6 = { stack: [], error: void 0, hasError: false };
+    try {
+        const sharedResourceByKeyWithClaimsRun = run.create();
+        const { leakDetector } = run.deps;
+        const claimResourceRelation = createRefCountedRelation({
+            lookupA: claimLookup,
+            lookupB: resourceLookup,
+        });
+        // This map and the relation's resource-key index use the same lookup and
+        // are inserted and removed together, so they keep the same canonical keys.
+        const resourcesByKey = createLookupMap({
+            lookup: resourceLookup,
+        });
+        const heldClaimLeases = new Set();
+        const sharedResourceByKeyWithClaimsHandle = {};
+        const notifyLastClaimRemoved = (claim, resource, resourceKey) => {
+            try {
+                onLastClaimRemoved?.(claim, resource, resourceKey);
+            }
+            catch (defect) {
+                sharedResourceByKeyWithClaimsRun.panic(defect);
+            }
+        };
+        const disposer = __addDisposableResource(env_6, new AsyncDisposableStack(), true);
+        // Explicit disposal stops claim operations and runs their finalizers before
+        // disposing the keyed registry. The nested stack is empty if keyed-registry
+        // creation fails. Both internal Runs attach to the root, whose disposal
+        // awaits them independently of this explicit-disposal stack.
+        const sharedResourceByKeyDisposer = disposer.use(new AsyncDisposableStack());
+        disposer.use(sharedResourceByKeyWithClaimsRun);
+        const releaseClaimLease = (heldClaimLease, notifyTransition = true) => {
+            const env_7 = { stack: [], error: void 0, hasError: false };
+            try {
+                if (!heldClaimLeases.delete(heldClaimLease))
+                    return false;
+                leakDetector.untrack(heldClaimLease);
+                const _resourceLeases = __addDisposableResource(env_7, heldClaimLease.resourceLeases, false);
+                for (const resourceKey of heldClaimLease.resourceKeys) {
+                    const decremented = claimResourceRelation.decrement(heldClaimLease.claim, resourceKey);
+                    if (decremented.count > 0)
+                        continue;
+                    const resource = resourcesByKey.get(decremented.b);
+                    assertNonNullable(resource, "Resource must exist while its claim-resource pair is retained.");
+                    if (notifyTransition) {
+                        notifyLastClaimRemoved(decremented.a, resource, decremented.b);
                     }
-                    return run(sharedResource.acquire);
-                }))),
-                release: (key) => unabortable(() => sharedResourceByKeyRun(mutexByKey.withLock(key, async () => {
-                    const sharedResource = sharedResourcesByKey.get(key);
-                    assert(sharedResource, "Release must not be called more times than acquire.");
-                    return sharedResourceByKeyRun(sharedResource.release);
-                }))),
-                getCount: (key) => () => sharedResourceByKeyRun(mutexByKey.withLock(key, async (run) => {
-                    const sharedResource = sharedResourcesByKey.get(key);
-                    if (!sharedResource)
-                        return ok(zeroNonNegativeInt);
-                    return run(sharedResource.getCount);
-                })),
-                get: (key) => sharedResourcesByKey.get(key)?.get(),
-                snapshot: () => {
-                    const resourcesByKey = new Map();
-                    const mutexSnapshotsByKey = new Map();
-                    for (const [key, sharedResource] of sharedResourcesByKey.entries()) {
-                        const resource = sharedResource.get();
-                        if (!resource)
-                            continue;
-                        resourcesByKey.set(key, resource);
-                        mutexSnapshotsByKey.set(key, mutexByKey.snapshot(key));
+                    if (!claimResourceRelation.hasB(decremented.b)) {
+                        // Delete before _resourceLeases disposes at function exit. While this
+                        // entry exists, its leases pin one resource generation.
+                        resourcesByKey.delete(decremented.b);
                     }
-                    return {
-                        resourcesByKey,
-                        mutexByKey: mutexSnapshotsByKey,
-                    };
-                },
-                [Symbol.asyncDispose]: () => disposables.disposeAsync(),
-            });
-        }
-        catch (e_4) {
-            env_4.error = e_4;
-            env_4.hasError = true;
-        }
-        finally {
-            const result_4 = __disposeResources(env_4);
-            if (result_4)
-                await result_4;
-        }
-    });
-}
-export function createSharedResourceByKeyWithClaims(create, { idleDisposeAfter, resourceLookup = identity, claimLookup = identity, onFirstClaimAdded, onLastClaimRemoved, } = {}) {
-    return unabortable(async (run) => {
-        const env_6 = { stack: [], error: void 0, hasError: false };
-        try {
-            const sharedResourceClaimsRun = run.create();
-            const disposer = __addDisposableResource(env_6, new AsyncDisposableStack(), true);
-            const keyByClaim = createRelation({
-                lookupA: claimLookup,
-                lookupB: resourceLookup,
-            });
-            const pairRefCountsByClaim = disposer.adopt(createLookupMap({ lookup: claimLookup }), (pairRefCountsByClaim) => {
-                const env_7 = { stack: [], error: void 0, hasError: false };
-                try {
-                    const disposer = __addDisposableResource(env_7, new DisposableStack(), false);
+                }
+                return true;
+            }
+            catch (e_7) {
+                env_7.error = e_7;
+                env_7.hasError = true;
+            }
+            finally {
+                __disposeResources(env_7);
+            }
+        };
+        const drainClaimLeases = () => {
+            const env_8 = { stack: [], error: void 0, hasError: false };
+            try {
+                const disposer = __addDisposableResource(env_8, new DisposableStack(), false);
+                disposer.defer(() => {
+                    claimResourceRelation.clear();
+                    resourcesByKey.clear();
+                });
+                for (const heldClaimLease of heldClaimLeases) {
                     disposer.defer(() => {
-                        pairRefCountsByClaim.clear();
+                        releaseClaimLease(heldClaimLease, false);
                     });
-                    for (const pairRefCountByKey of pairRefCountsByClaim.values()) {
-                        disposer.use(pairRefCountByKey);
-                    }
-                }
-                catch (e_7) {
-                    env_7.error = e_7;
-                    env_7.hasError = true;
-                }
-                finally {
-                    __disposeResources(env_7);
                 }
-            });
-            const mutexByKey = disposer.use(createMutexByKey({ lookup: resourceLookup }));
-            disposer.defer(() => {
-                keyByClaim.clear();
-            });
-            const sharedResourcesByKeyResult = await sharedResourceClaimsRun(createSharedResourceByKey(create, {
-                idleDisposeAfter,
-                lookup: resourceLookup,
-            }));
-            assertNotAborted(sharedResourcesByKeyResult);
-            const sharedResourcesByKey = disposer.use(sharedResourcesByKeyResult.value);
-            // Register as the last so disposal aborts further calls first.
-            disposer.use(sharedResourceClaimsRun);
-            /** Asserts that one call does not contain the same logical key twice. */
-            const assertNoDuplicateResourceKeys = (resourceKeys) => {
-                assert(createLookupSet({
-                    lookup: resourceLookup,
-                    values: resourceKeys,
-                }).size === resourceKeys.length, "resourceKeys must not contain lookup duplicates.");
-            };
-            const disposables = disposer.move();
-            return ok({
-                addClaim: (claim, resourceKeys) => unabortable(() => sharedResourceClaimsRun(async (run) => {
-                    assertNoDuplicateResourceKeys(resourceKeys);
-                    for (const resourceKey of resourceKeys) {
-                        const added = await run(mutexByKey.withLock(resourceKey, async (run) => {
-                            let pairRefCountByKey = pairRefCountsByClaim.get(claim);
-                            if (!pairRefCountByKey) {
-                                pairRefCountByKey = createRefCountByKey({
-                                    lookup: resourceLookup,
-                                });
-                                pairRefCountsByClaim.set(claim, pairRefCountByKey);
-                            }
-                            if (pairRefCountByKey.has(resourceKey)) {
-                                pairRefCountByKey.increment(resourceKey);
-                                return ok();
-                            }
-                            const hasClaimsForKey = keyByClaim.hasB(resourceKey);
-                            let firstResource;
-                            if (!hasClaimsForKey) {
-                                const resourceResult = await run(sharedResourcesByKey.acquire(resourceKey));
-                                assertNotAborted(resourceResult);
-                                firstResource = resourceResult.value;
-                            }
-                            assert(keyByClaim.add(claim, resourceKey), "Claim-resource relation must be absent before first retain.");
-                            pairRefCountByKey.increment(resourceKey);
-                            if (firstResource) {
-                                onFirstClaimAdded?.(claim, firstResource, resourceKey);
-                            }
-                            return ok();
-                        }));
-                        assertNotAborted(added);
+            }
+            catch (e_8) {
+                env_8.error = e_8;
+                env_8.hasError = true;
+            }
+            finally {
+                __disposeResources(env_8);
+            }
+        };
+        sharedResourceByKeyWithClaimsRun.defer(() => {
+            leakDetector.untrack(sharedResourceByKeyWithClaimsHandle);
+        });
+        sharedResourceByKeyWithClaimsRun.defer(drainClaimLeases);
+        const sharedResourceByKey = sharedResourceByKeyDisposer.use(await sharedResourceByKeyWithClaimsRun.ok(createSharedResourceByKey(create, {
+            idleDisposeAfter,
+            lookup: resourceLookup,
+        })));
+        run.signal.throwIfAborted();
+        const disposables = disposer.move();
+        const acquireClaim = (claim, resourceKeys, project) => () => {
+            const resourceKeysSnapshot = [
+                resourceKeys[0],
+                ...resourceKeys.slice(1),
+            ];
+            return sharedResourceByKeyWithClaimsRun(async (run) => {
+                const env_9 = { stack: [], error: void 0, hasError: false };
+                try {
+                    assert(createLookupSet({
+                        lookup: resourceLookup,
+                        values: resourceKeysSnapshot,
+                    }).size === resourceKeysSnapshot.length, "resourceKeys must not contain lookup duplicates.");
+                    const resourceLeases = __addDisposableResource(env_9, new DisposableStack(), false);
+                    const [firstResourceKey, ...remainingResourceKeys] = resourceKeysSnapshot;
+                    // acquire releases a transferred lease before surfacing owner abort,
+                    // so a throwing await cannot leave ownership uncollected.
+                    const firstResourceLease = resourceLeases.use(await run.ok(sharedResourceByKey.acquire(firstResourceKey)));
+                    const resources = [
+                        [firstResourceLease.resource, firstResourceKey],
+                    ];
+                    const firstClaimTransitions = [];
+                    for (const resourceKey of remainingResourceKeys) {
+                        const resourceLease = resourceLeases.use(await run.ok(sharedResourceByKey.acquire(resourceKey)));
+                        resources.push([resourceLease.resource, resourceKey]);
                     }
-                    return ok();
-                })),
-                removeClaim: (claim, resourceKeys) => unabortable(() => sharedResourceClaimsRun(async (run) => {
-                    assertNoDuplicateResourceKeys(resourceKeys);
-                    for (const resourceKey of resourceKeys) {
-                        const removed = await run(mutexByKey.withLock(resourceKey, async (run) => {
-                            const pairRefCountByKey = pairRefCountsByClaim.get(claim);
-                            assert(pairRefCountByKey, "Claim-resource pair must not be removed more times than added.");
-                            if (pairRefCountByKey.decrement(resourceKey) > 0) {
-                                return ok();
-                            }
-                            if (pairRefCountByKey.keys().size === 0) {
-                                pairRefCountsByClaim.delete(claim);
-                                pairRefCountByKey[Symbol.dispose]();
-                            }
-                            assert(keyByClaim.remove(claim, resourceKey), "Claim-resource relation must exist while its ref count is positive.");
-                            if (keyByClaim.hasB(resourceKey)) {
-                                return ok();
+                    run.signal.throwIfAborted();
+                    for (const [resource, resourceKey] of resources) {
+                        const incremented = claimResourceRelation.increment(claim, resourceKey);
+                        resourcesByKey.getOrInsert(incremented.b, resource);
+                        if (incremented.count === 1) {
+                            firstClaimTransitions.push([
+                                incremented.a,
+                                resource,
+                                incremented.b,
+                            ]);
+                        }
+                    }
+                    const heldClaimLease = {
+                        claim,
+                        resourceKeys: resourceKeysSnapshot,
+                        resourceLeases: resourceLeases.move(),
+                    };
+                    heldClaimLeases.add(heldClaimLease);
+                    const release = () => releaseClaimLease(heldClaimLease);
+                    const claimLease = {
+                        release,
+                        [Symbol.dispose]: release,
+                    };
+                    leakDetector.track(claimLease, {
+                        name: "ClaimLease",
+                        isLeaked: () => heldClaimLeases.has(heldClaimLease),
+                    }, heldClaimLease);
+                    try {
+                        const env_10 = { stack: [], error: void 0, hasError: false };
+                        try {
+                            let succeeded = false;
+                            const compensations = __addDisposableResource(env_10, new DisposableStack(), false);
+                            for (const [claim, resource, resourceKey,] of firstClaimTransitions) {
+                                onFirstClaimAdded?.(claim, resource, resourceKey);
+                                compensations.defer(() => {
+                                    if (!succeeded) {
+                                        notifyLastClaimRemoved(claim, resource, resourceKey);
+                                    }
+                                });
                             }
-                            const resource = sharedResourcesByKey.get(resourceKey);
-                            assert(resource, "Resource must exist when the last claim is removed.");
-                            onLastClaimRemoved?.(claim, resource, resourceKey);
-                            const releaseResult = await run(sharedResourcesByKey.release(resourceKey));
-                            assertNotAborted(releaseResult);
-                            return ok();
-                        }));
-                        assertNotAborted(removed);
+                            succeeded = true;
+                        }
+                        catch (e_9) {
+                            env_10.error = e_9;
+                            env_10.hasError = true;
+                        }
+                        finally {
+                            __disposeResources(env_10);
+                        }
                     }
-                    return ok();
-                })),
-                getResource: (key) => sharedResourcesByKey.get(key),
-                getClaimsForResource: (key) => new Set(keyByClaim.iterateA(key)),
-                getResourceKeysForClaim: (claim) => new Set(keyByClaim.iterateB(claim)),
-                getResourcesForClaim: (claim) => {
-                    const resources = new Set();
-                    for (const key of keyByClaim.iterateB(claim)) {
-                        const resource = sharedResourcesByKey.get(key);
-                        assert(resource, "Resource must exist for every retained claim-resource relation.");
-                        resources.add(resource);
+                    catch (defect) {
+                        releaseClaimLease(heldClaimLease, false);
+                        throw defect;
                     }
-                    return resources;
-                },
-                [Symbol.asyncDispose]: () => disposables.disposeAsync(),
+                    return ok(project(claimLease, resources));
+                }
+                catch (e_10) {
+                    env_9.error = e_10;
+                    env_9.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_9);
+                }
             });
-        }
-        catch (e_6) {
-            env_6.error = e_6;
-            env_6.hasError = true;
-        }
-        finally {
-            const result_6 = __disposeResources(env_6);
-            if (result_6)
-                await result_6;
-        }
-    });
-}
-const createOwnedResource = (resource) => {
-    const stack = new AsyncDisposableStack();
-    stack.use(resource);
-    return { resource, stack };
+        };
+        const sharedResourceByKeyWithClaims = {
+            claim: (claim, resourceKeys) => acquireClaim(claim, resourceKeys, (claimLease) => claimLease),
+            use: (claim, resourceKeys, callback) => async (run) => {
+                const env_11 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const acquired = await run.ok(acquireClaim(claim, resourceKeys, (claimLease, resources) => ({
+                        claimLease,
+                        resources,
+                    })));
+                    const _claimLease = __addDisposableResource(env_11, acquired.claimLease, false);
+                    return await run(callback(acquired.resources));
+                }
+                catch (e_11) {
+                    env_11.error = e_11;
+                    env_11.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_11);
+                }
+            },
+            getClaimsForResource: (resourceKey) => new Set(claimResourceRelation.getAs(resourceKey)),
+            getResourceKeysForClaim: (claim) => new Set(claimResourceRelation.getBs(claim)),
+            forEachResourceForClaim: (claim, callback) => {
+                const resources = claimResourceRelation
+                    .getBs(claim)
+                    .map((resourceKey) => {
+                    const resource = resourcesByKey.get(resourceKey);
+                    assertNonNullable(resource, "Resource must exist for every active claim-resource relation.");
+                    return [resource, resourceKey];
+                });
+                // Releasing the final ClaimLease from a callback only schedules inner
+                // disposal: the mutex Task resumes after this synchronous frame, so all
+                // snapshotted resources remain live through the loop.
+                for (const [resource, resourceKey] of resources) {
+                    callback(resource, resourceKey);
+                }
+            },
+            snapshot: () => {
+                const retainCountsByResourceKeyByClaimSnapshot = new Map();
+                for (const [claim, resourceKey, count,] of claimResourceRelation.getEntries()) {
+                    retainCountsByResourceKeyByClaimSnapshot
+                        .getOrInsertComputed(claim, () => new Map())
+                        .set(resourceKey, count);
+                }
+                return {
+                    claimLeaseCount: NonNegativeInt.orThrow(heldClaimLeases.size),
+                    retainCountsByResourceKeyByClaim: retainCountsByResourceKeyByClaimSnapshot,
+                    resourcesByKey: sharedResourceByKey.snapshot().resourcesByKey,
+                };
+            },
+            [Symbol.asyncDispose]: () => disposables.disposeAsync(),
+        };
+        leakDetector.track(sharedResourceByKeyWithClaims, {
+            name: "SharedResourceByKeyWithClaims",
+            isLeaked: () => sharedResourceByKeyWithClaimsRun.getState().type === "Running",
+        }, sharedResourceByKeyWithClaimsHandle);
+        return ok(sharedResourceByKeyWithClaims);
+    }
+    catch (e_6) {
+        env_6.error = e_6;
+        env_6.hasError = true;
+    }
+    finally {
+        const result_3 = __disposeResources(env_6);
+        if (result_3)
+            await result_3;
+    }
 };
-// TODO: Make lifecycle callbacks exception-safe. `onDisposed`,
-// `onFirstClaimAdded`, and `onLastClaimRemoved` can currently leave resource
-// bookkeeping in a partially updated state if they throw.
+// TODO: Add a lease-based reloadable resource when a concrete use case needs
+// resource swapping. A ResourceRef-style get/set API is unsafe because set can
+// dispose a resource still held by a caller of get. Model resource generations
+// explicitly and distinguish two replacement policies, probably as separate
+// APIs rather than a boolean option:
+// - Overlapping: create and validate the replacement, publish it to new leases,
+//   then dispose the old generation after its existing leases drain. This
+//   supports zero-downtime reload and keeps the old generation when creation
+//   fails, but both generations temporarily exist.
+// - Exclusive: stop or queue new leases, drain and dispose the old generation,
+//   then create and publish the replacement. This guarantees at most one live
+//   resource, but introduces downtime and leaves no valid resource when creation
+//   fails unless the owner retries or recreates the old configuration.