@velajs/vela 1.16.0 → 1.17.0

package/dist/live/live.types.d.ts

@@ -0,0 +1,138 @@
+import type { WsClient } from '../index';
+/**
+ * Identity captured at subscribe time and replayed into every re-run of the
+ * subscription's query — never re-read from the client afterwards. Free-form;
+ * `expiresAt` (epoch ms) is the one recognized field: a lapsed identity drops
+ * the socket before it receives another scoped push (outbound enforcement —
+ * a passive subscriber never trips inbound checks).
+ */
+export interface LiveIdentity {
+    [key: string]: unknown;
+    expiresAt?: number;
+}
+/** Second positional argument every `@LiveQuery` handler receives. */
+export interface LiveQueryContext {
+    identity?: LiveIdentity;
+    /** The subscribed connection's id. */
+    clientId: string;
+    /** Rooms the connection was in when it subscribed. */
+    rooms: string[];
+}
+export interface LiveQueryOptions<A = unknown> {
+    /**
+     * Dependency tags this query's result is built from — the invalidation
+     * contract. Static for the common case; the function form derives
+     * per-entity tags from the (parsed) subscribe args. Writes invalidate tags
+     * via `LiveInvalidation.invalidate()` (the CRUD bridge does it
+     * automatically with `crud:<table>` tags).
+     */
+    tags: string[] | ((args: A) => string[]);
+    /** Key field for incremental list deltas (default `'id'`). */
+    key?: string;
+    /**
+     * Args validator, run ONCE at subscribe (a zod schema's `.parse` slots in
+     * directly). A throw rejects the subscription with a `bad_args` error frame.
+     */
+    parse?: (args: unknown) => A;
+}
+/** One `@LiveQuery` declaration on a `@LiveResolver` class. */
+export interface LiveQueryMetadata {
+    name: string;
+    methodName: string | symbol;
+    options: LiveQueryOptions;
+}
+/** Class-level marker meta written by `@LiveResolver()`. */
+export interface LiveResolverMetadata {
+}
+/** A position in this log scope's ordered invalidation log. */
+export interface CommitStamp {
+    cursor: number;
+    epoch: string;
+}
+/**
+ * Resume verdict for a reconnecting subscription:
+ * - `'resume'` — nothing the subscription depends on changed while away; keep
+ *   the client's cached value and just advance its cursor.
+ * - `'rerun'` — a relevant tag was invalidated in the gap; re-run and snapshot.
+ * - `'snapshot'` — the gap cannot be reasoned about (epoch fork, trimmed log,
+ *   rollback); re-run and snapshot.
+ */
+export type ResumeVerdict = 'resume' | 'rerun' | 'snapshot';
+/**
+ * The ordered tag-invalidation log for ONE log scope (this process on
+ * node/bun/deno; one Durable Object on Cloudflare). Cursor = monotonic
+ * sequence; epoch = timeline token rolled whenever monotonicity can no longer
+ * be guaranteed (process restart, DO reset).
+ */
+export interface CursorLog {
+    append(tags: string[]): CommitStamp | Promise<CommitStamp>;
+    current(): CommitStamp | Promise<CommitStamp>;
+    evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict | Promise<ResumeVerdict>;
+}
+/** A tag invalidation crossing the driver seam. `room` addresses the log scope holding the subscribers (advisory for local delivery). */
+export interface InvalidationCommand {
+    room?: string;
+    tags: string[];
+    /** Origin instance id — lets pub/sub drivers drop their own echo. */
+    origin?: string;
+}
+/** What a driver delivers invalidations INTO — the live engine of one log scope. */
+export interface LiveInvalidationSink {
+    applyInvalidation(cmd: InvalidationCommand): CommitStamp | Promise<CommitStamp>;
+}
+/**
+ * Cross-boundary invalidation transport — the live sibling of the WebSocket
+ * `SyncDriver`, carrying TAGS (re-run instructions) instead of pre-serialized
+ * frames. `localLive()` is the in-core single-scope default; platform packages
+ * (`durableObjectLive()` in @velajs/cloudflare, `redisLive()` in
+ * websocket-node) implement it out-of-core. `dispatch` returns the commit
+ * stamp of the targeted log scope when the driver can observe it.
+ */
+export interface LiveDriver {
+    readonly kind: string;
+    bind(sink: LiveInvalidationSink): void;
+    dispatch(cmd: InvalidationCommand): CommitStamp | undefined | Promise<CommitStamp | undefined>;
+    start?(): void | Promise<void>;
+    stop?(): void | Promise<void>;
+}
+/** One live subscription as tracked by the engine (and persisted by transports that survive eviction). */
+export interface SubscriptionRecord {
+    sub: string;
+    query: string;
+    args: unknown;
+    /** Frozen at subscribe from the (parsed) args. */
+    tags: string[];
+    /** Delta key field (subscribe-frame override wins over the handler option). */
+    key?: string;
+    identity?: LiveIdentity;
+    /**
+     * The last result this subscription confirmed on the wire (the delta diff
+     * baseline). `undefined` after a cursor-resume: the server never re-ran the
+     * query, so the next relevant change sends a full snapshot.
+     */
+    lastJson?: string;
+    lastCursor?: number;
+}
+export interface LivePresenceOptions {
+    /** Roster entries older than this are filtered at read time (default 30_000 ms). */
+    ttlMs?: number;
+}
+export interface LiveModuleOptions {
+    /** Cross-boundary invalidation driver. Defaults to `localLive()`. */
+    driver?: LiveDriver;
+    /** Ordered invalidation log. Defaults to the in-memory per-process log. */
+    log?: CursorLog;
+    /**
+     * Identity capture at subscribe. Default: a shallow copy of `client.data`
+     * (whatever the app's upgrade/`handleConnection` auth stamped there), or
+     * `undefined` when empty.
+     */
+    identity?: (client: WsClient) => LiveIdentity | undefined;
+    /** Presence preset configuration; `false` disables the built-in resolver. */
+    presence?: LivePresenceOptions | false;
+}
+/** Meta carried by the `'live'` entrypoint (transports reach the engine through it). */
+export interface LiveEntrypointMeta {
+    /** The engine — typed loosely to avoid a circular type edge; cast to `LiveEngine`. */
+    engine: unknown;
+}

