@fitzzero/quickdraw-core 5.1.2 → 5.1.3

package/dist/server/index.d.ts

@@ -1,19 +1,19 @@
-import { J as AnyContract, at as ProjectionName, ai as FullProjectionOf, ac as CollectionName, ap as MethodName, d as StandardSchemaV1, c as InferOutput, N as NullableProjection, P as ProjectionList, aq as MethodOf, as as ParsedInputOf, ao as KindOf, A as AccessLevel, af as EntityOf, ar as OutputOf } from '../infer-BmoZsL9a.js';
-import { M as ModelName, v as PolicyFor, w as RowForms, x as AccessFor, H as HandlerContext, y as ModelColumn, z as WatchAccess, B as PublicAccess, E as HandlerArgs, G as CustomAccess, I as ShareMode, J as ChannelOptions, K as StreamOptions, u as RoomLeaveHandler, L as ChannelsRequired, h as Service, N as BaseContext, O as CallerFor, l as RunContext, m as RunOptions, o as StreamHandle, P as Presence, n as ServerRooms, Q as AccessPolicy, T as AnyAccessPolicy, V as PolicyColumns, X as PolicyForeign, Y as PolicyTools, k as AccessFilter, Z as RowAccess, q as AccessEngine, b as StorageWhere } from '../caller-BT-Mv4bD.js';
-export { aI as ANY_FIELD, aA as AccessForm, aB as AccessRequest, _ as AffectsLink, p as AnyContext, A as AnyService, r as AppRooms, aC as AuthenticatedAccess, aq as CallOptions, d as Caller, a9 as ChannelAccess, aa as ChannelContext, ab as ChannelHandler, ac as ChannelImplementation, ad as ChannelRoomOf, a4 as CollectionScope, a6 as ContextRooms, a7 as ContextServices, C as CountArgs, a3 as DEFAULT_BULK_THRESHOLD, i as DevWarning, D as DevWarningError, j as DevWarningKind, aD as EntryAccess, F as FindManyArgs, f as FlushInfo, e as FlushSink, at as ForeignColumns, au as ForeignColumnsOf, aE as IdKeyOf, aF as IdSelector, aL as LinkInterest, av as MembershipRead, ar as MethodCaller, aN as N_PLUS_ONE_STATEMENTS, aw as ParentLink, ax as PolicyKind, ay as PolicyReads, $ as ProjectedOutput, a0 as Projection, ae as RoomLeave, af as RoomLeaveReason, ag as RoomLeft, ah as RoomTarget, az as RowLevel, R as RowLevels, aG as ScopeAccess, aH as ServiceAccess, as as ServiceCaller, ai as ServiceChannel, a5 as ServiceCollection, g as ServiceMethod, aj as ServiceStream, c as StatementCount, S as StorageAdapter, a as StorageRow, ak as StreamImplementation, al as StreamPushArgs, am as StreamPushManyArgs, an as StreamSeed, ao as StreamSeedContext, t as StreamSubscriptions, ap as StreamValidation, a1 as TierGroup, a2 as Tiers, a8 as TouchOptions, aJ as UnitOfWork, U as UnitOfWorkFactory, aK as UnitOfWorkScope, W as WriteRecord, aM as formatDevWarning, s as storageOf } from '../caller-BT-Mv4bD.js';
-import { S as ServerOptions, Q as QuickdrawServer } from '../createServer-Cp-Wk500.js';
-export { C as ClusterClient, u as ClusterOptions, D as DEFAULT_STALL_INTERVAL_MS, e as DEFAULT_STALL_MAX_MS, f as DEFAULT_STALL_THRESHOLD_MS, p as DisconnectUserOptions, E as EntitySubscription, a as EntitySubscriptions, H as HttpApp, I as IoRedisLike, L as LegacyReply, t as LegacyWireOptions, M as MIN_STALL_INTERVAL_MS, m as QuickdrawIo, n as QuickdrawServerSocket, o as QuickdrawSocketData, y as RateLimitOptions, z as RateLimiter, R as RotateOptions, g as STALL_RESOLUTION_MS, b as ScopeSubscription, c as ScopeSubscriptions, l as ServerOnlyOptions, h as SlowMethod, q as SocketCors, r as SocketOptions, s as SocketRateLimitOptions, i as StallReport, j as StallWatchdogOptions, T as TopicWatch, d as TopicWatches, w as applyRateLimitMiddleware, v as createRateLimiter, k as createServer, x as createTieredRateLimiter } from '../createServer-Cp-Wk500.js';
-import { ad as Version } from '../envelope-DzWyIXjj.js';
-export { ag as MAX_ENTITY_IDS_PER_SOCKET, ah as MAX_SCOPES_PER_SOCKET, ai as MAX_TOPICS_PER_SOCKET } from '../envelope-DzWyIXjj.js';
-import { Q as QuickdrawTypes, D as DbOf, d as PrincipalKindOf, c as PrincipalOf, M as MaybePromise, b as McpContextOf, C as ContextExtensionOf, P as Principal } from '../types-CYliTP65.js';
-export { a as McpContext, T as Transport } from '../types-CYliTP65.js';
-import { c as DispatcherOptions, D as Dispatcher, d as DispatcherCollections } from '../http-DotQ5bj8.js';
-export { p as AccessChange, q as AccessChangeListener, A as AccessOptions, e as ChangeLogOptions, C as ContractOfServices, k as DEFAULT_LIMITS, g as DbOfServices, i as DispatchRequest, j as DispatchResult, o as DispatcherAccess, a as DispatcherBaseOptions, l as DispatcherLimits, u as HttpMiddleware, H as HttpRouter, v as HttpRouterOptions, b as HttpTransportOptions, L as LimitsOptions, m as PipelineOptions, P as PrincipalOfServices, R as RegisteredMethod, h as Registry, S as SharedData, n as SubscriptionLimits, T as TrackingOptions, V as VersionRequest, r as VersionSource, f as createDispatcher, s as createHttpRouter, t as toCallReply } from '../http-DotQ5bj8.js';
-import { l as CrudMethodName, d as CrudContractOptions, S as ScalarFieldOf, N as NumberFieldOf, m as CrudMethods, H as AdminMethodsOf, w as AdminContractOptions, G as AdminMethods } from '../admin-DWWrT1h6.js';
-import { S as SearchContractOptions, T as TextFieldOf, b as SearchMethods, n as SharingMethodName, f as SharingByNameMethod, g as SharingContractOptions, o as SharingMethods } from '../sharing-UDLn1049.js';
-import { x as AdminNeverWritable, l as AdminFieldConfig } from '../adminSchemas-D4bFKsrb.js';
-export { a as CallOutcome, C as CallRecord } from '../metrics-DW80Exve.js';
-export { b as AuthenticateRequest, A as AuthenticateResult, c as HttpAuthenticateRequest, d as HttpCredentialSource, S as ServerAuth, e as ServiceAccessSource, a as ServiceGrants, f as SocketAuthenticateRequest, r as recordSocketSession } from '../auth-DXiSJZaf.js';
+import { J as AnyContract, at as ProjectionName, ai as FullProjectionOf, ac as CollectionName, A as AccessLevel, ap as MethodName, d as StandardSchemaV1, c as InferOutput, N as NullableProjection, P as ProjectionList, aq as MethodOf, as as ParsedInputOf, ao as KindOf, af as EntityOf, ar as OutputOf } from '../infer-Br62cnyW.js';
+import { M as ModelName, u as PolicyFor, v as RowForms, w as AccessFor, x as HandlerContext, y as ModelColumn, z as WatchAccess, B as PublicAccess, E as HandlerArgs, G as CustomAccess, I as ShareMode, J as ChannelOptions, K as StreamOptions, t as RoomLeaveHandler, H as HostLeaveHandler, L as ChannelsRequired, h as Service, N as BaseContext, O as CallerFor, R as RunContext, k as RunOptions, n as StreamHandle, P as Presence, m as ServerRooms, Q as AccessPolicy, T as AnyAccessPolicy, V as PolicyColumns, X as PolicyForeign, Y as PolicyTools, Z as AccessFilter, _ as RowAccess, p as AccessEngine, b as StorageWhere } from '../caller-BTwGl7vm.js';
+export { aP as ANY_FIELD, aF as AccessChange, aG as AccessChangeListener, aH as AccessForm, aI as AccessRequest, $ as AffectsLink, o as AnyContext, A as AnyService, q as AppRooms, aJ as AuthenticatedAccess, au as CallOptions, d as Caller, ab as ChannelAccess, ac as ChannelContext, ad as ChannelHandler, ae as ChannelImplementation, af as ChannelRoomOf, a5 as CollectionScope, a7 as ContextAccess, a8 as ContextRooms, a9 as ContextServices, C as CountArgs, a4 as DEFAULT_BULK_THRESHOLD, i as DevWarning, D as DevWarningError, j as DevWarningKind, l as DispatcherAccess, aK as EntryAccess, F as FindManyArgs, f as FlushInfo, e as FlushSink, ax as ForeignColumns, ay as ForeignColumnsOf, ag as HostLeave, aL as IdKeyOf, aM as IdSelector, aS as LinkInterest, az as MembershipRead, av as MethodCaller, aU as N_PLUS_ONE_STATEMENTS, aA as ParentLink, aB as PolicyKind, aC as PolicyReads, a0 as ProjectedOutput, a1 as Projection, ah as RoomLeave, ai as RoomLeaveReason, aj as RoomLeft, ak as RoomTarget, aD as RowLevel, aE as RowLevels, aN as ScopeAccess, aO as ServiceAccess, aw as ServiceCaller, al as ServiceChannel, a6 as ServiceCollection, g as ServiceMethod, am as ServiceStream, c as StatementCount, S as StorageAdapter, a as StorageRow, an as StreamImplementation, ao as StreamPushArgs, ap as StreamPushManyArgs, aq as StreamSeed, ar as StreamSeedContext, as as StreamSubscribersArgs, r as StreamSubscriptions, at as StreamValidation, a2 as TierGroup, a3 as Tiers, aa as TouchOptions, aQ as UnitOfWork, U as UnitOfWorkFactory, aR as UnitOfWorkScope, W as WriteRecord, aT as formatDevWarning, s as storageOf } from '../caller-BTwGl7vm.js';
+import { S as ServerOptions, Q as QuickdrawServer } from '../createServer-Bx5HOcYK.js';
+export { C as ClusterClient, u as ClusterOptions, D as DEFAULT_STALL_INTERVAL_MS, e as DEFAULT_STALL_MAX_MS, f as DEFAULT_STALL_THRESHOLD_MS, p as DisconnectUserOptions, E as EntitySubscription, a as EntitySubscriptions, H as HttpApp, I as IoRedisLike, L as LegacyReply, t as LegacyWireOptions, M as MIN_STALL_INTERVAL_MS, m as QuickdrawIo, n as QuickdrawServerSocket, o as QuickdrawSocketData, y as RateLimitOptions, z as RateLimiter, R as RotateOptions, g as STALL_RESOLUTION_MS, b as ScopeSubscription, c as ScopeSubscriptions, l as ServerOnlyOptions, h as SlowMethod, q as SocketCors, r as SocketOptions, s as SocketRateLimitOptions, i as StallReport, j as StallWatchdogOptions, T as TopicWatch, d as TopicWatches, w as applyRateLimitMiddleware, v as createRateLimiter, k as createServer, x as createTieredRateLimiter } from '../createServer-Bx5HOcYK.js';
+import { aA as Version } from '../envelope-BMBaxppV.js';
+export { aD as MAX_ENTITY_IDS_PER_SOCKET, aE as MAX_SCOPES_PER_SOCKET, aF as MAX_TOPICS_PER_SOCKET } from '../envelope-BMBaxppV.js';
+import { Q as QuickdrawTypes, D as DbOf, d as PrincipalKindOf, b as PrincipalOf, M as MaybePromise, c as McpContextOf, C as ContextExtensionOf, P as Principal } from '../types-CLRCQGnO.js';
+export { a as McpContext, T as Transport } from '../types-CLRCQGnO.js';
+import { c as DispatcherOptions, D as Dispatcher, d as DispatcherCollections } from '../http-YzLAar3w.js';
+export { A as AccessOptions, e as ChangeLogOptions, C as ContractOfServices, k as DEFAULT_LIMITS, g as DbOfServices, i as DispatchRequest, j as DispatchResult, a as DispatcherBaseOptions, l as DispatcherLimits, q as HttpMiddleware, H as HttpRouter, r as HttpRouterOptions, b as HttpTransportOptions, L as LimitsOptions, m as PipelineOptions, P as PrincipalOfServices, R as RegisteredMethod, h as Registry, S as SharedData, n as SubscriptionLimits, T as TrackingOptions, V as VersionRequest, o as VersionSource, f as createDispatcher, p as createHttpRouter, t as toCallReply } from '../http-YzLAar3w.js';
+import { l as CrudMethodName, d as CrudContractOptions, S as ScalarFieldOf, N as NumberFieldOf, m as CrudMethods, H as AdminMethodsOf, w as AdminContractOptions, G as AdminMethods } from '../admin-CS7JB_UH.js';
+import { S as SearchContractOptions, T as TextFieldOf, b as SearchMethods, n as SharingMethodName, f as SharingByNameMethod, g as SharingContractOptions, o as SharingMethods } from '../sharing-BrsmlDv_.js';
+import { x as AdminNeverWritable, l as AdminFieldConfig, t as AdminData } from '../adminSchemas-29cGgrg5.js';
+export { a as CallOutcome, C as CallRecord } from '../metrics-CTVpw0gu.js';
+export { b as AuthenticateRequest, A as AuthenticateResult, c as HttpAuthenticateRequest, d as HttpCredentialSource, S as ServerAuth, e as ServiceAccessSource, a as ServiceGrants, f as SocketAuthenticateRequest, r as recordSocketSession } from '../auth-DtdYjrZ9.js';
 import { Server } from 'socket.io';
 import { L as Logger } from '../logger-Yz93KzdV.js';
 import 'node:http';
