@fitzzero/quickdraw-core 3.9.1 → 4.1.0

package/dist/server/index.d.ts

@@ -1,10 +1,158 @@
-import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, A as AdminListPayload, c as AdminListResponse, d as AdminSetACLPayload, e as AdminSubscribersResponse, S as ServiceRegistryInstance, B as BaseServiceInstance, f as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-ClgSr90l.js';
+import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, S as ServiceRegistryInstance, B as BaseServiceInstance, c as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-87lWXyNP.js';
+export { d as QuickdrawIdentity } from '../types-87lWXyNP.js';
 import { Server, Socket } from 'socket.io';
 import { z } from 'zod';
-import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, ServiceChannelContext, ServiceChannelDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
+import { CollectionSnapshotPage, Logger, CollectionSubscribePayload, CollectionSnapshotResponse, CollectionUnsubscribePayload, ACL, AccessLevel, QuickdrawEventName, QuickdrawEventData, ServiceMethodContext, ServiceMethodDefinition, ServiceChannelContext, ServiceChannelDefinition, AdminServiceMeta, AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, AdminFieldConfig } from '../shared/index.js';
 import { Router } from 'express';
 import 'http';
 
+/**
+ * A scope-keyed collection of a service's rows.
+ *
+ * A collection is "rows of this service, grouped by a scope id derived from
+ * the row" (`task.projectId`, `message.chatId`, `chatMember.userId`).
+ * Membership is a pure function of the row — that is what makes automatic
+ * add/remove/update emission, room-based multi-node fanout, and one-line ACL
+ * zero-thought.
+ *
+ * **ACL model (deliberate simplification):** a collection item is
+ * *scope-visible* — anyone who passes `checkScopeAccess` sees every item in
+ * full. There is no per-subscriber field tiering inside a collection; if a
+ * field is sensitive, strip it in `toItem`/`snapshot`. If visibility varies
+ * per user within a scope, that is not a collection — model it as separate
+ * scopes or per-entity subscriptions.
+ */
+interface CollectionDefinition<TEntity, TItem extends {
+    id: string;
+}> {
+    /**
+     * Which scope(s) a row belongs to. `null` = not in this collection
+     * (static predicate filtering). An array supports fan-out scopes
+     * (e.g. a chat appearing in every member's "myChats").
+     */
+    resolveScopeId: (entity: TEntity) => string | string[] | null | Promise<string | string[] | null>;
+    /** ACL for joining the scope room. Runs once at subscribe time. */
+    checkScopeAccess: (userId: string, scopeId: string, socket: QuickdrawSocket) => boolean | Promise<boolean>;
+    /** Initial page + re-snapshot query. Server-ordered. */
+    snapshot: (scopeId: string, opts: {
+        cursor: string | null;
+        limit: number;
+        userId: string;
+    }) => Promise<CollectionSnapshotPage<TItem>>;
+    /**
+     * Row -> collection item DTO for automatic delta emission.
+     * May be async (fetch with includes). Default: the service's `toDto`.
+     */
+    toItem?: (entity: TEntity) => TItem | Promise<TItem>;
+    /** Default page size for snapshot requests. Default 100, max clamp 500. */
+    defaultLimit?: number;
+    /**
+     * Revision source for `added`/`updated` deltas, instead of `Date.now()`
+     * at emit. Must return epoch-milliseconds-comparable numbers (e.g. the
+     * row's `updatedAt`). Use when multi-node clock skew bites.
+     */
+    revOf?: (item: TItem) => number;
+}
+/**
+ * A write observed by the CRUD trio, fed to {@link CollectionManager.notify}
+ * for automatic delta emission.
+ */
+type CollectionWriteEvent<TEntity> = {
+    type: "create";
+    after: TEntity;
+} | {
+    type: "update";
+    before: TEntity | null;
+    after: TEntity;
+} | {
+    type: "delete";
+    before: TEntity;
+};
+interface CollectionManagerOptions<TEntity> {
+    serviceName: string;
+    getIo: () => Server | null;
+    logger: Logger;
+    /** Fallback item mapper when a definition has no `toItem` (the service's `toDto`). */
+    defaultToItem: (entity: TEntity) => {
+        id: string;
+    } | Promise<{
+        id: string;
+    }>;
+}
+/**
+ * Per-service collection state and emission logic: holds definitions, serves
+ * snapshot subscriptions, and turns write events into scope-room deltas.
+ *
+ * All emission is room-based (`io.to(room).emit`) — Redis-adapter-safe by
+ * construction. No collection state lives in any in-process subscriber map.
+ */
+declare class CollectionManager<TEntity extends {
+    id: string;
+}> {
+    private readonly definitions;
+    private readonly serviceName;
+    private readonly getIo;
+    private readonly logger;
+    private readonly defaultToItem;
+    constructor(options: CollectionManagerOptions<TEntity>);
+    define(name: string, config: CollectionDefinition<TEntity, {
+        id: string;
+    }>): void;
+    getAll(): Map<string, CollectionDefinition<TEntity, {
+        id: string;
+    }>>;
+    get size(): number;
+    /**
+     * Handle a `{service}:collection:subscribe`.
+     *
+     * Cursor-less: ACL check, join the scope room, snapshot with `ids`.
+     * Cursor-bearing: pure paging — ACL check, no room join, `ids` stripped
+     * (pruning against a partial page would drop valid cached rows).
+     *
+     * Returns `null` on access denial or unknown collection (indistinguishable
+     * to the client, mirroring entity subscribe semantics).
+     */
+    subscribe(payload: CollectionSubscribePayload, socket: QuickdrawSocket): Promise<CollectionSnapshotResponse<{
+        id: string;
+    }> | null>;
+    /** Handle a `{service}:collection:unsubscribe` — leave the scope room. */
+    unsubscribe(payload: CollectionUnsubscribePayload, socket: QuickdrawSocket): void;
+    /**
+     * Turn a write event into deltas for every collection on the service.
+     *
+     * - create: `added` to each scope of `after`.
+     * - update: diff scopes of `before` vs `after` — in both → `updated`,
+     *   `after` only → `added`, `before` only → `removed`. Scope moves and
+     *   predicate entry/exit fall out for free.
+     * - delete: `removed` to each scope of `before`.
+     *
+     * Errors in app-provided callbacks are logged, never thrown — the write
+     * has already committed; emission failures must not fail the response.
+     */
+    notify(event: CollectionWriteEvent<TEntity>): Promise<void>;
+    private notifyOne;
+    /** Emit `updated` (client upserts; added-vs-updated is cosmetic). */
+    emitUpsert(collection: string, scopeId: string, item: {
+        id: string;
+    }): void;
+    emitRemove(collection: string, scopeId: string, id: string): void;
+    /** A move is removed-from-old + added-to-new. */
+    emitMove(collection: string, fromScopeId: string, toScopeId: string, item: {
+        id: string;
+    }): void;
+    /** Clients re-snapshot (debounced) — for bulk ops and mass reorders. */
+    emitReset(collection: string, scopeId: string): void;
+    /**
+     * Force sockets out of a scope room — ACL revocation that works across
+     * nodes (`socketsLeave` is adapter-safe). With `userId`, only that user's
+     * sockets are kicked; without, the whole room is cleared.
+     */
+    kickFromCollection(collection: string, scopeId: string, userId?: string): void;
+    private toItem;
+    private revFor;
+    private emitDelta;
+}
+
 /**
  * Base class for all quickdraw services.
  *
@@ -20,6 +168,8 @@ import 'http';
  * @typeParam TUpdateInput - The update input type
  * @typeParam TServiceMethods - Service method definitions map
  * @typeParam TChannels - Service channel payload map (high-frequency fire-and-forget events)
+ * @typeParam TDto - The wire shape emitted to subscribers (defaults to TEntity; see `toDto`)
+ * @typeParam TCollections - Collection map: name -> { item } (see `defineCollection`)
  *
  * @example
  * ```typescript
@@ -51,7 +201,19 @@ declare abstract class BaseService<TEntity extends {
     response: unknown;
 }>, TChannels extends {
     [K in keyof TChannels]: unknown;
-} = Record<string, unknown>> {
+} = Record<string, unknown>, TDto extends {
+    id: string;
+} = TEntity, TCollections extends {
+    [K in keyof TCollections]: {
+        item: {
+            id: string;
+        };
+    };
+} = Record<string, {
+    item: {
+        id: string;
+    };
+}>> {
     readonly serviceName: string;
     protected readonly hasEntryACL: boolean;
     protected readonly defaultACL: ACL;
@@ -61,6 +223,7 @@ declare abstract class BaseService<TEntity extends {
     protected io: Server | null;
     private readonly publicMethods;
     private readonly publicChannels;
+    private readonly collections;
     private adminMeta;
     constructor(options: BaseServiceOptions);
     /**
@@ -80,14 +243,20 @@ declare abstract class BaseService<TEntity extends {
     /**
      * Get the Socket.io room name for an entry.
      * Used for room-based broadcasting across services.
+     * Static counterpart: `serviceRoom(serviceName, entryId)` from the root export.
      */
     getRoomName(entryId: string): string;
     /**
      * Subscribe a socket to an entity's updates.
-     * Returns the current entity data if access is granted, null otherwise.
-     * Also joins the socket to the entity's Socket.io room for cross-service events.
+     * Returns the current entity data (as the wire DTO, filtered for the
+     * subscriber's tier) if access is granted, null otherwise.
+     *
+     * Joins the entity's Socket.io room; subscribers with elevated access
+     * additionally join `{room}:full` so `emitUpdate` can address the two
+     * tiers as rooms (adapter-safe). The tier is fixed here, at subscribe
+     * time — an access change takes effect on re-subscribe.
      */