package/dist/live/live.types.js

@@ -0,0 +1 @@
+/** Meta carried by the `'live'` entrypoint (transports reach the engine through it). */ export { };

package/dist/live/presence.d.ts

@@ -0,0 +1,44 @@
+/** The invalidation tag for one room's roster. `$`-prefixed: never collides with app tags. */
+export declare const presenceTag: (room: string) => string;
+/** The built-in roster query name (`useLiveQuery`-able like any app query). */
+export declare const PRESENCE_ROSTER_QUERY = "$presence.roster";
+/** One present connection as returned by the roster query. Keyed by `id` so list deltas apply. */
+export interface PresenceMember {
+    /** The connection id that heartbeats this membership. */
+    id: string;
+    meta?: unknown;
+    lastSeen: number;
+}
+/**
+ * The presence preset's server half. Heartbeats arrive as `{ t: 'presence' }`
+ * frames on the live socket (routed here by the engine); the roster is a
+ * built-in live query invalidated per room. Departure is immediate: the WS
+ * close hook reaps the member without waiting out the TTL. Staleness (an
+ * ungraceful drop the transport never noticed) is filtered AT READ TIME —
+ * no timers, per the edge rules (`setInterval` is forbidden).
+ *
+ * Scope note: the roster lives in this log scope (one process on node, one
+ * room-DO on Cloudflare — where it is exactly the room's roster).
+ */
+export declare class PresenceService {
+    private readonly ttlMs;
+    readonly enabled: boolean;
+    private readonly rooms;
+    private readonly roomsByClient;
+    private invalidator?;
+    constructor(ttlMs?: number, enabled?: boolean);
+    /** Wired by the engine so beats/reaps invalidate through the live driver. */
+    bindInvalidator(invalidator: (tags: string[]) => void): void;
+    beat(room: string, clientId: string, meta?: unknown): void;
+    /** Immediate departure on socket close — peers see it without a TTL wait. */
+    reap(clientId: string): void;
+    roster(room: string): PresenceMember[];
+}
+/** The built-in resolver backing `$presence.roster`. Registered by `LiveModule` unless presence is disabled. */
+export declare class PresenceResolver {
+    private readonly presence;
+    constructor(presence: PresenceService);
+    roster(args: {
+        room: string;
+    }): PresenceMember[];
+}

package/dist/live/presence.js