@@ -101,6 +101,14 @@ type HandlerResult<C extends AnyContract, Output, Proj> = Output extends Standar
  * wrapped by `nullable` and `listOf`.
  */
 type HandlerOutputOf<C extends AnyContract, M extends MethodName<C>, Proj = Record<never, never>> = HandlerResult<C, MethodOf<C, M>["output"], Proj>;
+/**
+ * A service-wide grant a collection's subscribers need besides the anchor or
+ * self check: `{ service: L }`, the caller's grant on the collection's own
+ * service at least `L`, as a method's `{ service: L }` form counts it.
+ */
+interface CollectionRequires {
+    readonly service: AccessLevel;
+}
 /**
  * How one collection's scopes are authorized (RFC 0003 section 7.1), in
  * `defineService`'s `collections` option.
@@ -114,8 +122,14 @@ type HandlerOutputOf<C extends AnyContract, M extends MethodName<C>, Proj = Reco
  *   On a service with an access policy its items still follow that policy:
  *   only the rows its user may read at `Read`, and a row the user loses goes
  *   out `removed`.
+ * - `requires: { service: L }`, beside either: the subscriber also needs a
+ *   service-wide grant of at least `L` on this service, as the service's
+ *   methods under `{ service: L }` do (`{ scopeAccess: "self", requires:
+ *   { service: "Read" } }`: the user's own rows, for holders of the Read
+ *   grant). Without it the scope is `FORBIDDEN`, and a socket whose grants
+ *   reload below it leaves the scope (`qd:revoked`, reason `"access"`).
  *
- * A service-wide `Admin` grant on this service passes either check, as it
+ * A service-wide `Admin` grant on this service passes every check, as it
  * passes every check of the service. `bulkThreshold` (default 200) is how
  * many changed rows of one scope one flush may send as deltas; past it the
  * scope gets one `reset` and its clients load it again.
@@ -123,10 +137,12 @@ type HandlerOutputOf<C extends AnyContract, M extends MethodName<C>, Proj = Reco
 type CollectionOption = {
     readonly anchor: AnyContract;
     readonly scopeAccess?: undefined;
+    readonly requires?: CollectionRequires;
     readonly bulkThreshold?: number;
 } | {
     readonly scopeAccess: "self";
     readonly anchor?: undefined;
+    readonly requires?: CollectionRequires;
     readonly bulkThreshold?: number;
 };
 /** `defineService`'s `collections` option: one entry per collection of the contract. */