-    subscribe(entryId: string, socket: QuickdrawSocket, requiredLevel?: AccessLevel): Promise<TEntity | null>;
+    subscribe(entryId: string, socket: QuickdrawSocket, requiredLevel?: AccessLevel): Promise<Partial<TDto> | null>;
     /**
      * Subscribe a socket to multiple entities at once.
      * Batches ACL checks and entity fetches for efficiency.
@@ -96,7 +265,7 @@ declare abstract class BaseService<TEntity extends {
      *
      * Default implementation runs individual checks/fetches in parallel via Promise.all.
      */
-    batchSubscribe(entryIds: string[], socket: QuickdrawSocket, requiredLevel?: AccessLevel): Promise<Record<string, TEntity | null>>;
+    batchSubscribe(entryIds: string[], socket: QuickdrawSocket, requiredLevel?: AccessLevel): Promise<Record<string, Partial<TDto> | null>>;
     /**
      * Batch ACL check for multiple entities.
      * Override in derived classes for efficient batch queries
@@ -131,17 +300,21 @@ declare abstract class BaseService<TEntity extends {
      * @param eventName - The event name to emit
      * @param data - The data to emit
      *
+     * Event names and payloads are typed via the augmentable
+     * `QuickdrawEventMap` — with no augmentation this degrades to
+     * `string`/`unknown` exactly as before.
+     *
      * @example
      * ```typescript
      * // In MessageService, notify chat subscribers of a new message
      * this.emitToRoom(
-     *   `chatService:${message.chatId}`,
+     *   serviceRoom('chatService', message.chatId),
      *   'chat:message',
      *   messageDTO
      * );
      * ```
      */
