opinionated-machine 6.14.0 → 6.15.0

package/README.md

@@ -58,6 +58,17 @@ Very opinionated DI framework for fastify, built on top of awilix
     - [Room Query Methods](#room-query-methods)
     - [Auto-Leave on Disconnect](#auto-leave-on-disconnect)
     - [Multi-Node Deployments with Redis](#multi-node-deployments-with-redis)
+  - [SSE Subscriptions](#sse-subscriptions)
+    - [Defining Event Metadata](#defining-event-metadata)
+    - [Defining Resolvers](#defining-resolvers)
+    - [Configuring the Manager](#configuring-the-manager)
+    - [Integrating with a Controller](#integrating-with-a-controller)
+    - [Publishing Events](#publishing-events)
+    - [Refreshing Preferences Mid-Connection](#refreshing-preferences-mid-connection)
+    - [Pipeline Semantics](#pipeline-semantics)
+    - [Multi-Node Support](#multi-node-support)
+    - [Data Loading with layered-loader](#data-loading-with-layered-loader)
+    - [Testing](#testing)
   - [SSE Test Utilities](#sse-test-utilities)
     - [Quick Reference](#quick-reference)
     - [Inject vs HTTP Comparison](#inject-vs-http-comparison)
@@ -1803,6 +1814,191 @@ The Redis adapter uses Pub/Sub for cross-node message propagation. When you call
 
 See the [@opinionated-machine/sse-rooms-redis](./packages/sse-rooms-redis/README.md) package for detailed documentation on Redis adapter configuration and usage.
 
+### SSE Subscriptions
+
+SSE Subscriptions add user-centered event filtering on top of SSE Rooms. Users connect once to a universal stream, and a **resolver pipeline** determines which events reach them based on membership, preferences, and arbitrary business rules.
+
+#### Defining Event Metadata
+
+Define a discriminated union describing all event scopes, then create type-safe guards with `defineEventMetadata()`:
+
+```typescript
+import { defineEventMetadata } from 'opinionated-machine'
+
+type EventMetadata =
+  | { scope: 'project'; projectId: string }
+  | { scope: 'team'; teamId: string }
+  | { scope: 'global' }
+
+const meta = defineEventMetadata<EventMetadata>()('scope', ['project', 'team', 'global'])
+
+// In resolvers, guards narrow the type:
+if (meta.project(event.metadata)) {
+  event.metadata.projectId // TypeScript knows this is string
+}
+```
+
+#### Defining Resolvers
+
+Resolvers are stateless filters evaluated in pipeline order. Each resolver can `allow`, `deny`, or `defer`:
+
+```typescript
+import type { SubscriptionResolver, SubscriptionContext, FilterVerdict } from 'opinionated-machine'
+
+class ProjectMembershipResolver {
+  readonly name = 'project-membership'
+
+  async onConnect(ctx: SubscriptionContext<UserCtx>) {
+    const memberships = await this.membershipLoader.get(ctx.userContext.userId)
+    const projectIds = new Set(memberships.map(m => m.projectId))
+    return {
+      userContext: { ...ctx.userContext, projectIds },
+      rooms: Array.from(projectIds).map(id => `project:${id}`),
+    }
+  }
+
+  evaluate(ctx: SubscriptionContext<UserCtx>, event: IncomingEvent<EventMetadata>): FilterVerdict {
+    if (meta.project(event.metadata)) {
+      return ctx.userContext.projectIds.has(event.metadata.projectId)
+        ? { action: 'allow' }
+        : { action: 'deny', reason: 'not a project member' }
+    }
+    return { action: 'defer' }
+  }
+
+  async refresh(ctx: SubscriptionContext<UserCtx>) {
+    // Re-fetch memberships on demand
+    const memberships = await this.membershipLoader.get(ctx.userContext.userId)
+    const projectIds = new Set(memberships.map(m => m.projectId))
+    return {
+      userContext: { ...ctx.userContext, projectIds },
+      rooms: Array.from(projectIds).map(id => `project:${id}`),
+    }
+  }
+}
+```
+
+#### Configuring the Manager
+
+```typescript
+import { SSESubscriptionManager } from 'opinionated-machine'
+
+const subscriptionManager = new SSESubscriptionManager<UserCtx, EventMetadata>(
+  {
+    resolveUserContext: async (request) => ({
+      userId: request.user.id,
+      projectIds: new Set(),
+      mutedEventTypes: new Set(),
+    }),
+    resolvers: [
+      new ProjectMembershipResolver(membershipLoader),
+      new MutePreferencesResolver(prefsLoader),
+    ],
+    defaultPolicy: 'deny',
+    resolveUserId: (ctx) => ctx.userId,
+  },
+  { sseRoomManager, sseRoomBroadcaster },
+)
+```
+
+#### Integrating with a Controller
+
+Wire `handleConnect` and `handleDisconnect` into the SSE session lifecycle:
+
+```typescript
+class NotificationController extends AbstractSSEController<Contracts> {
+  private handleStream = buildHandler(contract, {
+    sse: (request, sse) => {
+      const session = sse.start('keepAlive')
+      this.subscriptionManager.handleConnect(session).catch(() => {
+        // Handle connection setup failure (e.g., resolver threw)
+      })
+    },
+  }, {
+    onClose: (session) => {
+      this.subscriptionManager.handleDisconnect(session)
+    },
+  })
+}
+```
+
+#### Publishing Events
+
+```typescript
+const result = await subscriptionManager.publish({
+  eventName: 'announcement',
+  data: { message: 'New feature released!' },
+  targetRooms: ['project:123'],
+  metadata: { scope: 'project', projectId: '123' },
+})
+// result: { delivered: 5, filtered: 2 }
+```
+
+`targetRooms` controls routing:
+- **Specific rooms** (`['project:123']`) — broadcast to those rooms, filter via resolver pipeline
+- **`undefined`** (omitted) — broadcast to all rooms of all managed connections
+- **Empty array** (`[]`) — no-op, returns `{ delivered: 0, filtered: 0 }`
+
+#### Refreshing Preferences Mid-Connection
+
+When a user updates preferences (e.g., mutes an event type), refresh their active connections:
+
+```typescript
+// In your REST endpoint handler:
+await prefsLoader.invalidateCacheFor(userId)
+await subscriptionManager.refreshUser(userId)
+```
+
+The manager diffs rooms and joins/leaves as needed — no reconnection required.
+
+#### Pipeline Semantics
+
+- Resolvers are evaluated in array order
+- First `deny` short-circuits — event is not delivered
+- `allow` does not short-circuit — subsequent resolvers can still deny
+- If all resolvers return `defer`, `defaultPolicy` applies (default: `deny`)
+- Resolver `evaluate()` errors are treated as `deny`
+- Resolver `refresh()` errors are caught per-resolver — the failed resolver keeps its previous state while remaining resolvers continue refreshing
+- Later resolvers in the array receive the accumulated `userContext` from earlier resolvers — use spread (`{ ...ctx.userContext, ...newFields }`) to preserve prior resolver data
+- `defaultPolicy` defaults to `'deny'` when not specified
+
+#### Multi-Node Support
+
+- Metadata flows through the adapter chain (Redis pub/sub) alongside the SSE message
+- Resolver pipeline runs locally on each node for its own connections
+- Wire format is a single v1 schema with optional `meta` — older nodes simply have no metadata
+- Use `layered-loader` for distributed cache invalidation across nodes
+
+#### Data Loading with layered-loader
+
+`layered-loader` is recommended (not required) for resolver data loading. It provides in-memory → Redis → DB caching with TTL, refresh-ahead, and distributed invalidation:
+
+```typescript
+import { Loader } from 'layered-loader'
+
+const membershipLoader = new Loader<ProjectMembership[]>({
+  inMemoryCache: { cacheType: 'lru-map', ttlInMsecs: 120_000, maxItems: 500 },
+  asyncCache: new RedisCache(redis, { json: true, ttlInMsecs: 900_000 }),
+  dataSources: [membershipDataSource],
+})
+```
+
+#### Testing
+
+Create mock resolvers for unit tests:
+
+```typescript
+const mockResolver = {
+  name: 'mock',
+  evaluate: vi.fn().mockReturnValue({ action: 'allow' }),
+}
+
+const manager = new SSESubscriptionManager(
+  { resolveUserContext: async () => mockContext, resolvers: [mockResolver] },
+  { sseRoomManager, sseRoomBroadcaster },
+)
+```
+
 ### SSE Test Utilities
 
 The library provides utilities for testing SSE endpoints.

package/dist/lib/sse/AbstractSSEController.js

@@ -393,9 +393,9 @@ export class AbstractSSEController {
      * })
      * ```
      */
-    broadcastToRoom(room, eventName, data, options) {
+    async broadcastToRoom(room, eventName, data, options) {
         if (!this._roomBroadcaster) {
-            return Promise.resolve(0);
+            return 0;
         }
         const message = {
             event: eventName,
@@ -403,7 +403,8 @@ export class AbstractSSEController {
             id: options?.id ?? randomUUID(),
             retry: options?.retry,
         };
-        return this._roomBroadcaster.broadcastMessage(room, message, options);
+        const { delivered } = await this._roomBroadcaster.broadcastMessage(room, message, options);
+        return delivered;
     }
     /**
      * Join a connection to one or more rooms.

package/dist/lib/sse/AbstractSSEController.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractSSEController.js","sourceRoot":"","sources":["../../../lib/sse/AbstractSSEController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAOxC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAOnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAmBlD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAkBlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,qBAAqB;IAGzC,gDAAgD;IACtC,WAAW,GAA4B,IAAI,GAAG,EAAE,CAAA;IAE1D,yCAAyC;IACxB,cAAc,CAAgB;IAE/C,0DAA0D;IACzC,YAAY,CAAiB;IAE9C,kEAAkE;IACjD,gBAAgB,CAAqB;IAEtD;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,aAAqB,EAAE,SAA+B;QAChE,IAAI,SAAS,EAAE,mBAAmB,EAAE,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,aAAa,EAAE,CAAA;QAC3C,CAAC;QAED,IAAI,SAAS,EAAE,eAAe,EAAE,CAAC;YAC/B,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC,eAAe,CAAA;YACjD,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC,WAAW,CAAA;YACzD,SAAS,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAA;QAChF,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAW,aAAa;QACtB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,wFAAwF;gBACtF,gDAAgD,CACnD,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAA;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAW,eAAe;QACxB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAA;IAC9B,CAAC;IA0BD;;;;;;;;;;;;;;;OAeG;IACK,KAAK,CAAC,SAAS,CAAI,YAAoB,EAAE,OAAsB;QACrE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,KAAK,CAAA;QACd,CAAC;QAED,kDAAkD;QAClD,IAAI,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACrD,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBACpB,MAAM,IAAI,aAAa,CAAC;wBACtB,OAAO,EAAE,0CAA0C,OAAO,CAAC,KAAK,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;wBAC5F,SAAS,EAAE,4BAA4B;qBACxC,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,UAAU,CAAC,KAAiB,CAAA;YAC1C,iFAAiF;YACjF,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;gBACnB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAA;YACF,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,uFAAuF;YACvF,6EAA6E;YAC7E,gEAAgE;YAChE,IAAI,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAA;YACvC,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,aAAa,CAAI,YAAoB,EAAE,OAAsB;QAClE,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;IAED;;;;OAIG;IACH,IAAW,oBAAoB;QAC7B,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,iBAAiB,CACtB,YAAoB,EACpB,OAKC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,SAAS,CAAI,OAAsB;QACjD,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;QACzD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;YAC/B,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;gBACtC,IAAI,EAAE,CAAA;YACR,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,WAAW,CACzB,OAAsB,EACtB,SAA8C;QAE9C,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,KAAK,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAChD,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;gBACjE,IAAI,EAAE,CAAA;YACR,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACO,cAAc;QACtB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED;;OAEG;IACO,kBAAkB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,eAAe,CAAC,YAAoB;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,UAAU,CAAC,KAAiB,CAAA;YAC1C,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;QAED,gEAAgE;QAChE,IAAI,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAA;QACvC,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACxB,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;QACzD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;QAC1B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,kBAAkB,CAAC,UAAsB;QAC9C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;QAE/C,IAAI,CAAC,uBAAuB,EAAE,CAAC,UAAU,CAAC,CAAA;QAC1C,qEAAqE;QACrE,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IAChD,CAAC;IAED;;;;;;OAMG;IACI,oBAAoB,CAAC,YAAoB;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,kEAAkE;YAClE,OAAM;QACR,CAAC;QACD,IAAI,CAAC,kBAAkB,EAAE,CAAC,UAAU,CAAC,CAAA;QACrC,8BAA8B;QAC9B,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAA;QAEnD,qCAAqC;QACrC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;QACzC,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAA;QAEtD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACvC,CAAC;IAED,+EAA+E;IAC/E,kBAAkB;IAClB,+EAA+E;IAE/E;;;;;OAKG;IACH,IAAc,WAAW;QACvB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED;;OAEG;IACH,IAAc,YAAY;QACxB,OAAO,IAAI,CAAC,YAAY,KAAK,SAAS,CAAA;IACxC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACO,eAAe,CACvB,IAAuB,EACvB,SAAoB,EACpB,IAES,EACT,OAAgE;QAEhE,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;QAC3B,CAAC;QACD,MAAM,OAAO,GAAe;YAC1B,KAAK,EAAE,SAAS;YAChB,IAAI;YACJ,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,UAAU,EAAE;YAC/B,KAAK,EAAE,OAAO,EAAE,KAAK;SACtB,CAAA;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACvE,CAAC;IAED;;;;;;OAMG;IACO,QAAQ,CAAC,YAAoB,EAAE,IAAuB;QAC9D,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC;IAED;;;;;;OAMG;IACO,SAAS,CAAC,YAAoB,EAAE,IAAuB;QAC/D,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;OAKG;IACO,oBAAoB,CAAC,IAAY;QACzC,OAAO,IAAI,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAChE,CAAC;IAED;;;;;OAKG;IACO,wBAAwB,CAAC,IAAY;QAC7C,OAAO,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnE,CAAC;CACF"}
+{"version":3,"file":"AbstractSSEController.js","sourceRoot":"","sources":["../../../lib/sse/AbstractSSEController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAOxC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAOnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAmBlD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAkBlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,qBAAqB;IAGzC,gDAAgD;IACtC,WAAW,GAA4B,IAAI,GAAG,EAAE,CAAA;IAE1D,yCAAyC;IACxB,cAAc,CAAgB;IAE/C,0DAA0D;IACzC,YAAY,CAAiB;IAE9C,kEAAkE;IACjD,gBAAgB,CAAqB;IAEtD;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,aAAqB,EAAE,SAA+B;QAChE,IAAI,SAAS,EAAE,mBAAmB,EAAE,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,aAAa,EAAE,CAAA;QAC3C,CAAC;QAED,IAAI,SAAS,EAAE,eAAe,EAAE,CAAC;YAC/B,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC,eAAe,CAAA;YACjD,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC,WAAW,CAAA;YACzD,SAAS,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAA;QAChF,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAW,aAAa;QACtB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,wFAAwF;gBACtF,gDAAgD,CACnD,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAA;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAW,eAAe;QACxB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAA;IAC9B,CAAC;IA0BD;;;;;;;;;;;;;;;OAeG;IACK,KAAK,CAAC,SAAS,CAAI,YAAoB,EAAE,OAAsB;QACrE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,KAAK,CAAA;QACd,CAAC;QAED,kDAAkD;QAClD,IAAI,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACrD,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBACpB,MAAM,IAAI,aAAa,CAAC;wBACtB,OAAO,EAAE,0CAA0C,OAAO,CAAC,KAAK,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;wBAC5F,SAAS,EAAE,4BAA4B;qBACxC,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,UAAU,CAAC,KAAiB,CAAA;YAC1C,iFAAiF;YACjF,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;gBACnB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAA;YACF,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,uFAAuF;YACvF,6EAA6E;YAC7E,gEAAgE;YAChE,IAAI,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAA;YACvC,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,aAAa,CAAI,YAAoB,EAAE,OAAsB;QAClE,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;IAED;;;;OAIG;IACH,IAAW,oBAAoB;QAC7B,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,iBAAiB,CACtB,YAAoB,EACpB,OAKC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,SAAS,CAAI,OAAsB;QACjD,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;QACzD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;YAC/B,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;gBACtC,IAAI,EAAE,CAAA;YACR,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,WAAW,CACzB,OAAsB,EACtB,SAA8C;QAE9C,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,KAAK,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAChD,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;gBACjE,IAAI,EAAE,CAAA;YACR,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACO,cAAc;QACtB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED;;OAEG;IACO,kBAAkB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,eAAe,CAAC,YAAoB;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,UAAU,CAAC,KAAiB,CAAA;YAC1C,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;QAED,gEAAgE;QAChE,IAAI,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAA;QACvC,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACxB,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;QACzD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;QAC1B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,kBAAkB,CAAC,UAAsB;QAC9C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;QAE/C,IAAI,CAAC,uBAAuB,EAAE,CAAC,UAAU,CAAC,CAAA;QAC1C,qEAAqE;QACrE,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IAChD,CAAC;IAED;;;;;;OAMG;IACI,oBAAoB,CAAC,YAAoB;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,kEAAkE;YAClE,OAAM;QACR,CAAC;QACD,IAAI,CAAC,kBAAkB,EAAE,CAAC,UAAU,CAAC,CAAA;QACrC,8BAA8B;QAC9B,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAA;QAEnD,qCAAqC;QACrC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;QACzC,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAA;QAEtD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACvC,CAAC;IAED,+EAA+E;IAC/E,kBAAkB;IAClB,+EAA+E;IAE/E;;;;;OAKG;IACH,IAAc,WAAW;QACvB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED;;OAEG;IACH,IAAc,YAAY;QACxB,OAAO,IAAI,CAAC,YAAY,KAAK,SAAS,CAAA;IACxC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACO,KAAK,CAAC,eAAe,CAC7B,IAAuB,EACvB,SAAoB,EACpB,IAES,EACT,OAAgE;QAEhE,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,OAAO,CAAC,CAAA;QACV,CAAC;QACD,MAAM,OAAO,GAAe;YAC1B,KAAK,EAAE,SAAS;YAChB,IAAI;YACJ,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,UAAU,EAAE;YAC/B,KAAK,EAAE,OAAO,EAAE,KAAK;SACtB,CAAA;QACD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QAC1F,OAAO,SAAS,CAAA;IAClB,CAAC;IAED;;;;;;OAMG;IACO,QAAQ,CAAC,YAAoB,EAAE,IAAuB;QAC9D,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC;IAED;;;;;;OAMG;IACO,SAAS,CAAC,YAAoB,EAAE,IAAuB;QAC/D,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;OAKG;IACO,oBAAoB,CAAC,IAAY;QACzC,OAAO,IAAI,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAChE,CAAC;IAED;;;;;OAKG;IACO,wBAAwB,CAAC,IAAY;QAC7C,OAAO,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnE,CAAC;CACF"}

package/dist/lib/sse/index.d.ts

@@ -2,6 +2,7 @@ export type { AllContractEventNames, AllContractEvents, AnySSEContractDefinition
 export { type BuildFastifySSERoutesReturnType, buildFastifyRoute, buildHandler, type FastifySSEHandlerConfig, type FastifySSEPreHandler, type FastifySSERouteOptions, type InferSSERequest, type RegisterSSERoutesOptions, type SSEContext, type SSEOnlyHandlers, type SSERouteHandler, type SSESession, } from '../routes/index.js';
 export { AbstractSSEController, type SSEControllerConfig, type SSEEventSender, type SSELogger, type SSEMessage, } from './AbstractSSEController.js';
 export { defineEvent, type SSEEventDefinition } from './defineEvent.js';
-export { defineRoom, InMemoryAdapter, type RoomBroadcastOptions, type RoomNameResolver, type SSERoomAdapter, SSERoomBroadcaster, SSERoomManager, type SSERoomManagerConfig, type SSERoomMessageHandler, type SSERoomOperations, } from './rooms/index.js';
+export { defineRoom, InMemoryAdapter, type PreDeliveryFilter, type RoomBroadcastOptions, type RoomNameResolver, type SSERoomAdapter, SSERoomBroadcaster, SSERoomManager, type SSERoomManagerConfig, type SSERoomMessageHandler, type SSERoomOperations, } from './rooms/index.js';
 export { type SSESessionEvent, SSESessionSpy } from './SSESessionSpy.js';
 export { type ParsedSSEEvent, type ParseSSEBufferResult, parseSSEBuffer, parseSSEEvents, } from './sseParser.js';
+export { defineEventMetadata, type ExtractMetadata, type FilterVerdict, type IncomingEvent, type MetadataGuard, type MetadataGuards, type PublishResult, type ResolverResult, SSESubscriptionManager, type SSESubscriptionManagerConfig, type SubscriptionContext, type SubscriptionPolicy, type SubscriptionResolver, } from './subscriptions/index.js';

package/dist/lib/sse/index.js

@@ -6,4 +6,6 @@ export { defineEvent } from './defineEvent.js';
 export { defineRoom, InMemoryAdapter, SSERoomBroadcaster, SSERoomManager, } from './rooms/index.js';
 export { SSESessionSpy } from './SSESessionSpy.js';
 export { parseSSEBuffer, parseSSEEvents, } from './sseParser.js';
+// SSE Subscriptions
+export { defineEventMetadata, SSESubscriptionManager, } from './subscriptions/index.js';
 //# sourceMappingURL=index.js.map

package/dist/lib/sse/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/sse/index.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,OAAO,EAEL,iBAAiB,EACjB,YAAY,GAUb,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,qBAAqB,GAKtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAA;AACvE,mCAAmC;AACnC,OAAO,EACL,UAAU,EACV,eAAe,EAIf,kBAAkB,EAClB,cAAc,GAIf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAwB,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAGL,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/sse/index.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,OAAO,EAEL,iBAAiB,EACjB,YAAY,GAUb,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,qBAAqB,GAKtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAA;AACvE,mCAAmC;AACnC,OAAO,EACL,UAAU,EACV,eAAe,EAKf,kBAAkB,EAClB,cAAc,GAIf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAwB,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAGL,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EAQnB,sBAAsB,GAKvB,MAAM,0BAA0B,CAAA"}

package/dist/lib/sse/rooms/SSERoomBroadcaster.d.ts

@@ -2,7 +2,7 @@ import type { z } from 'zod';
 import type { SSEEventDefinition } from '../defineEvent.js';
 import type { SSEMessage } from '../sseTypes.js';
 import type { SSERoomManager } from './SSERoomManager.js';
-import type { RoomBroadcastOptions } from './types.js';
+import type { BroadcastResult, PreDeliveryFilter, RoomBroadcastOptions } from './types.js';
 /**
  * Shared, non-generic room broadcaster that can be registered once in DI
  * and used by multiple controllers and domain services.
@@ -31,9 +31,18 @@ export declare class SSERoomBroadcaster {
     private readonly _roomManager;
     private readonly senders;
     private readonly dedupCache;
+    private preDeliveryFilter?;
     constructor(deps: {
         sseRoomManager: SSERoomManager;
     });
+    /**
+     * Set a pre-delivery filter that runs before sending to each connection.
+     * Used by SSESubscriptionManager for resolver pipeline evaluation.
+     * Only one filter can be active at a time — calling this method twice throws,
+     * to prevent silently replacing an already-installed filter (which is almost
+     * always a wiring bug, e.g. registering two SSESubscriptionManagers).
+     */
+    setPreDeliveryFilter(filter: PreDeliveryFilter): void;
     /**
      * Public getter for the underlying room manager.
      * Used by the route builder for `session.rooms`.
@@ -54,11 +63,13 @@ export declare class SSERoomBroadcaster {
      * @param event - Event definition created by `defineEvent()`
      * @param data - Event data (must match the schema from the event definition)
      * @param options - Broadcast options (local, id, retry)
-     * @returns Number of local connections the message was sent to
+     * @returns Number of local connections the message was successfully delivered to.
+     *          For separate `delivered`/`filtered` counts, call {@link broadcastMessage}.
      */
     broadcastToRoom<T extends z.ZodType>(room: string | string[], event: SSEEventDefinition<string, T>, data: z.input<T>, options?: RoomBroadcastOptions & {
         id?: string;
         retry?: number;
+        metadata?: Record<string, unknown>;
     }): Promise<number>;
     /**
      * Lower-level broadcast API — sends a raw SSEMessage to all connections in one or more rooms.
@@ -68,9 +79,14 @@ export declare class SSERoomBroadcaster {
      * @param room - Room name or array of room names
      * @param message - The SSE message to broadcast
      * @param options - Broadcast options (local)
-     * @returns Number of local connections the message was sent to
+     * @returns `delivered` is the number of local connections the message was sent to;
+     *          `filtered` is the number of local connections skipped by the pre-delivery
+     *          filter. Returning both per-call (rather than tracking on the broadcaster)
+     *          avoids races between concurrent broadcasts.
      */
-    broadcastMessage(room: string | string[], message: SSEMessage, options?: RoomBroadcastOptions): Promise<number>;
+    broadcastMessage(room: string | string[], message: SSEMessage, options?: RoomBroadcastOptions & {
+        metadata?: Record<string, unknown>;
+    }): Promise<BroadcastResult>;
     /**
      * Get all connection IDs in a room.
      *

package/dist/lib/sse/rooms/SSERoomBroadcaster.js

@@ -29,13 +29,27 @@ export class SSERoomBroadcaster {
     _roomManager;
     senders = [];
     dedupCache = new Map();
+    preDeliveryFilter;
     constructor(deps) {
         this._roomManager = deps.sseRoomManager;
         // Wire up adapter message handler to forward remote broadcasts to local connections
-        this._roomManager.onRemoteMessage((room, message, _sourceNodeId) => {
-            return this.handleRemoteBroadcast(room, message);
+        this._roomManager.onRemoteMessage((room, message, _sourceNodeId, metadata) => {
+            return this.handleRemoteBroadcast(room, message, metadata);
         });
     }
+    /**
+     * Set a pre-delivery filter that runs before sending to each connection.
+     * Used by SSESubscriptionManager for resolver pipeline evaluation.
+     * Only one filter can be active at a time — calling this method twice throws,
+     * to prevent silently replacing an already-installed filter (which is almost
+     * always a wiring bug, e.g. registering two SSESubscriptionManagers).
+     */
+    setPreDeliveryFilter(filter) {
+        if (this.preDeliveryFilter) {
+            throw new Error('SSERoomBroadcaster pre-delivery filter is already set; only one filter can be active at a time');
+        }
+        this.preDeliveryFilter = filter;
+    }
     /**
      * Public getter for the underlying room manager.
      * Used by the route builder for `session.rooms`.
@@ -60,16 +74,18 @@ export class SSERoomBroadcaster {
      * @param event - Event definition created by `defineEvent()`
      * @param data - Event data (must match the schema from the event definition)
      * @param options - Broadcast options (local, id, retry)
-     * @returns Number of local connections the message was sent to
+     * @returns Number of local connections the message was successfully delivered to.
+     *          For separate `delivered`/`filtered` counts, call {@link broadcastMessage}.
      */
-    broadcastToRoom(room, event, data, options) {
+    async broadcastToRoom(room, event, data, options) {
         const message = {
             event: event.event,
             data,
             id: options?.id ?? randomUUID(),
             retry: options?.retry,
         };
-        return this.broadcastMessage(room, message, options);
+        const { delivered } = await this.broadcastMessage(room, message, options);
+        return delivered;
     }
     /**
      * Lower-level broadcast API — sends a raw SSEMessage to all connections in one or more rooms.
@@ -79,25 +95,36 @@ export class SSERoomBroadcaster {
      * @param room - Room name or array of room names
      * @param message - The SSE message to broadcast
      * @param options - Broadcast options (local)
-     * @returns Number of local connections the message was sent to
+     * @returns `delivered` is the number of local connections the message was sent to;
+     *          `filtered` is the number of local connections skipped by the pre-delivery
+     *          filter. Returning both per-call (rather than tracking on the broadcaster)
+     *          avoids races between concurrent broadcasts.
      */
     async broadcastMessage(room, message, options) {
         const rooms = Array.isArray(room) ? room : [room];
         const connectionIds = this.collectRoomConnections(rooms);
-        // Send to all local connections
-        let sent = 0;
+        let delivered = 0;
+        let filtered = 0;
         for (const connId of connectionIds) {
+            // Check pre-delivery filter if set
+            if (this.preDeliveryFilter) {
+                const allowed = await this.preDeliveryFilter(connId, message, options?.metadata);
+                if (!allowed) {
+                    filtered++;
+                    continue;
+                }
+            }
             if (await this.sendToConnection(connId, message)) {
-                sent++;
+                delivered++;
             }
         }
         // Publish to adapter for cross-node propagation (unless local-only)
         if (!options?.local) {
             for (const r of rooms) {
-                await this._roomManager.publish(r, message, options);
+                await this._roomManager.publish(r, message, options, options?.metadata);
             }
         }
-        return sent;
+        return { delivered, filtered };
     }
     /**
      * Get all connection IDs in a room.
@@ -139,12 +166,17 @@ export class SSERoomBroadcaster {
      * Handle broadcasts from other nodes (via adapter).
      * Deduplicates messages per-connection based on message ID.
      */
-    async handleRemoteBroadcast(room, message) {
+    async handleRemoteBroadcast(room, message, metadata) {
         const connectionIds = this._roomManager.getConnectionsInRoom(room);
         for (const connId of connectionIds) {
             if (this.isDuplicateMessage(connId, message.id)) {
                 continue;
             }
+            if (this.preDeliveryFilter) {
+                const allowed = await this.preDeliveryFilter(connId, message, metadata);
+                if (!allowed)
+                    continue;
+            }
             await this.sendToConnection(connId, message);
         }
     }

package/dist/lib/sse/rooms/SSERoomBroadcaster.js.map

@@ -1 +1 @@
-{"version":3,"file":"SSERoomBroadcaster.js","sourceRoot":"","sources":["../../../../lib/sse/rooms/SSERoomBroadcaster.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAOxC,8EAA8E;AAC9E,MAAM,oBAAoB,GAAG,IAAI,CAAA;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,kBAAkB;IACZ,YAAY,CAAgB;IAC5B,OAAO,GAA8D,EAAE,CAAA;IACvE,UAAU,GAA6B,IAAI,GAAG,EAAE,CAAA;IAEjE,YAAY,IAAwC;QAClD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,cAAc,CAAA;QAEvC,oFAAoF;QACpF,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE;YACjE,OAAO,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAClD,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;OAGG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,MAA6D;QAC1E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC3B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,eAAe,CACb,IAAuB,EACvB,KAAoC,EACpC,IAAgB,EAChB,OAAgE;QAEhE,MAAM,OAAO,GAAe;YAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI;YACJ,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,UAAU,EAAE;YAC/B,KAAK,EAAE,OAAO,EAAE,KAAK;SACtB,CAAA;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACtD,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,gBAAgB,CACpB,IAAuB,EACvB,OAAmB,EACnB,OAA8B;QAE9B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACjD,MAAM,aAAa,GAAG,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAA;QAExD,gCAAgC;QAChC,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;YACnC,IAAI,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;gBACjD,IAAI,EAAE,CAAA;YACR,CAAC;QACH,CAAC;QAED,oEAAoE;QACpE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;YACtD,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,IAAY;QAC/B,OAAO,IAAI,CAAC,YAAY,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;IACrD,CAAC;IAED;;;;;OAKG;IACH,wBAAwB,CAAC,IAAY;QACnC,OAAO,IAAI,CAAC,YAAY,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAA;IACzD,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,YAAoB;QACpC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACtC,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,gBAAgB,CAAC,MAAc,EAAE,GAAe;QAC5D,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC9B,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,qBAAqB,CAAC,IAAY,EAAE,OAAmB;QACnE,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;QAClE,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChD,SAAQ;YACV,CAAC;YACD,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,kBAAkB,CAAC,YAAoB,EAAE,SAA6B;QAC5E,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,IAAI,GAAG,EAAE,CAAA;YACjB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAA;QAC1C,CAAC;QAED,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,oDAAoD;QACpD,IAAI,KAAK,CAAC,IAAI,IAAI,oBAAoB,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAe,CAAA;YACpD,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACtB,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACpB,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;OAEG;IACK,sBAAsB,CAAC,KAAe;QAC5C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAA;QACvC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,aAAa,CAAA;IACtB,CAAC;CACF"}
+{"version":3,"file":"SSERoomBroadcaster.js","sourceRoot":"","sources":["../../../../lib/sse/rooms/SSERoomBroadcaster.ts"],"names":[],"mappings":"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"}

package/dist/lib/sse/rooms/SSERoomManager.d.ts

@@ -128,7 +128,10 @@ export declare class SSERoomManager {
      *
      * @param room - The room to publish to
      * @param message - The SSE message to broadcast
-     * @param options - Broadcast options
+     * @param options - Broadcast options (e.g. `local: true` to skip adapter)
+     * @param metadata - Optional opaque metadata propagated to other nodes
+     *   alongside the message. Used by `SSESubscriptionManager` for cross-node
+     *   resolver evaluation; not delivered to clients.
      */
-    publish(room: string, message: SSEMessage, options?: RoomBroadcastOptions): Promise<void>;
+    publish(room: string, message: SSEMessage, options?: RoomBroadcastOptions, metadata?: Record<string, unknown>): Promise<void>;
 }

package/dist/lib/sse/rooms/SSERoomManager.js

@@ -51,12 +51,12 @@ export class SSERoomManager {
         this.adapter = config.adapter ?? new InMemoryAdapter();
         this.nodeId = config.nodeId ?? randomUUID();
         // Set up adapter message handler
-        this.adapter.onMessage((room, message, sourceNodeId) => {
+        this.adapter.onMessage((room, message, sourceNodeId, metadata) => {
             // Skip messages from this node (we already handled them locally)
             if (sourceNodeId === this.nodeId) {
                 return;
             }
-            this.messageHandler?.(room, message, sourceNodeId);
+            return this.messageHandler?.(room, message, sourceNodeId, metadata);
         });
     }
     /**
@@ -222,13 +222,16 @@ export class SSERoomManager {
      *
      * @param room - The room to publish to
      * @param message - The SSE message to broadcast
-     * @param options - Broadcast options
+     * @param options - Broadcast options (e.g. `local: true` to skip adapter)
+     * @param metadata - Optional opaque metadata propagated to other nodes
+     *   alongside the message. Used by `SSESubscriptionManager` for cross-node
+     *   resolver evaluation; not delivered to clients.
      */
-    async publish(room, message, options) {
+    async publish(room, message, options, metadata) {
         if (options?.local) {
             return; // Skip adapter for local-only broadcasts
         }
-        await this.adapter.publish(room, message);
+        await this.adapter.publish(room, message, metadata);
     }
 }
 //# sourceMappingURL=SSERoomManager.js.map

package/dist/lib/sse/rooms/SSERoomManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"SSERoomManager.js","sourceRoot":"","sources":["../../../../lib/sse/rooms/SSERoomManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SSERoomManager.js","sourceRoot":"","sources":["../../../../lib/sse/rooms/SSERoomManager.ts"],"names":[],"mappings":"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"}

package/dist/lib/sse/rooms/adapters/InMemoryAdapter.d.ts

@@ -13,6 +13,6 @@ export declare class InMemoryAdapter implements SSERoomAdapter {
     disconnect(): Promise<void>;
     subscribe(_room: string): Promise<void>;
     unsubscribe(_room: string): Promise<void>;
-    publish(_room: string, _message: SSEMessage): Promise<void>;
+    publish(_room: string, _message: SSEMessage, _metadata?: Record<string, unknown>): Promise<void>;
     onMessage(_handler: SSERoomMessageHandler): void;
 }

package/dist/lib/sse/rooms/adapters/InMemoryAdapter.js

@@ -23,7 +23,7 @@ export class InMemoryAdapter {
         // No-op for in-memory adapter
         return Promise.resolve();
     }
-    publish(_room, _message) {
+    publish(_room, _message, _metadata) {
         // No-op for in-memory adapter - messages are only sent locally
         // The controller handles local delivery directly
         return Promise.resolve();

package/dist/lib/sse/rooms/adapters/InMemoryAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryAdapter.js","sourceRoot":"","sources":["../../../../../lib/sse/rooms/adapters/InMemoryAdapter.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IAC1B,OAAO;QACL,8BAA8B;QAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,UAAU;QACR,8BAA8B;QAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,SAAS,CAAC,KAAa;QACrB,kEAAkE;QAClE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,WAAW,CAAC,KAAa;QACvB,8BAA8B;QAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,OAAO,CAAC,KAAa,EAAE,QAAoB;QACzC,+DAA+D;QAC/D,iDAAiD;QACjD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,SAAS,CAAC,QAA+B;QACvC,wDAAwD;IAC1D,CAAC;CACF"}
+{"version":3,"file":"InMemoryAdapter.js","sourceRoot":"","sources":["../../../../../lib/sse/rooms/adapters/InMemoryAdapter.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IAC1B,OAAO;QACL,8BAA8B;QAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,UAAU;QACR,8BAA8B;QAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,SAAS,CAAC,KAAa;QACrB,kEAAkE;QAClE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,WAAW,CAAC,KAAa;QACvB,8BAA8B;QAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,OAAO,CAAC,KAAa,EAAE,QAAoB,EAAE,SAAmC;QAC9E,+DAA+D;QAC/D,iDAAiD;QACjD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,SAAS,CAAC,QAA+B;QACvC,wDAAwD;IAC1D,CAAC;CACF"}

package/dist/lib/sse/rooms/index.d.ts

@@ -2,4 +2,4 @@ export { InMemoryAdapter } from './adapters/InMemoryAdapter.js';
 export { defineRoom } from './defineRoom.js';
 export { SSERoomBroadcaster } from './SSERoomBroadcaster.js';
 export { SSERoomManager } from './SSERoomManager.js';
-export type { RoomBroadcastOptions, RoomNameResolver, SSERoomAdapter, SSERoomManagerConfig, SSERoomMessageHandler, SSERoomOperations, } from './types.js';
+export type { PreDeliveryFilter, RoomBroadcastOptions, RoomNameResolver, SSERoomAdapter, SSERoomManagerConfig, SSERoomMessageHandler, SSERoomOperations, } from './types.js';

package/dist/lib/sse/rooms/types.d.ts

@@ -63,8 +63,11 @@ export type SSERoomAdapter = {
      *
      * @param room - The room to publish to
      * @param message - The SSE message to broadcast
+     * @param metadata - Optional opaque metadata for cross-node subscription
+     *   filtering (e.g. event scope, project id). Adapters serialize this
+     *   alongside the message; it is not delivered to SSE clients.
      */
-    publish(room: string, message: SSEMessage): Promise<void>;
+    publish(room: string, message: SSEMessage, metadata?: Record<string, unknown>): Promise<void>;
     /**
      * Register a handler for messages received from other nodes.
      * The handler should forward the message to local connections in the room.
@@ -75,8 +78,37 @@ export type SSERoomAdapter = {
 };
 /**
  * Handler for messages received from the adapter (other nodes).
+ *
+ * @param room - The room the message was published to
+ * @param message - The SSE message
+ * @param sourceNodeId - Id of the node that originated the publish; used to
+ *   suppress echoing the publisher's own messages back to it
+ * @param metadata - Optional opaque metadata attached at publish time;
+ *   `undefined` for v1 (pre-metadata) messages from older nodes
+ */
+export type SSERoomMessageHandler = (room: string, message: SSEMessage, sourceNodeId: string, metadata?: Record<string, unknown>) => void | Promise<void>;
+/**
+ * Pre-delivery filter called before sending to each connection.
+ * Returns true to deliver, false to skip.
+ *
+ * Used by SSESubscriptionManager to inject resolver pipeline evaluation
+ * into the broadcaster's delivery path.
+ *
+ * When no filter is set, all connections receive all messages (existing behavior).
  */
-export type SSERoomMessageHandler = (room: string, message: SSEMessage, sourceNodeId: string) => void | Promise<void>;
+export type PreDeliveryFilter = (connectionId: string, message: SSEMessage, metadata?: Record<string, unknown>) => Promise<boolean> | boolean;
+/**
+ * Result of a single broadcast call.
+ *
+ * Returned per-call (rather than tracked on the broadcaster) so that concurrent
+ * broadcasts cannot interleave their counters.
+ */
+export type BroadcastResult = {
+    /** Local connections the message was successfully sent to. */
+    delivered: number;
+    /** Local connections skipped by the pre-delivery filter. */
+    filtered: number;
+};
 /**
  * Configuration for the SSE Room Manager.
  */