@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Resource.d.ts

@@ -3,261 +3,696 @@
  *
  * @module
  */
-import { type Lookup, type LookupOption } from "./Lookup.js";
-import { type SemaphoreSnapshot, type Task } from "./Task.js";
-import { type Duration } from "./Time.js";
-import { NonNegativeInt } from "./Type.js";
-export { createRefCount, createRefCountByKey, type CreateRefCountByKeyOptions, type RefCount, type RefCountByKey, } from "./RefCount.js";
+import type { NonEmptyReadonlyArray } from "./Array.ts";
+import { type Lookup, type LookupOption } from "./Lookup.ts";
+import { type SemaphoreSnapshot, type Task } from "./Task.ts";
+import { type PositiveDuration } from "./Time.ts";
+import { NonNegativeInt } from "./Type.ts";
+import { type DistributiveOmit } from "./Types.ts";
 /**
  * Disposable resource.
  *
  * A resource is any object that implements {@link Disposable} or
  * {@link AsyncDisposable}.
  *
+ * Successfully returning an owned Resource transfers ownership of a live
+ * resource to the caller. Return a typed Result error for a recoverable
+ * creation failure; use `undefined` only when absence is a valid success. If
+ * creation fails, aborts, or defects, use {@link AsyncDisposableStack} to
+ * dispose partially created resources and return no Resource. Never represent
+ * failed creation with an already-disposed Resource.
+ *
  * Disposal must succeed. A disposer that throws indicates an unrecoverable
  * invariant violation, not a recoverable domain error, so resource lifecycle
- * APIs let that error propagate. Disposal failures shall surface at the app
- * boundary, where they are shown to the user and logged. The purpose of
- * resource helpers is to guarantee cleanup and prevent leaks.
+ * APIs let that error propagate as a defect. The purpose of resource helpers is
+ * to guarantee cleanup and prevent leaks.
  *
- * @see {@link ResourceRef}
- * @see {@link createResourceRef}
  * @see {@link SharedResource}
  * @see {@link createSharedResource}
- * @see {@link SharedResourceByKey}
- * @see {@link createSharedResourceByKey}
  */
 export type Resource = Disposable | AsyncDisposable;
 /**
  * Borrowed {@link Resource}.
  *
- * A borrowed resource is a {@link Resource} without disposal methods.
+ * A borrowed resource removes disposal methods from a {@link Resource}'s type.
+ * The runtime object is unchanged.
  *
  * Another abstraction owns the resource and controls its lifecycle. Exposing
- * disposal would break that ownership and allow callers to dispose a resource
- * they do not own.
+ * disposal in the type would break that ownership and allow callers to dispose
+ * a resource they do not own.
  */
-export type BorrowedResource<T extends Resource> = Omit<T, typeof Symbol.dispose | typeof Symbol.asyncDispose>;
+export type BorrowedResource<T extends Resource> = DistributiveOmit<T, typeof Symbol.dispose | typeof Symbol.asyncDispose>;
 /**
- * {@link Resource} reference.
+ * An owned lease on a shared {@link Resource}.
  *
- * A {@link MutexRef}-like reference for resources. `ResourceRef` controls the
- * resource lifecycle.
+ * A lease keeps the underlying resource alive. Release it with
+ * {@link Lease.release} or `using`; releasing the last lease starts the resource
+ * disposal path. Release is idempotent, so double release is a safe no-op.
  *
- * Callers get the current resource as {@link BorrowedResource} to ensure only
- * the `ResourceRef` can dispose it.
+ * Release is synchronous accounting and never waits for resource disposal.
+ * Disposal completion belongs to the owning {@link SharedResource}: it may be
+ * delayed by {@link SharedResourceOptions.idleDisposeAfter | idleDisposeAfter}
+ * and is awaited by the owner's async disposal.
  *
- * Setting a new resource first disposes the current one and then sets the next.
- * Calling abort on the returned Fiber does not roll that change back once it
- * has started. The create Task must not fail. If it could fail, the current
- * resource would be disposed without the next resource installed.
+ * Release does not revoke {@link Lease.resource | resource}; a released lease
+ * keeps a plain reference, and using it after the resource is disposed is a
+ * programmer error that nothing catches statically. Create resources with the
+ * {@link disposable} helper so use-after-dispose throws eagerly instead of
+ * operating on disposed state.
  */