-    emitToRoom(roomName: string, eventName: string, data: unknown): void;
+    emitToRoom<E extends QuickdrawEventName>(roomName: string, eventName: E, data: QuickdrawEventData<E & string>): void;
     /**
      * Emit a custom event to a room using Socket.io's volatile flag.
      *
@@ -163,7 +336,7 @@ declare abstract class BaseService<TEntity extends {
      * );
      * ```
      */
-    emitToRoomVolatile(roomName: string, eventName: string, data: unknown): void;
+    emitToRoomVolatile<E extends QuickdrawEventName>(roomName: string, eventName: E, data: QuickdrawEventData<E & string>): void;
     /**
      * Emit a custom event to a specific user's room.
      * Users join `user:{userId}` on connection (set up in auth middleware).
@@ -176,19 +349,19 @@ declare abstract class BaseService<TEntity extends {
      * this.emitToUserRoom(userId, "budget:shared", { budgetId, sharedBy });
      * ```
      */
-    emitToUserRoom(userId: string, eventName: string, data: unknown): void;
-    /**
-     * Get any active socket for room-based operations.
-     */
-    private getAnySubscriberSocket;
+    emitToUserRoom<E extends QuickdrawEventName>(userId: string, eventName: E, data: QuickdrawEventData<E & string>): void;
     /**
      * Emit an update to all subscribers of an entity.
-     * Uses tier-based pre-filtering: computes filtered versions once,
-     * then selects the appropriate version per subscriber.
+     *
+     * Room-based and therefore Redis-adapter-safe: elevated subscribers (in
+     * `{room}:full`, joined at subscribe time) receive the payload unfiltered;
+     * everyone else in the entity room receives it with protected fields
+     * stripped. Wire format and audience match the pre-4.0 per-socket path,
+     * but updates now cross nodes.
      *
      * Can be called from external method composition files.
      */
