@velajs/vela 1.18.0 → 1.19.1

package/dist/live/index.js

@@ -1,16 +1,826 @@
-// @velajs/vela/live — first-party live-query subsystem (tag-based realtime
-// reactivity), authored entirely on the public API plus the shared wire
-// package @velajs/live-protocol (the live-openness audit test enforces it).
-// Subpath-only, like @velajs/vela/queue: the main barrel stays lean and the
-// name stays free for platform packages.
-export { LiveModule } from "./live.module.js";
-export { LiveResolver, LiveQuery, getLiveQueries } from "./live.decorators.js";
-export { LiveEngine, LIVE_SUBS_DATA_KEY, readPersistedLiveSubscriptions } from "./live.engine.js";
-export { LiveInvalidation, localLive, perAppLiveDriver, stampCommitHeaders } from "./live.invalidation.js";
-export { InMemoryCursorLog } from "./live.cursor.js";
-export { encodeSubscriptionUpdate } from "./live.delta.js";
-export { PresenceService, PresenceResolver, presenceTag, PRESENCE_ROSTER_QUERY } from "./presence.js";
-export { LIVE_DRIVER, LIVE_CURSOR_LOG, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA, LIVE_QUERY_METADATA } from "./live.tokens.js";
-// The wire contract (frames, delta codec, headers) is re-exported so app code
-// and transports need a single import surface.
-export { LIVE_PROTOCOL, LIVE_EVENT, LIVE_ERROR_CODES, COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, encodeLiveEnvelope, encodeLiveFrame, readLiveEnvelope, isClientLiveFrame, isServerLiveFrame, encodeListDelta, applyListDelta } from "@velajs/live-protocol";
+import { C as InjectionToken, a as Injectable, i as Inject, n as __decorateParam, o as Optional, r as __decorateMetadata, t as __decorate } from "../decorate-GcSMAbKn.js";
+import { G as getMetadata, L as PipelineRunner, W as defineMetadata } from "../route.manager-DRAZ5X04.js";
+import { n as resolveErrorReporter, t as DiscoveryService } from "../discovery.service-BYm95SSD.js";
+import { t as Container } from "../container-BqUHID4l.js";
+import { E as runInEntrypointScope, T as buildEntrypointExecutionContext, c as toErrorBody, s as isVelaError, w as resolveScopedComponents } from "../src-eb5CI6Xn.js";
+import { n as defineModule } from "../define-module-NOyOZNXD.js";
+import { E as createDiscoverableDecorator, p as ReservedWsEvent } from "../websocket-DXmB-MWJ.js";
+import { getContext } from "hono/context-storage";
+import { COMMIT_CURSOR_HEADER, COMMIT_CURSOR_HEADER as COMMIT_CURSOR_HEADER$1, COMMIT_EPOCH_HEADER, COMMIT_EPOCH_HEADER as COMMIT_EPOCH_HEADER$1, DEFAULT_KEY_FIELD, DEFAULT_KEY_FIELD as DEFAULT_KEY_FIELD$1, LIVE_ERROR_CODES, LIVE_ERROR_CODES as LIVE_ERROR_CODES$1, LIVE_EVENT, LIVE_PROTOCOL, LIVE_PROTOCOL as LIVE_PROTOCOL$1, applyListDelta, encodeListDelta, encodeListDelta as encodeListDelta$1, encodeLiveEnvelope, encodeLiveEnvelope as encodeLiveEnvelope$1, encodeLiveFrame, isClientLiveFrame, isClientLiveFrame as isClientLiveFrame$1, isServerLiveFrame, readLiveEnvelope } from "@velajs/live-protocol";
+//#region src/live/live.cursor.ts
+const intersects = (a, b) => a.some((tag) => b.has(tag));
+/**
+* The in-core `CursorLog`: a bounded in-memory ring, epoch minted per process
+* (Web Crypto). A restart rolls the epoch, so every reconnecting client falls
+* back to snapshot — exactly the documented node/dev semantics. Within one
+* process lifetime resume works for gaps the ring still covers; a trimmed gap
+* degrades to snapshot (mirrors lunora's CDC retention rule,
+* `ctx-db-cdc.ts` — retention gap → snapshot).
+*
+* The Cloudflare transport replaces this with a Durable-Object SQLite log so
+* resume survives hibernation and eviction.
+*/
+var InMemoryCursorLog = class {
+	maxEntries;
+	epoch = crypto.randomUUID();
+	entries = [];
+	seq = 0;
+	constructor(maxEntries = 1024) {
+		this.maxEntries = maxEntries;
+	}
+	append(tags) {
+		this.seq += 1;
+		this.entries.push({
+			seq: this.seq,
+			tags
+		});
+		if (this.entries.length > this.maxEntries) this.entries.splice(0, this.entries.length - this.maxEntries);
+		return {
+			cursor: this.seq,
+			epoch: this.epoch
+		};
+	}
+	current() {
+		return {
+			cursor: this.seq,
+			epoch: this.epoch
+		};
+	}
+	evaluateResume(sinceCursor, sinceEpoch, subscriptionTags) {
+		if (sinceEpoch !== this.epoch) return "snapshot";
+		if (sinceCursor > this.seq) return "snapshot";
+		if (sinceCursor === this.seq) return "resume";
+		const oldest = this.entries[0];
+		if (oldest === void 0 || oldest.seq > sinceCursor + 1) return "snapshot";
+		const subTags = new Set(subscriptionTags);
+		for (const entry of this.entries) {
+			if (entry.seq <= sinceCursor) continue;
+			if (intersects(entry.tags, subTags)) return "rerun";
+		}
+		return "resume";
+	}
+};
+//#endregion
+//#region src/live/live.tokens.ts
+const LIVE_RESOLVER_METADATA = "vela:live:resolver";
+const LIVE_QUERY_METADATA = "vela:live:query";
+/** The invalidation driver in effect for a `LiveModule` instance (`localLive()` by default). */
+const LIVE_DRIVER = new InjectionToken("vela:live:driver");
+/** The ordered tag-invalidation log backing cursors/epochs for this log scope. */
+const LIVE_CURSOR_LOG = new InjectionToken("vela:live:cursor-log");
+const LIVE_MODULE_OPTIONS = new InjectionToken("LIVE_MODULE_OPTIONS");
+//#endregion
+//#region src/live/live.decorators.ts
+const LiveResolverMeta = createDiscoverableDecorator(LIVE_RESOLVER_METADATA);
+/**
+* Marks a provider class as a live-query resolver:
+*
+* ```ts
+* @LiveResolver()
+* @Injectable()
+* class TodoLive {
+*   constructor(private readonly todos: TodoService) {}
+*
+*   @LiveQuery('todos.list', { tags: (a: { listId: string }) => [`todos:${a.listId}`] })
+*   list(args: { listId: string }, ctx: LiveQueryContext) {
+*     return this.todos.byList(args.listId, ctx.identity?.userId);
+*   }
+* }
+* ```
+*
+* Clients subscribe by query name over the `$live` reserved event; the engine
+* re-runs a handler whenever one of its tags is invalidated and pushes the
+* result (as a keyed delta when possible). Stack with `@Injectable()`, exactly
+* like `@Processor`.
+*/
+function LiveResolver() {
+	return LiveResolverMeta({});
+}
+/**
+* Declares a live query on a resolver method. The handler receives
+* `(args, ctx: LiveQueryContext)` positionally — args are validated once at
+* subscribe (via `options.parse`), then replayed verbatim into every re-run
+* under the subscriber's captured identity.
+*/
+function LiveQuery(name, options) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const existing = getMetadata("vela:live:query", ctor) ?? [];
+		existing.push({
+			name,
+			methodName: propertyKey,
+			options
+		});
+		defineMetadata(LIVE_QUERY_METADATA, existing, ctor);
+	};
+}
+/** `@LiveQuery` entries declared on a resolver class (declaration order). */
+function getLiveQueries(resolverClass) {
+	return getMetadata("vela:live:query", resolverClass) ?? [];
+}
+//#endregion
+//#region src/live/live.delta.ts
+/**
+* Decide what one re-run puts on the wire — pure, so the contract is
+* unit-testable without sockets:
+*
+* - byte-identical to the baseline → `settled` (cursor still advances; this
+*   is what drops client optimistic layers for writes that didn't change the
+*   result);
+* - baseline exists and the shared codec can diff → `delta` (batched keyed
+*   row ops);
+* - otherwise (first send after subscribe/resume, codec bailed, unparseable
+*   baseline) → full `data` snapshot.
+*/
+function encodeSubscriptionUpdate(record, json, result, stamp, initial) {
+	const settled = {
+		t: "settled",
+		sub: record.sub,
+		cursor: stamp.cursor,
+		epoch: stamp.epoch
+	};
+	if (!initial && record.lastJson !== void 0) {
+		if (record.lastJson === json) return settled;
+		let previous;
+		let parsed = false;
+		try {
+			previous = JSON.parse(record.lastJson);
+			parsed = true;
+		} catch {}
+		if (parsed) {
+			const ops = encodeListDelta$1(previous, result, record.key ?? DEFAULT_KEY_FIELD$1);
+			if (ops !== void 0 && ops.length > 0) return {
+				t: "delta",
+				sub: record.sub,
+				ops,
+				cursor: stamp.cursor,
+				epoch: stamp.epoch
+			};
+			if (ops !== void 0) return settled;
+		}
+	}
+	return {
+		t: "data",
+		sub: record.sub,
+		snapshot: result,
+		cursor: stamp.cursor,
+		epoch: stamp.epoch
+	};
+}
+//#endregion
+//#region src/live/presence.ts
+/** The invalidation tag for one room's roster. `$`-prefixed: never collides with app tags. */
+const presenceTag = (room) => `$presence:${room}`;
+/** The built-in roster query name (`useLiveQuery`-able like any app query). */
+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).
+*/
+var PresenceService = class {
+	ttlMs;
+	enabled;
+	rooms = /* @__PURE__ */ new Map();
+	roomsByClient = /* @__PURE__ */ new Map();
+	invalidator;
+	constructor(ttlMs = 3e4, 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: /* @__PURE__ */ new Map() };
+			this.rooms.set(room, state);
+		}
+		state.members.set(clientId, {
+			meta,
+			lastSeen: Date.now()
+		});
+		let joined = this.roomsByClient.get(clientId);
+		if (!joined) {
+			joined = /* @__PURE__ */ 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
+		}));
+	}
+};
+let PresenceResolver = class PresenceResolver {
+	presence;
+	constructor(presence) {
+		this.presence = presence;
+	}
+	roster(args) {
+		return this.presence.roster(args.room);
+	}
+};
+__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 };
+		}
+	}),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Array)
+], PresenceResolver.prototype, "roster", null);
+PresenceResolver = __decorate([
+	LiveResolver(),
+	Injectable(),
+	__decorateParam(0, Inject(PresenceService)),
+	__decorateMetadata("design:paramtypes", [typeof PresenceService === "undefined" ? Object : PresenceService])
+], PresenceResolver);
+//#endregion
+//#region src/live/live.engine.ts
+var _LiveEngine;
+/** 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.
+*/
+const LIVE_SUBS_DATA_KEY = "__velaLiveSubs";
+/** Read the subscription records a transport persisted for a connection (wake/restore path). */
+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 void 0;
+	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 !== void 0; item = queue.shift()) await run(item);
+	});
+	await Promise.all(workers);
+}
+let LiveEngine = _LiveEngine = class LiveEngine {
+	container;
+	discovery;
+	log;
+	options;
+	presence;
+	queries = /* @__PURE__ */ new Map();
+	connections = /* @__PURE__ */ new Map();
+	pendingTags = /* @__PURE__ */ 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) => {
+			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 }
+		}];
+	}
+	async handleReservedEvent(path, client, message) {
+		const frame = message.data;
+		if (!isClientLiveFrame$1(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);
+	}
+	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);
+	}
+	async onSubscribe(path, client, frame) {
+		if (frame.v !== void 0 && frame.v > LIVE_PROTOCOL$1) {
+			this.sendFrame(client, {
+				t: "error",
+				sub: frame.sub,
+				code: LIVE_ERROR_CODES$1.UNSUPPORTED_PROTOCOL,
+				message: `server speaks live protocol v${LIVE_PROTOCOL$1}, 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$1.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$1.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$1.BAD_ARGS,
+				message: err instanceof Error ? err.message : "invalid subscription args",
+				fatal: true
+			});
+			return;
+		}
+		if (!await this.runSubscribeGuards(registered, client, frame.query, args)) {
+			this.sendFrame(client, {
+				t: "error",
+				sub: frame.sub,
+				code: LIVE_ERROR_CODES$1.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
+		});
+		if (frame.sinceCursor !== void 0 && frame.sinceEpoch !== void 0) {
+			if (await this.log.evaluateResume(frame.sinceCursor, frame.sinceEpoch, tags) === "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;
+		}
+	}
+	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();
+			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 });
+			});
+		}
+	}
+	/**
+	* Map a resolver failure to its live error-frame code. A branded
+	* {@link VelaError} carries an HTTP-ish status that projects onto the live
+	* vocabulary (403 → forbidden, 400/422 → bad_args); everything else — and
+	* every unbranded error — is `internal` (the client sees a redacted message).
+	*/
+	static liveFrameCode(err) {
+		if (!isVelaError(err)) return LIVE_ERROR_CODES$1.INTERNAL;
+		if (err.status === 403) return LIVE_ERROR_CODES$1.FORBIDDEN;
+		if (err.status === 400 || err.status === 422) return LIVE_ERROR_CODES$1.BAD_ARGS;
+		return LIVE_ERROR_CODES$1.INTERNAL;
+	}
+	async push(conn, record, stamp, { initial }) {
+		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 {}
+			return;
+		}
+		let json;
+		let result;
+		try {
+			result = await this.runQuery(record, conn.client);
+			if (result === void 0) result = null;
+			json = JSON.stringify(result);
+		} catch (err) {
+			if (initial) {
+				conn.subs.delete(record.sub);
+				const reporter = resolveErrorReporter(this.container);
+				reporter.report(err, {
+					edge: "live",
+					source: record.query
+				});
+				const safe = toErrorBody(err, { catalog: reporter.catalog });
+				this.sendFrame(conn.client, {
+					t: "error",
+					sub: record.sub,
+					code: _LiveEngine.liveFrameCode(err),
+					message: safe.body.error.message,
+					fatal: true
+				});
+			} else if (this.container.getDiagnostics() !== "silent") 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) => {
+			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) => {
+					return instance[registered.methodName].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: /* @__PURE__ */ new Map()
+			};
+			this.connections.set(client.id, conn);
+		}
+		return conn;
+	}
+	sendFrame(client, frame) {
+		try {
+			client.sendRaw(encodeLiveEnvelope$1(frame));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+LiveEngine = _LiveEngine = __decorate([
+	ReservedWsEvent("$live"),
+	Injectable(),
+	__decorateParam(0, Inject(Container)),
+	__decorateParam(1, Inject(DiscoveryService)),
+	__decorateParam(2, Inject(LIVE_CURSOR_LOG)),
+	__decorateParam(3, Inject(LIVE_DRIVER)),
+	__decorateParam(4, Inject(LIVE_MODULE_OPTIONS)),
+	__decorateParam(5, Optional()),
+	__decorateParam(5, Inject(PresenceService)),
+	__decorateMetadata("design:paramtypes", [
+		typeof Container === "undefined" ? Object : Container,
+		typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+		Object,
+		Object,
+		Object,
+		typeof PresenceService === "undefined" ? Object : PresenceService
+	])
+], LiveEngine);
+//#endregion
+//#region src/live/live.invalidation.ts
+/** Single-scope default driver: deliver straight to this process's engine. */
+function localLive() {
+	let sink;
+	return {
+		kind: "local",
+		bind(s) {
+			sink = s;
+		},
+		dispatch(cmd) {
+			return sink?.applyInvalidation(cmd);
+		}
+	};
+}
+/**
+* Per-app wrapper around a (possibly SHARED) driver instance.
+*
+* A driver passed to `LiveModule.forRoot({ driver })` is a plain config object
+* — and on Cloudflare the SAME app module (thus the same driver object)
+* bootstraps in the Worker isolate AND inside each Durable Object, often
+* within one isolate. Mutable per-app state must therefore never live on the
+* driver itself: the DO flipping a shared `durableObjectLive()` into local
+* mode would otherwise poison the Worker's engine, which then executes the
+* DO's storage handle in the wrong request context ("Cannot perform I/O on
+* behalf of a different request").
+*
+* The wrapper owns the per-app sink and the per-app local-mode flag; isolate-
+* wide concerns (env capture) forward to the underlying driver. Platform init
+* hooks (`_setLocalMode`, `_initializeEnv`) are exposed pass-through so
+* platform packages can keep type-guarding on their presence.
+*/
+function perAppLiveDriver(underlying) {
+	let ownSink;
+	let localMode = false;
+	const cfHooks = underlying;
+	return {
+		get kind() {
+			return underlying.kind;
+		},
+		bind(sink) {
+			ownSink = sink;
+			underlying.bind(sink);
+		},
+		dispatch(cmd) {
+			if (localMode && ownSink) return ownSink.applyInvalidation(cmd);
+			return underlying.dispatch(cmd);
+		},
+		start: underlying.start ? () => underlying.start?.() : void 0,
+		stop: underlying.stop ? () => underlying.stop?.() : void 0,
+		_setLocalMode() {
+			localMode = true;
+		},
+		_initializeEnv(env) {
+			cfHooks._initializeEnv?.(env);
+		}
+	};
+}
+/**
+* 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}.
+*/
+var LiveInvalidation = class {
+	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). */
+function stampCommitHeaders(c, stamp) {
+	c.header(COMMIT_CURSOR_HEADER$1, String(stamp.cursor));
+	c.header(COMMIT_EPOCH_HEADER$1, 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 {}
+}
+//#endregion
+//#region src/live/live.module.ts
+/**
+* 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) => perAppLiveDriver(o.driver ?? localLive()),
+				inject: [OPTIONS]
+			},
+			{
+				provide: PresenceService,
+				useFactory: (o) => {
+					const presence = o.presence;
+					if (presence === false) return new PresenceService(void 0, false);
+					return new PresenceService(presence?.ttlMs, true);
+				},
+				inject: [OPTIONS]
+			},
+			{
+				provide: LiveInvalidation,
+				useFactory: (driver) => new LiveInvalidation(driver),
+				inject: [LIVE_DRIVER]
+			},
+			LiveEngine,
+			...options?.presence === false ? [] : [PresenceResolver]
+		],
+		exports: [
+			LiveEngine,
+			LiveInvalidation,
+			LIVE_DRIVER,
+			LIVE_CURSOR_LOG,
+			PresenceService
+		]
+	})
+});
+var LiveModule = class extends ConfigurableModuleClass {};
+//#endregion
+export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, InMemoryCursorLog, LIVE_CURSOR_LOG, LIVE_DRIVER, LIVE_ERROR_CODES, LIVE_EVENT, LIVE_MODULE_OPTIONS, LIVE_PROTOCOL, LIVE_QUERY_METADATA, LIVE_RESOLVER_METADATA, LIVE_SUBS_DATA_KEY, LiveEngine, LiveInvalidation, LiveModule, LiveQuery, LiveResolver, PRESENCE_ROSTER_QUERY, PresenceResolver, PresenceService, applyListDelta, encodeListDelta, encodeLiveEnvelope, encodeLiveFrame, encodeSubscriptionUpdate, getLiveQueries, isClientLiveFrame, isServerLiveFrame, localLive, perAppLiveDriver, presenceTag, readLiveEnvelope, readPersistedLiveSubscriptions, stampCommitHeaders };
+
+//# sourceMappingURL=index.js.map