@velajs/vela 1.16.0 → 1.17.0

package/dist/live/live.engine.js

@@ -0,0 +1,448 @@
+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 { LIVE_ERROR_CODES, LIVE_PROTOCOL, encodeLiveEnvelope, isClientLiveFrame } from "@velajs/live-protocol";
+import { Container, DiscoveryService, Inject, Injectable, Optional, PipelineRunner, ReservedWsEvent, buildEntrypointExecutionContext, resolveScopedComponents, runInEntrypointScope } from "../index.js";
+import { getLiveQueries } from "./live.decorators.js";
+import { encodeSubscriptionUpdate } from "./live.delta.js";
+import { LIVE_CURSOR_LOG, LIVE_DRIVER, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA } from "./live.tokens.js";
+import { PresenceService } from "./presence.js";
+/** How many subscriptions refresh concurrently per flush (lunora's socket-pool default). */ const REFRESH_POOL_SIZE = 8;
+/**
+ * Where the engine persists a connection's subscription records inside
+ * `client.data` (committed through `WsClient.commit()`). On Cloudflare that
+ * lands in the hibernation attachment, so subscriptions survive DO eviction;
+ * the transport replays them via `restoreSubscription` on wake. On node,
+ * `commit()` is a no-op and this is just in-memory bookkeeping.
+ */ export const LIVE_SUBS_DATA_KEY = '__velaLiveSubs';
+/** Read the subscription records a transport persisted for a connection (wake/restore path). */ export function readPersistedLiveSubscriptions(client) {
+    const raw = client.data?.[LIVE_SUBS_DATA_KEY];
+    if (!Array.isArray(raw)) return [];
+    return raw.filter((record)=>typeof record === 'object' && record !== null && typeof record.sub === 'string' && typeof record.query === 'string' && Array.isArray(record.tags));
+}
+const defaultIdentity = (client)=>{
+    const data = client.data;
+    if (!data || Object.keys(data).length === 0) return undefined;
+    return {
+        ...data
+    };
+};
+async function runPool(items, size, run) {
+    const queue = [
+        ...items
+    ];
+    const workers = Array.from({
+        length: Math.min(size, queue.length)
+    }, async ()=>{
+        for(let item = queue.shift(); item !== undefined; item = queue.shift()){
+            await run(item);
+        }
+    });
+    await Promise.all(workers);
+}
+export class LiveEngine {
+    container;
+    discovery;
+    log;
+    options;
+    presence;
+    queries = new Map();
+    connections = new Map();
+    pendingTags = new Set();
+    drainChain = Promise.resolve();
+    draining = false;
+    constructor(container, discovery, log, driver, options, presence){
+        this.container = container;
+        this.discovery = discovery;
+        this.log = log;
+        this.options = options;
+        this.presence = presence;
+        driver.bind(this);
+        this.presence?.bindInvalidator((tags)=>{
+            void driver.dispatch({
+                tags
+            });
+        });
+    }
+    async onApplicationBootstrap() {
+        for (const found of this.discovery.providersWithMeta(LIVE_RESOLVER_METADATA)){
+            if (!found.instance) continue;
+            for (const declared of getLiveQueries(found.metatype)){
+                if (this.queries.has(declared.name)) {
+                    const msg = `[vela] duplicate @LiveQuery('${declared.name}') ` + `(${found.metatype.name}); keeping the first.`;
+                    if (this.container.getDiagnostics() === 'throw') throw new Error(msg);
+                    console.warn(msg);
+                    continue;
+                }
+                this.queries.set(declared.name, {
+                    token: found.metatype,
+                    methodName: declared.methodName,
+                    options: declared.options
+                });
+            }
+        }
+    }
+    /** The `'live'` entrypoint — how transports (node registrar, CF DO bootstrap) find the engine. */ collectEntrypoints() {
+        return [
+            {
+                kind: 'live',
+                token: LiveEngine,
+                instance: this,
+                meta: {
+                    engine: this
+                }
+            }
+        ];
+    }
+    // ---- ReservedWsEventHandler ----
+    async handleReservedEvent(path, client, message) {
+        const frame = message.data;
+        // Forward-compat: unknown frame shapes are ignored, not errors.
+        if (!isClientLiveFrame(frame)) return;
+        switch(frame.t){
+            case 'sub':
+                await this.onSubscribe(path, client, frame);
+                return;
+            case 'unsub':
+                {
+                    const conn = this.connections.get(client.id);
+                    if (!conn) return;
+                    conn.subs.delete(frame.sub);
+                    if (conn.subs.size === 0) this.connections.delete(client.id);
+                    await this.persistSubscriptions(conn);
+                    return;
+                }
+            case 'presence':
+                if (this.presence?.enabled) {
+                    this.presence.beat(frame.room, client.id, frame.meta);
+                }
+                return;
+        }
+    }
+    async handleSocketClose(_path, client) {
+        this.connections.delete(client.id);
+        this.presence?.reap(client.id);
+    }
+    // ---- LiveInvalidationSink ----
+    async applyInvalidation(cmd) {
+        const stamp = await this.log.append(cmd.tags);
+        for (const tag of cmd.tags)this.pendingTags.add(tag);
+        this.scheduleDrain();
+        return stamp;
+    }
+    /** Settles when every pending invalidation has been flushed (tests, graceful transports). */ async whenIdle() {
+        do {
+            await this.drainChain;
+        }while (this.draining || this.pendingTags.size > 0)
+    }
+    /**
+   * Re-attach a persisted subscription without the subscribe handshake — the
+   * Cloudflare transport replays hibernation-attachment records through this
+   * on wake. No frames are sent; the next relevant invalidation pushes.
+   */ restoreSubscription(path, client, record) {
+        this.ensureConnection(path, client).subs.set(record.sub, record);
+    }
+    // ---- subscribe path ----
+    async onSubscribe(path, client, frame) {
+        if (frame.v !== undefined && frame.v > LIVE_PROTOCOL) {
+            this.sendFrame(client, {
+                t: 'error',
+                sub: frame.sub,
+                code: LIVE_ERROR_CODES.UNSUPPORTED_PROTOCOL,
+                message: `server speaks live protocol v${LIVE_PROTOCOL}, client asked for v${frame.v}`,
+                fatal: true
+            });
+            return;
+        }
+        const conn = this.ensureConnection(path, client);
+        if (conn.subs.has(frame.sub)) {
+            this.sendFrame(client, {
+                t: 'error',
+                sub: frame.sub,
+                code: LIVE_ERROR_CODES.DUPLICATE_SUB,
+                message: `subscription id '${frame.sub}' is already active on this socket`,
+                fatal: false
+            });
+            return;
+        }
+        const registered = this.queries.get(frame.query);
+        if (!registered) {
+            this.sendFrame(client, {
+                t: 'error',
+                sub: frame.sub,
+                code: LIVE_ERROR_CODES.UNKNOWN_QUERY,
+                message: `no @LiveQuery('${frame.query}') is registered`,
+                fatal: true
+            });
+            return;
+        }
+        let args = frame.args;
+        if (registered.options.parse) {
+            try {
+                args = registered.options.parse(frame.args);
+            } catch (err) {
+                this.sendFrame(client, {
+                    t: 'error',
+                    sub: frame.sub,
+                    code: LIVE_ERROR_CODES.BAD_ARGS,
+                    message: err instanceof Error ? err.message : 'invalid subscription args',
+                    fatal: true
+                });
+                return;
+            }
+        }
+        // Resolver-tier guards run ONCE, here (app-wide guards already ran in the
+        // dispatcher's reserved-event path). Re-runs are server-initiated and rely
+        // on the identity captured below instead of re-authorizing.
+        if (!await this.runSubscribeGuards(registered, client, frame.query, args)) {
+            this.sendFrame(client, {
+                t: 'error',
+                sub: frame.sub,
+                code: LIVE_ERROR_CODES.FORBIDDEN,
+                message: `subscription to '${frame.query}' was rejected`,
+                fatal: true
+            });
+            return;
+        }
+        const identity = (this.options.identity ?? defaultIdentity)(client);
+        const tags = typeof registered.options.tags === 'function' ? registered.options.tags(args) : registered.options.tags;
+        const record = {
+            sub: frame.sub,
+            query: frame.query,
+            args,
+            tags,
+            key: frame.key ?? registered.options.key,
+            identity
+        };
+        conn.subs.set(frame.sub, record);
+        await this.persistSubscriptions(conn);
+        this.sendFrame(client, {
+            t: 'ack',
+            sub: frame.sub
+        });
+        // Resume: when the client's cursor is still explainable and none of the
+        // subscription's tags were invalidated in the gap, a tiny `resume` frame
+        // keeps its cached value — no re-run at all. The diff baseline stays
+        // undefined, so the next relevant change sends a full snapshot.
+        if (frame.sinceCursor !== undefined && frame.sinceEpoch !== undefined) {
+            const verdict = await this.log.evaluateResume(frame.sinceCursor, frame.sinceEpoch, tags);
+            if (verdict === 'resume') {
+                const stamp = await this.log.current();
+                if (this.sendFrame(client, {
+                    t: 'resume',
+                    sub: frame.sub,
+                    cursor: stamp.cursor,
+                    epoch: stamp.epoch
+                })) {
+                    record.lastCursor = stamp.cursor;
+                }
+                return;
+            }
+        }
+        await this.push(conn, record, await this.log.current(), {
+            initial: true
+        });
+    }
+    async runSubscribeGuards(registered, client, query, args) {
+        const guards = resolveScopedComponents('guard', registered.token, registered.methodName, this.container);
+        if (guards.length === 0) return true;
+        const context = buildEntrypointExecutionContext('live', registered.token, registered.methodName, {
+            query,
+            args,
+            client
+        });
+        try {
+            for (const guard of guards){
+                if (!await guard.canActivate(context)) return false;
+            }
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    // ---- refresh path ----
+    scheduleDrain() {
+        if (this.draining) return;
+        this.draining = true;
+        this.drainChain = this.drainChain.then(()=>this.drainLoop()).catch((err)=>{
+            if (this.container.getDiagnostics() !== 'silent') {
+                console.warn('[vela] live refresh flush failed:', err);
+            }
+        }).finally(()=>{
+            this.draining = false;
+            if (this.pendingTags.size > 0) this.scheduleDrain();
+        });
+    }
+    async drainLoop() {
+        while(this.pendingTags.size > 0){
+            const changed = new Set(this.pendingTags);
+            this.pendingTags.clear();
+            // The stamp is resolved once per pass, BEFORE the re-runs (lunora
+            // resolves its CDC cut the same way): results can only be newer than
+            // the cursor they carry.
+            const stamp = await this.log.current();
+            const work = [];
+            for (const conn of this.connections.values()){
+                for (const record of conn.subs.values()){
+                    if (record.tags.some((tag)=>changed.has(tag))) work.push({
+                        conn,
+                        record
+                    });
+                }
+            }
+            await runPool(work, REFRESH_POOL_SIZE, async ({ conn, record })=>{
+                await this.push(conn, record, stamp, {
+                    initial: false
+                });
+            });
+        }
+    }
+    async push(conn, record, stamp, { initial }) {
+        // Outbound expiry enforcement — the only place expiry CAN be enforced for
+        // a passive subscriber.
+        const expiresAt = record.identity?.expiresAt;
+        if (typeof expiresAt === 'number' && expiresAt <= Date.now()) {
+            this.connections.delete(conn.client.id);
+            try {
+                conn.client.close(1008, 'identity expired');
+            } catch  {
+            // already gone
+            }
+            return;
+        }
+        let json;
+        let result;
+        try {
+            result = await this.runQuery(record, conn.client);
+            // `undefined` has no JSON form — normalize so the frame always carries
+            // an explicit `snapshot` and the baseline stays a string.
+            if (result === undefined) result = null;
+            json = JSON.stringify(result);
+        } catch (err) {
+            if (initial) {
+                conn.subs.delete(record.sub);
+                this.sendFrame(conn.client, {
+                    t: 'error',
+                    sub: record.sub,
+                    code: LIVE_ERROR_CODES.INTERNAL,
+                    message: err instanceof Error ? err.message : 'live query failed',
+                    fatal: true
+                });
+            } else if (this.container.getDiagnostics() !== 'silent') {
+                // Transient: baseline untouched, the subscription retries next flush.
+                console.warn(`[vela] live query '${record.query}' re-run failed (will retry):`, err);
+            }
+            return;
+        }
+        const frame = encodeSubscriptionUpdate(record, json, result, stamp, initial);
+        if (this.sendFrame(conn.client, frame)) {
+            record.lastJson = json;
+            record.lastCursor = stamp.cursor;
+        }
+    }
+    async runQuery(record, client) {
+        const registered = this.queries.get(record.query);
+        if (!registered) throw new Error(`live query '${record.query}' disappeared from the registry`);
+        return runInEntrypointScope(this.container, async (scope)=>{
+            // Async seam: lazy resolver modules materialize, request-scoped
+            // resolvers rebuild per run (mirrors queue dispatch).
+            const instance = await scope.resolveAsync(registered.token);
+            const liveContext = {
+                identity: record.identity,
+                clientId: client.id,
+                rooms: [
+                    ...client.rooms
+                ]
+            };
+            const context = buildEntrypointExecutionContext('live', registered.token, registered.methodName, {
+                query: record.query,
+                args: record.args,
+                client
+            });
+            const interceptors = resolveScopedComponents('interceptor', registered.token, registered.methodName, scope);
+            return PipelineRunner.run({
+                context,
+                guards: [],
+                interceptors,
+                resolveArgs: async ()=>[
+                        record.args,
+                        liveContext
+                    ],
+                invoke: async (args)=>{
+                    const method = instance[registered.methodName];
+                    return method.apply(instance, args);
+                }
+            });
+        });
+    }
+    /**
+   * Mirror the connection's records into `client.data` + `commit()` so
+   * hibernating transports can replay them on wake. The volatile diff
+   * baseline (`lastJson`/`lastCursor`) is deliberately stripped: it can be
+   * large (the whole last result vs the 16 KiB attachment cap) and a lost
+   * baseline just means the next relevant change sends a full snapshot.
+   */ async persistSubscriptions(conn) {
+        const records = [
+            ...conn.subs.values()
+        ].map(({ lastJson: _lastJson, lastCursor: _lastCursor, ...persisted })=>persisted);
+        try {
+            conn.client.data[LIVE_SUBS_DATA_KEY] = records;
+            await conn.client.commit();
+        } catch (err) {
+            if (this.container.getDiagnostics() !== 'silent') {
+                console.warn('[vela] live subscription persistence failed (resume across eviction disabled):', err);
+            }
+        }
+    }
+    ensureConnection(path, client) {
+        let conn = this.connections.get(client.id);
+        if (!conn) {
+            conn = {
+                client,
+                path,
+                subs: new Map()
+            };
+            this.connections.set(client.id, conn);
+        }
+        return conn;
+    }
+    sendFrame(client, frame) {
+        try {
+            client.sendRaw(encodeLiveEnvelope(frame));
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+}
+LiveEngine = _ts_decorate([
+    ReservedWsEvent('$live'),
+    Injectable(),
+    _ts_param(0, Inject(Container)),
+    _ts_param(1, Inject(DiscoveryService)),
+    _ts_param(2, Inject(LIVE_CURSOR_LOG)),
+    _ts_param(3, Inject(LIVE_DRIVER)),
+    _ts_param(4, Inject(LIVE_MODULE_OPTIONS)),
+    _ts_param(5, Optional()),
+    _ts_param(5, Inject(PresenceService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Container === "undefined" ? Object : Container,
+        typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+        typeof CursorLog === "undefined" ? Object : CursorLog,
+        typeof LiveDriver === "undefined" ? Object : LiveDriver,
+        typeof LiveModuleOptions === "undefined" ? Object : LiveModuleOptions,
+        typeof PresenceService === "undefined" ? Object : PresenceService
+    ])
+], LiveEngine);

package/dist/live/live.invalidation.d.ts

@@ -0,0 +1,27 @@
+import type { CommitStamp, InvalidationCommand, LiveDriver } from './live.types';
+/** Single-scope default driver: deliver straight to this process's engine. */
+export declare function localLive(): LiveDriver;
+/**
+ * The injectable invalidation surface for custom (non-CRUD) write paths:
+ *
+ * ```ts
+ * await this.live.invalidate({ tags: ['todos:' + listId] });
+ * ```
+ *
+ * Every affected live query re-runs and pushes. Returns the commit stamp of
+ * the targeted log scope so mutation endpoints can expose it to the client
+ * (`Vela-Commit-Cursor` / `Vela-Commit-Epoch`) — the cursor optimistic
+ * updates gate on. When ambient request access is enabled
+ * (`VelaFactory.create(m, { ambientContainer: true })`) the headers are
+ * stamped onto the current HTTP response automatically; otherwise stamp them
+ * yourself via {@link stampCommitHeaders}.
+ */
+export declare class LiveInvalidation {
+    private readonly driver;
+    constructor(driver: LiveDriver);
+    invalidate(cmd: InvalidationCommand): Promise<CommitStamp | undefined>;
+}
+/** Write the commit headers onto a Hono context (a mutation route's response). */
+export declare function stampCommitHeaders(c: {
+    header: (name: string, value: string) => unknown;
+}, stamp: CommitStamp): void;

package/dist/live/live.invalidation.js

@@ -0,0 +1,56 @@
+import { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER } from "@velajs/live-protocol";
+import { getContext } from "hono/context-storage";
+/** Single-scope default driver: deliver straight to this process's engine. */ export function localLive() {
+    let sink;
+    return {
+        kind: 'local',
+        bind (s) {
+            sink = s;
+        },
+        dispatch (cmd) {
+            return sink?.applyInvalidation(cmd);
+        }
+    };
+}
+/**
+ * The injectable invalidation surface for custom (non-CRUD) write paths:
+ *
+ * ```ts
+ * await this.live.invalidate({ tags: ['todos:' + listId] });
+ * ```
+ *
+ * Every affected live query re-runs and pushes. Returns the commit stamp of
+ * the targeted log scope so mutation endpoints can expose it to the client
+ * (`Vela-Commit-Cursor` / `Vela-Commit-Epoch`) — the cursor optimistic
+ * updates gate on. When ambient request access is enabled
+ * (`VelaFactory.create(m, { ambientContainer: true })`) the headers are
+ * stamped onto the current HTTP response automatically; otherwise stamp them
+ * yourself via {@link stampCommitHeaders}.
+ */ export class LiveInvalidation {
+    driver;
+    constructor(driver){
+        this.driver = driver;
+    }
+    async invalidate(cmd) {
+        const stamp = await this.driver.dispatch(cmd);
+        if (stamp) stampAmbientCommitHeaders(stamp);
+        return stamp;
+    }
+}
+/** Write the commit headers onto a Hono context (a mutation route's response). */ export function stampCommitHeaders(c, stamp) {
+    c.header(COMMIT_CURSOR_HEADER, String(stamp.cursor));
+    c.header(COMMIT_EPOCH_HEADER, stamp.epoch);
+}
+/**
+ * Best-effort automatic header stamping through Hono's ambient context
+ * storage. A no-op outside a request or when `contextStorage()` isn't
+ * registered — ALS keeps this per-request-correct under concurrency (a
+ * mutable singleton slot would race interleaved awaits).
+ */ function stampAmbientCommitHeaders(stamp) {
+    try {
+        stampCommitHeaders(getContext(), stamp);
+    } catch  {
+    // Ambient access not enabled, or invalidate() ran outside a request
+    // (queue job, cron tick) — there is no HTTP response to stamp.
+    }
+}

package/dist/live/live.module.d.ts

@@ -0,0 +1,28 @@
+import type { LiveModuleOptions } from './live.types';
+/**
+ * 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.
+ */
+declare const ConfigurableModuleClass: import("../module").ConfigurableModuleClassType<LiveModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class LiveModule extends ConfigurableModuleClass {
+}
+export {};

package/dist/live/live.module.js

@@ -0,0 +1,83 @@
+import { defineModule } from "../index.js";
+import { InMemoryCursorLog } from "./live.cursor.js";
+import { LiveEngine } from "./live.engine.js";
+import { LiveInvalidation, localLive } 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,
+                    useFactory: (o)=>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');