-    emitUpdate(entryId: string, data: Partial<TEntity>): void;
+    emitUpdate(entryId: string, data: Partial<TDto>): void;
     /**
      * Check if a user has access to subscribe to an entity.
      * Override in derived classes for custom logic.
@@ -218,18 +391,25 @@ declare abstract class BaseService<TEntity extends {
      * Throws if access is denied.
      */
     ensureAccessForMethod(requiredLevel: AccessLevel, socket: QuickdrawSocket, entryId?: string): Promise<void>;
+    /**
+     * Map a raw row to the wire DTO. Default: identity.
+     * May fetch (e.g. Prisma includes). Used by the CRUD trio's auto-emission,
+     * by `subscribe`/`batchSubscribe` initial payloads, and as the default
+     * `toItem` for collections.
+     */
+    protected toDto(entity: TEntity): TDto | Promise<TDto>;
     /**
      * Get the list of fields that should be stripped for non-elevated subscribers.
      * Override in derived classes to customize which fields are protected.
      *
      * @example
      * ```typescript
-     * protected override getProtectedFields(): (keyof User)[] {
+     * protected override getProtectedFields(): (keyof UserDto)[] {
      *   return ['email', 'serviceAccess', 'discordId'];
      * }
      * ```
      */
-    protected getProtectedFields(): (keyof TEntity)[];
+    protected getProtectedFields(): (keyof TDto)[];
     /**
      * Check if a socket has elevated access to an entity (receives full data).
      * Default: owner (socket.userId === entryId) or service-level Admin.
@@ -246,42 +426,70 @@ declare abstract class BaseService<TEntity extends {
      */
     protected hasElevatedAccess(socket: QuickdrawSocket, entryId: string): boolean;
     /**
-     * Strip protected fields from an entity.
-     * Used internally by filterEntityForSubscriber.
+     * Strip protected fields from a DTO.
+     * Used internally by filterEntityForSubscriber and emitUpdate.
      */
-    protected stripProtectedFields<T extends Partial<TEntity>>(entity: T): T;
+    protected stripProtectedFields<T extends Partial<TDto>>(entity: T): T;
     /**
-     * Filter entity data based on subscriber's access level.
+     * Filter DTO data based on subscriber's access level.
      * Override for complex filtering logic (e.g., multiple tiers).
      *
+     * Note: this shapes the *initial* subscribe payload only. Live emits are
+     * two-tier by room (`emitUpdate`) — full for elevated subscribers,
+     * protected-fields-stripped for everyone else.
+     *
      * @example
      * ```typescript
      * protected override filterEntityForSubscriber(
-     *   entity: Partial<TEntity>,
+     *   entity: Partial<UserDto>,
      *   socket: QuickdrawSocket,
      *   entryId: string
-     * ): Partial<TEntity> {
+     * ): Partial<UserDto> {
      *   if (this.hasElevatedAccess(socket, entryId)) return entity;
      *   if (this.isFriend(socket.userId, entryId)) return this.stripForFriends(entity);
      *   return this.stripProtectedFields(entity);
      * }
      * ```
      */
