@fitzzero/quickdraw-core 5.1.1 → 5.1.3

package/dist/{caller-CXTFswBO.d.ts → caller-BTwGl7vm.d.ts}

@@ -1,10 +1,10 @@
-import { ad as Version, a5 as Revision } from './envelope-Cp3YcVxC.js';
-import { L as Logger } from './logger-BY28acW-.js';
-import { A as AccessLevel, J as AnyContract, y as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, ag as EventName, ah as EventPayloadOf, aa as ChannelName, ab as ChannelPayloadOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, ae as ContractMap, ap as MethodName, al as InputOf, ar as OutputOf } from './infer-Teo1xpsd.js';
-import { P as Principal, Q as QuickdrawTypes, M as MaybePromise, c as PrincipalOf, a as McpContext, T as Transport, C as ContextExtensionOf, b as McpContextOf, D as DbOf } from './types-Cu0vmx7c.js';
+import { A as AccessLevel, J as AnyContract, y as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, ag as EventName, ah as EventPayloadOf, aB as ServerChannelName, ab as ChannelPayloadOf, aa as ChannelName, aC as ServerStreamName, az as StreamName, am as IsScopedStream, ay as StreamItemOf, ae as ContractMap, ap as MethodName, al as InputOf, ar as OutputOf } from './infer-Br62cnyW.js';
+import { P as Principal, Q as QuickdrawTypes, M as MaybePromise, b as PrincipalOf, a as McpContext, T as Transport, C as ContextExtensionOf, c as McpContextOf, D as DbOf } from './types-CLRCQGnO.js';
+import { L as Logger } from './logger-Yz93KzdV.js';
+import { aA as Version, as as Revision } from './envelope-BMBaxppV.js';
 
 /** What a development warning is about. */
