@velajs/cloudflare 1.8.0 → 1.10.0

package/dist/cloudflare-factory.js

@@ -2,6 +2,7 @@ import { VelaFactory } from "@velajs/vela";
 import { BindingRef } from "./binding-ref.js";
 import { CloudflareApplication } from "./cloudflare-application.js";
 import { EnvRef } from "./env-ref.js";
+import { initializeWorkerLive } from "./websocket/do-live.js";
 import { registerWebSocketRoutes } from "./websocket/websocket-routing.js";
 // Walks every provider registered in the container and pulls out the
 // BindingRef instances. Replaces the old module-level `bindingsRegistry`
@@ -63,6 +64,7 @@ function collectBindingRefs(container) {
  */ export function cloudflareAdapter() {
     let initialized = false;
     let refs = [];
+    let liveContainer;
     return {
         name: 'cloudflare',
         requestMiddleware: [
@@ -75,11 +77,15 @@ function collectBindingRefs(container) {
                         if (ref instanceof EnvRef) ref._initialize(env);
                         else ref._initialize(env[ref.bindingName]);
                     }
+                    // Live queries: hand the durableObjectLive() driver its env so
+                    // Worker-side invalidations can resolve the room DO namespace.
+                    if (liveContainer) initializeWorkerLive(liveContainer, env);
                 }
                 await next();
             }
         ],
         onBootstrap: ({ container })=>{
+            liveContainer = container;
             refs = collectBindingRefs(container);
         }
     };

package/dist/index.d.ts

@@ -23,11 +23,17 @@ export { AIService } from './services/ai.service';
 export { VectorizeService } from './services/vectorize.service';
 export { HyperdriveService } from './services/hyperdrive.service';
 export { EnvService } from './services/env.service';
+export { FlagshipFlagDriver, flagshipFlagDriver } from './services/flagship-flag.driver';
+export type { FlagshipBinding, FlagshipFlagDriverOptions } from './services/flagship-flag.driver';
+export { KvFlagDriver, kvFlagDriver } from './services/kv-flag.driver';
+export type { KvFlagDriverOptions } from './services/kv-flag.driver';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';
 export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom, } from './websocket/index';
 export type { WsGatewayRoute } from './websocket/index';
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, liveInvalidateToRoom, } from './websocket/index';
+export type { CfLiveDriver, DurableObjectLiveOptions } from './websocket/index';
 export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException, } from '@velajs/vela/websocket';
 export type { WsClient, WsServer, WsResponse, WsMessage, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from '@velajs/vela/websocket';
 export type { CloudflareEnv, ScheduledRegistration, QueueRegistration } from './types';

package/dist/index.js

@@ -24,11 +24,16 @@ export { AIService } from "./services/ai.service.js";
 export { VectorizeService } from "./services/vectorize.service.js";
 export { HyperdriveService } from "./services/hyperdrive.service.js";
 export { EnvService } from "./services/env.service.js";
+// Feature-flag drivers (implement @velajs/feature-flags' FeatureFlagDriver contract)
+export { FlagshipFlagDriver, flagshipFlagDriver } from "./services/flagship-flag.driver.js";
+export { KvFlagDriver, kvFlagDriver } from "./services/kv-flag.driver.js";
 // Decorators
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";
 export { QueueConsumer } from "./decorators/queue-consumer.js";
 // WebSocket (Durable Object transport for the Vela WebSocketModule)
 export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom } from "./websocket/index.js";
+// Live queries (Durable Object transport for @velajs/vela/live)
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, liveInvalidateToRoom } from "./websocket/index.js";
 // Re-export the core gateway API so a Cloudflare app can import it from one place.
 export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException } from "@velajs/vela/websocket";

package/dist/services/flagship-flag.driver.d.ts