-    protected filterEntityForSubscriber(entity: Partial<TEntity>, socket: QuickdrawSocket, entryId: string): Partial<TEntity>;
+    protected filterEntityForSubscriber(entity: Partial<TDto>, socket: QuickdrawSocket, entryId: string): Partial<TDto>;
+    /** Transform or validate create input. Runs before the insert. */
+    protected beforeCreate(data: TCreateInput): Promise<TCreateInput>;
+    /** Runs after a create has committed and been emitted. */
+    protected afterCreate(_entity: TEntity): Promise<void>;
+    /**
+     * Transform or validate update input. `before` is the pre-write row when
+     * the service has collections or overrides an update/delete hook
+     * (otherwise null — the extra fetch is skipped).
+     */
+    protected beforeUpdate(_id: string, data: TUpdateInput, _before: TEntity | null): Promise<TUpdateInput>;
+    /** Runs after an update has committed and been emitted. */
+    protected afterUpdate(_before: TEntity | null, _after: TEntity): Promise<void>;
+    /** Runs before the delete. Throw to veto (delete() then returns false). */
+    protected beforeDelete(_before: TEntity): Promise<void>;
+    /** Runs after a delete has committed and been emitted. */
+    protected afterDelete(_before: TEntity): Promise<void>;
+    /**
+     * Whether writes need the pre-write row: true when the service has
+     * collections (scope diffing needs `before`) or overrides one of the
+     * update/delete hooks that receive it.
+     */
+    private needsBeforeEntity;
     /**
      * Find an entity by ID.
      */
     protected findById(id: string): Promise<TEntity | null>;
     /**
-     * Create an entity and emit to subscribers.
+     * Create an entity, emit to subscribers, and notify collections.
      */
     protected create(data: TCreateInput): Promise<TEntity>;
     /**
-     * Update an entity and emit to subscribers.
+     * Update an entity, emit to subscribers, and notify collections.
+     * Returns null when the write fails (e.g. the row does not exist).
      */
     protected update(id: string, data: TUpdateInput): Promise<TEntity | null>;
     /**
-     * Delete an entity and emit deletion event to subscribers.
+     * Delete an entity, emit the deletion event, and notify collections.
+     * Returns false when the write fails or a beforeDelete hook throws.
      */
     protected delete(id: string): Promise<boolean>;
     /**
@@ -369,6 +577,99 @@ declare abstract class BaseService<TEntity extends {
      * ```
      */
     protected verifyAllMethods(expectedMethods: readonly (keyof TServiceMethods & string)[]): void;