@@ -0,0 +1,130 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable } from "../index.js";
+import { LiveQuery, LiveResolver } from "./live.decorators.js";
+/** The invalidation tag for one room's roster. `$`-prefixed: never collides with app tags. */ export const presenceTag = (room)=>`$presence:${room}`;
+/** The built-in roster query name (`useLiveQuery`-able like any app query). */ export const PRESENCE_ROSTER_QUERY = '$presence.roster';
+/**
+ * The presence preset's server half. Heartbeats arrive as `{ t: 'presence' }`
+ * frames on the live socket (routed here by the engine); the roster is a
+ * built-in live query invalidated per room. Departure is immediate: the WS
+ * close hook reaps the member without waiting out the TTL. Staleness (an
+ * ungraceful drop the transport never noticed) is filtered AT READ TIME —
+ * no timers, per the edge rules (`setInterval` is forbidden).
+ *
+ * Scope note: the roster lives in this log scope (one process on node, one
+ * room-DO on Cloudflare — where it is exactly the room's roster).
+ */ export class PresenceService {
+    ttlMs;
+    enabled;
+    rooms = new Map();
+    roomsByClient = new Map();
+    invalidator;
+    constructor(ttlMs = 30_000, enabled = true){
+        this.ttlMs = ttlMs;
+        this.enabled = enabled;
+    }
+    /** Wired by the engine so beats/reaps invalidate through the live driver. */ bindInvalidator(invalidator) {
+        this.invalidator = invalidator;
+    }
+    beat(room, clientId, meta) {
+        if (!this.enabled) return;
+        let state = this.rooms.get(room);
+        if (!state) {
+            state = {
+                members: new Map()
+            };
+            this.rooms.set(room, state);
+        }
+        state.members.set(clientId, {
+            meta,
+            lastSeen: Date.now()
+        });
+        let joined = this.roomsByClient.get(clientId);
+        if (!joined) {
+            joined = new Set();
+            this.roomsByClient.set(clientId, joined);
+        }
+        joined.add(room);
+        this.invalidator?.([
+            presenceTag(room)
+        ]);
+    }
+    /** Immediate departure on socket close — peers see it without a TTL wait. */ reap(clientId) {
+        const joined = this.roomsByClient.get(clientId);
+        if (!joined) return;
+        this.roomsByClient.delete(clientId);
+        for (const room of joined){
+            const state = this.rooms.get(room);
+            if (!state) continue;
+            state.members.delete(clientId);
+            if (state.members.size === 0) this.rooms.delete(room);
+            this.invalidator?.([
+                presenceTag(room)
+            ]);
+        }
+    }
+    roster(room) {
+        const state = this.rooms.get(room);
+        if (!state) return [];
+        const oldestAlive = Date.now() - this.ttlMs;
+        return [
+            ...state.members.entries()
+        ].filter(([, member])=>member.lastSeen >= oldestAlive).map(([id, member])=>({
+                id,
+                meta: member.meta,
+                lastSeen: member.lastSeen
+            }));
+    }
+}
+export class PresenceResolver {
+    presence;
+    constructor(presence){
+        this.presence = presence;
+    }
+    roster(args) {
+        return this.presence.roster(args.room);
+    }
+}
+_ts_decorate([
+    LiveQuery(PRESENCE_ROSTER_QUERY, {
+        tags: (args)=>[
+                presenceTag(args.room)
+            ],
+        parse: (args)=>{
+            const room = args?.room;
+            if (typeof room !== 'string' || room.length === 0) {
+                throw new Error("presence roster args require a non-empty 'room' string");
+            }
+            return {
+                room
+            };
+        }
+    }),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        Object
+    ]),
+    _ts_metadata("design:returntype", Array)
+], PresenceResolver.prototype, "roster", null);
+PresenceResolver = _ts_decorate([
+    LiveResolver(),
+    Injectable(),
+    _ts_param(0, Inject(PresenceService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof PresenceService === "undefined" ? Object : PresenceService
+    ])
+], PresenceResolver);

package/dist/websocket/index.d.ts

@@ -1,4 +1,4 @@
-export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, } from './websocket.decorators';
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, ReservedWsEvent, } from './websocket.decorators';
 export { WebSocketModule } from './websocket.module';
 export type { WebSocketModuleOptions } from './websocket.module';
 export { WsDispatcher, type WsEntrypointMeta } from './ws-dispatcher';
@@ -8,5 +8,5 @@ export type { SyncDriver, RoomRegistry } from './ws-sync';
 export { buildWsExecutionContext } from './ws-execution-context';
 export { WsException, toErrorFrame } from './ws-exception';
 export { resolveWsArgs } from './ws-argument-resolver';