@@ -0,0 +1,57 @@
+import type { FeatureFlagDriver, FlagContext } from '@velajs/feature-flags';
+/**
+ * The subset of a Cloudflare **Flagship** binding this driver evaluates against
+ * — the four typed value methods. The binding itself returns the supplied
+ * `defaultValue` on evaluation errors; transport-level failures reject and are
+ * left to propagate (never-throw is the service layer's job, not the driver's).
+ *
+ * @see https://developers.cloudflare.com/flagship/binding/
+ */
+export interface FlagshipBinding {
+    getBooleanValue(key: string, defaultValue: boolean, context?: FlagContext): Promise<boolean>;
+    getStringValue(key: string, defaultValue: string, context?: FlagContext): Promise<string>;
+    getNumberValue(key: string, defaultValue: number, context?: FlagContext): Promise<number>;
+    getObjectValue<T extends object>(key: string, defaultValue: T, context?: FlagContext): Promise<T>;
+}
+export interface FlagshipFlagDriverOptions {
+    /** Driver name used for `use(name)` / default-driver selection. Default `"flagship"`. */
+    name?: string;
+}
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */
+export declare class FlagshipFlagDriver implements FeatureFlagDriver {
+    readonly name: string;
+    private readonly resolve;
+    constructor(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions);
+    getBoolean(key: string, fallback: boolean, ctx?: FlagContext): Promise<boolean>;
+    getString(key: string, fallback: string, ctx?: FlagContext): Promise<string>;
+    getNumber(key: string, fallback: number, ctx?: FlagContext): Promise<number>;
+    getObject<T extends object>(key: string, fallback: T, ctx?: FlagContext): Promise<T>;
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */
+export declare function flagshipFlagDriver(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions): FlagshipFlagDriver;

package/dist/services/flagship-flag.driver.js

@@ -0,0 +1,49 @@
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */ export class FlagshipFlagDriver {
+    name;
+    resolve;
+    constructor(binding, options = {}){
+        this.resolve = typeof binding === 'function' ? binding : ()=>binding;
+        this.name = options.name ?? 'flagship';
+    }
+    getBoolean(key, fallback, ctx) {
+        return this.resolve().getBooleanValue(key, fallback, ctx);
+    }
+    getString(key, fallback, ctx) {
+        return this.resolve().getStringValue(key, fallback, ctx);
+    }
+    getNumber(key, fallback, ctx) {
+        return this.resolve().getNumberValue(key, fallback, ctx);
+    }
+    getObject(key, fallback, ctx) {
+        return this.resolve().getObjectValue(key, fallback, ctx);
+    }
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */ export function flagshipFlagDriver(binding, options) {
+    return new FlagshipFlagDriver(binding, options);
+}

package/dist/services/kv-flag.driver.d.ts

@@ -0,0 +1,48 @@
+import type { FeatureFlagDriver, FlagContext } from '@velajs/feature-flags';
+import { KVService } from './kv.service';
+export interface KvFlagDriverOptions {
+    /** Driver name used for `use(name)` / default-driver selection. Default `"kv"`. */
+    name?: string;
+    /** Prefix prepended to every flag key before the KV read. Default `""` (none). */
+    prefix?: string;
+}
+/**
+ * Cloudflare KV-backed {@link FeatureFlagDriver}. Flags are stored as JSON
+ * values under an optional key prefix and read with `get(key, 'json')`. Reads
+ * are type-checked against the requested type: a missing key or a value of the
+ * wrong JSON type returns the caller's `fallback`. KV has no targeting, so the
+ * evaluation context is ignored.
+ *
+ * The driver stays honest — it does **not** swallow errors. A KV failure (or a
+ * `SyntaxError` from a malformed stored value) propagates; the never-throw
+ * guarantee lives in `@velajs/feature-flags`'s service layer.
+ *
+ * Placed like {@link KVCacheStore}: construct it in a wiring factory over a
+ * resolved {@link KVService}.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [KVService],
+ *   useFactory: (kv: KVService) => ({ drivers: [new KvFlagDriver(kv, { prefix: 'flag:' })] }),
+ * });
+ * ```
+ */
+export declare class KvFlagDriver implements FeatureFlagDriver {
+    private readonly kv;
+    readonly name: string;
+    private readonly prefix;
+    constructor(kv: KVService, options?: KvFlagDriverOptions);
+    private get ns();
+    getBoolean(key: string, fallback: boolean, _ctx?: FlagContext): Promise<boolean>;
+    getString(key: string, fallback: string, _ctx?: FlagContext): Promise<string>;
+    getNumber(key: string, fallback: number, _ctx?: FlagContext): Promise<number>;
+    getObject<T extends object>(key: string, fallback: T, _ctx?: FlagContext): Promise<T>;
+    /**
+     * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+     * when `matches` accepts its type; otherwise the caller's fallback. A missing
+     * key reads as `null` → fallback. Read/parse errors are left to propagate.
+     */
+    private read;
+}
+/** Convenience factory for {@link KvFlagDriver}. */
+export declare function kvFlagDriver(kv: KVService, options?: KvFlagDriverOptions): KvFlagDriver;

package/dist/services/kv-flag.driver.js

@@ -0,0 +1,62 @@
+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 "@velajs/vela";
+import { KVService } from "./kv.service.js";
+export class KvFlagDriver {
+    kv;
+    name;
+    prefix;
+    constructor(kv, options = {}){
+        this.kv = kv;
+        this.name = options.name ?? 'kv';
+        this.prefix = options.prefix ?? '';
+    }
+    get ns() {
+        return this.kv.namespace;
+    }
+    getBoolean(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'boolean');
+    }
+    getString(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'string');
+    }
+    getNumber(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'number');
+    }
+    getObject(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'object' && v !== null);
+    }
+    /**
+   * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+   * when `matches` accepts its type; otherwise the caller's fallback. A missing
+   * key reads as `null` → fallback. Read/parse errors are left to propagate.
+   */ async read(key, fallback, matches) {
+        const value = await this.ns.get(this.prefix + key, 'json');
+        if (value === null || value === undefined) return fallback;
+        return matches(value) ? value : fallback;
+    }
+}
+KvFlagDriver = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(KVService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof KVService === "undefined" ? Object : KVService,
+        typeof KvFlagDriverOptions === "undefined" ? Object : KvFlagDriverOptions
+    ])
+], KvFlagDriver);
+/** Convenience factory for {@link KvFlagDriver}. */ export function kvFlagDriver(kv, options) {
+    return new KvFlagDriver(kv, options);
+}

