@fitzzero/quickdraw-core 3.9.1 → 4.1.0

package/dist/server/index.js

@@ -11,6 +11,21 @@ import * as path from 'path';
 function channelEventName(serviceName, channelName) {
   return `channel:${serviceName}:${channelName}`;
 }
+function serviceRoom(serviceName, entryId) {
+  return `${serviceName}:${entryId}`;
+}
+function serviceFullRoom(serviceName, entryId) {
+  return `${serviceRoom(serviceName, entryId)}:full`;
+}
+function collectionRoom(serviceName, collection, scopeId) {
+  return `${serviceName}:collection:${collection}:${scopeId}`;
+}
+function collectionEventName(serviceName, collection, scopeId) {
+  return collectionRoom(serviceName, collection, scopeId);
+}
+function userRoom(userId) {
+  return `user:${userId}`;
+}
 var consoleLogger = {
   info: (message, meta) => console.log(`[INFO] ${message}`, meta ?? ""),
   warn: (message, meta) => console.warn(`[WARN] ${message}`, meta ?? ""),
@@ -19,6 +34,219 @@ var consoleLogger = {
   child: () => consoleLogger
 };
 
+// src/server/collections.ts
+var DEFAULT_PAGE_LIMIT = 100;
+var MAX_PAGE_LIMIT = 500;
+var MAX_IDS = 5e3;
+var CollectionManager = class {
+  definitions = /* @__PURE__ */ new Map();
+  serviceName;
+  getIo;
+  logger;
+  defaultToItem;
+  constructor(options) {
+    this.serviceName = options.serviceName;
+    this.getIo = options.getIo;
+    this.logger = options.logger;
+    this.defaultToItem = options.defaultToItem;
+  }
+  define(name, config) {
+    if (this.definitions.has(name)) {
+      throw new Error(`${this.serviceName}: collection "${name}" is already defined`);
+    }
+    this.definitions.set(name, config);
+  }
+  getAll() {
+    return this.definitions;
+  }
+  get size() {
+    return this.definitions.size;
+  }
+  // ===========================================================================
+  // Wire operations (called by BaseService on behalf of the registry)
+  // ===========================================================================
+  /**
+   * 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).
+   */
+  async subscribe(payload, socket) {
+    const definition = this.definitions.get(payload.collection);
+    if (!definition) {
+      this.logger.debug(`Unknown collection ${this.serviceName}:${payload.collection}`);
+      return null;
+    }
+    if (!socket.userId) return null;
+    const allowed = await definition.checkScopeAccess(socket.userId, payload.scopeId, socket);
+    if (!allowed) return null;
+    const cursor = payload.cursor ?? null;
+    if (cursor === null) {
+      void socket.join(collectionRoom(this.serviceName, payload.collection, payload.scopeId));
+    }
+    const rev = Date.now();
+    const limit = Math.min(
+      Math.max(payload.limit ?? definition.defaultLimit ?? DEFAULT_PAGE_LIMIT, 1),
+      MAX_PAGE_LIMIT
+    );
+    const page = await definition.snapshot(payload.scopeId, {
+      cursor,
+      limit,
+      userId: socket.userId
+    });
+    const response = { ...page, rev };
+    if (cursor !== null) {
+      delete response.ids;
+      delete response.idsTruncated;
+    } else if (response.ids && response.ids.length > MAX_IDS) {
+      delete response.ids;
+      response.idsTruncated = true;
+    }
+    return response;
+  }
+  /** Handle a `{service}:collection:unsubscribe` — leave the scope room. */
+  unsubscribe(payload, socket) {
+    void socket.leave(collectionRoom(this.serviceName, payload.collection, payload.scopeId));
+  }
+  // ===========================================================================
+  // Automatic emission (the single choke point for the CRUD trio)
+  // ===========================================================================
+  /**
+   * 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.
+   */
+  async notify(event) {
+    if (this.definitions.size === 0) return;
+    for (const [name, definition] of this.definitions) {
+      try {
+        await this.notifyOne(name, definition, event);
+      } catch (error) {
+        this.logger.error(`Collection emission failed for ${this.serviceName}:${name}`, {
+          eventType: event.type,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  }
+  async notifyOne(name, definition, event) {
+    switch (event.type) {
+      case "create": {
+        const scopes = normalizeScopes(await definition.resolveScopeId(event.after));
+        if (scopes.length === 0) return;
+        const item = await this.toItem(definition, event.after);
+        const rev = this.revFor(definition, item);
+        for (const scopeId of scopes) {
+          this.emitDelta(name, scopeId, { type: "added", item, rev });
+        }
+        return;
+      }
+      case "update": {
+        const beforeScopes = event.before ? normalizeScopes(await definition.resolveScopeId(event.before)) : [];
+        const afterScopes = normalizeScopes(await definition.resolveScopeId(event.after));
+        const beforeSet = new Set(beforeScopes);
+        const afterSet = new Set(afterScopes);
+        const removed = beforeScopes.filter((s) => !afterSet.has(s));
+        const entered = afterScopes.filter((s) => !beforeSet.has(s));
+        const stayed = afterScopes.filter((s) => beforeSet.has(s));
+        if (entered.length > 0 || stayed.length > 0) {
+          const item = await this.toItem(definition, event.after);
+          const rev = this.revFor(definition, item);
+          for (const scopeId of stayed) {
+            this.emitDelta(name, scopeId, { type: "updated", item, rev });
+          }
+          for (const scopeId of entered) {
+            this.emitDelta(name, scopeId, { type: "added", item, rev });
+          }
+        }
+        for (const scopeId of removed) {
+          this.emitDelta(name, scopeId, { type: "removed", id: event.after.id, rev: Date.now() });
+        }
+        return;
+      }
+      case "delete": {
+        const scopes = normalizeScopes(await definition.resolveScopeId(event.before));
+        for (const scopeId of scopes) {
+          this.emitDelta(name, scopeId, { type: "removed", id: event.before.id, rev: Date.now() });
+        }
+      }
+    }
+  }
+  // ===========================================================================
+  // Manual choke points (for hand-rolled write paths)
+  // ===========================================================================
+  /** Emit `updated` (client upserts; added-vs-updated is cosmetic). */
+  emitUpsert(collection, scopeId, item) {
+    const definition = this.definitions.get(collection);
+    const rev = definition ? this.revFor(definition, item) : Date.now();
+    this.emitDelta(collection, scopeId, { type: "updated", item, rev });
+  }
+  emitRemove(collection, scopeId, id) {
+    this.emitDelta(collection, scopeId, { type: "removed", id, rev: Date.now() });
+  }
+  /** A move is removed-from-old + added-to-new. */
+  emitMove(collection, fromScopeId, toScopeId, item) {
+    const definition = this.definitions.get(collection);
+    const rev = definition ? this.revFor(definition, item) : Date.now();
+    this.emitDelta(collection, fromScopeId, { type: "removed", id: item.id, rev });
+    this.emitDelta(collection, toScopeId, { type: "added", item, rev });
+  }
+  /** Clients re-snapshot (debounced) — for bulk ops and mass reorders. */
+  emitReset(collection, scopeId) {
+    this.emitDelta(collection, scopeId, { type: "reset", rev: Date.now() });
+  }
+  /**
+   * 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, scopeId, userId) {
+    const io = this.getIo();
+    if (!io) {
+      this.logger.debug(`No io instance; cannot kick from ${this.serviceName}:${collection}`);
+      return;
+    }
+    const room = collectionRoom(this.serviceName, collection, scopeId);
+    io.in(userId ? userRoom(userId) : room).socketsLeave(room);
+  }
+  // ===========================================================================
+  // Internals
+  // ===========================================================================
+  async toItem(definition, entity) {
+    return definition.toItem ? await definition.toItem(entity) : await this.defaultToItem(entity);
+  }
+  revFor(definition, item) {
+    return definition.revOf?.(item) ?? Date.now();
+  }
+  emitDelta(collection, scopeId, delta) {
+    const io = this.getIo();
+    if (!io) {
+      this.logger.debug(
+        `No io instance; dropping ${delta.type} delta for ${this.serviceName}:${collection}:${scopeId}`
+      );
+      return;
+    }
+    const room = collectionRoom(this.serviceName, collection, scopeId);
+    io.to(room).emit(collectionEventName(this.serviceName, collection, scopeId), delta);
+  }
+};
+function normalizeScopes(scopes) {
+  if (scopes === null) return [];
+  if (typeof scopes === "string") return [scopes];
+  return [...new Set(scopes)];
+}
+
 // src/server/utils/zodToAdminFields.ts
 var NON_EDITABLE_FIELDS = /* @__PURE__ */ new Set(["id", "createdAt", "updatedAt", "created_at", "updated_at"]);
 var DEFAULT_HIDDEN_FIELDS = /* @__PURE__ */ new Set(["acl", "serviceAccess", "service_access"]);
@@ -166,12 +394,14 @@ function mergeWithDefaultFields(schemaFields, options = {}) {
 }
 
 // src/server/BaseService.ts
-var BaseService = class {
+var BaseService = class _BaseService {
   serviceName;
   hasEntryACL;
   defaultACL;
   logger;
-  // Subscription tracking: entryId -> Set of sockets
+  // Subscription tracking: entryId -> Set of sockets.
+  // Retained for admin introspection (adminGetSubscribers) only — emission
+  // is room-based and never reads this map.
   subscribers = /* @__PURE__ */ new Map();
   // Prisma delegate for DB operations
   delegate;
@@ -181,6 +411,8 @@ var BaseService = class {
   publicMethods = /* @__PURE__ */ new Map();
   // Collection of channels for registry discovery
   publicChannels = /* @__PURE__ */ new Map();
+  // Scope-keyed collections (definitions, snapshot dispatch, delta emission)
+  collections;
   // Admin metadata configuration (set by installAdminMethods)
   adminMeta = null;
   constructor(options) {
@@ -188,6 +420,12 @@ var BaseService = class {
     this.hasEntryACL = options.hasEntryACL ?? false;
     this.defaultACL = options.defaultACL ?? [];
     this.logger = options.logger?.child({ service: this.serviceName }) ?? consoleLogger.child({ service: this.serviceName });
+    this.collections = new CollectionManager({
+      serviceName: this.serviceName,
+      getIo: () => this.io,
+      logger: this.logger,
+      defaultToItem: (entity) => this.toDto(entity)
+    });
   }
   /**
    * Set the Prisma delegate for this service.
@@ -220,14 +458,20 @@ var BaseService = class {
   /**
    * 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) {
-    return `${this.serviceName}:${entryId}`;
+    return serviceRoom(this.serviceName, entryId);
   }
   /**
    * 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.
    */
   async subscribe(entryId, socket, requiredLevel = "Read") {
     if (!socket.userId) {
@@ -248,10 +492,13 @@ var BaseService = class {
     this.subscribers.get(entryId).add(socket);
     const roomName = this.getRoomName(entryId);
     void socket.join(roomName);
+    if (this.hasElevatedAccess(socket, entryId)) {
+      void socket.join(serviceFullRoom(this.serviceName, entryId));
+    }
     this.logger.debug(`User ${socket.userId} subscribed to ${entryId} (room: ${roomName})`);
     const entity = await this.findById(entryId);
     if (!entity) return null;
-    return this.filterEntityForSubscriber(entity, socket, entryId);
+    return this.filterEntityForSubscriber(await this.toDto(entity), socket, entryId);
   }
   /**
    * Subscribe a socket to multiple entities at once.
@@ -273,9 +520,9 @@ var BaseService = class {
     );
     const allowedIds = entryIds.filter((id) => accessMap.get(id) === true);
     const entities = allowedIds.length > 0 ? await this.findByIds(allowedIds) : [];
-    const entityMap = /* @__PURE__ */ new Map();
+    const dtoMap = /* @__PURE__ */ new Map();
     for (const entity of entities) {
-      entityMap.set(entity.id, entity);
+      dtoMap.set(entity.id, await this.toDto(entity));
     }
     for (const entryId of allowedIds) {
       if (!this.subscribers.has(entryId)) {
@@ -283,15 +530,18 @@ var BaseService = class {
       }
       this.subscribers.get(entryId).add(socket);
       void socket.join(this.getRoomName(entryId));
+      if (this.hasElevatedAccess(socket, entryId)) {
+        void socket.join(serviceFullRoom(this.serviceName, entryId));
+      }
     }
     const results = {};
     for (const entryId of entryIds) {
-      const entity = entityMap.get(entryId);
-      if (!entity || !accessMap.get(entryId)) {
+      const dto = dtoMap.get(entryId);
+      if (!dto || !accessMap.get(entryId)) {
         results[entryId] = null;
         continue;
       }
-      results[entryId] = this.filterEntityForSubscriber(entity, socket, entryId);
+      results[entryId] = this.filterEntityForSubscriber(dto, socket, entryId);
     }
     this.logger.debug(
       `User ${socket.userId} batch-subscribed to ${allowedIds.length}/${entryIds.length} entities`
@@ -337,8 +587,8 @@ var BaseService = class {
         this.subscribers.delete(entryId);
       }
     }
-    const roomName = this.getRoomName(entryId);
-    void socket.leave(roomName);
+    void socket.leave(this.getRoomName(entryId));
+    void socket.leave(serviceFullRoom(this.serviceName, entryId));
   }
   /**
    * Remove a socket from all subscriptions (called on disconnect).
@@ -347,8 +597,8 @@ var BaseService = class {
     for (const [entryId, sockets] of this.subscribers.entries()) {
       if (sockets.has(socket)) {
         sockets.delete(socket);
-        const roomName = this.getRoomName(entryId);
-        void socket.leave(roomName);
+        void socket.leave(this.getRoomName(entryId));
+        void socket.leave(serviceFullRoom(this.serviceName, entryId));
         if (sockets.size === 0) {
           this.subscribers.delete(entryId);
         }
@@ -365,29 +615,29 @@ var BaseService = class {
    * @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, eventName, data) {
-    if (this.io) {
-      this.io.to(roomName).emit(eventName, data);
-      this.logger.debug(`Emitted ${eventName} to room ${roomName}`);
-      return;
-    }
-    const anySocket = this.getAnySubscriberSocket();
-    if (!anySocket) {
-      this.logger.debug(`No sockets available to emit to room ${roomName}`);
+    if (!this.io) {
+      this.logger.debug(
+        `No io instance (service not registered); dropping ${eventName} to room ${roomName}`
+      );
       return;
     }
-    anySocket.to(roomName).emit(eventName, data);
-    this.logger.debug(`Emitted ${eventName} to room ${roomName} (via socket fallback)`);
+    this.io.to(roomName).emit(eventName, data);
+    this.logger.debug(`Emitted ${eventName} to room ${roomName}`);
   }
   /**
    * Emit a custom event to a room using Socket.io's volatile flag.
@@ -411,13 +661,8 @@ var BaseService = class {
    * ```
    */
   emitToRoomVolatile(roomName, eventName, data) {
-    if (this.io) {
-      this.io.to(roomName).volatile.emit(eventName, data);
-      return;
-    }
-    const anySocket = this.getAnySubscriberSocket();
-    if (!anySocket) return;
-    anySocket.to(roomName).volatile.emit(eventName, data);
+    if (!this.io) return;
+    this.io.to(roomName).volatile.emit(eventName, data);
   }
   /**
    * Emit a custom event to a specific user's room.
@@ -432,37 +677,29 @@ var BaseService = class {
    * ```
    */
   emitToUserRoom(userId, eventName, data) {
-    this.emitToRoom(`user:${userId}`, eventName, data);
-  }
-  /**
-   * Get any active socket for room-based operations.
-   */
-  getAnySubscriberSocket() {
-    for (const sockets of this.subscribers.values()) {
-      const first = sockets.values().next();
-      if (!first.done) {
-        return first.value;
-      }
-    }
-    return null;
+    this.emitToRoom(userRoom(userId), eventName, data);
   }
   /**
    * 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, data) {
-    const subs = this.subscribers.get(entryId);
-    if (!subs || subs.size === 0) return;
-    const eventName = `${this.serviceName}:update:${entryId}`;
-    const fullData = data;
-    const publicData = this.stripProtectedFields(data);
-    for (const socket of subs) {
-      const payload = this.hasElevatedAccess(socket, entryId) ? fullData : publicData;
-      socket.emit(eventName, payload);
+    if (!this.io) {
+      this.logger.debug(`No io instance (service not registered); dropping update for ${entryId}`);
+      return;
     }
+    const eventName = `${this.serviceName}:update:${entryId}`;
+    const room = this.getRoomName(entryId);
+    const fullRoom = serviceFullRoom(this.serviceName, entryId);
+    this.io.to(fullRoom).emit(eventName, data);
+    this.io.to(room).except(fullRoom).emit(eventName, this.stripProtectedFields(data));
   }
   // ===========================================================================
   // Access Control
@@ -559,15 +796,24 @@ var BaseService = class {
     throw new Error("Insufficient permissions");
   }
   // ===========================================================================
-  // Protected Fields Filtering
+  // DTO Mapping & Protected Fields Filtering
   // ===========================================================================
+  /**
+   * 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.
+   */
+  toDto(entity) {
+    return entity;
+  }
   /**
    * 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'];
    * }
    * ```
@@ -593,8 +839,8 @@ var BaseService = class {
     return socket.userId === entryId || this.hasServiceAccess(socket, "Admin");
   }
   /**
-   * Strip protected fields from an entity.
-   * Used internally by filterEntityForSubscriber.
+   * Strip protected fields from a DTO.
+   * Used internally by filterEntityForSubscriber and emitUpdate.
    */
   stripProtectedFields(entity) {
     const protectedFields = this.getProtectedFields();
@@ -605,16 +851,20 @@ var BaseService = class {
     return result;
   }
   /**
-   * 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);
@@ -625,6 +875,52 @@ var BaseService = class {
     return this.hasElevatedAccess(socket, entryId) ? entity : this.stripProtectedFields(entity);
   }
   // ===========================================================================
+  // Write Lifecycle Hooks
+  // ===========================================================================
+  // Overridable extension points around the CRUD trio — the home for
+  // cross-cutting side effects (audit logging, denormalized counters, search
+  // indexing) without overriding create/update/delete wholesale. Collections
+  // are notified automatically between emit and the after* hook.
+  //
+  // Semantics: before* hooks may veto by throwing (nothing is written);
+  // after* hooks run once the write has committed, so a throw propagates to
+  // the caller but cannot undo the write.
+  /** Transform or validate create input. Runs before the insert. */
+  async beforeCreate(data) {
+    return data;
+  }
+  /** Runs after a create has committed and been emitted. */
+  async afterCreate(_entity) {
+  }
+  /**
+   * 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).
+   */
+  async beforeUpdate(_id, data, _before) {
+    return data;
+  }
+  /** Runs after an update has committed and been emitted. */
+  async afterUpdate(_before, _after) {
+  }
+  /** Runs before the delete. Throw to veto (delete() then returns false). */
+  async beforeDelete(_before) {
+  }
+  /** Runs after a delete has committed and been emitted. */
+  async afterDelete(_before) {
+  }
+  /**
+   * 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.
+   */
+  needsBeforeEntity() {
+    if (this.collections.size > 0) return true;
+    const base = _BaseService.prototype;
+    const self = this;
+    return self.beforeUpdate !== base.beforeUpdate || self.afterUpdate !== base.afterUpdate || self.beforeDelete !== base.beforeDelete || self.afterDelete !== base.afterDelete;
+  }
+  // ===========================================================================
   // CRUD Operations
   // ===========================================================================
   /**
@@ -636,44 +932,60 @@ var BaseService = class {
     });
   }
   /**
-   * Create an entity and emit to subscribers.
+   * Create an entity, emit to subscribers, and notify collections.
    */
   async create(data) {
-    const entity = await this.getDelegate().create({ data });
-    this.emitUpdate(entity.id, entity);
+    const prepared = await this.beforeCreate(data);
+    const entity = await this.getDelegate().create({ data: prepared });
+    this.emitUpdate(entity.id, await this.toDto(entity));
+    await this.collections.notify({ type: "create", after: entity });
+    await this.afterCreate(entity);
     this.logger.info(`Created entity ${entity.id}`);
     return entity;
   }
   /**
-   * 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).
    */
   async update(id, data) {
+    const before = this.needsBeforeEntity() ? await this.findById(id) : null;
+    const prepared = await this.beforeUpdate(id, data, before);
+    let entity;
     try {
-      const entity = await this.getDelegate().update({
+      entity = await this.getDelegate().update({
         where: { id },
-        data
+        data: prepared
       });
-      this.emitUpdate(id, entity);
-      this.logger.info(`Updated entity ${id}`);
-      return entity;
     } catch {
       return null;
     }
+    this.emitUpdate(id, await this.toDto(entity));
+    await this.collections.notify({ type: "update", before, after: entity });
+    await this.afterUpdate(before, entity);
+    this.logger.info(`Updated entity ${id}`);
+    return entity;
   }
   /**
-   * 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.
    */
   async delete(id) {
+    const before = this.needsBeforeEntity() ? await this.findById(id) : null;
     try {
+      if (before) await this.beforeDelete(before);
       await this.getDelegate().delete({
         where: { id }
       });
-      this.emitUpdate(id, { id, deleted: true });
-      this.logger.info(`Deleted entity ${id}`);
-      return true;
     } catch {
       return false;
     }
+    this.emitUpdate(id, { id, deleted: true });
+    if (before) {
+      await this.collections.notify({ type: "delete", before });
+      await this.afterDelete(before);
+    }
+    this.logger.info(`Deleted entity ${id}`);
+    return true;
   }
   // ===========================================================================
   // Public Method Definition
@@ -803,6 +1115,109 @@ var BaseService = class {
     }
   }
   // ===========================================================================
+  // Collections (scope-keyed list subscriptions)
+  // ===========================================================================
+  /**
+   * 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),
+   * });
+   * ```
+   */
+  defineCollection(name, config) {
+    this.collections.define(name, config);
+  }
+  /**
+   * Get all collection definitions for registry discovery.
+   */
+  getCollections() {
+    return this.collections.getAll();
+  }
+  /**
+   * 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.
+   */
+  async subscribeCollection(payload, socket) {
+    return await this.collections.subscribe(payload, socket);
+  }
+  /**
+   * Handle a `{service}:collection:unsubscribe` (called by ServiceRegistry).
+   */
+  unsubscribeCollection(payload, socket) {
+    this.collections.unsubscribe(payload, socket);
+  }
+  /**
+   * 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.
+   */
+  async notifyCollections(event) {
+    await this.collections.notify(event);
+  }
+  /**
+   * 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(collection, scopeId, item) {
+    this.collections.emitUpsert(collection, scopeId, item);
+  }
+  /**
+   * Emit a `removed` delta (id-only) to a scope room.
+   *
+   * Can be called from external method composition files.
+   */
+  emitCollectionRemove(collection, scopeId, id) {
+    this.collections.emitRemove(collection, scopeId, id);
+  }
+  /**
+   * Emit a scope move: `removed` from the old scope + `added` to the new.
+   *
+   * Can be called from external method composition files.
+   */
+  emitCollectionMove(collection, fromScopeId, toScopeId, item) {
+    this.collections.emitMove(collection, fromScopeId, toScopeId, item);
+  }
+  /**
+   * 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(collection, scopeId) {
+    this.collections.emitReset(collection, scopeId);
+  }
+  /**
+   * 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, scopeId, userId) {
+    this.collections.kickFromCollection(collection, scopeId, userId);
+    return Promise.resolve();
+  }
+  // ===========================================================================
   // Admin Methods
   // ===========================================================================
   /**
@@ -1030,7 +1445,7 @@ var BaseService = class {
         where: { id: entryId },
         data: { acl }
       });
-      this.emitUpdate(entryId, entity);
+      this.emitUpdate(entryId, await this.toDto(entity));
       this.logger.info(`Updated ACL for entity ${entryId}`);
       return entity;
     } catch (error) {
@@ -1069,23 +1484,25 @@ var BaseService = class {
     }
     const subs = this.subscribers.get(entryId);
     const count = subs?.size ?? 0;
-    this.emitUpdate(entryId, entity);
+    this.emitUpdate(entryId, await this.toDto(entity));
     this.logger.info(`Re-emitted entity ${entryId} to ${count} subscribers`);
     return { success: true, subscriberCount: count };
   }
   /**
    * 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.
    */
   adminUnsubscribeAll(entryId) {
     const subs = this.subscribers.get(entryId);
     const count = subs?.size ?? 0;
-    if (subs) {
-      const eventName = `${this.serviceName}:unsubscribed:${entryId}`;
-      for (const socket of subs) {
-        socket.emit(eventName, { reason: "admin_action" });
-      }
-      this.subscribers.delete(entryId);
-    }
+    const room = this.getRoomName(entryId);
+    const fullRoom = serviceFullRoom(this.serviceName, entryId);
+    this.emitToRoom(room, `${this.serviceName}:unsubscribed:${entryId}`, {
+      reason: "admin_action"
+    });
+    this.io?.in(room).socketsLeave([room, fullRoom]);
+    this.subscribers.delete(entryId);
     this.logger.info(`Unsubscribed ${count} sockets from entity ${entryId}`);
     return { success: true, unsubscribedCount: count };
   }
@@ -1100,6 +1517,18 @@ var BaseService = class {
   }
 };
 
+// src/server/BaseRpcService.ts
+var BaseRpcService = class extends BaseService {
+  /** RPC services have no entities to subscribe to. */
+  async subscribe() {
+    return null;
+  }
+  /** RPC services have no entities to subscribe to. */
+  async batchSubscribe() {
+    return {};
+  }
+};
+
 // src/server/ServiceRegistry.ts
 var CHANNEL_ABUSE_WINDOW_MS = 1e4;
 var CHANNEL_ABUSE_MULTIPLIER = 100;
@@ -1155,6 +1584,7 @@ var ServiceRegistry = class {
       this.registerSubscriptionListener(socket, `${serviceName}:subscribe`, service);
       this.registerBatchSubscriptionListener(socket, `${serviceName}:batchSubscribe`, service);
       this.registerUnsubscriptionListener(socket, `${serviceName}:unsubscribe`, service);
+      this.registerCollectionListeners(socket, serviceName, service);
     }
   }
   /**
@@ -1480,6 +1910,72 @@ var ServiceRegistry = class {
       }
     );
   }
+  /**
+   * 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.
+   */
+  registerCollectionListeners(socket, serviceName, service) {
+    socket.on(
+      `${serviceName}:collection:subscribe`,
+      async (payload, callback) => {
+        try {
+          if (!socket.userId) {
+            callback?.({ success: false, error: "Authentication required", code: 401 });
+            return;
+          }
+          if (!isValidCollectionPayload(payload) || !isValidSubscribeExtras(payload)) {
+            callback?.({ success: false, error: "Invalid collection payload", code: 400 });
+            return;
+          }
+          if (!service.subscribeCollection) {
+            callback?.({ success: false, error: "Service has no collections", code: 404 });
+            return;
+          }
+          const data = await service.subscribeCollection(payload, socket);
+          if (data === null) {
+            callback?.({
+              success: false,
+              error: "Access denied or unknown collection",
+              code: 403
+            });
+            return;
+          }
+          callback?.({ success: true, data });
+        } catch (error) {
+          this.logger.error(`Error in collection subscription ${serviceName}:`, {
+            error: error instanceof Error ? error.message : "Unknown error"
+          });
+          callback?.({
+            success: false,
+            error: error instanceof Error ? error.message : "Collection subscription failed"
+          });
+        }
+      }
+    );
+    socket.on(
+      `${serviceName}:collection:unsubscribe`,
+      (payload, callback) => {
+        try {
+          if (!isValidCollectionPayload(payload)) {
+            callback?.({ success: false, error: "Invalid collection payload", code: 400 });
+            return;
+          }
+          service.unsubscribeCollection?.(payload, socket);
+          callback?.({ success: true, data: { unsubscribed: true } });
+        } catch (error) {
+          this.logger.error(`Error in collection unsubscription ${serviceName}:`, {
+            error: error instanceof Error ? error.message : "Unknown error"
+          });
+          callback?.({
+            success: false,
+            error: error instanceof Error ? error.message : "Collection unsubscription failed"
+          });
+        }
+      }
+    );
+  }
   /**
    * Get list of registered service names.
    */
@@ -1493,6 +1989,16 @@ var ServiceRegistry = class {
     return Array.from(this.services.values());
   }
 };
+function isValidCollectionPayload(payload) {
+  if (!payload || typeof payload !== "object") return false;
+  const p = payload;
+  return typeof p.collection === "string" && typeof p.scopeId === "string";
+}
+function isValidSubscribeExtras(payload) {
+  const cursorOk = payload.cursor === void 0 || payload.cursor === null || typeof payload.cursor === "string";
+  const limitOk = payload.limit === void 0 || typeof payload.limit === "number" && payload.limit > 0;
+  return cursorOk && limitOk;
+}
 function createQuickdrawServer(options) {
   const logger = options.logger ?? consoleLogger;
   const serverLogger = logger.child({ service: "QuickdrawServer" });
@@ -1518,9 +2024,16 @@ function createQuickdrawServer(options) {
     try {
       if (options.auth?.authenticate) {
         const auth = socket.handshake.auth;
-        const userId = await options.auth.authenticate(quickdrawSocket, auth);
-        quickdrawSocket.userId = userId;
-        quickdrawSocket.serviceAccess = {};
+        const result = await options.auth.authenticate(quickdrawSocket, auth);
+        const identity = typeof result === "string" ? { userId: result } : result;
+        quickdrawSocket.userId = identity?.userId;
+        quickdrawSocket.principalType = identity?.principalType;
+        quickdrawSocket.claims = identity?.claims;
+        let serviceAccess = identity?.serviceAccess;
+        if (!serviceAccess && identity?.userId && options.auth.loadServiceAccess) {
+          serviceAccess = await options.auth.loadServiceAccess(identity.userId) ?? void 0;
+        }
+        quickdrawSocket.serviceAccess = serviceAccess ?? {};
       }
       next();
     } catch (error) {
@@ -1540,6 +2053,14 @@ function createQuickdrawServer(options) {
       socketId: quickdrawSocket.id,
       userId: quickdrawSocket.userId
     });
+    if (quickdrawSocket.userId) {
+      void quickdrawSocket.join(userRoom(quickdrawSocket.userId));
+    }
+    quickdrawSocket.emit("auth:info", {
+      userId: quickdrawSocket.userId ?? null,
+      serviceAccess: quickdrawSocket.serviceAccess ?? {},
+      principalType: quickdrawSocket.principalType
+    });
     quickdrawSocket.on("disconnect", () => {
       serverLogger.info("Socket disconnected", {
         socketId: quickdrawSocket.id,
@@ -2946,6 +3467,6 @@ Auto-generated documentation for all services.
   );
 }
 
-export { BaseService, DEFAULT_MOCK_PATH_PREFIX, McpRegistry, OAUTH_RETURN_ORIGIN_COOKIE, SESSION_COOKIE, ServiceRegistry, 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 { BaseRpcService, BaseService, CollectionManager, DEFAULT_MOCK_PATH_PREFIX, McpRegistry, OAUTH_RETURN_ORIGIN_COOKIE, SESSION_COOKIE, ServiceRegistry, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map