+    /**
+     * Declare a collection: rows of this service grouped by a scope id derived
+     * from the row. Declared in the constructor next to defineMethod /
+     * defineChannel; discovered by ServiceRegistry the same way.
+     *
+     * Once declared, the CRUD trio emits `added`/`updated`/`removed` deltas to
+     * the scope rooms automatically — including scope moves (a row whose scope
+     * changes is removed-from-old + added-to-new) and predicate entry/exit
+     * (`resolveScopeId` returning null). Hand-rolled write paths use the
+     * emitCollection* choke points instead.
+     *
+     * @example
+     * ```typescript
+     * type TaskCollections = { cardsByProject: { item: TaskCardDTO } };
+     *
+     * this.defineCollection("cardsByProject", {
+     *   resolveScopeId: (task) => task.projectId,
+     *   checkScopeAccess: (userId, projectId) => this.isProjectMember(userId, projectId),
+     *   snapshot: (projectId, { cursor, limit }) => this.getCardPage(projectId, cursor, limit),
+     *   toItem: (task) => this.buildCardDTO(task.id),
+     * });
+     * ```
+     */
+    protected defineCollection<K extends keyof TCollections & string>(name: K, config: CollectionDefinition<TEntity, TCollections[K]["item"]>): void;
+    /**
+     * Get all collection definitions for registry discovery.
+     */
+    getCollections(): Map<string, CollectionDefinition<TEntity, {
+        id: string;
+    }>>;
+    /**
+     * Handle a `{service}:collection:subscribe` (called by ServiceRegistry).
+     * Cursor-less calls join the scope room and return the first page (with
+     * `ids` when the snapshot provides them); cursor-bearing calls are pure
+     * paging. Returns null on access denial or unknown collection.
+     */
+    subscribeCollection(payload: CollectionSubscribePayload, socket: QuickdrawSocket): Promise<CollectionSnapshotResponse<{
+        id: string;
+    }> | null>;
+    /**
+     * Handle a `{service}:collection:unsubscribe` (called by ServiceRegistry).
+     */
+    unsubscribeCollection(payload: CollectionUnsubscribePayload, socket: QuickdrawSocket): void;
+    /**
+     * Notify all collections of a write this service performed outside the
+     * CRUD trio, with full scope-move diffing. Prefer the emitCollection*
+     * choke points when you already know the delta shape.
+     */
+    protected notifyCollections(event: {
+        type: "create";
+        after: TEntity;
+    } | {
+        type: "update";
+        before: TEntity | null;
+        after: TEntity;
+    } | {
+        type: "delete";
+        before: TEntity;
+    }): Promise<void>;
+    /**
+     * Emit an `updated` delta for an item to a scope room (client upserts —
+     * added-vs-updated is cosmetic). The choke point for hand-rolled write
+     * paths that already hold the item DTO.
+     *
+     * Can be called from external method composition files.
+     */
+    emitCollectionUpsert<K extends keyof TCollections & string>(collection: K, scopeId: string, item: TCollections[K]["item"]): void;
+    /**
+     * Emit a `removed` delta (id-only) to a scope room.
+     *
+     * Can be called from external method composition files.
+     */
+    emitCollectionRemove<K extends keyof TCollections & string>(collection: K, scopeId: string, id: string): void;
+    /**
+     * Emit a scope move: `removed` from the old scope + `added` to the new.
+     *
+     * Can be called from external method composition files.
+     */
+    emitCollectionMove<K extends keyof TCollections & string>(collection: K, fromScopeId: string, toScopeId: string, item: TCollections[K]["item"]): void;
+    /**
+     * Tell subscribers to re-snapshot the scope (debounced client-side) — the
+     * honest fallback for bulk operations and mass reorders.
+     *
+     * Can be called from external method composition files.
+     */
+    emitCollectionReset<K extends keyof TCollections & string>(collection: K, scopeId: string): void;
+    /**
+     * Force sockets out of a collection scope room (adapter-safe ACL
+     * revocation). With `userId`, only that user's sockets; without, everyone.
+     * Promise-shaped for forward compatibility with adapters that resolve
+     * membership asynchronously.
+     */
+    kickFromCollection(collection: string, scopeId: string, userId?: string): Promise<void>;
     /**
      * Install standard admin CRUD methods.
      * Call this in derived class constructor to expose admin endpoints.
@@ -445,6 +746,8 @@ declare abstract class BaseService<TEntity extends {
     }>;
     /**
      * Admin method: Unsubscribe all sockets from an entity.
+     * Room-based (adapter-safe): clears the entity's rooms across all nodes.
+     * The reported count covers this node's introspection map only.
      */
     protected adminUnsubscribeAll(entryId: string): {
         success: boolean;
@@ -456,6 +759,49 @@ declare abstract class BaseService<TEntity extends {
     protected getDefaultDeniedFields(): string[];
 }
 
+/**
+ * Base class for delegate-less, method-only services — methods, channels,
+ * ACL, and logging without a Prisma delegate, CRUD, or entity subscriptions.
+ *
+ * Use for services that orchestrate rather than own rows: build/deploy
+ * triggers, external API bridges, health/vibe checks. Replaces the
+ * `BaseService<never, never, never, TMethods>` contortion.
+ *
+ * Entity subscribe/batchSubscribe resolve to null/empty (there are no
+ * entities), and the inherited CRUD trio throws if reached (no delegate).
+ * Room emits (`emitToRoom`, `emitToUserRoom`, volatile) work as usual.
+ *
+ * @example
+ * ```typescript
+ * class CloudBuildService extends BaseRpcService<CloudBuildMethods> {
+ *   constructor() {
+ *     super({ serviceName: "cloudBuildService" });
+ *     this.defineMethod("triggerBuild", "Moderate", async (payload, ctx) => {
+ *       return await this.startBuild(payload.ref, ctx.userId);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseRpcService<TServiceMethods extends {
+    [K in keyof TServiceMethods]: {
+        payload: unknown;
+        response: unknown;
+    };
+} = Record<string, {
+    payload: unknown;
+    response: unknown;
+}>, TChannels extends {
+    [K in keyof TChannels]: unknown;
+} = Record<string, unknown>> extends BaseService<{
+    id: string;
+}, Record<string, unknown>, Record<string, unknown>, TServiceMethods, TChannels> {
+    /** RPC services have no entities to subscribe to. */
+    subscribe(): Promise<null>;
+    /** RPC services have no entities to subscribe to. */
+    batchSubscribe(): Promise<Record<string, null>>;
+}
+
 /**
  * Central registry for auto-discovering and registering service methods as Socket.io events.
  *
@@ -544,6 +890,13 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
      * Register unsubscription listener for a service.
      */
     private registerUnsubscriptionListener;