-export { WS_SERVER, WS_SYNC_DRIVER, WS_ROOM_REGISTRY, WS_MODULE_OPTIONS, WS_GATEWAY_METADATA, WS_SUBSCRIBE_METADATA, WsParamType, } from './websocket.tokens';
-export type { WsClient, WsServer, WsMessage, WsResponse, BroadcastCommand, BroadcastOperator, WebSocketGatewayOptions, SubscribeMessageMetadata, WsExecutionContext, WsArgumentsHost, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket.types';
+export { WS_SERVER, WS_SYNC_DRIVER, WS_ROOM_REGISTRY, WS_MODULE_OPTIONS, WS_GATEWAY_METADATA, WS_SUBSCRIBE_METADATA, WS_RESERVED_METADATA, RESERVED_WS_EVENT_PREFIX, WsParamType, } from './websocket.tokens';
+export type { WsClient, WsServer, WsMessage, WsResponse, BroadcastCommand, BroadcastOperator, WebSocketGatewayOptions, SubscribeMessageMetadata, ReservedWsEventMetadata, ReservedWsEventHandler, WsExecutionContext, WsArgumentsHost, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket.types';

package/dist/websocket/index.js

@@ -1,5 +1,5 @@
 // Decorators
-export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer } from "./websocket.decorators.js";
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, ReservedWsEvent } from "./websocket.decorators.js";
 // Module
 export { WebSocketModule } from "./websocket.module.js";
 // Dispatcher (injected/called by transports) + the 'websocket' entrypoint meta
@@ -13,4 +13,4 @@ export { WsException, toErrorFrame } from "./ws-exception.js";
 // Argument resolution (used by transports building custom dispatch)
 export { resolveWsArgs } from "./ws-argument-resolver.js";
 // Tokens
-export { WS_SERVER, WS_SYNC_DRIVER, WS_ROOM_REGISTRY, WS_MODULE_OPTIONS, WS_GATEWAY_METADATA, WS_SUBSCRIBE_METADATA, WsParamType } from "./websocket.tokens.js";
+export { WS_SERVER, WS_SYNC_DRIVER, WS_ROOM_REGISTRY, WS_MODULE_OPTIONS, WS_GATEWAY_METADATA, WS_SUBSCRIBE_METADATA, WS_RESERVED_METADATA, RESERVED_WS_EVENT_PREFIX, WsParamType } from "./websocket.tokens.js";

package/dist/websocket/websocket.decorators.d.ts

@@ -16,6 +16,20 @@ export declare function WebSocketGateway(options?: WebSocketGatewayOptions): Cla
  * exactly like `@OnEvent` (`event-emitter.decorators.ts`).
  */
 export declare function SubscribeMessage(event: string): MethodDecorator;
+/**
+ * Claims a reserved (`$`-prefixed) envelope event for a framework-module
+ * provider (see `ReservedWsEventHandler`). Reserved frames route to the
+ * decorated provider across every gateway path — gateways themselves may not
+ * subscribe to `$…` events. Stack with `@Injectable()` like `@Processor`.
+ *
+ * @example
+ * ```ts
+ * @ReservedWsEvent('$live')
+ * @Injectable()
+ * class LiveEngine implements ReservedWsEventHandler { … }
+ * ```
+ */
+export declare function ReservedWsEvent(event: string): ClassDecorator;
 /** Injects the inbound message payload (the envelope's `data`) into a handler parameter. */
 export declare const MessageBody: () => ParameterDecorator;
 /** Injects the connected socket (`WsClient`) into a handler parameter. */

package/dist/websocket/websocket.decorators.js

@@ -1,7 +1,8 @@
 import { Scope } from "../constants.js";
 import { Inject } from "../container/decorators.js";