@@ -212,7 +228,7 @@ type ShareOptions<A> = {
      * handler runs with the first caller's `ctx`, and every caller gets its
      * result, so a `"all"` result must depend on the input only: its
      * handler reads nothing of the caller (in development, reading
-     * `ctx.principal`, `ctx.services` or `ctx.mcp` warns
+     * `ctx.principal`, `ctx.services`, `ctx.mcp` or `ctx.access` warns
      * `[quickdraw:shared-principal]`, and a strict test app fails the
      * call). `"all"` is not allowed with `custom` access, nor on the kit
      * methods whose result depends on who asks (the read/write kit's
@@ -341,9 +357,10 @@ interface ServiceDefinition<T extends QuickdrawTypes, C extends AnyContract, A,
      * How each collection of the contract authorizes its scopes (RFC 0003
      * section 7.1): `{ anchor: contract }`, the contract whose rows the scope
      * values are ids of, or `{ scopeAccess: "self" }` for a scope that is the
-     * subscriber's user id; plus `bulkThreshold`. Required when the contract
-     * declares collections. Needs `model`. A self scope's items still follow
-     * the service's `access` policy, when it has one.
+     * subscriber's user id; plus `requires: { service: L }`, a service-wide
+     * grant every subscriber needs besides, and `bulkThreshold`. Required
+     * when the contract declares collections. Needs `model`. A self scope's
+     * items still follow the service's `access` policy, when it has one.
      */
     readonly collections?: CollectionOptions<C>;
     /**
@@ -400,6 +417,20 @@ interface ServiceDefinition<T extends QuickdrawTypes, C extends AnyContract, A,
      * },
      */
     readonly onRoomLeave?: RoomLeaveHandler<PrincipalOf<T>>;
+    /**
+     * Called once when the host of an app room leaves it (host mode, RFC 0003
+     * section 12.5): its own leave, a removal, or a disconnect, with the room,
+     * the host's socket and principal and the reason. The room has no host
+     * then, and its sockets heard `qd:host [room, null]`; the app decides
+     * what follows (another host, the game's end). Run as `onRoomLeave` is,
+     * beside `createServer`'s own, in a unit of work of its own.
+     *
+     * @example
+     * onHostLeave: ({ room }) => {
+     *   qd.rooms.emit(room, game, "hostLeft", { room });
+     * },
+     */
+    readonly onHostLeave?: HostLeaveHandler<PrincipalOf<T>>;
     /**
      * Whether a service-wide `Admin` grant passes every access check of this
      * service (RFC 0003 section 4.1). Default `true`.
@@ -513,10 +544,12 @@ interface Quickdraw<T extends QuickdrawTypes> {
     /**
      * The handle of a stream (RFC 0003 section 12.5), for handlers, jobs and
      * timers: `qd.stream(task, "logs").push(taskId, line)` (`push(item)` for a
-     * global stream; `pushMany(taskId, lines)` for several at once). Each push
-     * goes through the dispatcher this instance created last, so a handle can
-     * be made when a module loads; pushing before any dispatcher exists, or to
-     * a stream it does not serve, throws.
+     * global stream; `pushMany(taskId, lines)` for several at once), and
+     * `await qd.stream(task, "logs").subscribers(taskId)`, how many sockets
+     * watch the feed on every node. Each use goes through the dispatcher this
+     * instance created last, so a handle can be made when a module loads;
+     * pushing before any dispatcher exists, or to a stream it does not serve,
+     * throws (`subscribers` rejects).
      * Throws a `TypeError` at once for a stream the contract does not declare.
      */
     stream<C extends AnyContract, K extends keyof C["streams"] & string>(contract: C, name: K): StreamHandle<C, K>;
@@ -844,8 +877,12 @@ type CrudMethodsOf<C extends AnyContract> = {
 type CrudKindOf<C extends AnyContract, M extends MethodName<C>> = C["methods"][M] extends {
     readonly "~crud"?: infer Kind;
 } ? Extract<Kind, CrudMethodName> : never;
-/** What a `custom` access check of a kit method reads from `ctx`. */
-type KitContext = Pick<BaseContext<Principal>, "principal" | "signal" | "log" | "requestId" | "transport">;
+/**
+ * What a `custom` access check of a kit method, and the app's callbacks a
+ * kit calls (`prepare`, `onWrite`, `onChange`, ...), read from `ctx`:
+ * `ctx.access` asks the caller's level on another row.
+ */
+type KitContext = Pick<BaseContext<Principal>, "principal" | "signal" | "log" | "requestId" | "transport" | "access">;
 /** One access form per kit method of `C`: what `crud.handlers`' `access` must give. */
 type CrudAccess<C extends AnyContract> = {
     readonly [M in CrudMethodsOf<C>]: AccessFor<ParsedInputOf<C, M>, KitContext>;
@@ -1232,6 +1269,35 @@ declare function labelOf(name: string): string;
 /** A service's name for people: "taskService" is "Tasks" (4.1's `toDisplayName`). */
 declare function displayNameOf(serviceName: string): string;
 
+/**
+ * A write the admin kit is about to make, as `prepare` hears it: `data` is
+ * the caller's data, checked; `before` is the row before the write, every
+ * field, read in the write's transaction (as `onWrite` hears it).
+ */
+type AdminPrepareCall<Row = unknown> = {
+    readonly method: "adminCreate";
+    readonly data: AdminData<Row>;
+} | {
+    readonly method: "adminUpdate";
+    readonly id: string;
+    readonly data: AdminData<Row>;
+    readonly before: Row;
+} | {
+    readonly method: "adminDelete";
+    readonly id: string;
+    readonly before: Row;
+};
+/**
+ * `admin.handlers`' `prepare`: runs before each write the kit makes, inside
+ * one transaction with it, after the caller's access and data were checked,
+ * with that transaction's tracked client as `db` (the app's client type
+ * `Db`, when `db` is annotated): its own writes commit with the edit, and a
+ * throw undoes them and the edit and fails the call. Before `adminCreate`
+ * and `adminUpdate` it may return column values, merged over the caller's
+ * data (each anchor column among them checked at the method's row level);
+ * what it returns before `adminDelete` is ignored.
+ */
+type AdminPrepare<Row = unknown, Db = unknown> = (call: AdminPrepareCall<Row>, ctx: KitContext, db: Db) => MaybePromise<Readonly<Record<string, unknown>> | void>;
 /** A write the admin kit made, as `onWrite` hears it. */
 interface AdminWrite<Row = unknown> {
     /** The method that wrote. */
@@ -1289,7 +1355,7 @@ type AdminFieldOverride = Partial<Pick<AdminFieldConfig, "type" | "label" | "req
 type NotAnAdminMethod<C extends AnyContract, A> = [Exclude<keyof A, AdminMethodsOf<C>>] extends [
     never
 ] ? unknown : `admin.handlers: ${Exclude<keyof A, AdminMethodsOf<C>> & string} is not a method admin.contract made for ${C["name"]}`;
-/** The options of `admin.handlers(contract, options)`. `Db` comes from an annotated `onWrite` `db`. */
+/** The options of `admin.handlers(contract, options)`. `Db` comes from an annotated `db` of `prepare` or `onWrite`. */
 interface AdminHandlersOptions<C extends AnyContract, A, Db = unknown> {
     /**
      * Forms that replace the kit's default, `{ service: "Admin" }`, per method.
@@ -1351,14 +1417,49 @@ interface AdminHandlersOptions<C extends AnyContract, A, Db = unknown> {
      * here, since any caller the form admits reaches any row by its id.
      */
     readonly rowless?: readonly AdminMethodsOf<C>[];
+    /**
+     * Runs before each write `adminCreate`, `adminUpdate` or `adminDelete`
+     * makes, in one transaction with it and `onWrite`, once the caller's
+     * access and data were checked: `{ method: "adminCreate", data }`,
+     * `{ method: "adminUpdate", id, data, before }` or
+     * `{ method: "adminDelete", id, before }` (`data` the caller's, `before`
+     * the row, every field), the call's `ctx`, and the transaction's tracked
+     * client as `db`. A throw fails the call and undoes everything.
+     *
+     * Before `adminCreate` and `adminUpdate` it may return column values,
+     * merged over the caller's data and written: a column the server computes
+     * (a hash, a slug), even one the caller may not write (hidden, not
+     * editable, above the caller's level, an owner column the policy reads),
+     * but never `id`, a timestamp, a relation or a nested write (`VALIDATION`).
+     * An anchor column it sets (an `inherit` parent, an anchored collection's
+     * scope) must name a row on which the caller has the method's row level
+     * (`FORBIDDEN`), as for the caller's data and the read/write kit's
+     * `prepare`: a lowered form never moves a row into a parent its caller
+     * cannot reach. Returning nothing, or `undefined` for a key, keeps the
+     * caller's data. What it returns before `adminDelete` is ignored.
+     *
+     * Its writes through `db` are tracked like any other: before a delete,
+     * delete or clear there the rows the database would delete or clear with
+     * the row (a cascade, `SET NULL`), which the tracked client never sees,
+     * so the rows and lists open on them are told.
+     *
+     * @example
+     * prepare: async (call, ctx, db: PrismaClient) => {
+     *   if (call.method === "adminDelete") {
+     *     // the database deletes a project's tasks with it: delete them first, tracked
+     *     await db.task.deleteMany({ where: { projectId: call.id } });
+     *   }
+     * },
+     */
+    readonly prepare?: AdminPrepare<EntityOf<C>, Db>;
     /**
      * Runs after each write `adminCreate`, `adminUpdate` or `adminDelete`
      * makes, in one transaction with it: `{ method, id, before?, after }` and
      * the call's `ctx`, with the transaction's tracked client as `db`. A
      * throw undoes the write and fails the call. For what an admin edit must
      * set off (a game reloading its tunables, an audit row) without wrapping
-     * the kit's handlers. Without it the kit opens no transaction and reads
-     * no `before`.
+     * the kit's handlers. Without it, `prepare` or `onCommitted`, the kit
+     * opens no transaction and reads no `before`.
      *
      * @example
      * onWrite: ({ method, after }) => {
@@ -1407,10 +1508,11 @@ type Empty = Record<never, never>;
 declare function handlers<C extends AnyContract, const A extends AdminAccess<C> = Empty, Db = unknown>(contract: C & NoInfer<AdminContract<C>>, options?: AdminHandlersOptions<C, A, Db>): AdminImplementations<C, A, Db>;
 /**
  * The admin kit: `admin.handlers(contract, { access?, displayName?,
- * hiddenFields?, editable?, fieldOverrides?, rowless?, grants? })` implements the
- * methods `admin.contract` made in `contract`, each open to a service-wide
- * `Admin` grant unless `access` gives another form. `admin.contract` is here
- * too, for server code; a shared package imports it from the root export.
+ * hiddenFields?, editable?, fieldOverrides?, rowless?, grants?, prepare?,
+ * onWrite?, onCommitted? })` implements the methods `admin.contract` made in
+ * `contract`, each open to a service-wide `Admin` grant unless `access` gives
+ * another form. `admin.contract` is here too, for server code; a shared
+ * package imports it from the root export.
  */
 declare const admin: Readonly<{
     contract: <const O extends AdminContractOptions>(options: O & NoInfer<O extends {
@@ -1447,7 +1549,9 @@ declare const admin: Readonly<{
  * option; docs/deploying.md). When the subscribing connection comes back
  * after a drop, the node's clients are told to reconnect within 2 seconds,
  * so they catch up on what the node missed; a publish Valkey did not take
- * is logged rather than left unhandled (`cluster/adapterClients.ts`).
+ * is logged rather than left unhandled (`cluster/adapterClients.ts`). Once
+ * the adapter is set, the node asks the others for the hosts of their app
+ * rooms, as a node started with a cluster adapter does (`realtime/hosts.ts`).
  *
  * @example
  * ```typescript
@@ -1658,4 +1762,4 @@ declare function decryptIfEncrypted(value: string): string;
 /** Safe wrapper that returns `null` instead of throwing on invalid/stale ciphertext. */
 declare function tryDecrypt(ciphertext: string, logger?: Logger): string | null;
 
-export { ADMIN_HIDDEN_FIELDS, AccessEngine, AccessFilter, AccessFor, type AccessMap, AccessPolicy, type AdminAccess, type AdminContract, type AdminDefaultAccess, type AdminFieldOf, type AdminFieldOverride, type AdminHandlersOptions, type AdminImplementations, type AdminOnCommitted, type AdminOnWrite, type AdminOutputOf, type AdminWrite, type AffectsOption, AnyAccessPolicy, BaseContext, type BasicAccessEngineOptions, CHANNEL_ABUSE_MULTIPLIER, CHANNEL_ABUSE_WINDOW_MS, CallerFor, ChannelOptions, ChannelsRequired, type CollectionOption, type CollectionOptions, type CollectionsRequired, ContextExtensionOf, type ContextFactory, type CrudAccess, type CrudCreateOf, type CrudHandlersOptions, type CrudImplementations, type CrudKindOf, type CrudMethodsOf, type CrudPrepare, CustomAccess, DbOf, type DefineService, Dispatcher, DispatcherCollections, DispatcherOptions, type EnvValidationResult, HandlerArgs, HandlerContext, type HandlerOutputOf, type HandlerRow, INDEX_MAX_ROWS, type InheritOptions, type InitArgs, type InitOptions, type JsonAclOptions, type JsonColumnValue, type KitContext, type KitHandler, type KitHandlerArgs, MAX_APP_ROOMS, MAX_ITEM_IDS, MAX_STREAMS_PER_SOCKET, MaybePromise, McpContextOf, type MembersOptions, type MethodAccess, type MethodImplementation, ModelColumn, ModelName, type NextOrdinalOptions, ORDINAL_STEP, PRESENCE_MAX_LAST_SEEN, PolicyFor, PolicyTools, Presence, Principal, type PrincipalFor, PrincipalKindOf, PrincipalOf, type ProjectCheck, type ProjectionOption, PublicAccess, type Quickdraw, QuickdrawServer, QuickdrawTypes, RESUME_MAX_AGE_MS, RESUME_MAX_DELTAS, type RedisAdapterOptions, type RedisAdapterResult, type ResolverMembership, type ResolverOptions, type ResolverReads, RoomLeaveHandler, RowAccess, type RowFor, RowForms, type RowFormsOf, RunContext, RunOptions, STREAM_MAX_SCOPES, type SearchAccess, type SearchContract, type SearchHandlersOptions, type SearchIdsOptions, type SearchImplementations, type SearchMethodsOf, type SearchStrategy, type SearchStrategyContext, ServerOptions, ServerRooms, Service, type ServiceDefinition, ShareMode, type SharingAccess, type SharingByNameOf, type SharingChange, type SharingChangeKind, type SharingContract, type SharingDefaultAccess, type SharingHandlersOptions, type SharingImplementations, type SharingKindOf, type SharingMethodsOf, type SharingOnChange, type SharingOptionsArgs, type SharingResolveUser, type SharingUserLookup, StorageWhere, StreamHandle, StreamOptions, type ValidateEnvOptions, WatchAccess, admin, anyOf, checkEnv, createBasicAccessEngine, crud, custom, decrypt, decryptIfEncrypted, displayNameOf, encrypt, everyone, inherit, initQuickdraw, isEncrypted, isRedisAdapterAvailable, jsonAcl, labelOf, meetsLevel, members, nextOrdinal, owner, requireEnv, requireRow, resolver, search, serviceGrant, setupRedisAdapter, sharing, tryDecrypt, validateEnv };
+export { ADMIN_HIDDEN_FIELDS, AccessEngine, AccessFilter, AccessFor, type AccessMap, AccessPolicy, type AdminAccess, type AdminContract, type AdminDefaultAccess, type AdminFieldOf, type AdminFieldOverride, type AdminHandlersOptions, type AdminImplementations, type AdminOnCommitted, type AdminOnWrite, type AdminOutputOf, type AdminPrepare, type AdminPrepareCall, type AdminWrite, type AffectsOption, AnyAccessPolicy, BaseContext, type BasicAccessEngineOptions, CHANNEL_ABUSE_MULTIPLIER, CHANNEL_ABUSE_WINDOW_MS, CallerFor, ChannelOptions, ChannelsRequired, type CollectionOption, type CollectionOptions, type CollectionRequires, type CollectionsRequired, ContextExtensionOf, type ContextFactory, type CrudAccess, type CrudCreateOf, type CrudHandlersOptions, type CrudImplementations, type CrudKindOf, type CrudMethodsOf, type CrudPrepare, CustomAccess, DbOf, type DefineService, Dispatcher, DispatcherCollections, DispatcherOptions, type EnvValidationResult, HandlerArgs, HandlerContext, type HandlerOutputOf, type HandlerRow, HostLeaveHandler, INDEX_MAX_ROWS, type InheritOptions, type InitArgs, type InitOptions, type JsonAclOptions, type JsonColumnValue, type KitContext, type KitHandler, type KitHandlerArgs, MAX_APP_ROOMS, MAX_ITEM_IDS, MAX_STREAMS_PER_SOCKET, MaybePromise, McpContextOf, type MembersOptions, type MethodAccess, type MethodImplementation, ModelColumn, ModelName, type NextOrdinalOptions, ORDINAL_STEP, PRESENCE_MAX_LAST_SEEN, PolicyFor, PolicyTools, Presence, Principal, type PrincipalFor, PrincipalKindOf, PrincipalOf, type ProjectCheck, type ProjectionOption, PublicAccess, type Quickdraw, QuickdrawServer, QuickdrawTypes, RESUME_MAX_AGE_MS, RESUME_MAX_DELTAS, type RedisAdapterOptions, type RedisAdapterResult, type ResolverMembership, type ResolverOptions, type ResolverReads, RoomLeaveHandler, RowAccess, type RowFor, RowForms, type RowFormsOf, RunContext, RunOptions, STREAM_MAX_SCOPES, type SearchAccess, type SearchContract, type SearchHandlersOptions, type SearchIdsOptions, type SearchImplementations, type SearchMethodsOf, type SearchStrategy, type SearchStrategyContext, ServerOptions, ServerRooms, Service, type ServiceDefinition, ShareMode, type SharingAccess, type SharingByNameOf, type SharingChange, type SharingChangeKind, type SharingContract, type SharingDefaultAccess, type SharingHandlersOptions, type SharingImplementations, type SharingKindOf, type SharingMethodsOf, type SharingOnChange, type SharingOptionsArgs, type SharingResolveUser, type SharingUserLookup, StorageWhere, StreamHandle, StreamOptions, type ValidateEnvOptions, WatchAccess, admin, anyOf, checkEnv, createBasicAccessEngine, crud, custom, decrypt, decryptIfEncrypted, displayNameOf, encrypt, everyone, inherit, initQuickdraw, isEncrypted, isRedisAdapterAvailable, jsonAcl, labelOf, meetsLevel, members, nextOrdinal, owner, requireEnv, requireRow, resolver, search, serviceGrant, setupRedisAdapter, sharing, tryDecrypt, validateEnv };