+    /**
+     * Register collection subscribe/unsubscribe listeners for a service.
+     *
+     * `{service}:collection:subscribe` doubles as the paging call: a
+     * cursor-bearing payload skips the room join and just returns a page.
+     */
+    private registerCollectionListeners;
     /**
      * Get list of registered service names.
      */
@@ -557,9 +910,20 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
 /**
  * Create a fully configured quickdraw server with one function call.
  *
+ * Authentication: `authenticate` may return a plain userId string or a
+ * structured {@link QuickdrawIdentity} (`{ userId?, principalType?, claims?,
+ * serviceAccess? }`) for non-trivial principal models (task tokens, runner
+ * tokens…). Service-level access comes from the identity's `serviceAccess`,
+ * or from `loadServiceAccess(userId)` when the identity omits it.
+ *
+ * On connection, authenticated sockets join `user:{userId}` (so
+ * `emitToUserRoom` and user-targeted kicks work out of the box) and every
+ * socket receives an `auth:info` event with
+ * `{ userId, serviceAccess, principalType }`.
+ *
  * @example
  * ```typescript
- * import { createQuickdrawServer } from '@quickdraw/core/server';
+ * import { createQuickdrawServer } from '@fitzzero/quickdraw-core/server';
  * import { ChatService, UserService } from './services';
  *
  * const { io, httpServer, registry } = createQuickdrawServer({
@@ -571,9 +935,13 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
  *   },
  *   auth: {
  *     authenticate: async (socket, auth) => {
- *       // Verify JWT and return userId
  *       const payload = await verifyJWT(auth.token);
- *       return payload.userId;
+ *       if (!payload) return undefined;
+ *       return { userId: payload.userId, principalType: "user" };
+ *     },
+ *     loadServiceAccess: async (userId) => {
+ *       const user = await prisma.user.findUnique({ where: { id: userId } });
+ *       return user?.serviceAccess as Record<string, AccessLevel> | null;
  *     },
  *   },
  * });
@@ -1431,4 +1799,4 @@ declare function createMcpRoutes(router: Router, options: McpHttpRoutesOptions):
  */
 declare function generateToolMetadata(options: GenerateToolMetadataOptions): void;
 