+import { createDiscoverableDecorator } from "../discovery/index.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
-import { WS_GATEWAY_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA, WsParamType } from "./websocket.tokens.js";
+import { RESERVED_WS_EVENT_PREFIX, WS_GATEWAY_METADATA, WS_RESERVED_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA, WsParamType } from "./websocket.tokens.js";
 /**
  * Marks a class as a WebSocket gateway. Mirrors `@Controller` for the socket
  * transport: registers the class as an injectable singleton and stores its
@@ -31,6 +32,27 @@ import { WS_GATEWAY_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA, WsParamType } fr
         });
     };
 }
+const ReservedWsEventMeta = createDiscoverableDecorator(WS_RESERVED_METADATA);
+/**
+ * Claims a reserved (`$`-prefixed) envelope event for a framework-module
+ * provider (see `ReservedWsEventHandler`). Reserved frames route to the
+ * decorated provider across every gateway path — gateways themselves may not
+ * subscribe to `$…` events. Stack with `@Injectable()` like `@Processor`.
+ *
+ * @example
+ * ```ts
+ * @ReservedWsEvent('$live')
+ * @Injectable()
+ * class LiveEngine implements ReservedWsEventHandler { … }
+ * ```
+ */ export function ReservedWsEvent(event) {
+    if (!event.startsWith(RESERVED_WS_EVENT_PREFIX)) {
+        throw new Error(`@ReservedWsEvent('${event}') must claim a '${RESERVED_WS_EVENT_PREFIX}'-prefixed event — ` + 'unprefixed events belong to app gateways (@SubscribeMessage).');
+    }
+    return ReservedWsEventMeta({
+        event
+    });
+}
 function wsParamDecorator(type) {
     return ()=>(target, propertyKey, parameterIndex)=>{
             if (propertyKey === undefined) {

package/dist/websocket/websocket.tokens.d.ts

@@ -4,6 +4,13 @@ import type { RoomRegistry, SyncDriver } from './ws-sync';
 import type { WsServer } from './websocket.types';
 export declare const WS_GATEWAY_METADATA = "vela:ws-gateway";
 export declare const WS_SUBSCRIBE_METADATA = "vela:ws-subscribe";
+export declare const WS_RESERVED_METADATA = "vela:ws-reserved";
+/**
+ * Event names starting with this prefix are RESERVED for framework modules
+ * (`$live`, …): app gateways may not subscribe to them, and inbound frames
+ * carrying them route to `@ReservedWsEvent` handlers instead of gateways.
+ */
+export declare const RESERVED_WS_EVENT_PREFIX = "$";
 export declare const WsParamType: {
     readonly SOCKET: "ws_socket";
     readonly BODY: "ws_body";

package/dist/websocket/websocket.tokens.js

@@ -2,6 +2,12 @@ import { InjectionToken } from "../container/types.js";
 // Free-form metadata keys — same string-token convention as ON_EVENT_METADATA / CRON_METADATA.
 export const WS_GATEWAY_METADATA = 'vela:ws-gateway';
 export const WS_SUBSCRIBE_METADATA = 'vela:ws-subscribe';
+export const WS_RESERVED_METADATA = 'vela:ws-reserved';
+/**
+ * Event names starting with this prefix are RESERVED for framework modules
+ * (`$live`, …): app gateways may not subscribe to them, and inbound frames
+ * carrying them route to `@ReservedWsEvent` handlers instead of gateways.
+ */ export const RESERVED_WS_EVENT_PREFIX = '$';
 // WebSocket parameter-decorator kinds — parallel to `ParamType` for HTTP, keyed
 // by the WS argument resolver rather than the Hono-bound HTTP one.
 export const WsParamType = {

package/dist/websocket/websocket.types.d.ts

@@ -70,6 +70,22 @@ export interface SubscribeMessageMetadata {
     event: string;
     methodName: string;
 }
+/** Class-level meta written by `@ReservedWsEvent(event)`. */
+export interface ReservedWsEventMetadata {
+    /** The reserved (`$`-prefixed) envelope event this provider handles. */
+    event: string;
+}
+/**
+ * A provider claiming a reserved (`$`-prefixed) envelope event across EVERY
+ * gateway path. Discovered by `WsDispatcher` at bootstrap via the
+ * `@ReservedWsEvent` decorator; inbound frames for the event route here
+ * (after app-wide guards), never to gateways. `handleSocketClose` fires for
+ * every closing socket so the handler can drop per-connection state.
+ */
+export interface ReservedWsEventHandler {
+    handleReservedEvent(path: string, client: WsClient, message: WsMessage): void | Promise<void>;
+    handleSocketClose?(path: string, client: WsClient): void | Promise<void>;
+}
 /**
  * A fully serializable broadcast instruction. Crosses isolate / Durable-Object /
  * Redis boundaries as JSON, so every sync driver speaks the same command.

package/dist/websocket/ws-dispatcher.d.ts

@@ -26,6 +26,7 @@ export declare class WsDispatcher implements OnApplicationBootstrap, Contributes
     private readonly server?;
     private readonly routeManager?;
     private readonly gateways;
+    private readonly reserved;
     constructor(container: Container, discovery: DiscoveryService, server?: WsServer | undefined, routeManager?: RouteManager | undefined);
     /** Paths of every discovered `@WebSocketGateway` — used by transports to register routes. */
     get gatewayPaths(): string[];
@@ -36,6 +37,14 @@ export declare class WsDispatcher implements OnApplicationBootstrap, Contributes
     handleClose(path: string, client: WsClient, _code: number, _reason: string): Promise<void>;
     handleError(path: string, _client: WsClient, err: unknown): Promise<void>;
     dispatchMessage(path: string, client: WsClient, raw: string | ArrayBuffer): Promise<void>;
+    /**
+     * Route a reserved (`$…`) frame to its claiming handler. App-wide (`APP_*` /
+     * `useGlobalGuards`) guards protect reserved frames exactly like gateway
+     * messages — guards-first, WS convention; handler/class-tier components are
+     * the claiming module's own concern (e.g. live resolvers run their scoped
+     * guards at subscribe).
+     */
+    private dispatchReserved;
     private reply;
     private runFilters;
     private trySend;

package/dist/websocket/ws-dispatcher.js

@@ -24,7 +24,7 @@ import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { resolveWsArgs } from "./ws-argument-resolver.js";
 import { buildWsExecutionContext } from "./ws-execution-context.js";
 import { toErrorFrame, WsException } from "./ws-exception.js";
-import { WS_GATEWAY_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA } from "./websocket.tokens.js";
+import { RESERVED_WS_EVENT_PREFIX, WS_GATEWAY_METADATA, WS_RESERVED_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA } from "./websocket.tokens.js";
 function hasAfterInit(x) {
     return typeof x?.afterInit === 'function';
 }
@@ -43,6 +43,7 @@ export class WsDispatcher {
     server;
     routeManager;
     gateways = new Map();
+    reserved = new Map();
     constructor(container, discovery, server, routeManager){
         this.container = container;
         this.discovery = discovery;
@@ -55,6 +56,19 @@ export class WsDispatcher {
         ];
     }
     async onApplicationBootstrap() {
+        // Reserved-event handlers first: modules claiming a `$…` event
+        // (@ReservedWsEvent) receive those frames across every gateway path.
+        for (const found of this.discovery.providersWithMeta(WS_RESERVED_METADATA)){
+            if (!found.instance) continue;
+            const event = found.meta.event;
+            if (this.reserved.has(event)) {
+                const msg = `[vela] duplicate @ReservedWsEvent('${event}') ` + `(${found.metatype.name}); keeping the first.`;
+                if (this.container.getDiagnostics() === 'throw') throw new Error(msg);
+                console.warn(msg);
+                continue;
+            }
+            this.reserved.set(event, found.instance);
+        }
         for (const found of this.discovery.providersWithMeta(WS_GATEWAY_METADATA)){
             if (!found.instance) continue;
             const gatewayClass = found.metatype;
@@ -98,6 +112,15 @@ export class WsDispatcher {
         }
     }
     async handleClose(path, client, _code, _reason) {
+        // Reserved handlers drop per-connection state first (isolated per handler)
+        // so a throwing gateway handleDisconnect can't leak live subscriptions.
+        for (const handler of this.reserved.values()){
+            try {
+                await handler.handleSocketClose?.(path, client);
+            } catch (err) {
+                await this.handleError(path, client, err);
+            }
+        }
         const entry = this.gateways.get(path);
         if (entry && hasHandleDisconnect(entry.instance)) {
             await entry.instance.handleDisconnect(client);
@@ -120,6 +143,13 @@ export class WsDispatcher {
             });
             return;
         }
+        // Reserved namespace: `$…` frames route to @ReservedWsEvent handlers
+        // (after app-wide guards) and NEVER reach gateway handlers; an unclaimed
+        // reserved event is dropped like any unknown event.
+        if (message.event.startsWith(RESERVED_WS_EVENT_PREFIX)) {
+            await this.dispatchReserved(path, client, message);
+            return;
+        }
         const handler = entry.handlers.get(message.event);
         if (!handler) return; // unknown event — ignored (NestJS parity)
         const ctx = buildWsExecutionContext(client, message.data, entry.gatewayClass, handler.methodName, message.event);
@@ -162,6 +192,31 @@ export class WsDispatcher {
             await this.runFilters(client, message, error, filters, ctx);
         }
     }
+    /**
+   * Route a reserved (`$…`) frame to its claiming handler. App-wide (`APP_*` /
+   * `useGlobalGuards`) guards protect reserved frames exactly like gateway
+   * messages — guards-first, WS convention; handler/class-tier components are
+   * the claiming module's own concern (e.g. live resolvers run their scoped
+   * guards at subscribe).
+   */ async dispatchReserved(path, client, message) {
+        const handler = this.reserved.get(message.event);
+        if (!handler) return;
+        const ctx = buildWsExecutionContext(client, message.data, handler.constructor, 'handleReservedEvent', message.event);
+        const globals = this.routeManager?.getGlobalComponents();
+        const guards = instantiateMany(globals?.guards ?? [], this.container);
+        try {
+            for (const guard of guards){
+                if (!await guard.canActivate(ctx)) {
+                    const frame = toErrorFrame(new WsException('Forbidden'));
+                    this.trySend(client, frame.event, frame.data, message.id);
+                    return;
+                }
+            }
+            await handler.handleReservedEvent(path, client, message);
+        } catch (err) {
+            await this.handleError(path, client, err);
+        }
+    }
     reply(client, message, result) {
         if (result === undefined || result === null) return;
         if (isWsResponse(result)) {
@@ -216,6 +271,14 @@ export class WsDispatcher {
         const allParams = MetadataRegistry.getParameters(ctor);
         const handlers = new Map();
         for (const { event, methodName } of subs){
+            // The `$` namespace belongs to framework modules (@ReservedWsEvent) — an
+            // app gateway subscribing to it would never receive the frames anyway.
+            if (event.startsWith(RESERVED_WS_EVENT_PREFIX)) {
+                const msg = `[vela] @SubscribeMessage('${event}') on ${gatewayClass.name}: the ` + `'${RESERVED_WS_EVENT_PREFIX}' event prefix is reserved for framework modules — skipped.`;
+                if (this.container.getDiagnostics() === 'throw') throw new Error(msg);
+                console.warn(msg);
+                continue;
+            }
             const paramMeta = [
                 ...allParams.get(methodName) ?? []
             ].sort((a, b)=>a.index - b.index);

package/dist/websocket-node/index.d.ts

@@ -2,3 +2,5 @@ export { NodeWsClient } from './node-ws-client';
 export { registerWebSocketGateways } from './register-gateways';
 export { redis } from './redis-sync';
 export type { RedisPubSubClient, RedisSyncOptions } from './redis-sync';
+export { redisLive } from './redis-live';
+export type { RedisLiveOptions } from './redis-live';

package/dist/websocket-node/index.js

@@ -3,3 +3,4 @@
 export { NodeWsClient } from "./node-ws-client.js";
 export { registerWebSocketGateways } from "./register-gateways.js";
 export { redis } from "./redis-sync.js";
+export { redisLive } from "./redis-live.js";

package/dist/websocket-node/redis-live.d.ts

@@ -0,0 +1,24 @@
+import type { LiveDriver } from '../live/index';
+import type { RedisPubSubClient } from './redis-sync';
+export interface RedisLiveOptions {
+    /** Connection used to publish invalidations. */
+    pub: RedisPubSubClient;
+    /** Separate connection kept in subscriber mode. */
+    sub: RedisPubSubClient;
+    /** Channel prefix. Default `vela:live`. */
+    prefix?: string;
+}
+/**
+ * Cross-instance live-invalidation driver for node/bun via Redis pub/sub —
+ * the live sibling of the WebSocket `redis()` sync driver, carrying TAGS
+ * instead of frames. Local-first: `dispatch` applies to this instance's
+ * engine immediately (its log stamps the returned commit cursor), then fans
+ * the command out so every peer re-runs ITS local subscriptions.
+ *
+ * Guarantees (same honesty as `redis()`): at-most-once, no cross-publisher
+ * ordering, no replay. Each instance keeps its own per-process epoch, so a
+ * client reconnecting onto a different instance always receives a full
+ * snapshot — exactly the protocol's multi-instance-node rule. Real cursor
+ * resume needs a shared ordered log (the Cloudflare DO transport).
+ */
+export declare function redisLive(options: RedisLiveOptions): LiveDriver;