package/dist/websocket/do-bootstrap.d.ts

@@ -1,6 +1,7 @@
 import type { Type } from '@velajs/vela';
 import { WsDispatcher } from '@velajs/vela/websocket';
 import type { WsServer } from '@velajs/vela/websocket';
+import type { LiveEngine } from '@velajs/vela/live';
 import { CfRoomRegistry } from './cf-room-registry';
 import type { DoStateLike } from './do-state';
 export interface DoRuntime {
@@ -9,6 +10,8 @@ export interface DoRuntime {
     server: WsServer;
     /** Gateway paths from `app.entrypoints.ofKind('websocket')` (discovery order). */
     gatewayPaths: string[];
+    /** The live-query engine (undefined when the app doesn't import LiveModule). */
+    live?: LiveEngine;
     close(signal?: string): Promise<void>;
 }
 /**

package/dist/websocket/do-bootstrap.js

@@ -3,6 +3,7 @@ import { local, WsDispatcher, WsServerImpl, WS_SERVER } from "@velajs/vela/webso
 import { BindingRef } from "../binding-ref.js";
 import { EnvRef } from "../env-ref.js";
 import { CfRoomRegistry } from "./cf-room-registry.js";
+import { initDoLive } from "./do-live.js";
 import { WsServerHolder } from "./ws-server-holder.js";
 /**
  * Slim DI bootstrap for the Durable Object isolate: wires the container and runs
@@ -38,6 +39,9 @@ import { WsServerHolder } from "./ws-server-holder.js";
     // per discovered gateway ({ meta: { path, dispatcher } }). Built by
     // callOnApplicationBootstrap(), so this slim no-routes path has it too.
     const wsEntrypoints = app.entrypoints.ofKind('websocket');
+    // Live queries: wire the SQLite cursor log + local driver mode and replay
+    // hibernation-persisted subscriptions into the fresh engine.
+    const live = initDoLive(app, container, ctx);
     return {
         // Zero gateways still yields a live dispatcher (module imported, nothing
         // decorated) — fall back to resolving it directly.
@@ -45,6 +49,7 @@ import { WsServerHolder } from "./ws-server-holder.js";
         registry,
         server,
         gatewayPaths: wsEntrypoints.map((ep)=>ep.meta.path),
+        live,
         close: (signal)=>app.close(signal)
     };
 }

package/dist/websocket/do-live.d.ts

@@ -0,0 +1,81 @@
+import type { Container } from '@velajs/vela';
+import type { CommitStamp, CursorLog, LiveDriver, LiveEngine, ResumeVerdict } from '@velajs/vela/live';
+import type { DoStateLike, SqlStorageLike } from './do-state';
+/**
+ * The durable `CursorLog`: an append-only tag-invalidation log in the DO's
+ * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
+ * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
+ * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
+ * client whose gap the log still covers gets a tiny `resume` instead of a
+ * re-run — the real-resume half of the live protocol.
+ *
+ * Constructed un-initialized at module-composition time (the same app module
+ * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
+ * handle inside the DO. In the Worker isolate it stays un-initialized — and is
+ * never consulted there, because `durableObjectLive()` routes every
+ * invalidation to the room DO's log (one log scope per room, exactly the
+ * protocol's model).
+ */
+export declare class DoCursorLog implements CursorLog {
+    private readonly maxRows;
+    private sql?;
+    private epoch?;
+    constructor(maxRows?: number);
+    /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */
+    _initialize(sql: SqlStorageLike): void;
+    append(tags: string[]): CommitStamp;
+    current(): CommitStamp;
+    evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict;
+    private assertReady;
+}
+export interface DurableObjectLiveOptions {
+    /** The wrangler binding name of the WebSocket DO namespace (e.g. `'CHAT_ROOM'`). */
+    binding: string;
+    /** Room used when an invalidation names none. Matches the client default. */
+    defaultRoom?: string;
+}
+export interface CfLiveDriver extends LiveDriver {
+    /** @internal — Worker isolate: capture `env` so the namespace binding resolves per dispatch. */
+    _initializeEnv(env: Record<string, unknown>): void;
+    /** @internal — DO isolate: deliver invalidations straight to this DO's engine. */
+    _setLocalMode(): void;
+}
+/**
+ * The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
+ * bootstraps in both isolates:
+ *
+ * - **Worker** (HTTP mutations, queue consumers, crons): route the command to
+ *   the room's Durable Object over the `invalidate` RPC — the same canonical
+ *   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
+ *   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
+ *   must carry).
+ * - **DO** (writes issued from inside the object): apply to the local engine.
+ */
+export declare function durableObjectLive(options: DurableObjectLiveOptions): CfLiveDriver;
+/** Worker-side wiring, called from `cloudflareAdapter`'s first-request middleware. */
+export declare function initializeWorkerLive(container: Container, env: Record<string, unknown>): void;
+/** The app-facing surface of the engine reached through `app.entrypoints.ofKind('live')`. */
+interface EntrypointsApp {
+    entrypoints: {
+        ofKind<M>(kind: string): Array<{
+            meta: M;
+        }>;
+    };
+}
+/**
+ * DO-side wiring, called from `buildDoRuntime`: initialize the SQLite cursor
+ * log, flip the driver to local mode, and replay every hibernation-persisted
+ * subscription into the (fresh) engine so an eviction is invisible to
+ * subscribers. Returns the engine for the `invalidate` RPC, or undefined when
+ * the app doesn't use LiveModule.
+ */
+export declare function initDoLive(app: EntrypointsApp, container: Container, ctx: DoStateLike): LiveEngine | undefined;
+/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */
+export declare function durableObjectCursorLog(maxRows?: number): DoCursorLog;
+/**
+ * Invalidate live tags in a room from a Worker (controller / cron / queue
+ * consumer) — the live sibling of `broadcastToRoom`. Returns the room log
+ * scope's commit stamp for `Vela-Commit-Cursor` stamping.
+ */
+export declare function liveInvalidateToRoom(ns: DurableObjectNamespace, room: string, tags: string[]): Promise<CommitStamp | undefined>;
+export {};

package/dist/websocket/do-live.js

@@ -0,0 +1,197 @@
+import { LIVE_CURSOR_LOG, LIVE_DRIVER, readPersistedLiveSubscriptions } from "@velajs/vela/live";
+import { CfWsClient } from "./cf-ws-client.js";
+import { roomToDurableId } from "./room-id.js";
+const DEFAULT_ROOM = 'default';
+const DEFAULT_MAX_LOG_ROWS = 4096;
+/**
+ * The durable `CursorLog`: an append-only tag-invalidation log in the DO's
+ * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
+ * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
+ * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
+ * client whose gap the log still covers gets a tiny `resume` instead of a
+ * re-run — the real-resume half of the live protocol.
+ *
+ * Constructed un-initialized at module-composition time (the same app module
+ * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
+ * handle inside the DO. In the Worker isolate it stays un-initialized — and is
+ * never consulted there, because `durableObjectLive()` routes every
+ * invalidation to the room DO's log (one log scope per room, exactly the
+ * protocol's model).
+ */ export class DoCursorLog {
+    maxRows;
+    sql;
+    epoch;
+    constructor(maxRows = DEFAULT_MAX_LOG_ROWS){
+        this.maxRows = maxRows;
+    }
+    /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */ _initialize(sql) {
+        this.sql = sql;
+        sql.exec('CREATE TABLE IF NOT EXISTS __vela_live_log (seq INTEGER PRIMARY KEY AUTOINCREMENT, ts REAL NOT NULL, tags TEXT NOT NULL)');
+        sql.exec('CREATE TABLE IF NOT EXISTS __vela_live_meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)');
+        const row = sql.exec("SELECT v FROM __vela_live_meta WHERE k = 'epoch'").toArray()[0];
+        if (row && typeof row.v === 'string') {
+            this.epoch = row.v;
+        } else {
+            this.epoch = crypto.randomUUID();
+            sql.exec("INSERT INTO __vela_live_meta (k, v) VALUES ('epoch', ?)", this.epoch);
+        }
+    }
+    append(tags) {
+        const sql = this.assertReady();
+        sql.exec('INSERT INTO __vela_live_log (ts, tags) VALUES (?, ?)', Date.now(), JSON.stringify(tags));
+        const stamp = this.current();
+        // Bounded retention: trimmed gaps degrade to snapshot-on-reconnect.
+        if (stamp.cursor > this.maxRows) {
+            sql.exec('DELETE FROM __vela_live_log WHERE seq <= ?', stamp.cursor - this.maxRows);
+        }
+        return stamp;
+    }
+    current() {
+        const sql = this.assertReady();
+        // sqlite_sequence survives DELETE-based trims, so the cursor never
+        // rewinds. The table itself only materializes on the first AUTOINCREMENT
+        // insert — before that the log is empty and the cursor is 0.
+        let cursor = 0;
+        try {
+            const row = sql.exec("SELECT seq FROM sqlite_sequence WHERE name = '__vela_live_log'").toArray()[0];
+            cursor = typeof row?.seq === 'number' ? row.seq : Number(row?.seq ?? 0);
+        } catch  {
+            cursor = 0;
+        }
+        return {
+            cursor,
+            epoch: this.epoch
+        };
+    }
+    evaluateResume(sinceCursor, sinceEpoch, subscriptionTags) {
+        const sql = this.assertReady();
+        const { cursor, epoch } = this.current();
+        if (sinceEpoch !== epoch) return 'snapshot'; // forked timeline (reset/recreated DO)
+        if (sinceCursor > cursor) return 'snapshot'; // rollback guard
+        if (sinceCursor === cursor) return 'resume';
+        const minRow = sql.exec('SELECT MIN(seq) AS m FROM __vela_live_log').toArray()[0];
+        const min = minRow?.m == null ? undefined : Number(minRow.m);
+        // The log must still cover (sinceCursor, cursor] — a trimmed gap cannot be reasoned about.
+        if (min === undefined || min > sinceCursor + 1) return 'snapshot';
+        const subTags = new Set(subscriptionTags);
+        for (const row of sql.exec('SELECT tags FROM __vela_live_log WHERE seq > ?', sinceCursor).toArray()){
+            let tags;
+            try {
+                tags = JSON.parse(String(row.tags));
+            } catch  {
+                return 'snapshot';
+            }
+            if (Array.isArray(tags) && tags.some((tag)=>subTags.has(tag))) return 'rerun';
+        }
+        return 'resume';
+    }
+    assertReady() {
+        if (!this.sql) {
+            throw new Error('DoCursorLog is not initialized. It only runs inside a SQLite-backed Durable Object ' + '(wrangler: new_sqlite_classes) — Worker-side invalidations must go through durableObjectLive(), ' + "which routes them to the room DO's log.");
+        }
+        return this.sql;
+    }
+}
+/**
+ * The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
+ * bootstraps in both isolates:
+ *
+ * - **Worker** (HTTP mutations, queue consumers, crons): route the command to
+ *   the room's Durable Object over the `invalidate` RPC — the same canonical
+ *   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
+ *   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
+ *   must carry).
+ * - **DO** (writes issued from inside the object): apply to the local engine.
+ */ export function durableObjectLive(options) {
+    let sink;
+    let env;
+    let localMode = false;
+    return {
+        kind: 'durable-object',
+        bind (boundSink) {
+            sink = boundSink;
+        },
+        _initializeEnv (capturedEnv) {
+            env = capturedEnv;
+        },
+        _setLocalMode () {
+            localMode = true;
+        },
+        dispatch (cmd) {
+            if (localMode) return sink?.applyInvalidation(cmd);
+            const namespace = env?.[options.binding];
+            if (!namespace) {
+                throw new Error(`durableObjectLive: binding '${options.binding}' is not available. In a Worker, ` + 'createCloudflareApp() captures env on the first request; check the wrangler binding name.');
+            }
+            const room = cmd.room ?? options.defaultRoom ?? DEFAULT_ROOM;
+            const stub = namespace.get(roomToDurableId(namespace, room));
+            return stub.invalidate({
+                ...cmd,
+                room
+            });
+        }
+    };
+}
+const isCfLiveDriver = (value)=>typeof value === 'object' && value !== null && typeof value._setLocalMode === 'function' && typeof value._initializeEnv === 'function';
+/** Worker-side wiring, called from `cloudflareAdapter`'s first-request middleware. */ export function initializeWorkerLive(container, env) {
+    let driver;
+    try {
+        driver = container.resolve(LIVE_DRIVER);
+    } catch  {
+        return; // LiveModule not imported
+    }
+    if (isCfLiveDriver(driver)) driver._initializeEnv(env);
+}
+/**
+ * DO-side wiring, called from `buildDoRuntime`: initialize the SQLite cursor
+ * log, flip the driver to local mode, and replay every hibernation-persisted
+ * subscription into the (fresh) engine so an eviction is invisible to
+ * subscribers. Returns the engine for the `invalidate` RPC, or undefined when
+ * the app doesn't use LiveModule.
+ */ export function initDoLive(app, container, ctx) {
+    const entry = app.entrypoints.ofKind('live')[0];
+    if (!entry) return undefined;
+    const engine = entry.meta.engine;
+    try {
+        const log = container.resolve(LIVE_CURSOR_LOG);
+        if (log instanceof DoCursorLog) {
+            const sql = ctx.storage?.sql;
+            if (!sql) {
+                throw new Error('DoCursorLog requires a SQLite-backed Durable Object: add this class to ' + "wrangler's `migrations[].new_sqlite_classes`. Falling back is not possible — " + 'either enable SQLite or drop the `log: durableObjectCursorLog()` option ' + '(snapshot-on-reconnect semantics).');
+            }
+            log._initialize(sql);
+        }
+    } catch (err) {
+        // Surface misconfiguration loudly — a silently un-initialized log would
+        // throw on the first subscribe instead.
+        if (err instanceof Error && err.message.includes('new_sqlite_classes')) throw err;
+    }
+    try {
+        const driver = container.resolve(LIVE_DRIVER);
+        if (isCfLiveDriver(driver)) driver._setLocalMode();
+    } catch  {
+    // LiveModule always provides LIVE_DRIVER when the engine exists; defensive only.
+    }
+    // Wake-time replay: subscriptions ride the hibernation attachments.
+    for (const ws of ctx.getWebSockets()){
+        const client = new CfWsClient(ctx, ws);
+        for (const record of readPersistedLiveSubscriptions(client)){
+            engine.restoreSubscription(client.path, client, record);
+        }
+    }
+    return engine;
+}
+/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */ export function durableObjectCursorLog(maxRows) {
+    return new DoCursorLog(maxRows);
+}
+/**
+ * Invalidate live tags in a room from a Worker (controller / cron / queue
+ * consumer) — the live sibling of `broadcastToRoom`. Returns the room log
+ * scope's commit stamp for `Vela-Commit-Cursor` stamping.
+ */ export async function liveInvalidateToRoom(ns, room, tags) {
+    const stub = ns.get(roomToDurableId(ns, room));
+    return stub.invalidate({
+        room,
+        tags
+    });
+}

package/dist/websocket/do-state.d.ts

@@ -4,6 +4,12 @@ export interface WsLike {
     serializeAttachment(value: unknown): void;
     deserializeAttachment(): unknown;
 }
+/** Structural view of the DO's SQLite handle (`ctx.storage.sql`, requires `new_sqlite_classes`). */
+export interface SqlStorageLike {
+    exec(query: string, ...bindings: unknown[]): {
+        toArray(): Record<string, unknown>[];
+    };
+}
 export interface DoStateLike {
     readonly id: {
         toString(): string;
@@ -12,6 +18,10 @@ export interface DoStateLike {
     acceptWebSocket(ws: WsLike, tags?: string[]): void;
     getWebSockets(tag?: string): WsLike[];
     setWebSocketAutoResponse?(pair: unknown): void;
+    /** Present on SQLite-backed DOs — the live cursor log lives here. */
+    readonly storage?: {
+        sql?: SqlStorageLike;
+    };
 }
 /** Per-connection metadata persisted in the hibernation attachment (≤ 16 KiB). */
 export interface WsAttachment {

package/dist/websocket/index.d.ts

@@ -1,6 +1,8 @@
 export { VelaWebSocketDurableObject } from './websocket.durable-object';
 export { CloudflareWebSocketModule } from './cloudflare-websocket.module';
 export { broadcastToRoom } from './broadcast';
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, initDoLive, initializeWorkerLive, liveInvalidateToRoom, } from './do-live';
+export type { CfLiveDriver, DurableObjectLiveOptions } from './do-live';
 export { CfWsClient } from './cf-ws-client';
 export { CfRoomRegistry } from './cf-room-registry';
 export { DoWebSocketHost } from './do-websocket-host';
@@ -10,4 +12,4 @@ export type { DoRuntime } from './do-bootstrap';
 export { registerWebSocketRoutes, collectWsGatewayRoutes } from './websocket-routing';
 export type { WsGatewayRoute } from './websocket-routing';
 export { roomTag, connTag, roomToDurableId } from './room-id';
-export type { DoStateLike, WsLike, WsAttachment } from './do-state';
+export type { DoStateLike, SqlStorageLike, WsLike, WsAttachment } from './do-state';

package/dist/websocket/index.js

@@ -3,6 +3,8 @@ export { VelaWebSocketDurableObject } from "./websocket.durable-object.js";
 // Module + server-initiated emit helper
 export { CloudflareWebSocketModule } from "./cloudflare-websocket.module.js";
 export { broadcastToRoom } from "./broadcast.js";
+// Live queries: durable cursor log + DO-routed invalidation driver
+export { DoCursorLog, durableObjectCursorLog, durableObjectLive, initDoLive, initializeWorkerLive, liveInvalidateToRoom } from "./do-live.js";
 // Transport internals (advanced use / testing)
 export { CfWsClient } from "./cf-ws-client.js";
 export { CfRoomRegistry } from "./cf-room-registry.js";

package/dist/websocket/websocket.durable-object.js

@@ -17,6 +17,7 @@ const PONG = '{"event":"pong"}';
  */ export function VelaWebSocketDurableObject(rootModule) {
     return class VelaWsDurableObject extends DurableObject {
         host;
+        liveEngine;
         ready;
         constructor(ctx, env){
             super(ctx, env);
@@ -29,6 +30,7 @@ const PONG = '{"event":"pong"}';
             this.ready = ctx.blockConcurrencyWhile(async ()=>{
                 const runtime = await buildDoRuntime(rootModule, ctx, env);
                 this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry, runtime.gatewayPaths);
+                this.liveEngine = runtime.live;
             });
         }
         async fetch(request) {
@@ -68,5 +70,14 @@ const PONG = '{"event":"pong"}';
             await this.ready;
             this.host.broadcast(cmd);
         }
+        /**
+     * DO RPC — live tag invalidation forwarded from a Worker (durableObjectLive /
+     * liveInvalidateToRoom). Appends to THIS log scope's cursor log and returns
+     * the commit stamp (what `Vela-Commit-Cursor` carries); the subscription
+     * refreshes fan out asynchronously.
+     */ async invalidate(cmd) {
+            await this.ready;
+            return this.liveEngine?.applyInvalidation(cmd);
+        }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,14 +45,21 @@
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/vela": ">=1.11.0",
+    "@velajs/feature-flags": "^0.1.0",
+    "@velajs/vela": ">=1.17.0",
     "hono": ">=4"
   },
+  "peerDependenciesMeta": {
+    "@velajs/feature-flags": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260624.1",
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.43",
-    "@velajs/vela": "^1.12.0",
+    "@velajs/feature-flags": "^0.1.0",
+    "@velajs/vela": "^1.17.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",