-export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, type AuthRequest, type AuthResponse, BaseService, BaseServiceInstance, BaseServiceOptions, type CookieResponse, type CookieSettings, DEFAULT_MOCK_PATH_PREFIX, type DiscordUser, type EnvValidationResult, type GenerateToolMetadataOptions, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type McpHttpRoutesOptions, ServiceMethodContext as McpMethodContext, ServiceMethodDefinition as McpMethodDefinition, McpRegistry, type McpRegistryInstance, type McpRegistryOptions, type McpServiceInstance, type McpStdioServerOptions, type McpToolDefinition, type MethodSpec, type MockOAuthProviderOptions, type MockOAuthRouter, type MockOAuthUser, OAUTH_RETURN_ORIGIN_COOKIE, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, type RateLimitOptions, type RateLimiter, type RedisAdapterOptions, type RedisAdapterResult, type RegisterMockOAuthOptions, type RequireAuthOptions, SESSION_COOKIE, type ServiceInfo, type ServiceMethodInfo, ServiceRegistry, ServiceRegistryInstance, type ServiceRegistryOptions, type ServiceToolSpec, type SessionCookieOptions, type ValidateEnvOptions, type ValidateOriginOptions, type ZodToAdminFieldsOptions, applyRateLimitMiddleware, bootstrapMcpServer, checkEnv, clearSessionCookie, createJWT, createMcpRoutes, createMcpStdioServer, createMockOAuthProvider, createOAuthURL, createQuickdrawServer, createRateLimiter, createRequireAuth, createTieredRateLimiter, decrypt, decryptIfEncrypted, discordProvider, encrypt, exchangeOAuthCode, extractBearerOrCookieToken, generateToolMetadata, getDefaultEntityFields, getDiscordAvatarUrl, googleProvider, isEncrypted, isMockOAuthEnabled, isRedisAdapterAvailable, mergeWithDefaultFields, registerMockOAuthProvider, requireEnv, setSessionCookie, setupRedisAdapter, tryDecrypt, validateEnv, validateRedirectOrigin, verifyJWT, zodToAdminFields };
+export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, type AuthRequest, type AuthResponse, BaseRpcService, BaseService, BaseServiceInstance, BaseServiceOptions, type CollectionDefinition, CollectionManager, type CollectionWriteEvent, type CookieResponse, type CookieSettings, DEFAULT_MOCK_PATH_PREFIX, type DiscordUser, type EnvValidationResult, type GenerateToolMetadataOptions, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type McpHttpRoutesOptions, ServiceMethodContext as McpMethodContext, ServiceMethodDefinition as McpMethodDefinition, McpRegistry, type McpRegistryInstance, type McpRegistryOptions, type McpServiceInstance, type McpStdioServerOptions, type McpToolDefinition, type MethodSpec, type MockOAuthProviderOptions, type MockOAuthRouter, type MockOAuthUser, OAUTH_RETURN_ORIGIN_COOKIE, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, type RateLimitOptions, type RateLimiter, type RedisAdapterOptions, type RedisAdapterResult, type RegisterMockOAuthOptions, type RequireAuthOptions, SESSION_COOKIE, type ServiceInfo, type ServiceMethodInfo, ServiceRegistry, ServiceRegistryInstance, type ServiceRegistryOptions, type ServiceToolSpec, type SessionCookieOptions, type ValidateEnvOptions, type ValidateOriginOptions, type ZodToAdminFieldsOptions, applyRateLimitMiddleware, bootstrapMcpServer, checkEnv, clearSessionCookie, createJWT, createMcpRoutes, createMcpStdioServer, createMockOAuthProvider, createOAuthURL, createQuickdrawServer, createRateLimiter, createRequireAuth, createTieredRateLimiter, decrypt, decryptIfEncrypted, discordProvider, encrypt, exchangeOAuthCode, extractBearerOrCookieToken, generateToolMetadata, getDefaultEntityFields, getDiscordAvatarUrl, googleProvider, isEncrypted, isMockOAuthEnabled, isRedisAdapterAvailable, mergeWithDefaultFields, registerMockOAuthProvider, requireEnv, setSessionCookie, setupRedisAdapter, tryDecrypt, validateEnv, validateRedirectOrigin, verifyJWT, zodToAdminFields };