@velajs/vela 1.16.0 → 1.17.1

package/dist/live/live.module.js

@@ -0,0 +1,87 @@
+import { defineModule } from "../index.js";
+import { InMemoryCursorLog } from "./live.cursor.js";
+import { LiveEngine } from "./live.engine.js";
+import { LiveInvalidation, localLive, perAppLiveDriver } from "./live.invalidation.js";
+import { LIVE_CURSOR_LOG, LIVE_DRIVER, LIVE_MODULE_OPTIONS } from "./live.tokens.js";
+import { PresenceResolver, PresenceService } from "./presence.js";
+/**
+ * First-party live-query module (tag-based realtime reactivity) — authored,
+ * like the queue module, entirely on vela's public API (`live-openness.test.ts`
+ * machine-verifies it; the only extra dependency is the shared wire package
+ * `@velajs/live-protocol`).
+ *
+ * ```ts
+ * imports: [WebSocketModule.forRoot({}), LiveModule.forRoot({})]
+ * ```
+ *
+ * App code declares `@LiveResolver` classes with `@LiveQuery(name, { tags })`
+ * methods; clients subscribe over the `$live` reserved WebSocket event; writes
+ * invalidate tags via `LiveInvalidation` (the `@velajs/crud` bridge does it
+ * automatically per table). See `LIVE.md` for the wire protocol, delivery
+ * guarantees, and the resume story.
+ *
+ * Deliberately EAGER (like WebSocketModule): the engine self-drives — it
+ * claims the `$live` event at bootstrap and receives invalidations from
+ * writes that never touch a live token — so the lazy-module contract
+ * ("nothing self-drives") rules laziness out.
+ */ const { ConfigurableModuleClass } = defineModule({
+    name: 'Live',
+    optionsToken: LIVE_MODULE_OPTIONS,
+    key: (options)=>`live#${options?.driver?.kind ?? 'local'}`,
+    setup: ({ OPTIONS, options })=>({
+            providers: [
+                {
+                    provide: LIVE_CURSOR_LOG,
+                    useFactory: (o)=>o.log ?? new InMemoryCursorLog(),
+                    inject: [
+                        OPTIONS
+                    ]
+                },
+                {
+                    provide: LIVE_DRIVER,
+                    // Wrapped per app: user-supplied drivers are shared config objects
+                    // (the same module bootstraps in the Worker AND in each Durable
+                    // Object), so per-app sink/mode state lives in the wrapper — see
+                    // perAppLiveDriver.
+                    useFactory: (o)=>perAppLiveDriver(o.driver ?? localLive()),
+                    inject: [
+                        OPTIONS
+                    ]
+                },
+                {
+                    provide: PresenceService,
+                    useFactory: (o)=>{
+                        const presence = o.presence;
+                        if (presence === false) return new PresenceService(undefined, false);
+                        return new PresenceService(presence?.ttlMs, true);
+                    },
+                    inject: [
+                        OPTIONS
+                    ]
+                },
+                {
+                    provide: LiveInvalidation,
+                    useFactory: (driver)=>new LiveInvalidation(driver),
+                    inject: [
+                        LIVE_DRIVER
+                    ]
+                },
+                LiveEngine,
+                // The built-in `$presence.roster` resolver. Skipping it is STRUCTURAL
+                // (`presence: false` must be visible at forRoot/forRootAsync call time,
+                // like queue's `queues`); a disabled-at-runtime service still no-ops.
+                ...options?.presence === false ? [] : [
+                    PresenceResolver
+                ]
+            ],
+            exports: [
+                LiveEngine,
+                LiveInvalidation,
+                LIVE_DRIVER,
+                LIVE_CURSOR_LOG,
+                PresenceService
+            ]
+        })
+});
+export class LiveModule extends ConfigurableModuleClass {
+}

package/dist/live/live.tokens.d.ts

@@ -0,0 +1,9 @@
+import { InjectionToken } from '../index';
+import type { CursorLog, LiveDriver, LiveModuleOptions } from './live.types';
+export declare const LIVE_RESOLVER_METADATA = "vela:live:resolver";
+export declare const LIVE_QUERY_METADATA = "vela:live:query";
+/** The invalidation driver in effect for a `LiveModule` instance (`localLive()` by default). */
+export declare const LIVE_DRIVER: InjectionToken<LiveDriver>;
+/** The ordered tag-invalidation log backing cursors/epochs for this log scope. */
+export declare const LIVE_CURSOR_LOG: InjectionToken<CursorLog>;
+export declare const LIVE_MODULE_OPTIONS: InjectionToken<LiveModuleOptions>;

package/dist/live/live.tokens.js

@@ -0,0 +1,8 @@
+import { InjectionToken } from "../index.js";
+// Free-form metadata keys — same string-token convention as the queue module.
+export const LIVE_RESOLVER_METADATA = 'vela:live:resolver';
+export const LIVE_QUERY_METADATA = 'vela:live:query';
+/** The invalidation driver in effect for a `LiveModule` instance (`localLive()` by default). */ export const LIVE_DRIVER = new InjectionToken('vela:live:driver');
+/** The ordered tag-invalidation log backing cursors/epochs for this log scope. */ export const LIVE_CURSOR_LOG = new InjectionToken('vela:live:cursor-log');
+// forRoot() options carrier.
+export const LIVE_MODULE_OPTIONS = new InjectionToken('LIVE_MODULE_OPTIONS');

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;