-type DevWarningKind = "n-plus-one" | "unbounded-read" | "oversized-response" | "nested-write" | "ambient-write" | "batch-read" | "batch-create-many" | "repeated-call" | "tiered-field-in-output" | "resolver-without-reads";
+type DevWarningKind = "n-plus-one" | "unbounded-read" | "oversized-response" | "nested-write" | "ambient-write" | "batch-read" | "batch-create-many" | "repeated-call" | "tiered-field-in-output" | "resolver-without-reads" | "untracked-access-model" | "shared-principal" | "channel-without-requires";
 /** One development warning. */
 interface DevWarning {
     readonly kind: DevWarningKind;
@@ -14,8 +14,8 @@ interface DevWarning {
     /**
      * What the warning is about within its call, for the once-only rule: the
      * model of an ambient write, the model, field and operation of a nested
-     * write, the connection of a repeated call. Empty for the kinds that are
-     * once per call site.
+     * write, the connection of a repeated call, the `ctx` member a shared run
+     * read. Empty for the kinds that are once per call site.
      */
     readonly subject?: string;
     /** What happened and what to do instead. */
@@ -95,11 +95,25 @@ interface StorageAdapter {
     registerInterest(model: string, columns: readonly string[]): void;
     /** The columns registered for `model`. */
     interestOf(model: string): readonly string[];
+    /**
+     * Declares that rows of `model` are the entries of a `via` collection over
+     * the junction `link` names: a `delete` or `deleteMany` of `model` reads
+     * the junction rows linking the rows it deletes just before, through the
+     * open transaction when there is one, and reports them in each write's
+     * `links`, so a flush tells only the scopes a deleted entry was linked to
+     * (the 5.1 audit's COLL-3). A link committed between that read and the
+     * delete is not read (`prisma/links.ts`). Optional: without it a deleted
+     * entry left scopes nobody can name, and every subscribed scope of its
+     * collection is told it was removed.
+     */
+    registerLinks?(model: string, link: LinkInterest): void;
+    /** The junctions registered for `model` (`registerLinks`). */
+    linksOf?(model: string): readonly LinkInterest[];
     /**
      * True where the caller runs inside an open transaction of this adapter,
-     * whose reads see writes that may still roll back. The access cache keeps
-     * nothing read there; an adapter without this method gets no access cache
-     * across requests.
+     * whose reads see writes that may still roll back. The access cache
+     * neither reads nor keeps anything there; an adapter without this method
+     * gets no access cache across requests.
      */
     inTransaction?(): boolean;
     /**
@@ -110,6 +124,15 @@ interface StorageAdapter {
      * cursor shows holding null.
      */
     nullable?(model: string, column: string): Promise<boolean>;
+    /**
+     * Whether the adapter can key `model`'s writes: false for a model without
+     * an `id` column (a table keyed by a composite `@@id`), whose writes are
+     * never tracked. `createServer` asks it, at start, for every model an
+     * access policy, a membership table or a `via` junction depends on, and
+     * names each it cannot track (the `untracked-access-model` warning). An
+     * adapter without it is not asked.
+     */
+    trackable?(model: string): Promise<boolean>;
     /** The units of work that record this adapter's writes; the dispatcher uses them. */
     readonly unitOfWork: UnitOfWorkFactory;
 }
@@ -119,6 +142,17 @@ interface StorageAdapter {
  * `trackPrisma` still carries it.
  */
 declare function storageOf(db: unknown): StorageAdapter | undefined;
+/**
+ * A junction whose rows link an entry model's rows to the scopes of a `via`
+ * collection (`registerLinks`): its model, as the client names it, the
+ * column holding the entry's id, and the columns a delete reads with it (the
+ * scope column, and the role columns of a members table's rule).
+ */
+interface LinkInterest {
+    readonly model: string;
+    readonly entry: string;
+    readonly columns: readonly string[];
+}
 
 /** A principal's level on one row: an access level, or `null` for none. */
 type RowLevel = AccessLevel | null;
@@ -301,7 +335,22 @@ type CollectionScope = {
     readonly scope: string;
     /** A junction write sends its entry again to every scope that still holds it (`via`'s `refreshEntry`). */
     readonly refreshEntry: boolean;
+    /**
+     * The junction is the item service's `members` table: only links whose
+     * role gives at least the collection's `access` count, by one rule per
+     * role column the policy's `members` reads of the table use (a link
+     * any rule counts counts), and a write of a role column can move the
+     * link in or out.
+     */
+    readonly levels?: readonly LinkLevel[];
 };
+/** One role rule of a `via` scope over the item service's `members` table. */
+interface LinkLevel {
+    /** The junction's role column. */
+    readonly column: string;
+    /** The stored roles that give at least the collection's `access`; none: no link counts by this column. */
+    readonly roles: readonly string[];
+}
 /** One collection of a service: its contract declaration and the service's option, checked. */
 interface ServiceCollection {
     readonly name: string;
@@ -319,6 +368,14 @@ interface ServiceCollection {
     readonly access: AccessLevel;
     /** The contract of the rows scope values are ids of; `undefined` for a `"self"` scope. */
     readonly anchor: AnyContract | undefined;
+    /**
+     * The service-wide grant on the collection's service every subscriber needs
+     * besides the anchor or self check (`requires: { service: L }`);
+     * `undefined` for none.
+     */
+    readonly requires: {
+        readonly service: AccessLevel;
+    } | undefined;
     /** More changed rows than this for one scope in one flush go out as one `reset`. */
     readonly bulkThreshold: number;
     /**
@@ -389,6 +446,14 @@ interface ServiceMethod {
      * caller is left to the form.
      */
     readonly kinds: readonly string[] | undefined;
+    /**
+     * The method's requirement on the caller's claims (RFC 0003 section 4.1,
+     * `access/claims.ts`), checked right after `kinds`, outside the access
+     * engine: `UNAUTHENTICATED` without a principal, `FORBIDDEN` unless it
+     * returns `true`. It adds to the access form, and no grant passes it, a
+     * service-wide `Admin` grant included. `undefined` when not declared.
+     */
+    readonly claims: ClaimsCheck | undefined;
     readonly handler: AnyHandler;
     readonly share: ShareMode | undefined;
     /** How long a shared result is reused after its run, in milliseconds. */
@@ -466,6 +531,8 @@ interface Service<T extends QuickdrawTypes = QuickdrawTypes, C extends AnyContra
      * rooms. `undefined` when the service declares none.
      */
     readonly onRoomLeave: RoomLeaveHandler | undefined;
+    /** The service's own `onHostLeave`: `createServer` runs it, beside the server's own, when a room's host leaves. */
+    readonly onHostLeave?: HostLeaveHandler | undefined;
     /** Type-only: the app types the service was defined with. Never set. */
     readonly "~types"?: T;
 }
@@ -524,6 +591,11 @@ interface ScopeAccess<Input = never> {
     readonly service?: never;
     readonly kind?: never;
 }
+/**
+ * A method's `claims`, as the pipeline calls it (`claims.ts`): `true` when
+ * the caller's claims allow the call with `input`.
+ */
+type ClaimsCheck = (claims: Principal["claims"], input: unknown) => boolean;
 /**
  * `custom(fn)`: the call passes when `fn(ctx, input)` resolves `true`. The
  * caller must be authenticated before `fn` runs, so `ctx.principal` is never
@@ -598,11 +670,27 @@ interface RowAccess {
     allows(form: EntryAccess | ScopeAccess, request: AccessRequest): MaybePromise<boolean>;
 }
 
+/**
+ * A row whose access may have changed: who may now see more or less of it.
+ * `id` is the row (the anchor subscriptions record); without it, any row of
+ * the service. `userId` is the user whose level may have changed; without it,
+ * anyone's.
+ */
+interface AccessChange {
+    /** The service name. */
+    readonly service: string;
+    readonly id?: string;
+    readonly userId?: string;
+}
+/** Receives access changes; a promise it returns is awaited before the flush moves on. */
+type AccessChangeListener = (change: AccessChange) => void | PromiseLike<void>;
+
 /**
  * Who is online and who is in a room (RFC 0003 section 12.5): `ctx.presence`,
  * `server.presence`, `qd.presence`. Every answer is a promise: on a server
  * with the in-memory adapter it comes from this process's sockets; behind a
- * cluster adapter (Redis) it asks every node (`io.in(room).fetchSockets()`).
+ * cluster adapter (Redis) it asks the other nodes too, which answer with
+ * user ids (or whether they have a socket of the user) alone.
  */
 interface Presence {
     /** True while the user has a socket connected (on any node). */
@@ -614,9 +702,14 @@ interface Presence {
      * the 100,000 users seen last).
      */
     lastSeen(userId: string): Promise<number | null>;
-    /** How many users have a socket in `room`. Anonymous sockets do not count. */
+    /**
+     * How many users have a socket in app room `room` that `ctx.rooms.join`
+     * put there (a raw `socket.join` does not count on this process).
+     * Anonymous sockets do not count. A framework room (`qd:`, `user:`) or a
+     * name with the shape of a socket id is `VALIDATION`.
+     */
     count(room: string): Promise<number>;
-    /** The ids of the users with a socket in `room`, each once. */
+    /** The ids of the users `count` counts in `room`, each once. */
     users(room: string): Promise<string[]>;
 }
 /** Whose sockets `rooms.leave(room, target)` takes out of a room: every socket of one user. */
@@ -639,8 +732,9 @@ interface ServerRooms {
     /**
      * Sends the contract's event to every socket in `room` as `qd:event`, on
      * every node. The payload is checked against the event's schema first: a
-     * payload that fails it throws `INTERNAL` and nothing is sent. Without a
-     * server it does nothing more.
+     * payload that fails it throws `INTERNAL` and nothing is sent. A room of
+     * the framework's (`qd:`, `user:`) throws `VALIDATION`: send to a user's
+     * sockets with `emitToUser`. Without a server it does nothing more.
      */
     emit<C extends AnyContract, E extends EventName<C>>(room: string, contract: C, event: E, payload: EventPayloadOf<C, E>): void;
     /** `emit` to every socket of one user (their `user:{userId}` room), on every node. */
@@ -670,6 +764,19 @@ interface ServerRooms {
      * it is 0.
      */
     size(room: string): number;
+    /**
+     * The host of app room `room` (host mode, RFC 0003 section 12.5): the id
+     * of the socket that serves the room's host-served channels and streams,
+     * or `null` when it has none. This node's record, which every node of a
+     * cluster keeps. Room names are checked as `join` checks them.
+     */
+    hostOf(room: string): string | null;
+    /**
+     * Leaves app room `room` without a host, on every node: its sockets hear
+     * `qd:host [room, null]`. Nothing happens for a room without one, and
+     * `onHostLeave` does not run (the host did not leave).
+     */
+    clearHost(room: string): void;
 }
 /**
  * `ctx.rooms` (RFC 0003 sections 3, 12.5 and 15): app-defined rooms the
@@ -685,12 +792,28 @@ interface ContextRooms extends ServerRooms {
      * nothing, for a call that did not arrive over a socket (HTTP, MCP, in
      * process). Room names starting with `qd:` or `user:` are refused with
      * `VALIDATION` (those rooms are joined only through their authorized
-     * paths), as are empty names and names over 256 characters; a socket in
-     * 100 app rooms is refused another with `CONFLICT`.
+     * paths), as are names with the shape of a Socket.IO socket id (20
+     * letters, digits, `_` or `-`: every socket is alone in the room of its
+     * id), empty names and names over 256 characters; a socket in 100 app
+     * rooms is refused another with `CONFLICT`.
      */
     join(room: string): boolean;
     /** Takes the calling socket out of an app room; `false` when it was not in it, or the call has no socket. */
     leave(room: string): boolean;
+    /**
+     * Makes the calling socket the host of app room `room` (host mode, RFC
+     * 0003 section 12.5): the room's sockets hear `qd:host [room, socketId]`
+     * on every node, and so does every socket that joins it later, until the
+     * host leaves the room (`onHostLeave` runs), another socket is made its
+     * host, or `clearHost` runs. Its peers then send the room's host-served
+     * channels to it and subscribe to its host-served streams over peer links.
+     * Returns `false`, doing nothing, for a call that did not arrive over a
+     * socket. The socket must be in the room (`FORBIDDEN`) and signed in
+     * (`UNAUTHENTICATED`), and the server must serve peer links
+     * (`createServer({ peers: true })`, else `INTERNAL`). Room names are
+     * checked as `join` checks them.
+     */
+    setHost(room: string): boolean;
     /** See {@link ServerRooms.leave}: every socket of the user, on every node, from any call. */
     leave(room: string, target: RoomTarget): Promise<void>;
 }
@@ -734,10 +857,31 @@ interface RoomLeave<P = Principal> {
  * error it throws is logged; a server's `close()` waits for it.
  */
 type RoomLeaveHandler<P = Principal> = (leave: RoomLeave<P>, ctx: RunContext) => void | PromiseLike<void>;
+/** The host of an app room left it (host mode): what `onHostLeave` hears. */
+interface HostLeave<P = Principal> {
+    readonly room: string;
+    /** The host socket that left. */
+    readonly socketId: string;
+    /** Its principal. */
+    readonly principal: P | null;
+    /** Its own leave, a removal, or a disconnect. */
+    readonly reason: RoomLeaveReason;
+}
+/**
+ * `onHostLeave` (a service's, beside `onRoomLeave`, and `createServer`'s):
+ * called once when the host of an app room leaves it, is taken out of it or
+ * disconnects, on the node that held it, after the room heard
+ * `qd:host [room, null]`, in a unit of work of its own. The room has no
+ * host until a method sets one again: the app decides what follows (another
+ * host, the end of the game).
+ */
+type HostLeaveHandler<P = Principal> = (leave: HostLeave<P>, ctx: RunContext) => void | PromiseLike<void>;
 /** The arguments of a stream's `push`: `(scope, item)` for a scoped stream, `(item)` for a global one. */
 type StreamPushArgs<C extends AnyContract, K extends StreamName<C>> = IsScopedStream<C, K> extends true ? [scope: string, item: StreamItemOf<C, K>] : [item: StreamItemOf<C, K>];
 /** The arguments of a stream's `pushMany`: `(scope, items)` for a scoped stream, `(items)` for a global one. */
 type StreamPushManyArgs<C extends AnyContract, K extends StreamName<C>> = IsScopedStream<C, K> extends true ? [scope: string, items: readonly StreamItemOf<C, K>[]] : [items: readonly StreamItemOf<C, K>[]];
+/** The arguments of a stream's `subscribers`: `(scope)` for a scoped stream, `()` for a global one. */
+type StreamSubscribersArgs<C extends AnyContract, K extends StreamName<C>> = IsScopedStream<C, K> extends true ? [scope: string] : [];
 /** What `qd.stream(contract, name)` returns. */
 interface StreamHandle<C extends AnyContract, K extends StreamName<C>> {
     /**
@@ -754,6 +898,19 @@ interface StreamHandle<C extends AnyContract, K extends StreamName<C>> {
      * with nothing kept or sent. The batch form of a `push` in a loop.
      */
     pushMany(...args: StreamPushManyArgs<C, K>): void;
+    /**
+     * How many sockets subscribe to the feed (`subscribers(scope)`, or
+     * `subscribers()` for a global stream), on every node, anonymous ones
+     * included: a job skips the work nobody watches. These are the sockets in
+     * the feed's room, the ones a push reaches: a subscribe counts from when it
+     * joins the feed, once it is authorized. Behind a cluster adapter the
+     * other nodes answer one request with a count each: an answer that does
+     * not arrive within `cluster.timeoutMs` counts as 0, and so does a node
+     * of an earlier version, which does not know the request. A host-served stream (`serve: "host"`) has no feed on
+     * the server, so, as for `push`, its handle refuses this with a
+     * `TypeError`: only the host's client knows who subscribes.
+     */
+    subscribers(...args: StreamSubscribersArgs<C, K>): Promise<number>;
 }
 /**
  * What a stream's `seed` function receives besides the scope: who is
@@ -815,7 +972,7 @@ type StreamValidation = "always" | "development";
  * subset): a seed computed at subscribe time, and when items are checked.
  */
 type StreamOptions<T extends QuickdrawTypes, C extends AnyContract> = {
-    readonly [K in StreamName<C>]?: StreamImplementation<T, C, K>;
+    readonly [K in ServerStreamName<C>]?: StreamImplementation<T, C, K>;
 };
 /** A stream's `seed` function as the subscribe path calls it, whatever its declared types. */
 type AnyStreamSeed = (scope: string | undefined, ctx: StreamSeedContext) => unknown;
@@ -850,7 +1007,12 @@ interface ChannelContext<P = Principal, Room extends string | undefined = string
 type ChannelHandler<T extends QuickdrawTypes, Payload, Room extends string | undefined = string | undefined> = (payload: Payload, ctx: ChannelContext<PrincipalOf<T>, Room>) => void | PromiseLike<void>;
 /** One channel's implementation in `defineService`: its handler, or `{ access, handler }`. */
 type ChannelImplementation<T extends QuickdrawTypes, Payload, Room extends string | undefined = string | undefined> = ChannelHandler<T, Payload, Room> | {
-    /** Default `"authenticated"`. */
+    /**
+     * Default `"authenticated"`. A channel whose contract declares no
+     * `requires` takes a message from every signed-in socket: declaring
+     * `access` (even `"authenticated"`) says so on purpose, and silences
+     * the `channel-without-requires` warning the server raises otherwise.
+     */
     readonly access?: ChannelAccess;
     readonly handler: ChannelHandler<T, Payload, Room>;
 };
@@ -860,12 +1022,15 @@ type ChannelRoomOf<C extends AnyContract, K extends ChannelName<C>> = C["channel
         readonly room: string | object;
     };
 } ? string : undefined;
-/** `defineService`'s `channels`: one implementation per channel of the contract. */
+/**
+ * `defineService`'s `channels`: one implementation per channel of the
+ * contract the server handles (a host-served one takes none).
+ */
 type ChannelOptions<T extends QuickdrawTypes, C extends AnyContract> = {
-    readonly [K in ChannelName<C>]: ChannelImplementation<T, ChannelPayloadOf<C, K>, ChannelRoomOf<C, K>>;
+    readonly [K in ServerChannelName<C>]: ChannelImplementation<T, ChannelPayloadOf<C, K>, ChannelRoomOf<C, K>>;
 };
 /** `{ channels }` is required when the contract declares channels: every message needs a handler. */
-type ChannelsRequired<C extends AnyContract> = [ChannelName<C>] extends [never] ? unknown : {
+type ChannelsRequired<C extends AnyContract> = [ServerChannelName<C>] extends [never] ? unknown : {
     readonly channels: unknown;
 };
 /**
@@ -920,6 +1085,12 @@ interface ServiceChannel {
         readonly prefix: string;
     } | undefined;
     readonly access: ChannelAccess;
+    /**
+     * True when the service named `access` for the channel (`{ access,
+     * handler }`), not a bare handler or `{ handler }`: a channel without
+     * `requires` warns `channel-without-requires` unless it did.
+     */
+    readonly accessDeclared: boolean;
     /**
      * The kinds of principal the channel's service admits, as a set for the
      * per-message check: a message from a socket of another kind, or without
@@ -950,6 +1121,8 @@ interface ServiceStream {
     readonly access: AccessForm | undefined;
     /** The contract's `access: { room }`: the app room a subscriber's socket must be in. */
     readonly room: StreamRoomAccess | undefined;
+    /** True for a stream the room's host pushes (`serve: "host"`): the server neither pushes nor subscribes it. */
+    readonly host: boolean;
 }
 /** A stream's `access: { room }`, compiled: the app room a subscriber's socket must be in. */
 type StreamRoomAccess = {
@@ -972,10 +1145,10 @@ interface TouchOptions {
  * `ctx.services`: in-process callers for the app's services (RFC 0003
  * sections 3 and 10), by service name: `ctx.services.projectService.get(input)`.
  * A call runs the whole pipeline (input check, access, handler, output
- * check) as the calling principal with transport `"internal"`, its writes
- * join the calling method's unit of work (one flush for both), and it is
- * cancelled with `ctx.signal`. Typed by the `contracts` of the app's types,
- * like `qd.caller`; untyped without them.
+ * check) as the calling principal with transport `"internal"` and the
+ * calling method's `ctx.mcp`, its writes join the calling method's unit of
+ * work (one flush for both), and it is cancelled with `ctx.signal`. Typed by
+ * the `contracts` of the app's types, like `qd.caller`; untyped without them.
  */
 type ContextServices<T extends QuickdrawTypes = QuickdrawTypes> = CallerFor<T>;
 
@@ -1012,7 +1185,10 @@ interface BaseContext<P = Principal, M = McpContext> {
     /**
      * The fields the MCP bridge's `context` option produced for this call, such
      * as the scopes of the agent's token; typed by `QuickdrawTypes["mcp"]`.
-     * `undefined` unless the call arrived over MCP.
+     * `undefined` unless the call arrived over MCP or was made through the
+     * `ctx.services` of a call that has it (nested calls too), which passes
+     * the same object on. Such a call's `transport` is `"internal"`: to tell a
+     * token's call apart, read `ctx.mcp`, not `ctx.transport`.
      */
     readonly mcp?: M;
     /**
@@ -1024,10 +1200,20 @@ interface BaseContext<P = Principal, M = McpContext> {
      */
     touch(target: string | AnyContract, ids: string | readonly string[], options?: TouchOptions): void;
     /**
-     * In-process callers for the app's services, as this call's principal:
-     * `await ctx.services.projectService.get({ id })`. See {@link ContextServices}.
+     * In-process callers for the app's services, as this call's principal and
+     * with its `ctx.mcp`: `await ctx.services.projectService.get({ id })`. See
+     * {@link ContextServices}.
      */
     readonly services: ContextServices;
+    /**
+     * The caller's levels on rows of the app's services, as the access forms
+     * count them (RFC 0003 section 4.3): `dispatcher.access` bound to
+     * `ctx.principal`, with the grants this call runs with. For a `custom`
+     * form that checks a row its key names only sometimes, or a parent its
+     * input names: `await ctx.access.can(project, input.projectId, "Moderate")`.
+     * See {@link ContextAccess}.
+     */
+    readonly access: ContextAccess;
     /**
      * App-defined rooms the calling socket joins and leaves (`join` answers
      * `false` for a call without a socket), and typed room events: `emit` and
@@ -1112,19 +1298,32 @@ interface WriteRecord {
     /** The written row's id. */
     readonly id: string;
     readonly op: "create" | "update" | "delete";
-    /** The fields the write set; `[ANY_FIELD]` when they are unknown. */
+    /**
+     * The fields the write set; `[ANY_FIELD]` when they are unknown. An update
+     * whose data held a nested write, which may set a foreign key through a
+     * relation, lists every interested column of the model besides its keys.
+     */
     readonly fields: readonly string[];
     /**
      * The row before the unit of work wrote it, for its interested columns: an
      * update's old values of the interested columns it changed (read first,
-     * narrowly), or a delete's values. A row the unit created has none.
+     * narrowly), or of every interested column when its data held a nested
+     * write, or a delete's values. A row the unit created has none.
      */
     readonly before?: Readonly<Record<string, unknown>>;
     /** The interested columns' values after the write, when the write returned them. */
     readonly after?: Readonly<Record<string, unknown>>;
+    /**
+     * On a delete of a model whose junction links are registered
+     * (`StorageAdapter.registerLinks`): per junction model, the junction rows
+     * that linked the row just before the delete (possibly none), with the
+     * registered columns. Absent when the links were not read.
+     */
+    readonly links?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
     /**
      * Set on a `create` an `upsert` recorded without reading whether its row
-     * existed (its `update` set no interested column): the row may have been
+     * existed (its `update` set no interested column and held no nested
+     * write, or the model has no interested columns): the row may have been
      * updated rather than created. Only merging reads it: a row created and
      * deleted in one unit is dropped from the flush only when its create is
      * certain.
@@ -1222,6 +1421,70 @@ interface FlushSink {
     onFlushError?(writes: readonly WriteRecord[], info: FlushInfo, error: unknown): void | Promise<void>;
 }
 
+/** The dispatcher's view of its services' access policies: `dispatcher.access`. */
+interface DispatcherAccess {
+    /**
+     * The principal's level on each of `ids` of `service`, as an `{ entry }`
+     * check counts it: the service's policy, or `Admin` on every row when the
+     * principal holds a service-wide `Admin` grant and the service keeps
+     * `adminBypass` on. A grant below `Admin` does not count. A row that is
+     * not found has no level. One batched lookup per policy.
+     */
+    levelsFor(service: AnyContract | string, principal: Principal, ids: readonly string[]): Promise<RowLevels>;
+    /**
+     * A filter for `db.<model>.findMany({ where })` matching exactly the rows of
+     * `service` on which `levelsFor` gives the principal at least `level`:
+     * `{}` (every row) for a service-wide `Admin` with `adminBypass`, or
+     * `"none"` when no row matches.
+     */
+    accessWhere(service: AnyContract | string, principal: Principal, level: AccessLevel): Promise<AccessFilter>;
+    /**
+     * Calls `listener` after each flush whose tracked writes may have changed
+     * someone's access to a row (`AccessChange`), once the cache no longer
+     * holds what they changed. A promise it returns is awaited before the
+     * dispatcher's other flush sinks run. Returns a function that removes it.
+     */
+    onAccessChanged(listener: AccessChangeListener): () => void;
+}
+/**
+ * `ctx.access` (RFC 0003 section 4.3): `dispatcher.access` bound to the
+ * call's caller, `ctx.principal`, with the grants that call runs with (its
+ * socket's, or those `qd.caller` loaded). For a `custom(...)` form or a
+ * handler that asks about a row its method's own form does not name: a
+ * payment's loan, a parent named by an optional key. `service` is a
+ * contract or a service name with an access policy on the dispatcher;
+ * another is a `TypeError`. An anonymous caller (a `"public"` method called
+ * without credentials) has no level on any row.
+ *
+ * @example
+ * access: custom(async (ctx, input) => await ctx.access.can(loan, input.loanId, "Moderate")),
+ */
+interface ContextAccess {
+    /**
+     * The caller's level on each of `ids` of `service`, as an `{ entry }`
+     * check counts it (`dispatcher.access.levelsFor` with `ctx.principal`): a
+     * service-wide `Admin` grant gives `Admin` on every id while the service
+     * keeps `adminBypass` on, and a row that is not found has no level. One
+     * batched lookup per policy. An empty map for an anonymous caller.
+     */
+    levelsFor(service: AnyContract | string, ids: readonly string[]): Promise<RowLevels>;
+    /**
+     * Whether the caller's level on row `id` of `service` is at least `level`,
+     * as `{ entry: level }` decides it on that row: `false` for a row that is
+     * not found (but for a service-wide `Admin` grant, which reaches every id
+     * without reading it, as for `{ entry }`) and for an anonymous caller.
+     */
+    can(service: AnyContract | string, id: string, level: AccessLevel): Promise<boolean>;
+    /**
+     * A filter for `db.<model>.findMany({ where })` matching exactly the rows
+     * of `service` on which `can` gives the caller `level`, for a hand-written
+     * list (`dispatcher.access.accessWhere` with `ctx.principal`): `{}` for a
+     * service-wide `Admin` with `adminBypass`, `"none"` when no row matches
+     * and for an anonymous caller.
+     */
+    where(service: AnyContract | string, level: AccessLevel): Promise<AccessFilter>;
+}
+
 /** Options of one in-process call. */
 interface CallOptions {
     /** Cancels the call (queries only), like a client's `qd:cancel`. */
@@ -1248,4 +1511,4 @@ type CallerFor<T extends QuickdrawTypes> = T extends {
     readonly contracts: infer Contracts extends ContractMap;
 } ? Caller<Contracts[keyof Contracts]> : Caller<AnyContract>;
 
-export { type ProjectedOutput as $, type AnyService as A, type PublicAccess as B, type CountArgs as C, DevWarningError as D, type HandlerArgs as E, type FindManyArgs as F, type CustomAccess as G, type HandlerContext as H, type ShareMode as I, type ChannelOptions as J, type StreamOptions as K, type ChannelsRequired as L, type ModelName as M, type BaseContext as N, type CallerFor as O, type Presence as P, type AccessPolicy as Q, type RowLevels as R, type StorageAdapter as S, type AnyAccessPolicy as T, type UnitOfWorkFactory as U, type PolicyColumns as V, type WriteRecord as W, type PolicyForeign as X, type PolicyTools as Y, type RowAccess as Z, type AffectsLink as _, type StorageRow as a, type Projection as a0, type TierGroup as a1, type Tiers as a2, DEFAULT_BULK_THRESHOLD as a3, type CollectionScope as a4, type ServiceCollection as a5, type ContextRooms as a6, type ContextServices as a7, type TouchOptions as a8, type ChannelAccess as a9, type AccessForm as aA, type AccessRequest as aB, type AuthenticatedAccess as aC, type EntryAccess as aD, type IdKeyOf as aE, type IdSelector as aF, type ScopeAccess as aG, type ServiceAccess as aH, ANY_FIELD as aI, type UnitOfWork as aJ, type UnitOfWorkScope as aK, formatDevWarning as aL, N_PLUS_ONE_STATEMENTS as aM, type ChannelContext as aa, type ChannelHandler as ab, type ChannelImplementation as ac, type ChannelRoomOf as ad, type RoomLeave as ae, type RoomLeaveReason as af, type RoomLeft as ag, type RoomTarget as ah, type ServiceChannel as ai, type ServiceStream as aj, type StreamImplementation as ak, type StreamPushArgs as al, type StreamPushManyArgs as am, type StreamSeed as an, type StreamSeedContext as ao, type StreamValidation as ap, type CallOptions as aq, type MethodCaller as ar, type ServiceCaller as as, type ForeignColumns as at, type ForeignColumnsOf as au, type MembershipRead as av, type ParentLink as aw, type PolicyKind as ax, type PolicyReads as ay, type RowLevel as az, type StorageWhere as b, type StatementCount as c, type Caller as d, type FlushSink as e, type FlushInfo as f, type ServiceMethod as g, type Service as h, type DevWarning as i, type DevWarningKind as j, type AccessFilter as k, type RunContext as l, type RunOptions as m, type ServerRooms as n, type StreamHandle as o, type AnyContext as p, type AccessEngine as q, type AppRooms as r, storageOf as s, type StreamSubscriptions as t, type RoomLeaveHandler as u, type PolicyFor as v, type RowForms as w, type AccessFor as x, type ModelColumn as y, type WatchAccess as z };
+export { type AffectsLink as $, type AnyService as A, type PublicAccess as B, type CountArgs as C, DevWarningError as D, type HandlerArgs as E, type FindManyArgs as F, type CustomAccess as G, type HostLeaveHandler as H, type ShareMode as I, type ChannelOptions as J, type StreamOptions as K, type ChannelsRequired as L, type ModelName as M, type BaseContext as N, type CallerFor as O, type Presence as P, type AccessPolicy as Q, type RunContext as R, type StorageAdapter as S, type AnyAccessPolicy as T, type UnitOfWorkFactory as U, type PolicyColumns as V, type WriteRecord as W, type PolicyForeign as X, type PolicyTools as Y, type AccessFilter as Z, type RowAccess as _, type StorageRow as a, type ProjectedOutput as a0, type Projection as a1, type TierGroup as a2, type Tiers as a3, DEFAULT_BULK_THRESHOLD as a4, type CollectionScope as a5, type ServiceCollection as a6, type ContextAccess as a7, type ContextRooms as a8, type ContextServices as a9, type ParentLink as aA, type PolicyKind as aB, type PolicyReads as aC, type RowLevel as aD, type RowLevels as aE, type AccessChange as aF, type AccessChangeListener as aG, type AccessForm as aH, type AccessRequest as aI, type AuthenticatedAccess as aJ, type EntryAccess as aK, type IdKeyOf as aL, type IdSelector as aM, type ScopeAccess as aN, type ServiceAccess as aO, ANY_FIELD as aP, type UnitOfWork as aQ, type UnitOfWorkScope as aR, type LinkInterest as aS, formatDevWarning as aT, N_PLUS_ONE_STATEMENTS as aU, type TouchOptions as aa, type ChannelAccess as ab, type ChannelContext as ac, type ChannelHandler as ad, type ChannelImplementation as ae, type ChannelRoomOf as af, type HostLeave as ag, type RoomLeave as ah, type RoomLeaveReason as ai, type RoomLeft as aj, type RoomTarget as ak, type ServiceChannel as al, type ServiceStream as am, type StreamImplementation as an, type StreamPushArgs as ao, type StreamPushManyArgs as ap, type StreamSeed as aq, type StreamSeedContext as ar, type StreamSubscribersArgs as as, type StreamValidation as at, type CallOptions as au, type MethodCaller as av, type ServiceCaller as aw, type ForeignColumns as ax, type ForeignColumnsOf as ay, type MembershipRead as az, type StorageWhere as b, type StatementCount as c, type Caller as d, type FlushSink as e, type FlushInfo as f, type ServiceMethod as g, type Service as h, type DevWarning as i, type DevWarningKind as j, type RunOptions as k, type DispatcherAccess as l, type ServerRooms as m, type StreamHandle as n, type AnyContext as o, type AccessEngine as p, type AppRooms as q, type StreamSubscriptions as r, storageOf as s, type RoomLeaveHandler as t, type PolicyFor as u, type RowForms as v, type AccessFor as w, type HandlerContext as x, type ModelColumn as y, type WatchAccess as z };

package/dist/chunk-2FDSKLBO.js

@@ -0,0 +1,82 @@
+import {
+  MAX_PEER_CANDIDATE_LENGTH,
+  MAX_PEER_SIGNAL_LENGTH,
+  MAX_SCOPE_LENGTH
+} from "./chunk-X4ZU4QH5.js";
+import {
+  isRecord
+} from "./chunk-QSU47XEX.js";
+
+// src/protocol/peer.ts
+var MAX_SOCKET_ID_LENGTH = 64;
+function isText(value) {
+  return typeof value === "string" && value.length <= MAX_PEER_SIGNAL_LENGTH;
+}
+function isCandidateText(value) {
+  return typeof value === "string" && value.length <= MAX_PEER_CANDIDATE_LENGTH;
+}
+function isRoomName(value) {
+  return typeof value === "string" && value !== "" && value.length <= MAX_SCOPE_LENGTH;
+}
+function isSocketId(value) {
+  return typeof value === "string" && value !== "" && value.length <= MAX_SOCKET_ID_LENGTH;
+}
+function isPeerLabel(value) {
+  return value === "rel" || value === "fast";
+}
+function nullable(value, check) {
+  return value === void 0 || value === null || check(value);
+}
+function isLineIndex(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function readDescription(value) {
+  if (!isRecord(value) || value.type !== "offer" && value.type !== "answer") {
+    return void 0;
+  }
+  return isText(value.sdp) ? { type: value.type, sdp: value.sdp } : void 0;
+}
+function readCandidate(value) {
+  if (!isRecord(value) || !isCandidateText(value.candidate)) {
+    return void 0;
+  }
+  const { sdpMid, sdpMLineIndex, usernameFragment } = value;
+  if (!nullable(sdpMid, isCandidateText) || !nullable(sdpMLineIndex, isLineIndex) || !nullable(usernameFragment, isCandidateText)) {
+    return void 0;
+  }
+  return {
+    candidate: value.candidate,
+    ...sdpMid === void 0 ? {} : { sdpMid },
+    ...sdpMLineIndex === void 0 ? {} : { sdpMLineIndex },
+    ...usernameFragment === void 0 ? {} : { usernameFragment }
+  };
+}
+function readSignal(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const { sdp, ice, relay, bye } = value;
+  if ([sdp, ice, relay, bye].filter((member) => member !== void 0).length !== 1) {
+    return void 0;
+  }
+  if (sdp !== void 0) {
+    const description = readDescription(sdp);
+    return description === void 0 ? void 0 : { sdp: description };
+  }
+  if (ice !== void 0) {
+    const candidate = readCandidate(ice);
+    return candidate === void 0 ? void 0 : { ice: candidate };
+  }
+  if (relay === true) {
+    return { relay: true };
+  }
+  return bye === true ? { bye: true } : void 0;
+}
+
+export {
+  isRoomName,
+  isSocketId,
+  isPeerLabel,
+  readSignal
+};
+//# sourceMappingURL=chunk-2FDSKLBO.js.map

package/dist/chunk-2FDSKLBO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol/peer.ts"],"sourcesContent":["// Reading peer link signals (RFC 0003 section 12.5), for the server that\n// forwards them and the client that applies them. A signal is copied member\n// by member, so what goes on is only what was read: a session description\n// of at most `MAX_PEER_SIGNAL_LENGTH` characters, an ICE candidate whose\n// strings hold at most `MAX_PEER_CANDIDATE_LENGTH`, `relay` or `bye`.\n// Internal: neither the package root nor `./client` exports these.\n\nimport type { PeerCandidate, PeerDescription, PeerLabel, PeerSignal } from \"./envelope\";\nimport { isRecord } from \"./guards\";\nimport { MAX_PEER_CANDIDATE_LENGTH, MAX_PEER_SIGNAL_LENGTH, MAX_SCOPE_LENGTH } from \"./version\";\n\n/** The longest socket id a peer frame may name. Socket.IO's are 20 characters. */\nexport const MAX_SOCKET_ID_LENGTH = 64;\n\n/** True for a string of at most `MAX_PEER_SIGNAL_LENGTH` characters, empty included. */\nfunction isText(value: unknown): value is string {\n  return typeof value === \"string\" && value.length <= MAX_PEER_SIGNAL_LENGTH;\n}\n\n/** True for a string of at most `MAX_PEER_CANDIDATE_LENGTH` characters, empty included. */\nfunction isCandidateText(value: unknown): value is string {\n  return typeof value === \"string\" && value.length <= MAX_PEER_CANDIDATE_LENGTH;\n}\n\n/** True for what may name an app room: 1 to `MAX_SCOPE_LENGTH` characters. */\nexport function isRoomName(value: unknown): value is string {\n  return typeof value === \"string\" && value !== \"\" && value.length <= MAX_SCOPE_LENGTH;\n}\n\n/** True for what may name a socket: 1 to `MAX_SOCKET_ID_LENGTH` characters. */\nexport function isSocketId(value: unknown): value is string {\n  return typeof value === \"string\" && value !== \"\" && value.length <= MAX_SOCKET_ID_LENGTH;\n}\n\n/** True for `rel` and `fast`. */\nexport function isPeerLabel(value: unknown): value is PeerLabel {\n  return value === \"rel\" || value === \"fast\";\n}\n\n/** True when `value` is absent, `null`, or passes `check`. */\nfunction nullable(value: unknown, check: (inner: unknown) => boolean): boolean {\n  return value === undefined || value === null || check(value);\n}\n\nfunction isLineIndex(value: unknown): boolean {\n  return typeof value === \"number\" && Number.isSafeInteger(value) && value >= 0;\n}\n\nfunction readDescription(value: unknown): PeerDescription | undefined {\n  if (!isRecord(value) || (value.type !== \"offer\" && value.type !== \"answer\")) {\n    return undefined;\n  }\n  return isText(value.sdp) ? { type: value.type, sdp: value.sdp } : undefined;\n}\n\nfunction readCandidate(value: unknown): PeerCandidate | undefined {\n  if (!isRecord(value) || !isCandidateText(value.candidate)) {\n    return undefined;\n  }\n  const { sdpMid, sdpMLineIndex, usernameFragment } = value;\n  if (\n    !nullable(sdpMid, isCandidateText) ||\n    !nullable(sdpMLineIndex, isLineIndex) ||\n    !nullable(usernameFragment, isCandidateText)\n  ) {\n    return undefined;\n  }\n  return {\n    candidate: value.candidate,\n    ...(sdpMid === undefined ? {} : { sdpMid: sdpMid as string | null }),\n    ...(sdpMLineIndex === undefined ? {} : { sdpMLineIndex: sdpMLineIndex as number | null }),\n    ...(usernameFragment === undefined\n      ? {}\n      : { usernameFragment: usernameFragment as string | null }),\n  };\n}\n\n/**\n * The signal `value` holds, copied, or `undefined` unless it holds exactly\n * one of `sdp`, `ice`, `relay: true` and `bye: true`, well formed. Fields\n * it does not know are left behind.\n */\nexport function readSignal(value: unknown): PeerSignal | undefined {\n  if (!isRecord(value)) {\n    return undefined;\n  }\n  const { sdp, ice, relay, bye } = value;\n  if ([sdp, ice, relay, bye].filter((member) => member !== undefined).length !== 1) {\n    return undefined;\n  }\n  if (sdp !== undefined) {\n    const description = readDescription(sdp);\n    return description === undefined ? undefined : { sdp: description };\n  }\n  if (ice !== undefined) {\n    const candidate = readCandidate(ice);\n    return candidate === undefined ? undefined : { ice: candidate };\n  }\n  if (relay === true) {\n    return { relay: true };\n  }\n  return bye === true ? { bye: true } : undefined;\n}\n"],"mappings":";;;;;;;;;;AAYO,IAAM,uBAAuB;AAGpC,SAAS,OAAO,OAAiC;AAC/C,SAAO,OAAO,UAAU,YAAY,MAAM,UAAU;AACtD;AAGA,SAAS,gBAAgB,OAAiC;AACxD,SAAO,OAAO,UAAU,YAAY,MAAM,UAAU;AACtD;AAGO,SAAS,WAAW,OAAiC;AAC1D,SAAO,OAAO,UAAU,YAAY,UAAU,MAAM,MAAM,UAAU;AACtE;AAGO,SAAS,WAAW,OAAiC;AAC1D,SAAO,OAAO,UAAU,YAAY,UAAU,MAAM,MAAM,UAAU;AACtE;AAGO,SAAS,YAAY,OAAoC;AAC9D,SAAO,UAAU,SAAS,UAAU;AACtC;AAGA,SAAS,SAAS,OAAgB,OAA6C;AAC7E,SAAO,UAAU,UAAa,UAAU,QAAQ,MAAM,KAAK;AAC7D;AAEA,SAAS,YAAY,OAAyB;AAC5C,SAAO,OAAO,UAAU,YAAY,OAAO,cAAc,KAAK,KAAK,SAAS;AAC9E;AAEA,SAAS,gBAAgB,OAA6C;AACpE,MAAI,CAAC,SAAS,KAAK,KAAM,MAAM,SAAS,WAAW,MAAM,SAAS,UAAW;AAC3E,WAAO;AAAA,EACT;AACA,SAAO,OAAO,MAAM,GAAG,IAAI,EAAE,MAAM,MAAM,MAAM,KAAK,MAAM,IAAI,IAAI;AACpE;AAEA,SAAS,cAAc,OAA2C;AAChE,MAAI,CAAC,SAAS,KAAK,KAAK,CAAC,gBAAgB,MAAM,SAAS,GAAG;AACzD,WAAO;AAAA,EACT;AACA,QAAM,EAAE,QAAQ,eAAe,iBAAiB,IAAI;AACpD,MACE,CAAC,SAAS,QAAQ,eAAe,KACjC,CAAC,SAAS,eAAe,WAAW,KACpC,CAAC,SAAS,kBAAkB,eAAe,GAC3C;AACA,WAAO;AAAA,EACT;AACA,SAAO;AAAA,IACL,WAAW,MAAM;AAAA,IACjB,GAAI,WAAW,SAAY,CAAC,IAAI,EAAE,OAAgC;AAAA,IAClE,GAAI,kBAAkB,SAAY,CAAC,IAAI,EAAE,cAA8C;AAAA,IACvF,GAAI,qBAAqB,SACrB,CAAC,IACD,EAAE,iBAAoD;AAAA,EAC5D;AACF;AAOO,SAAS,WAAW,OAAwC;AACjE,MAAI,CAAC,SAAS,KAAK,GAAG;AACpB,WAAO;AAAA,EACT;AACA,QAAM,EAAE,KAAK,KAAK,OAAO,IAAI,IAAI;AACjC,MAAI,CAAC,KAAK,KAAK,OAAO,GAAG,EAAE,OAAO,CAAC,WAAW,WAAW,MAAS,EAAE,WAAW,GAAG;AAChF,WAAO;AAAA,EACT;AACA,MAAI,QAAQ,QAAW;AACrB,UAAM,cAAc,gBAAgB,GAAG;AACvC,WAAO,gBAAgB,SAAY,SAAY,EAAE,KAAK,YAAY;AAAA,EACpE;AACA,MAAI,QAAQ,QAAW;AACrB,UAAM,YAAY,cAAc,GAAG;AACnC,WAAO,cAAc,SAAY,SAAY,EAAE,KAAK,UAAU;AAAA,EAChE;AACA,MAAI,UAAU,MAAM;AAClB,WAAO,EAAE,OAAO,KAAK;AAAA,EACvB;AACA,SAAO,QAAQ,OAAO,EAAE,KAAK,KAAK,IAAI;AACxC;","names":[]}