-export interface ResourceRef<T extends Resource, D = unknown> extends AsyncDisposable {
-    /** Returns the current resource. */
-    readonly get: Task<BorrowedResource<T>, never, D>;
+export interface Lease<T extends Resource> extends Disposable {
+    /** The leased resource. */
+    readonly resource: BorrowedResource<T>;
+    /** Whether this acquisition created the leased resource generation. */
+    readonly created: boolean;
     /**
-     * Disposes the current resource and then creates and sets the next.
+     * Releases this lease.
      *
-     * Once started, this operation runs to completion even if the caller aborts
-     * its Fiber. Always await the result instead of treating abort as rollback.
+     * Returns whether this call released a still-held lease. Returns `false` if
+     * the lease was already released, drained by disposal of its owning
+     * {@link SharedResource}, or drained by disposal of the Run tree that owns
+     * it.
      */
-    readonly set: (create: Task<T, never, D>) => Task<void, never, D>;
+    readonly release: () => boolean;
 }
-/** Creates {@link ResourceRef}. */
-export declare const createResourceRef: <T extends Resource, D>(create: Task<T, never, D>) => Task<ResourceRef<T, D>, never, D>;
 /**
  * Shared {@link Resource}.
  *
- * Lazily acquires the underlying resource on the first
- * {@link SharedResource.acquire | acquire} call, shares it across callers, and
- * disposes it when the last caller {@link SharedResource.release | releases}
- * it.
+ * Lazily creates the underlying resource on the first
+ * {@link SharedResource.acquire | acquire} call, shares it across callers via
+ * {@link Lease}s, and disposes it when the last lease is released.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   all,
+ *   createRun,
+ *   createSharedResource,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * interface Connection extends Disposable {
+ *   readonly send: (message: string) => void;
+ * }
+ *
+ * let createdCount = 0;
+ * const createConnection: Task<Connection> = () => {
+ *   createdCount += 1;
+ *   return ok({
+ *     send: (_message) => {},
+ *     [Symbol.dispose]: () => {},
+ *   });
+ * };
+ *
+ * await using run = createRun();
+ * await using sharedConnection = await run.ok(
+ *   createSharedResource(createConnection, { idleDisposeAfter: "5s" }),
+ * );
+ *
+ * // Creating the owner is lazy; no connection is open yet.
+ * expect(createdCount).toBe(0);
+ *
+ * // `use` owns and releases a lease around each operation.
+ * const send = (message: string): Task<void> =>
+ *   sharedConnection.use((connection) => () => {
+ *     connection.send(message);
+ *     return ok();
+ *   });
+ *
+ * {
+ *   // An explicit lease can span several operations. Concurrent `use` calls
+ *   // share the connection kept alive by this lease.
+ *   using batchLease = await run.ok(sharedConnection.acquire);
+ *   batchLease.resource.send("first");
+ *   batchLease.resource.send("second");
+ *   await run.ok(all([send("hello"), send("world")], { concurrency: 2 }));
+ * }
+ *
+ * // Reacquiring during the idle delay reuses the same generation.
+ * using reusedLease = await run.ok(sharedConnection.acquire);
+ * expect(reusedLease.created).toBe(false);
+ * expect(createdCount).toBe(1);
+ * ```
+ *
+ * ## FAQ
+ *
+ * ### Why release a lease with `using`?
+ *
+ * `using` guarantees a {@link Lease} is released on every exit path: normal
+ * completion, a thrown error, and abort — abort surfaces as an exception in
+ * Task code, so stack unwinding runs disposers. Binding a lease to an ordinary
+ * `const` instead is a deliberate ownership transfer; the new owner must
+ * guarantee release.
  *
- * Calls to {@link SharedResource.release | release} must be balanced with
- * successful calls to {@link SharedResource.acquire | acquire}. Releasing more
- * times than acquired is a programmer error checked with {@link assert}.
+ * ### What happens when a lease leaks?
+ *
+ * Nothing in JavaScript enforces `using` or release; a lease that is never
+ * released compiles silently (see [MDN resource management
+ * pitfalls](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Resource_management#pitfalls);
+ * a lint rule may eventually close this gap:
+ * https://github.com/typescript-eslint/typescript-eslint/issues/8255). Encoding
+ * resource lifetime in the type system would not be bulletproof either: types
+ * can force a lifetime to exist, but a lifetime scoped too widely leaks just as
+ * silently. Evolu therefore stays JS-native — `using` in the language — and
+ * bounds the damage structurally. A leaked lease keeps the resource alive but
+ * never past its owner: disposing a SharedResource drains all outstanding
+ * leases and disposes the resource. A leaked SharedResource is bounded by its
+ * Run, whose disposal also drains its leases and disposes its current resource.
+ * Leaks are also observable — {@link SharedResource.snapshot | snapshot} exposes
+ * a lease count that never returns to zero — and detected: in development
+ * builds, a lease that is garbage-collected without release logs a warning with
+ * its acquire stack via the LeakDetector dependency.
  */
-export interface SharedResource<T extends Resource, D = unknown> extends AsyncDisposable {
+export interface SharedResource<T extends Resource> extends AsyncDisposable {
     /**
-     * Acquires a shared reference.
+     * Acquires a {@link Lease} on the shared resource.
      *
      * The first call lazily creates the resource. Later calls reuse the same
-     * resource until the final {@link SharedResource.release | release} starts the
-     * final disposal path. Disposal happens immediately by default, or after
-     * {@link SharedResourceOptions.idleDisposeAfter | idleDisposeAfter} elapses
-     * when configured.
+     * resource until the last lease is released.
+     *
+     * Once started, acquire runs to completion even when the caller aborts its
+     * Fiber, and the returned lease still counts as held. If resource creation or
+     * disposal is in progress, acquire waits for it to complete. Always await the
+     * result and release the lease; a caller that stops waiting (for example with
+     * the `daemon` helper) abandons a lease that is never released, retaining the
+     * resource until the owning {@link SharedResource} is disposed.
      *
-     * Once started, acquire runs to completion even if the caller aborts its
-     * Fiber. Always await the result. A successful result still counts as an
-     * acquired lease and must later be balanced with
-     * {@link SharedResource.release | release}.
+     * Owner disposal is different from caller abort: if disposal starts before a
+     * lease is transferred, acquire aborts with `runDisposedAbortReason` from the
+     * SharedResource's internal Run. A resource returned by `create` after
+     * shutdown starts remains owned by this SharedResource and is disposed
+     * without a lease escaping. Transfer occurs when the internal acquisition
+     * completes, before the caller necessarily resumes. If owner disposal starts
+     * in that gap, the caller can receive a lease already drained by disposal.
+     * Its `release` returns `false`, and its resource must not be used.
      */
-    readonly acquire: Task<BorrowedResource<T>, never, D>;
+    readonly acquire: Task<Lease<T>>;
     /**
-     * Releases one previously acquired shared reference.
+     * Acquires a {@link Lease} on the current resource without creating one.
      *
-     * When the last acquired reference is released, the current resource is
-     * disposed immediately by default. If
-     * {@link SharedResourceOptions.idleDisposeAfter | idleDisposeAfter} is set,
-     * disposal is scheduled instead and a new acquire during that delay reuses
-     * the current resource.
+     * Waits for preceding creation or disposal to finish. Returns `undefined` if
+     * no current resource remains. Owner disposal while waiting aborts the
+     * acquisition before a lease is transferred. As with `acquire`, owner
+     * disposal after transfer can drain the lease before the caller resumes.
+     */
+    readonly acquireCurrent: Task<Lease<T> | undefined>;
+    /**
+     * Acquires a {@link Lease}, runs a Task with the shared resource, and releases
+     * the lease after the Task settles.
      *
-     * Once started, release runs to completion even if the caller aborts its
-     * Fiber. Always await the result instead of assuming no cleanup happened.
+     * Creates the resource when absent. The callback receives whether this use
+     * created the resource generation. While the owner remains running, the lease
+     * prevents ordinary idle disposal. Disposing this SharedResource is forceful:
+     * it drains the lease and may dispose the resource before or while the
+     * callback Task runs.
      */
-    readonly release: Task<void, never, D>;
-    /** Returns the current acquire count. */
-    readonly getCount: Task<NonNegativeInt, never, D>;
-    /** Returns the current resource, or `undefined` if absent. */
-    readonly get: () => BorrowedResource<T> | undefined;
+    readonly use: <R, E, D>(callback: (resource: BorrowedResource<T>, created: boolean) => Task<R, E, D>) => Task<R, E, D>;
     /** Returns the current shared-resource state for monitoring/debugging. */
     readonly snapshot: () => SharedResourceSnapshot;
 }
 /** Snapshot returned by {@link SharedResource.snapshot}. */
 export interface SharedResourceSnapshot {
     /**
-     * Whether the resource has no current value, no borrowers, and no pending
-     * idle disposal.
+     * Whether the resource has no current value, no leases, no pending idle
+     * disposal, and no acquisition in progress.
      */
     readonly isIdle: boolean;
-    /** Current mutex state for monitoring/debugging. */
+    /** Current active lease count. */
+    readonly leaseCount: NonNegativeInt;
+    /** Whether a current resource exists. */
+    readonly hasResource: boolean;
+    /** Whether delayed idle disposal is scheduled and pending. */
+    readonly idleDisposePending: boolean;
+    /** Current internal mutex state for monitoring/debugging. */
     readonly mutex: SemaphoreSnapshot;
 }
 /** Options for {@link createSharedResource}. */
 export interface SharedResourceOptions {
     /**
-     * Keeps the resource alive briefly after the last release.
+     * Keeps the resource alive briefly after the last lease is released.
      *
      * This avoids immediate disposal when the resource is expensive to create and
      * likely to be acquired again soon. A new acquire during this delay cancels
      * the pending disposal and reuses the current resource.
      */
-    readonly idleDisposeAfter?: Duration | undefined;
-    /** Called after the current resource is disposed and cleared. */
-    readonly onDisposed?: () => void;
+    readonly idleDisposeAfter?: PositiveDuration | undefined;
+    /**
+     * Called after each current resource disposal is attempted and the current
+     * reference is cleared, including during {@link SharedResource} disposal.
+     * Native disposal still calls it if the resource disposer defects. Not called
+     * if no resource was created.
+     */
+    readonly onDisposed?: (() => void) | undefined;
 }
-/** Creates {@link SharedResource}. */
-export declare const createSharedResource: <T extends Resource, D>(create: Task<T, never, D>, { idleDisposeAfter, onDisposed }?: SharedResourceOptions) => Task<SharedResource<T, D>, never, D>;
+/**
+ * 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 declare const createSharedResource: <T extends Resource, D>(create: Task<T, never, D>, { idleDisposeAfter, onDisposed }?: SharedResourceOptions) => Task<SharedResource<T>, never, D>;
 /**
  * Shared {@link Resource}s keyed by logical identity.
  *
  * A map-like registry of {@link SharedResource}s. Each key owns at most one
- * current resource instance.
- *
- * The first {@link SharedResourceByKey.acquire | acquire} for a key lazily
- * creates that key's resource. Later acquires for the same key reuse the same
- * resource until the final {@link SharedResourceByKey.release | release} starts
- * the final disposal path for that key. Disposal and registry removal happen
- * immediately by default, or after
- * {@link SharedResourceByKeyOptions.idleDisposeAfter | idleDisposeAfter} elapses
- * when configured.
+ * current resource instance. The first
+ * {@link SharedResourceByKey.acquire | acquire} for a key lazily creates that
+ * key's resource; releasing the key's last {@link Lease} disposes it and removes
+ * the key from the registry.
  *
  * Different keys are independent and may progress concurrently. Operations for
- * the same key are serialized. Calls to
- * {@link SharedResourceByKey.release | release} must be balanced with successful
- * calls to {@link SharedResourceByKey.acquire | acquire}. Acquire and release
- * may still be aborted before they start on an already-stopped Run, but once
- * started they run to completion. Releasing more times than acquired is a
- * programmer error checked with {@link assert}.
- *
- * By default, {@link createSharedResourceByKey} uses reference identity for
- * keys, matching native `Map`. Callers may instead provide a
- * {@link Lookup
- * lookup} so logical equality is based on a derived stable key.
+ * the same key are serialized.
+ *
+ * By default, keys use reference identity, matching native `Map`. Callers may
+ * instead provide a {@link Lookup lookup} so logical equality is based on a
+ * derived stable key.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   all,
+ *   createRun,
+ *   createSharedResourceByKey,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * interface Connection extends Disposable {
+ *   readonly ownerId: string;
+ *   readonly send: (message: string) => void;
+ *   readonly flush: () => ReadonlyArray<string>;
+ * }
+ *
+ * const createConnection =
+ *   (ownerId: string): Task<Connection> =>
+ *   () => {
+ *     const pendingMessages: Array<string> = [];
+ *     return ok({
+ *       ownerId,
+ *       send: (message) => {
+ *         pendingMessages.push(message);
+ *       },
+ *       flush: () => pendingMessages.splice(0),
+ *       [Symbol.dispose]: () => {},
+ *     });
+ *   };
+ *
+ * await using run = createRun();
+ * await using connections = await run.ok(
+ *   createSharedResourceByKey(createConnection, {
+ *     idleDisposeAfter: "30s",
+ *   }),
+ * );
+ * const send = (ownerId: string, message: string): Task<void> =>
+ *   connections.use(ownerId, (connection) => () => {
+ *     connection.send(message);
+ *     return ok();
+ *   });
+ *
+ * // Same-key calls share one connection. Work for different keys remains
+ * // independent, so all three operations can run concurrently.
+ * await run.ok(
+ *   all(
+ *     [
+ *       send("owner-1", "first"),
+ *       send("owner-1", "second"),
+ *       send("owner-2", "hello"),
+ *     ],
+ *     { concurrency: 3 },
+ *   ),
+ * );
+ *
+ * // `acquireCurrent` does not create absent keys. The idle delay keeps the two
+ * // existing connections available to enumerate and flush.
+ * using missingLease = await run.ok(connections.acquireCurrent("owner-3"));
+ * const messagesByOwnerId = new Map<string, ReadonlyArray<string>>();
+ * await run.ok(
+ *   connections.forEachCurrent((connection) => {
+ *     messagesByOwnerId.set(connection.ownerId, connection.flush());
+ *   }),
+ * );
+ *
+ * expect(missingLease).toBeUndefined();
+ * expect(messagesByOwnerId).toEqual(
+ *   new Map([
+ *     ["owner-1", ["first", "second"]],
+ *     ["owner-2", ["hello"]],
+ *   ]),
+ * );
+ * ```
  */
-export interface SharedResourceByKey<K, T extends Resource, D = unknown> extends AsyncDisposable {
+export interface SharedResourceByKey<K, T extends Resource> extends AsyncDisposable {
     /**
-     * Acquires the shared resource for `key`, creating it on first use.
+     * Acquires a {@link Lease} on the shared resource for `key`, creating the
+     * resource on first use.
      *
-     * Once started, acquire runs to completion even if the caller aborts its
-     * Fiber. Always await the result. A successful result still counts as an
-     * acquired lease for `key` and must later be balanced with
-     * {@link SharedResourceByKey.release | release}.
+     * The same contract as {@link SharedResource.acquire}: once started, acquire
+     * runs to completion even when the caller aborts its Fiber, and the returned
+     * lease still counts as held. Registry disposal before lease transfer aborts
+     * the acquisition. Always await the result and release the lease.
      */
-    readonly acquire: (key: K) => Task<BorrowedResource<T>, never, D>;
+    readonly acquire: (key: K) => Task<Lease<T>>;
     /**
-     * Releases one previously acquired shared reference for `key`.
+     * Acquires a {@link Lease} on the current resource for `key` without creating
+     * one.
      *
-     * When the last acquired reference for `key` is released, that key's current
-     * resource is disposed and removed from the registry immediately by default.
-     * If {@link SharedResourceByKeyOptions.idleDisposeAfter | idleDisposeAfter} is
-     * set, disposal and registry removal are scheduled instead and a new acquire
-     * for the same key during that delay reuses the current resource.
+     * Waits for preceding creation or disposal for the same key to finish.
+     * Returns `undefined` if no current resource remains. Registry disposal while
+     * waiting aborts the acquisition before a lease is transferred. Registry
+     * disposal after transfer can drain the lease before the caller resumes,
+     * matching {@link SharedResource.acquireCurrent}.
+     */
+    readonly acquireCurrent: (key: K) => Task<Lease<T> | undefined>;
+    /**
+     * Acquires a {@link Lease}, runs a Task with the shared resource for `key`,
+     * and releases the lease after the Task settles.
      *
-     * Once started, release runs to completion even if the caller aborts its
-     * Fiber. Always await the result instead of assuming no cleanup happened.
+     * Creates the resource when absent. The callback receives whether this use
+     * created the resource generation. While the registry remains running, the
+     * lease prevents ordinary idle disposal. Disposing this registry is forceful:
+     * it drains the lease and may dispose the resource before or while the
+     * callback Task runs.
      */
-    readonly release: (key: K) => Task<void, never, D>;
-    /** Returns the current acquire count for `key`. Missing keys return `0`. */
-    readonly getCount: (key: K) => Task<NonNegativeInt, never, D>;
-    /** Returns the current resource for `key`, or `undefined` if absent. */
-    readonly get: (key: K) => BorrowedResource<T> | undefined;
-    /** Returns current keyed resources and their per-key mutex state. */
-    readonly snapshot: () => SharedResourceByKeySnapshot<K, T>;
+    readonly use: <R, E, D>(key: K, callback: (resource: BorrowedResource<T>, created: boolean) => Task<R, E, D>) => Task<R, E, D>;
+    /**
+     * Calls `callback` for each current resource it can lease from keys
+     * registered when this Task starts.
+     *
+     * Never creates resources. A resource whose creation is in progress may be
+     * included after creation finishes; one disposed before its temporary lease
+     * is acquired is skipped. Each acquired lease stays held while later keys are
+     * awaited, and every callback runs while all acquired resources remain
+     * leased. Caller abort is observed between keys; already-collected leases are
+     * released and no callbacks run.
+     */
+    readonly forEachCurrent: (callback: (resource: BorrowedResource<T>, key: K) => void) => Task<void>;
+    /** Returns current per-key shared-resource states for monitoring/debugging. */
+    readonly snapshot: () => SharedResourceByKeySnapshot<K>;
 }
 /** Snapshot returned by {@link SharedResourceByKey.snapshot}. */
-export interface SharedResourceByKeySnapshot<K, T extends Resource> {
-    /** Current borrowed resources by key. */
-    readonly resourcesByKey: ReadonlyMap<K, BorrowedResource<T>>;
-    /** Current mutex state for each key in the resource snapshot. */
-    readonly mutexByKey: ReadonlyMap<K, SemaphoreSnapshot | null>;
+export interface SharedResourceByKeySnapshot<K> {
+    /**
+     * Current registered {@link SharedResourceSnapshot} for each key.
+     *
+     * A key is absent during the brief first-acquire interval before its
+     * SharedResource is registered, even though that acquire may already hold the
+     * key mutex.
+     */
+    readonly resourcesByKey: ReadonlyMap<K, SharedResourceSnapshot>;
 }
 /** Options for {@link createSharedResourceByKey}. */
 export interface SharedResourceByKeyOptions<K, L = K> extends Pick<SharedResourceOptions, "idleDisposeAfter">, LookupOption<K, L> {
-    /** Called after `key`'s current resource is disposed and cleared. */
-    readonly onDisposed?: (key: K) => void;
+    /**
+     * Called with `key` after each current resource for that key is disposed,
+     * including during {@link SharedResourceByKey} disposal. Not called for keys
+     * whose resources were never created.
+     *
+     * After ordinary idle disposal, the key is removed before this callback
+     * unless a same-key operation is already in progress. A regular acquire can
+     * then create the next current resource. An acquireCurrent that finds no
+     * resource removes the retained key before returning.
+     */
+    readonly onDisposed?: ((key: K) => void) | undefined;
 }
 /**
  * Creates {@link SharedResourceByKey}.
  *
- * The `create` Task is scoped to one key. It must not fail, matching
- * {@link createSharedResource}.
+ * The `create` callback returns a Task scoped to one key. The returned Task
+ * must not fail, matching {@link createSharedResource}.
+ *
+ * Create each resource with {@link disposable} when its shape supports it. The
+ * same disposal-guard recommendation as {@link createSharedResource} applies.
+ *
+ * The returned Task must not directly or transitively acquire the same logical
+ * key or call `forEachCurrent` on this registry. Same-key acquisition is
+ * non-reentrant, and `forEachCurrent` attempts to acquire every registered key.
+ * Different keys remain independent.
+ *
+ * Like {@link createSharedResource}, dependencies are captured when the registry
+ * is created; dependencies provided to later acquire calls do not change what
+ * the returned Task observes.
  */
-export declare function createSharedResourceByKey<K = unknown, T extends Resource = Resource, D = unknown>(create: (key: K) => Task<T, never, D>): Task<SharedResourceByKey<K, T, D>, never, D>;
-export declare function createSharedResourceByKey<K, T extends Resource, D, L = K>(create: (key: K) => Task<T, never, D>, options: SharedResourceByKeyOptions<K, L>): Task<SharedResourceByKey<K, T, D>, never, D>;
+export declare function createSharedResourceByKey<K = unknown, T extends Resource = Resource, D = unknown>(create: (key: K) => Task<T, never, D>): Task<SharedResourceByKey<K, T>, never, D>;
+export declare function createSharedResourceByKey<K, T extends Resource, D, L = K>(create: (key: K) => Task<T, never, D>, options: SharedResourceByKeyOptions<K, L>): Task<SharedResourceByKey<K, T>, never, D>;
 /**
- * Shared {@link Resource}s keyed by logical identity and retained by claims.
+ * Shared keyed {@link Resource}s retained through claims.
  *
- * This combines {@link SharedResourceByKey} with claim tracking. Resources are
- * kept alive while at least one claim retains their key.
+ * A claim identifies an application-level owner such as an account, tenant, or
+ * open document. Resource keys identify the shared resources that owner needs,
+ * such as relay URLs, database names, or worker IDs.
  *
- * By default, {@link createSharedResourceByKeyWithClaims} uses reference
- * identity for both resource keys and claims, matching native `Map` and `Set`.
- * Callers may instead provide {@link Lookup lookup} functions so logical
- * equality is based on derived stable keys.
+ * Use this abstraction when each owner needs a set of keyed resources and those
+ * sets can overlap. Calling {@link SharedResourceByKeyWithClaims.claim |
+ * claim}
+ * retains every resource in one owner's set. Overlapping owners share one
+ * resource instance per key, and the resource remains alive until every
+ * {@link ClaimLease} retaining that key is released.
+ *
+ * Relation queries reflect active claims, not physical resource liveness. With
+ * `idleDisposeAfter`, a resource can outlive its last claim.
+ *
+ * Use {@link SharedResourceByKey} instead when callers only need independent
+ * leases by key and the application does not need to associate those leases
+ * with logical owners.
+ *
+ * Two accounts can share a relay connection while one also uses a local-network
+ * transport:
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   createSharedResourceByKeyWithClaims,
+ *   ok,
+ *   type Brand,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * type AccountId = string & Brand<"AccountId">;
+ * type TransportUrl = string & Brand<"TransportUrl">;
+ *
+ * interface Connection extends Disposable {
+ *   readonly url: TransportUrl;
+ * }
+ *
+ * const createConnection =
+ *   (url: TransportUrl): Task<Connection> =>
+ *   () =>
+ *     ok({
+ *       url,
+ *       [Symbol.dispose]: () => {},
+ *     });
+ * // These literals stand in for values validated at application boundaries.
+ * const accountA = "account-a" as AccountId;
+ * const accountB = "account-b" as AccountId;
+ * const relay = "wss://relay.example.com" as TransportUrl;
+ * const localNetwork = "ws://local-network" as TransportUrl;
+ *
+ * await using run = createRun();
+ * await using transports = await run.ok(
+ *   createSharedResourceByKeyWithClaims<
+ *     TransportUrl,
+ *     AccountId,
+ *     Connection
+ *   >(createConnection),
+ * );
+ *
+ * {
+ *   // Account A retains both transports.
+ *   using accountATransports = await run.ok(
+ *     transports.claim(accountA, [relay, localNetwork]),
+ *   );
+ *
+ *   {
+ *     // Account B reuses the relay already retained by account A.
+ *     using accountBRelay = await run.ok(
+ *       transports.claim(accountB, [relay]),
+ *     );
+ *     expect(transports.getClaimsForResource(relay)).toEqual(
+ *       new Set([accountA, accountB]),
+ *     );
+ *     expect(transports.getResourceKeysForClaim(accountA)).toEqual(
+ *       new Set([relay, localNetwork]),
+ *     );
+ *   }
+ *
+ *   // Releasing account B leaves account A's relay retain intact.
+ *   expect(transports.getClaimsForResource(relay)).toEqual(
+ *     new Set([accountA]),
+ *   );
+ * }
+ *
+ * // Releasing the final claim removes the relation for both transports.
+ * expect(transports.getClaimsForResource(relay)).toEqual(new Set());
+ * expect(transports.getClaimsForResource(localNetwork)).toEqual(new Set());
+ * ```
  */
-export interface SharedResourceByKeyWithClaims<K, C, T extends Resource, D = unknown> extends AsyncDisposable {
-    /** Retains each resource key for `claim`. */
-    readonly addClaim: (claim: C, resourceKeys: ReadonlyArray<K>) => Task<void, never, D>;
-    /** Releases each previously retained resource key for `claim`. */
-    readonly removeClaim: (claim: C, resourceKeys: ReadonlyArray<K>) => Task<void, never, D>;
-    /** Returns the current resource for `key`, or `undefined` if absent. */
-    readonly getResource: (key: K) => BorrowedResource<T> | undefined;
-    /** Returns the current unique claims retaining `key`. */
-    readonly getClaimsForResource: (key: K) => ReadonlySet<C>;
-    /** Returns the current unique resource keys retained by `claim`. */
+export interface SharedResourceByKeyWithClaims<K, C, T extends Resource> extends AsyncDisposable {
+    /**
+     * Retains every resource key for `claim`, creating absent resources lazily.
+     *
+     * Keys are snapshotted when this Task starts and acquired sequentially in
+     * input order.
+     *
+     * `resourceKeys` must not contain logical duplicates according to
+     * {@link SharedResourceByKeyWithClaimsOptions.resourceLookup}. A duplicate is
+     * a programmer defect that panics the owning Run.
+     *
+     * The returned {@link ClaimLease} releases all retains added by this call.
+     * Resource creation must succeed, so this Task has no recoverable error.
+     */
+    readonly claim: (claim: C, resourceKeys: NonEmptyReadonlyArray<K>) => Task<ClaimLease>;
+    /**
+     * Retains every resource key for `claim`, runs a Task with those resources,
+     * and releases the resulting {@link ClaimLease} after the Task settles.
+     *
+     * The callback receives only the resources retained by this call, in input
+     * order. Other active ClaimLeases for the same logical claim are excluded.
+     * While this registry remains running, every borrowed resource remains valid
+     * until the callback Task settles. Disposing this registry is forceful: it
+     * drains the ClaimLease and may dispose resources before or while the
+     * callback Task runs.
+     */
+    readonly use: <R, E, D>(claim: C, resourceKeys: NonEmptyReadonlyArray<K>, callback: (resources: NonEmptyReadonlyArray<readonly [BorrowedResource<T>, K]>) => Task<R, E, D>) => Task<R, E, D>;
+    /**
+     * Returns the current unique claims retaining `resourceKey`.
+     *
+     * Returns an empty snapshot when no claim retains the key, including after
+     * this registry is disposed.
+     */
+    readonly getClaimsForResource: (resourceKey: K) => ReadonlySet<C>;
+    /**
+     * Returns the current unique resource keys retained by `claim`.
+     *
+     * Returns an empty snapshot when the claim retains no keys, including after
+     * this registry is disposed.
+     */
     readonly getResourceKeysForClaim: (claim: C) => ReadonlySet<K>;
-    /** Returns the current unique resources retained by `claim`. */
-    readonly getResourcesForClaim: (claim: C) => ReadonlySet<BorrowedResource<T>>;
+    /**
+     * Calls `callback` for each current resource retained by `claim`.
+     *
+     * The keys and resources are snapshotted before the first callback runs.
+     * Resources remain valid until this synchronous iteration returns, even if a
+     * callback releases the final retaining ClaimLease. Callbacks must not retain
+     * or asynchronously use borrowed resources afterward. Does nothing when the
+     * claim retains no resources, including after this registry is disposed.
+     */
+    readonly forEachResourceForClaim: (claim: C, callback: (resource: BorrowedResource<T>, resourceKey: K) => void) => void;
+    /**
+     * Returns current claim-retain and keyed-resource states.
+     *
+     * While a claim is acquiring keys, `resourcesByKey` can include inner leases
+     * not yet reflected by `claimLeaseCount` or
+     * `retainCountsByResourceKeyByClaim`.
+     */
+    readonly snapshot: () => SharedResourceByKeyWithClaimsSnapshot<K, C>;
+}
+/** Snapshot returned by {@link SharedResourceByKeyWithClaims.snapshot}. */
+export interface SharedResourceByKeyWithClaimsSnapshot<K, C> {
+    /** Number of currently held ClaimLeases. */
+    readonly claimLeaseCount: NonNegativeInt;
+    /** Current retain count for every active logical claim-resource pair. */
+    readonly retainCountsByResourceKeyByClaim: ReadonlyMap<C, ReadonlyMap<K, number>>;
+    /** Current registered {@link SharedResourceSnapshot} for each key. */
+    readonly resourcesByKey: ReadonlyMap<K, SharedResourceSnapshot>;
+}
+/**
+ * An owned lease on the resource-retains added by one claim operation.
+ *
+ * A ClaimLease is a grouped ownership token. For example, a claim for one
+ * account can retain its relay, local-network, and Bluetooth transports. The
+ * ClaimLease releases that whole group together; it does not expose or transfer
+ * ownership of the resources themselves.
+ *
+ * Releasing the lease removes every retain added by that claim call. Release is
+ * idempotent and synchronous; resource disposal remains owned by the
+ * {@link SharedResourceByKeyWithClaims} that created the lease.
+ */
+export interface ClaimLease extends Disposable {
+    /**
+     * Releases every resource retain owned by this claim lease.
+     *
+     * Returns whether this call released a still-held lease. Returns `false` if
+     * the lease was already released or drained by disposal of its owning
+     * {@link SharedResourceByKeyWithClaims} or the Run tree that owns it.
+     */
+    readonly release: () => boolean;
 }
 /** Options for {@link createSharedResourceByKeyWithClaims}. */
 export interface SharedResourceByKeyWithClaimsOptions<K, C, T extends Resource, LK = K, LC = C> extends Pick<SharedResourceOptions, "idleDisposeAfter"> {
-    /** Derives logical identity for resource keys. Defaults to {@link identity}. */
+    /** Derives the identity used to compare resource keys. */
     readonly resourceLookup?: Lookup<K, LK>;
-    /** Derives logical identity for claims. Defaults to {@link identity}. */
+    /** Derives the identity used to compare claims. */
     readonly claimLookup?: Lookup<C, LC>;
-    /** Called when a key transitions from zero claims to one claim. */
+    /**
+     * Called when a claim-resource pair transitions from zero retains to one.
+     *
+     * This is a pair-retain transition, not a resource-generation transition: a
+     * resource can already be retained by other claims or be idling after an
+     * earlier release. Arguments use the first stored representatives for their
+     * logical claim and key.
+     */
     readonly onFirstClaimAdded?: (claim: C, resource: BorrowedResource<T>, resourceKey: K) => void;
-    /** Called when a key transitions from one claim to zero claims. */
+    /**
+     * Called when a claim-resource pair transitions from one retain to zero.
+     *
+     * Runs before the ClaimLease's inner resource lease is released. Other claims
+     * can still retain the same resource. Arguments use the first stored
+     * representatives for their logical claim and key. During normal release, the
+     * current pair and earlier keys from the same ClaimLease are already absent
+     * from relation reads; later keys remain. During compensation for a failed
+     * first-claim callback, the failed claim remains fully visible.
+     */
     readonly onLastClaimRemoved?: (claim: C, resource: BorrowedResource<T>, resourceKey: K) => void;
 }
 /**
  * Creates {@link SharedResourceByKeyWithClaims}.
  *
- * Claim-resource pairs are reference-counted by logical identity. The
- * underlying resource for a key is acquired on the first active claim and
- * released when the last active claim for that key is removed.
+ * 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 declare function createSharedResourceByKeyWithClaims<T extends Resource, K = unknown, C = unknown, D = unknown>(create: (key: K) => Task<T, never, D>): Task<SharedResourceByKeyWithClaims<K, C, T, D>, never, D>;
-export declare function createSharedResourceByKeyWithClaims<T extends Resource, K, C, D, LK = K, LC = C>(create: (key: K) => Task<T, never, D>, options: SharedResourceByKeyWithClaimsOptions<K, C, T, LK, LC>): Task<SharedResourceByKeyWithClaims<K, C, T, D>, never, D>;
+export declare const createSharedResourceByKeyWithClaims: <K = unknown, C = unknown, T extends Resource = Resource, D = unknown, LK = K, LC = C>(create: (key: K) => Task<T, never, D>, { idleDisposeAfter, resourceLookup, claimLookup, onFirstClaimAdded, onLastClaimRemoved, }?: SharedResourceByKeyWithClaimsOptions<K, C, T, LK, LC>) => Task<SharedResourceByKeyWithClaims<K, C, T>, never, D>;
 //# sourceMappingURL=Resource.d.ts.map