@velajs/cloudflare 1.10.0 → 2.0.0

package/dist/nonce-validation-LE0vFk-7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-validation-LE0vFk-7.js","names":["encoder","encoder"],"sources":["../src/websocket/room-id.ts","../src/environment.ts","../src/root-module.ts","../src/websocket/do-pitr.ts","../src/websocket/ws-server-holder.ts","../src/websocket/do-state.ts","../src/websocket/cf-ws-client.ts","../src/websocket/do-live.ts","../src/nonce/nonce-validation.ts"],"sourcesContent":["// Canonical room ↔ Durable Object mappings. The SAME functions are used by the\n// Worker upgrade route (to pick the DO) and by every server-initiated emit — so\n// a connection and a later broadcast always resolve to the same DO instance.\n\n/** Hibernation tag marking a socket's hub room (set at accept; immutable after). */\nexport function roomTag(roomId: string): string {\n  return `room:${roomId}`;\n}\n\n/** Hibernation tag addressing one connection directly. */\nexport function connTag(connId: string): string {\n  return `conn:${connId}`;\n}\n\nconst DO_ROOM_NAME_PREFIX = 'vela:ws:v2:';\nconst MAX_DO_ROOM_NAME_BYTES = 1_024;\nconst encoder = new TextEncoder();\n\n/** Stable, collision-free Durable Object name for one gateway's room. */\nexport function durableObjectRoomName(gatewayPath: string, roomId: string): string {\n  if (\n    typeof gatewayPath !== 'string' ||\n    gatewayPath.length === 0 ||\n    typeof roomId !== 'string' ||\n    roomId.length === 0 ||\n    /[\\u0000-\\u001f\\u007f]/.test(gatewayPath) ||\n    /[\\u0000-\\u001f\\u007f]/.test(roomId)\n  ) {\n    throw new Error('A non-empty, control-free gateway path and room id are required');\n  }\n  const name = `${DO_ROOM_NAME_PREFIX}${encodeURIComponent(gatewayPath)}:${encodeURIComponent(roomId)}`;\n  if (encoder.encode(name).byteLength > MAX_DO_ROOM_NAME_BYTES) {\n    throw new Error('The gateway/room Durable Object name exceeds 1024 bytes');\n  }\n  return name;\n}\n\n/** One Durable Object instance per gateway + room, addressed by name. */\nexport function roomToDurableId(\n  ns: Pick<DurableObjectNamespace, 'idFromName'>,\n  gatewayPath: string,\n  roomId: string,\n): DurableObjectId {\n  return ns.idFromName(durableObjectRoomName(gatewayPath, roomId));\n}\n","import { defineProvider, InjectionToken } from '@velajs/vela';\nimport type { Container } from '@velajs/vela/internal';\n\n/** An application's native Workers environment, including bindings and secrets. */\nexport interface CloudflareEnvironment<T extends object> {\n  /** Typed token used by @Inject and provider factories. */\n  readonly token: InjectionToken<T>;\n  /** The environment supplied by the current platform event or DO constructor. */\n  readonly env: T;\n}\n\n/**\n * Register native bindings before provider factories or lifecycle hooks run.\n * No platform I/O is performed here; callers create applications inside an event.\n */\nexport function registerCloudflareEnvironment<T extends object>(\n  container: Container,\n  environment: CloudflareEnvironment<T>,\n): void {\n  container.register(defineProvider(environment.token, { useValue: environment.env }));\n  container.markGlobalToken(environment.token);\n}\n\n/** Reject accidental reuse of an application with another event's environment. */\nexport function assertCloudflareEnvironment<T extends object>(expected: T, actual: T): void {\n  if (actual !== expected) {\n    throw new Error(\n      'This Cloudflare application belongs to a different environment. ' +\n        'Create an application with the current event environment.',\n    );\n  }\n}\n","import type { Type } from '@velajs/vela';\n\n/** A static module, or a module graph built from this Worker's native environment. */\nexport type CloudflareRoot<T extends object> = Type | { create(env: T): Type };\n\nexport function resolveCloudflareRoot<T extends object>(root: CloudflareRoot<T>, env: T): Type {\n  return typeof root === 'function' ? root : root.create(env);\n}\n","/**\n * Durable Object point-in-time recovery (PITR) — thin, testable wrappers over a\n * SQLite-backed DO's native bookmark API. A SQLite Durable Object exposes three\n * storage methods (last-30-days PITR):\n *\n *   - `getCurrentBookmark()` — an opaque bookmark for the storage's current state.\n *   - `getBookmarkForTime(t)` — the bookmark closest to a wall-clock instant.\n *   - `onNextSessionRestoreBookmark(b)` — arm a restore to bookmark `b`; the DO\n *     restores to it the next time it starts a session, and the call RETURNS a\n *     bookmark for the state JUST BEFORE the restore (the undo handle).\n *\n * These methods are ABSENT on a non-SQLite DO (key-value storage) and in some\n * local-dev runtimes, so this module models storage structurally with all three\n * methods OPTIONAL and degrades to a typed {@link DoPitrUnavailableError} (a\n * `code: 'PITR_UNAVAILABLE'`, HTTP 409 error) rather than an\n * `undefined is not a function` TypeError when a needed method is missing.\n *\n * Neither wrapper aborts the DO — `armDoPitr` only ARMS the restore and returns\n * the undo bookmark; the caller (the WS-DO RPC method) decides whether to\n * `ctx.abort()` to apply it immediately vs. on the next natural restart.\n *\n * This file is `cloudflare:workers`-free and pulls in NOTHING from `@velajs/vela`\n * or `@velajs/studio` — it is the raw capability the studio `TimeTravelPort`\n * wraps. Dependency direction is one-way: studio → cloudflare, never the reverse.\n */\n\n/**\n * The subset of `DurableObjectStorage` this module touches, with every method\n * OPTIONAL so it structurally models a non-SQLite DO whose storage has none of\n * them. A real `DurableObjectStorage` (whose methods are required) is assignable\n * to this shape.\n */\nexport interface DoPitrStorage {\n  getCurrentBookmark?(): Promise<string>;\n  getBookmarkForTime?(timestamp: number | Date): Promise<string>;\n  onNextSessionRestoreBookmark?(bookmark: string): Promise<string>;\n}\n\n/** A read of a DO's current bookmark (+ the by-time bookmark when a time is given). */\nexport interface DoPitrBookmarkRead {\n  /** The bookmark for the DO storage's current state. */\n  current: string;\n  /** The bookmark closest to the requested time (only when `time` was passed). */\n  forTime?: string;\n}\n\n/** Arming input for {@link armDoPitr}: a target (bookmark WINS over time) + restart intent. */\nexport interface DoPitrArmOptions {\n  /** An explicit target bookmark. Takes precedence over `time`. */\n  bookmark?: string;\n  /** A wall-clock target (epoch ms, ISO string, or Date), resolved to a bookmark. */\n  time?: number | string | Date;\n  /** Caller intent to restart-now; recorded on the result. `armDoPitr` never aborts. */\n  restart?: boolean;\n}\n\n/** The result of arming a PITR restore (before any restart is applied). */\nexport interface DoPitrArmResult {\n  /** The bookmark the restore is armed to. */\n  restoredTo: string;\n  /** The bookmark for the pre-restore state — restore to this to undo. */\n  undoBookmark: string;\n  /** Whether a restart-now was requested (the RPC layer performs the actual abort). */\n  restarted: boolean;\n}\n\n/** The RPC surface a PITR-capable Vela WebSocket DO stub exposes to a Worker. */\nexport interface VelaDoPitrRpc {\n  pitrCurrentBookmark(): Promise<DoPitrBookmarkRead>;\n  pitrBookmarkForTime(time: number | string): Promise<DoPitrBookmarkRead>;\n  pitrArmRestore(opts: DoPitrArmOptions): Promise<DoPitrArmResult>;\n}\n\n/** Structural view of a DO id (avoids depending on `@cloudflare/workers-types` downstream). */\nexport interface DoPitrId {\n  toString(): string;\n  readonly name?: string | null;\n}\n\n/**\n * Structural view of a DO namespace binding whose stubs speak the PITR RPC. A\n * downstream (the studio `@velajs/studio/cloudflare` port) types the app's\n * namespace binding as this shape to reach the PITR methods without importing\n * `@cloudflare/workers-types`.\n */\nexport interface DoPitrNamespace {\n  idFromName(name: string): DoPitrId;\n  get(id: DoPitrId): VelaDoPitrRpc;\n}\n\nconst PITR_UNAVAILABLE_CODE = 'PITR_UNAVAILABLE';\n\n/**\n * Thrown when a DO's storage lacks the SQLite bookmark API (non-SQLite DO, or a\n * local runtime without PITR). Carries a stable `code` + HTTP 409 `status`, and\n * a recognizable `name`/message so the studio port can map it to\n * `TIMETRAVEL_UNAVAILABLE` even after the error crosses the Worker→DO RPC hop\n * (which preserves `name` + `message`, not arbitrary own-properties).\n */\nexport class DoPitrUnavailableError extends Error {\n  readonly code = PITR_UNAVAILABLE_CODE;\n  readonly status = 409;\n\n  constructor(message = 'Durable Object point-in-time recovery is unavailable on this storage') {\n    super(`${PITR_UNAVAILABLE_CODE}: ${message}`);\n    this.name = 'DoPitrUnavailableError';\n  }\n}\n\n/**\n * True when `error` signals DO PITR unavailability. Robust across the Worker→DO\n * RPC hop: checks the `code` own-property (same process) AND the `name` / message\n * sentinel (survive RPC serialization) so a downstream can classify it either way.\n */\nexport function isDoPitrUnavailable(error: unknown): boolean {\n  if (typeof error !== 'object' || error === null) return false;\n  const record = error as { code?: unknown; name?: unknown; message?: unknown };\n  if (record.code === PITR_UNAVAILABLE_CODE) return true;\n  if (record.name === 'DoPitrUnavailableError') return true;\n  return (\n    typeof record.message === 'string' && record.message.startsWith(`${PITR_UNAVAILABLE_CODE}:`)\n  );\n}\n\n/** Normalize an epoch-ms number / ISO string / Date to the `number | Date` the DO API accepts. */\nfunction toStorageTime(time: number | string | Date): number | Date {\n  if (typeof time === 'number') return time;\n  if (time instanceof Date) return time;\n  const asNumber = Number(time);\n  return time.trim() !== '' && Number.isFinite(asNumber) ? asNumber : new Date(time);\n}\n\n/**\n * Read a DO's current bookmark, and — when `time` is given — the bookmark closest\n * to that instant. Throws {@link DoPitrUnavailableError} when a needed method is\n * absent, never `undefined is not a function`.\n */\nexport async function readDoPitrBookmark(\n  storage: DoPitrStorage,\n  time?: number | string | Date,\n): Promise<DoPitrBookmarkRead> {\n  const getCurrent = storage.getCurrentBookmark;\n  if (typeof getCurrent !== 'function') throw new DoPitrUnavailableError();\n  const current = await getCurrent.call(storage);\n  if (time === undefined) return { current };\n  const getForTime = storage.getBookmarkForTime;\n  if (typeof getForTime !== 'function') throw new DoPitrUnavailableError();\n  const forTime = await getForTime.call(storage, toStorageTime(time));\n  return { current, forTime };\n}\n\n/**\n * Arm a PITR restore. Resolves the target (an explicit `bookmark` WINS over\n * `time`), arms it via `onNextSessionRestoreBookmark`, and returns the undo\n * bookmark the DO reports for the pre-restore state. Does NOT abort — the caller\n * decides whether to restart now. Throws {@link DoPitrUnavailableError} when the\n * arming API (or the by-time resolver a `time` target needs) is absent.\n */\nexport async function armDoPitr(\n  storage: DoPitrStorage,\n  opts: DoPitrArmOptions,\n): Promise<DoPitrArmResult> {\n  const armRestore = storage.onNextSessionRestoreBookmark;\n  if (typeof armRestore !== 'function') throw new DoPitrUnavailableError();\n\n  let target: string;\n  if (opts.bookmark !== undefined) {\n    target = opts.bookmark;\n  } else if (opts.time !== undefined) {\n    const getForTime = storage.getBookmarkForTime;\n    if (typeof getForTime !== 'function') throw new DoPitrUnavailableError();\n    target = await getForTime.call(storage, toStorageTime(opts.time));\n  } else {\n    throw new DoPitrUnavailableError('a target bookmark or time is required to arm a restore');\n  }\n\n  const undoBookmark = await armRestore.call(storage, target);\n  return { restoredTo: target, undoBookmark, restarted: opts.restart === true };\n}\n","import { Injectable } from '@velajs/vela';\nimport { resolveMaxFrameBytes } from '@velajs/vela/websocket';\nimport type { BroadcastOperator, WsServer } from '@velajs/vela/websocket';\n\n/**\n * Late-bound `WsServer`. Provided as `WS_SERVER` (one per DI container, i.e. per\n * Durable Object instance), then pointed at the ctx-backed server once the DO\n * builds. Gateways inject it via `@WebSocketServer()`; it throws if used before\n * a runtime binds it (e.g. from the stateless Worker isolate).\n */\n@Injectable()\nexport class WsServerHolder implements WsServer {\n  private target?: WsServer;\n  private maxFrameBytes?: number;\n\n  setTarget(server: WsServer): void {\n    this.target = server;\n    if (this.maxFrameBytes !== undefined) server.setOutboundFrameLimit?.(this.maxFrameBytes);\n  }\n\n  setOutboundFrameLimit(maxFrameBytes: number): void {\n    const resolved = resolveMaxFrameBytes({ maxFrameBytes });\n    this.maxFrameBytes =\n      this.maxFrameBytes === undefined ? resolved : Math.max(this.maxFrameBytes, resolved);\n    this.target?.setOutboundFrameLimit?.(this.maxFrameBytes);\n  }\n\n  private get resolved(): WsServer {\n    if (!this.target) {\n      throw new Error(\n        'WebSocket server is only available inside a WebSocket Durable Object. To ' +\n          'push from a Worker HTTP handler, use broadcastToRoom(namespace, gatewayPath, room, ...).',\n      );\n    }\n    return this.target;\n  }\n\n  emit(event: string, data?: unknown): void | Promise<void> {\n    return this.resolved.emit(event, data);\n  }\n  to(room: string): BroadcastOperator {\n    return this.resolved.to(room);\n  }\n  in(room: string): BroadcastOperator {\n    return this.resolved.in(room);\n  }\n  except(room: string): BroadcastOperator {\n    return this.resolved.except(room);\n  }\n}\n","// Minimal structural views of the Durable Object runtime, so the transport\n// logic is unit-testable in Node with fakes. Real `DurableObjectState` and\n// `WebSocket` (from @cloudflare/workers-types) satisfy these structurally.\n\n/** Cloudflare's serialized WebSocket hibernation attachment ceiling. */\nexport const MAX_WS_ATTACHMENT_BYTES = 16_384;\n\nexport interface WsLike {\n  send(message: string | ArrayBuffer): void;\n  close(code?: number, reason?: string): void;\n  serializeAttachment(value: unknown): void;\n  deserializeAttachment(): unknown;\n}\n\n/** Structural view of the DO's SQLite handle (`ctx.storage.sql`, requires `new_sqlite_classes`). */\nexport interface SqlStorageLike {\n  exec(query: string, ...bindings: unknown[]): { toArray(): Record<string, unknown>[] };\n}\n\nexport interface DoStateLike {\n  readonly id: { toString(): string; readonly name?: string | null };\n  acceptWebSocket(ws: WsLike, tags?: string[]): void;\n  getWebSockets(tag?: string): WsLike[];\n  setWebSocketAutoResponse?(pair: unknown): void;\n  /** Present on SQLite-backed DOs — the live cursor log lives here. */\n  readonly storage?: { sql?: SqlStorageLike };\n}\n\n/** Per-connection metadata persisted in the hibernation attachment (≤ 16 KiB). */\nexport interface WsAttachment {\n  connId: string;\n  /** Only active sockets may dispatch frames or receive fan-out. */\n  state: 'pending' | 'active' | 'rejected';\n  userId?: string;\n  /** Verified, issuer-qualified connection principal. */\n  principal?: {\n    issuer: string;\n    subject: string;\n    principalType: 'user' | 'service';\n  };\n  /** Trusted server-derived tenant boundary for this connection. */\n  tenantId?: string;\n  /** Verified auth credential expiry in epoch milliseconds. */\n  expiresAtMs?: number;\n  /** The gateway route path this socket belongs to — used to route messages. */\n  path: string;\n  /** Validated inbound/outbound gateway frame ceiling, persisted across hibernation. */\n  maxFrameBytes?: number;\n  /** Dynamically-joined room names (the hub room is also a hibernation tag). */\n  rooms: string[];\n  data: Record<string, unknown>;\n}\n","import type { WsClient } from '@velajs/vela/websocket';\nimport {\n  assertWebSocketRoomId,\n  DEFAULT_WS_MAX_FRAME_BYTES,\n  DEFAULT_WS_MAX_JOINED_ROOMS,\n  webSocketFrameFits,\n} from '@velajs/vela/websocket';\nimport {\n  MAX_WS_ATTACHMENT_BYTES,\n  type DoStateLike,\n  type WsAttachment,\n  type WsLike,\n} from './do-state';\nconst encoder = new TextEncoder();\n\nconst EMPTY: WsAttachment = { connId: '', state: 'rejected', path: '', rooms: [], data: {} };\n\n/**\n * Core `WsClient` over a native Cloudflare `WebSocket` inside a Durable Object.\n * Per-connection state lives in the hibernation attachment (survives eviction),\n * so a fresh `CfWsClient` is reconstructed per message with no in-memory state.\n */\nexport class CfWsClient<\n  TData extends Record<string, unknown> = Record<string, unknown>,\n> implements WsClient<TData> {\n  private readonly attachment: WsAttachment;\n\n  constructor(\n    private readonly ctx: DoStateLike,\n    private readonly ws: WsLike,\n  ) {\n    const raw = ws.deserializeAttachment() as WsAttachment | null;\n    this.attachment = raw ?? { ...EMPTY, data: {} };\n  }\n\n  get id(): string {\n    return this.attachment.connId;\n  }\n\n  /** The gateway route path this socket connected on (used to route messages). */\n  get path(): string {\n    return this.attachment.path;\n  }\n\n  get rooms(): ReadonlySet<string> {\n    return new Set(this.attachment.rooms);\n  }\n\n  get data(): TData {\n    return this.attachment.data as TData;\n  }\n\n  set data(value: TData) {\n    this.attachment.data = value;\n  }\n\n  get raw(): unknown {\n    return this.ws;\n  }\n\n  get maxFrameBytes(): number {\n    const value = this.attachment.maxFrameBytes;\n    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0\n      ? value\n      : DEFAULT_WS_MAX_FRAME_BYTES;\n  }\n\n  send(event: string, data?: unknown, id?: string): void {\n    this.sendRaw(JSON.stringify(id !== undefined ? { id, event, data } : { event, data }));\n  }\n\n  sendRaw(payload: string): void {\n    if (!webSocketFrameFits(payload, this.maxFrameBytes)) {\n      this.close(1009, 'Message too large');\n      return;\n    }\n    this.ws.send(payload);\n  }\n\n  join(room: string): void {\n    assertWebSocketRoomId(room);\n    if (!this.attachment.rooms.includes(room)) {\n      if (this.attachment.rooms.length >= DEFAULT_WS_MAX_JOINED_ROOMS) {\n        throw new Error(`A WebSocket may join at most ${DEFAULT_WS_MAX_JOINED_ROOMS} rooms`);\n      }\n      this.attachment.rooms.push(room);\n      this.persist();\n    }\n  }\n\n  leave(room: string): void {\n    const next = this.attachment.rooms.filter((r) => r !== room);\n    if (next.length !== this.attachment.rooms.length) {\n      this.attachment.rooms = next;\n      this.persist();\n    }\n  }\n\n  /** Persist `data`/room mutations to the hibernation attachment. */\n  commit(): void {\n    this.persist();\n  }\n\n  close(code?: number, reason?: string): void {\n    this.ws.close(code, reason);\n  }\n\n  private persist(): void {\n    const serialized = JSON.stringify(this.attachment);\n    if (encoder.encode(serialized).length > MAX_WS_ATTACHMENT_BYTES) {\n      throw new Error(\n        `WebSocket attachment exceeds the 16 KiB Cloudflare limit. Store large ` +\n          `per-connection state in Durable Object storage keyed by connId instead.`,\n      );\n    }\n    this.ws.serializeAttachment(this.attachment);\n  }\n}\n","import type { Container } from '@velajs/vela';\nimport {\n  LIVE_CURSOR_LOG,\n  LIVE_DRIVER,\n  LiveEngine,\n  readPersistedLiveSubscriptions,\n} from '@velajs/vela/live';\nimport type {\n  CommitStamp,\n  CursorLog,\n  InvalidationCommand,\n  LiveDriver,\n  LiveInvalidationSink,\n  ResumeVerdict,\n} from '@velajs/vela/live';\nimport { CfWsClient } from './cf-ws-client';\nimport type { DoStateLike, SqlStorageLike } from './do-state';\nimport { roomToDurableId } from './room-id';\n\nconst DEFAULT_ROOM = 'default';\nconst DEFAULT_MAX_LOG_ROWS = 4096;\n\n/**\n * The durable `CursorLog`: an append-only tag-invalidation log in the DO's\n * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in\n * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is\n * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting\n * client whose gap the log still covers gets a tiny `resume` instead of a\n * re-run — the real-resume half of the live protocol.\n *\n * Constructed un-initialized at module-composition time (the same app module\n * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite\n * handle inside the DO. In the Worker isolate it stays un-initialized — and is\n * never consulted there, because `durableObjectLive()` routes every\n * invalidation to the room DO's log (one log scope per room, exactly the\n * protocol's model).\n */\nexport class DoCursorLog implements CursorLog {\n  private sql?: SqlStorageLike;\n  private epoch?: string;\n\n  constructor(private readonly maxRows = DEFAULT_MAX_LOG_ROWS) {}\n\n  /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */\n  _initialize(sql: SqlStorageLike): void {\n    this.sql = sql;\n    sql.exec(\n      'CREATE TABLE IF NOT EXISTS __vela_live_log (seq INTEGER PRIMARY KEY AUTOINCREMENT, ts REAL NOT NULL, tags TEXT NOT NULL)',\n    );\n    sql.exec('CREATE TABLE IF NOT EXISTS __vela_live_meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)');\n    const row = sql.exec(\"SELECT v FROM __vela_live_meta WHERE k = 'epoch'\").toArray()[0];\n    if (row && typeof row.v === 'string') {\n      this.epoch = row.v;\n    } else {\n      this.epoch = crypto.randomUUID();\n      sql.exec(\"INSERT INTO __vela_live_meta (k, v) VALUES ('epoch', ?)\", this.epoch);\n    }\n  }\n\n  append(tags: string[]): CommitStamp {\n    const sql = this.assertReady();\n    sql.exec(\n      'INSERT INTO __vela_live_log (ts, tags) VALUES (?, ?)',\n      Date.now(),\n      JSON.stringify(tags),\n    );\n    const stamp = this.current();\n    // Bounded retention: trimmed gaps degrade to snapshot-on-reconnect.\n    if (stamp.cursor > this.maxRows) {\n      sql.exec('DELETE FROM __vela_live_log WHERE seq <= ?', stamp.cursor - this.maxRows);\n    }\n    return stamp;\n  }\n\n  current(): CommitStamp {\n    const sql = this.assertReady();\n    // sqlite_sequence survives DELETE-based trims, so the cursor never\n    // rewinds. The table itself only materializes on the first AUTOINCREMENT\n    // insert — before that the log is empty and the cursor is 0.\n    let cursor = 0;\n    try {\n      const row = sql\n        .exec(\"SELECT seq FROM sqlite_sequence WHERE name = '__vela_live_log'\")\n        .toArray()[0];\n      cursor = typeof row?.seq === 'number' ? row.seq : Number(row?.seq ?? 0);\n    } catch {\n      cursor = 0;\n    }\n    if (!this.epoch) throw new Error('DoCursorLog epoch is not initialized.');\n    return { cursor, epoch: this.epoch };\n  }\n\n  evaluateResume(\n    sinceCursor: number,\n    sinceEpoch: string,\n    subscriptionTags: string[],\n  ): ResumeVerdict {\n    const sql = this.assertReady();\n    const { cursor, epoch } = this.current();\n    if (sinceEpoch !== epoch) return 'snapshot'; // forked timeline (reset/recreated DO)\n    if (sinceCursor > cursor) return 'snapshot'; // rollback guard\n    if (sinceCursor === cursor) return 'resume';\n\n    const minRow = sql.exec('SELECT MIN(seq) AS m FROM __vela_live_log').toArray()[0];\n    const min = minRow?.m == null ? undefined : Number(minRow.m);\n    // The log must still cover (sinceCursor, cursor] — a trimmed gap cannot be reasoned about.\n    if (min === undefined || min > sinceCursor + 1) return 'snapshot';\n\n    const subTags = new Set(subscriptionTags);\n    for (const row of sql\n      .exec('SELECT tags FROM __vela_live_log WHERE seq > ?', sinceCursor)\n      .toArray()) {\n      let tags: unknown;\n      try {\n        tags = JSON.parse(String(row.tags));\n      } catch {\n        return 'snapshot';\n      }\n      if (\n        Array.isArray(tags) &&\n        tags.some((tag: unknown) => typeof tag === 'string' && subTags.has(tag))\n      )\n        return 'rerun';\n    }\n    return 'resume';\n  }\n\n  private assertReady(): SqlStorageLike {\n    if (!this.sql) {\n      throw new Error(\n        'DoCursorLog is not initialized. It only runs inside a SQLite-backed Durable Object ' +\n          '(wrangler: new_sqlite_classes) — Worker-side invalidations must go through durableObjectLive(), ' +\n          \"which routes them to the room DO's log.\",\n      );\n    }\n    return this.sql;\n  }\n}\n\nexport interface DurableObjectLiveOptions {\n  /** Native, RPC-typed namespace supplied by the application's environment. */\n  namespace: LiveNamespace;\n  /** Exact `@WebSocketGateway()` path sharing this room/log namespace. */\n  gatewayPath: string;\n  /** Room used when an invalidation names none. Matches the client default. */\n  defaultRoom?: string;\n}\n\nexport interface LiveInvalidateStub {\n  invalidate(cmd: InvalidationCommand): Promise<CommitStamp | undefined>;\n}\n\n/** Only the native namespace operations required for live invalidation. */\nexport interface LiveNamespace {\n  idFromName(name: string): DurableObjectId;\n  get(id: DurableObjectId): LiveInvalidateStub;\n}\n\n/** One driver per application; construct from a LiveModule driver factory. */\nexport class CfLiveDriver implements LiveDriver {\n  readonly kind = 'durable-object';\n  private sink: LiveInvalidationSink | undefined;\n  private localMode = false;\n\n  constructor(private readonly options: DurableObjectLiveOptions) {}\n\n  bind(sink: LiveInvalidationSink): void {\n    this.sink = sink;\n  }\n\n  /** @internal — a DO dispatches to its own engine and SQLite log. */\n  _setLocalMode(): void {\n    this.localMode = true;\n  }\n\n  dispatch(cmd: InvalidationCommand): Promise<CommitStamp | undefined> | CommitStamp | undefined {\n    if (this.localMode) return this.sink?.applyInvalidation(cmd);\n    const { namespace, gatewayPath, defaultRoom } = this.options;\n    const room = cmd.room ?? defaultRoom ?? DEFAULT_ROOM;\n    return namespace\n      .get(roomToDurableId(namespace, gatewayPath, room))\n      .invalidate({ ...cmd, room });\n  }\n}\n\n/** Use in LiveModule.forRootAsync: driver: () => durableObjectLive({ namespace: env.ROOMS, ... }). */\nexport function durableObjectLive(options: DurableObjectLiveOptions): CfLiveDriver {\n  return new CfLiveDriver(options);\n}\n\n/** The app-facing surface of the engine reached through `app.entrypoints.ofKind('live')`. */\ninterface EntrypointsApp {\n  entrypoints: { ofKind(kind: string): Array<{ meta: unknown }> };\n}\n\n/** @internal — prepare per-DO resources before user lifecycle hooks can invalidate. */\nexport function initializeDoLiveResources(container: Container, ctx: DoStateLike): void {\n  if (container.has(LIVE_CURSOR_LOG)) {\n    const log = container.resolve(LIVE_CURSOR_LOG);\n    if (log instanceof DoCursorLog) {\n      const sql = ctx.storage?.sql;\n      if (!sql) {\n        throw new Error(\n          'DoCursorLog requires a SQLite-backed Durable Object: add this class to ' +\n            \"wrangler's `migrations[].new_sqlite_classes`. Falling back is not possible — \" +\n            'either enable SQLite or drop the `log: () => durableObjectCursorLog()` option ' +\n            '(snapshot-on-reconnect semantics).',\n        );\n      }\n      log._initialize(sql);\n    }\n  }\n\n  if (container.has(LIVE_DRIVER)) {\n    const driver = container.resolve(LIVE_DRIVER);\n    if (driver instanceof CfLiveDriver) driver._setLocalMode();\n  }\n}\n\n/**\n * DO-side wiring after lifecycle, called from `buildDoRuntime`: replay every hibernation-persisted\n * subscription into the (fresh) engine so an eviction is invisible to\n * subscribers. Returns the engine for the `invalidate` RPC, or undefined when\n * the app doesn't use LiveModule.\n */\nexport function initDoLive(app: EntrypointsApp, ctx: DoStateLike): LiveEngine | undefined {\n  const entry = app.entrypoints.ofKind('live')[0];\n  if (!entry) return undefined;\n  if (typeof entry.meta !== 'object' || entry.meta === null || !('engine' in entry.meta)) {\n    throw new Error('Invalid live entrypoint metadata.');\n  }\n  const engine = entry.meta.engine;\n  if (!(engine instanceof LiveEngine)) throw new Error('Invalid live entrypoint engine.');\n\n  // Wake-time replay: subscriptions ride the hibernation attachments.\n  for (const ws of ctx.getWebSockets()) {\n    const client = new CfWsClient(ctx, ws);\n    for (const record of readPersistedLiveSubscriptions(client)) {\n      engine.restoreSubscription(client.path, client, record);\n    }\n  }\n\n  return engine;\n}\n\n/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */\nexport function durableObjectCursorLog(maxRows?: number): DoCursorLog {\n  return new DoCursorLog(maxRows);\n}\n\n/**\n * Invalidate live tags in a room from a Worker (controller / cron / queue\n * consumer) — the live sibling of `broadcastToRoom`. Returns the room log\n * scope's commit stamp for `Vela-Commit-Cursor` stamping.\n */\nexport async function liveInvalidateToRoom(\n  ns: LiveNamespace,\n  gatewayPath: string,\n  room: string,\n  tags: string[],\n): Promise<CommitStamp | undefined> {\n  const stub = ns.get(roomToDurableId(ns, gatewayPath, room));\n  return stub.invalidate({ room, tags });\n}\n","const encoder = new TextEncoder();\nexport const MAX_NONCE_BYTES = 512;\nexport function isCanonicalBoundedText(value: unknown, maxBytes: number): value is string {\n  if (typeof value !== 'string') return false;\n  for (const character of value) {\n    const codePoint = character.codePointAt(0);\n    if (\n      codePoint !== undefined &&\n      (codePoint <= 0x1f || codePoint === 0x7f || (codePoint >= 0xd800 && codePoint <= 0xdfff))\n    ) {\n      return false;\n    }\n  }\n  return value.length > 0 && value === value.trim() && encoder.encode(value).byteLength <= maxBytes;\n}\n\nexport function isValidExpiry(\n  expEpochSeconds: unknown,\n  nowEpochSeconds: number,\n): expEpochSeconds is number {\n  return (\n    typeof expEpochSeconds === 'number' &&\n    Number.isSafeInteger(expEpochSeconds) &&\n    expEpochSeconds > 0 &&\n    expEpochSeconds >= nowEpochSeconds\n  );\n}\n"],"mappings":"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"}

package/dist/nonce.durable-object-Df3_42Sy.d.ts

@@ -0,0 +1,141 @@
+import { Type } from "@velajs/vela";
+import { DurableObject } from "cloudflare:workers";
+//#region src/root-module.d.ts
+/** A static module, or a module graph built from this Worker's native environment. */
+type CloudflareRoot<T extends object> = Type | {
+  create(env: T): Type;
+};
+//#endregion
+//#region src/websocket/do-pitr.d.ts
+/**
+ * Durable Object point-in-time recovery (PITR) — thin, testable wrappers over a
+ * SQLite-backed DO's native bookmark API. A SQLite Durable Object exposes three
+ * storage methods (last-30-days PITR):
+ *
+ *   - `getCurrentBookmark()` — an opaque bookmark for the storage's current state.
+ *   - `getBookmarkForTime(t)` — the bookmark closest to a wall-clock instant.
+ *   - `onNextSessionRestoreBookmark(b)` — arm a restore to bookmark `b`; the DO
+ *     restores to it the next time it starts a session, and the call RETURNS a
+ *     bookmark for the state JUST BEFORE the restore (the undo handle).
+ *
+ * These methods are ABSENT on a non-SQLite DO (key-value storage) and in some
+ * local-dev runtimes, so this module models storage structurally with all three
+ * methods OPTIONAL and degrades to a typed {@link DoPitrUnavailableError} (a
+ * `code: 'PITR_UNAVAILABLE'`, HTTP 409 error) rather than an
+ * `undefined is not a function` TypeError when a needed method is missing.
+ *
+ * Neither wrapper aborts the DO — `armDoPitr` only ARMS the restore and returns
+ * the undo bookmark; the caller (the WS-DO RPC method) decides whether to
+ * `ctx.abort()` to apply it immediately vs. on the next natural restart.
+ *
+ * This file is `cloudflare:workers`-free and pulls in NOTHING from `@velajs/vela`
+ * or `@velajs/studio` — it is the raw capability the studio `TimeTravelPort`
+ * wraps. Dependency direction is one-way: studio → cloudflare, never the reverse.
+ */
+/**
+ * The subset of `DurableObjectStorage` this module touches, with every method
+ * OPTIONAL so it structurally models a non-SQLite DO whose storage has none of
+ * them. A real `DurableObjectStorage` (whose methods are required) is assignable
+ * to this shape.
+ */
+interface DoPitrStorage {
+  getCurrentBookmark?(): Promise<string>;
+  getBookmarkForTime?(timestamp: number | Date): Promise<string>;
+  onNextSessionRestoreBookmark?(bookmark: string): Promise<string>;
+}
+/** A read of a DO's current bookmark (+ the by-time bookmark when a time is given). */
+interface DoPitrBookmarkRead {
+  /** The bookmark for the DO storage's current state. */
+  current: string;
+  /** The bookmark closest to the requested time (only when `time` was passed). */
+  forTime?: string;
+}
+/** Arming input for {@link armDoPitr}: a target (bookmark WINS over time) + restart intent. */
+interface DoPitrArmOptions {
+  /** An explicit target bookmark. Takes precedence over `time`. */
+  bookmark?: string;
+  /** A wall-clock target (epoch ms, ISO string, or Date), resolved to a bookmark. */
+  time?: number | string | Date;
+  /** Caller intent to restart-now; recorded on the result. `armDoPitr` never aborts. */
+  restart?: boolean;
+}
+/** The result of arming a PITR restore (before any restart is applied). */
+interface DoPitrArmResult {
+  /** The bookmark the restore is armed to. */
+  restoredTo: string;
+  /** The bookmark for the pre-restore state — restore to this to undo. */
+  undoBookmark: string;
+  /** Whether a restart-now was requested (the RPC layer performs the actual abort). */
+  restarted: boolean;
+}
+/** The RPC surface a PITR-capable Vela WebSocket DO stub exposes to a Worker. */
+interface VelaDoPitrRpc {
+  pitrCurrentBookmark(): Promise<DoPitrBookmarkRead>;
+  pitrBookmarkForTime(time: number | string): Promise<DoPitrBookmarkRead>;
+  pitrArmRestore(opts: DoPitrArmOptions): Promise<DoPitrArmResult>;
+}
+/** Structural view of a DO id (avoids depending on `@cloudflare/workers-types` downstream). */
+interface DoPitrId {
+  toString(): string;
+  readonly name?: string | null;
+}
+/**
+ * Structural view of a DO namespace binding whose stubs speak the PITR RPC. A
+ * downstream (the studio `@velajs/studio/cloudflare` port) types the app's
+ * namespace binding as this shape to reach the PITR methods without importing
+ * `@cloudflare/workers-types`.
+ */
+interface DoPitrNamespace {
+  idFromName(name: string): DoPitrId;
+  get(id: DoPitrId): VelaDoPitrRpc;
+}
+/**
+ * Thrown when a DO's storage lacks the SQLite bookmark API (non-SQLite DO, or a
+ * local runtime without PITR). Carries a stable `code` + HTTP 409 `status`, and
+ * a recognizable `name`/message so the studio port can map it to
+ * `TIMETRAVEL_UNAVAILABLE` even after the error crosses the Worker→DO RPC hop
+ * (which preserves `name` + `message`, not arbitrary own-properties).
+ */
+declare class DoPitrUnavailableError extends Error {
+  readonly code = "PITR_UNAVAILABLE";
+  readonly status = 409;
+  constructor(message?: string);
+}
+/**
+ * True when `error` signals DO PITR unavailability. Robust across the Worker→DO
+ * RPC hop: checks the `code` own-property (same process) AND the `name` / message
+ * sentinel (survive RPC serialization) so a downstream can classify it either way.
+ */
+declare function isDoPitrUnavailable(error: unknown): boolean;
+/**
+ * Read a DO's current bookmark, and — when `time` is given — the bookmark closest
+ * to that instant. Throws {@link DoPitrUnavailableError} when a needed method is
+ * absent, never `undefined is not a function`.
+ */
+declare function readDoPitrBookmark(storage: DoPitrStorage, time?: number | string | Date): Promise<DoPitrBookmarkRead>;
+/**
+ * Arm a PITR restore. Resolves the target (an explicit `bookmark` WINS over
+ * `time`), arms it via `onNextSessionRestoreBookmark`, and returns the undo
+ * bookmark the DO reports for the pre-restore state. Does NOT abort — the caller
+ * decides whether to restart now. Throws {@link DoPitrUnavailableError} when the
+ * arming API (or the by-time resolver a `time` target needs) is absent.
+ */
+declare function armDoPitr(storage: DoPitrStorage, opts: DoPitrArmOptions): Promise<DoPitrArmResult>;
+//#endregion
+//#region src/nonce/nonce.durable-object.d.ts
+/**
+ * SQLite Durable Object that atomically consumes nonces.
+ *
+ * Export this class from the Worker entry and register it through a Wrangler
+ * `new_sqlite_classes` migration. `INSERT ... ON CONFLICT DO NOTHING RETURNING`
+ * is the single-use decision; all SQL runs synchronously before the RPC method
+ * yields, and the nonce primary key is the final concurrency boundary.
+ */
+declare class VelaNonceDurableObject extends DurableObject<Record<string, unknown>> {
+  private sql?;
+  constructor(ctx: DurableObjectState, env: Record<string, unknown>);
+  claim(nonce: string, expEpochSeconds: number): Promise<boolean>;
+}
+//#endregion
+export { DoPitrId as a, DoPitrUnavailableError as c, isDoPitrUnavailable as d, readDoPitrBookmark as f, DoPitrBookmarkRead as i, VelaDoPitrRpc as l, DoPitrArmOptions as n, DoPitrNamespace as o, CloudflareRoot as p, DoPitrArmResult as r, DoPitrStorage as s, VelaNonceDurableObject as t, armDoPitr as u };
+//# sourceMappingURL=nonce.durable-object-Df3_42Sy.d.ts.map

package/package.json

@@ -1,73 +1,95 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.10.0",
+  "version": "2.0.0",
   "description": "Cloudflare Workers integration for Vela framework",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "sideEffects": false,
   "keywords": [
-    "vela",
     "cloudflare",
     "cloudflare-workers",
-    "kv",
     "d1",
-    "r2",
-    "queues",
+    "decorators",
     "edge",
     "framework",
-    "decorators"
+    "kv",
+    "queues",
+    "r2",
+    "vela"
   ],
-  "author": "ksh",
+  "homepage": "https://github.com/velajs/vela/tree/main/cloudflare#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/vela/issues"
+  },
   "license": "MIT",
+  "author": "ksh",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/velajs/cloudflare.git"
+    "url": "git+https://github.com/velajs/vela.git",
+    "directory": "cloudflare"
   },
-  "homepage": "https://github.com/velajs/cloudflare#readme",
-  "bugs": {
-    "url": "https://github.com/velajs/cloudflare/issues"
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./durable-objects": {
+      "types": "./dist/durable-objects.d.ts",
+      "import": "./dist/durable-objects.js"
+    }
   },
-  "engines": {
-    "node": ">=20"
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@changesets/cli": "2.31.0",
+    "@cloudflare/vitest-plugin": "1.1.13",
+    "@cloudflare/workers-types": "5.20260920.1",
+    "@swc/core": "1.15.43",
+    "hono": "4.13.8",
+    "oxfmt": "0.58.0",
+    "oxlint": "1.73.0",
+    "publint": "0.3.21",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "unplugin-swc": "1.5.9",
+    "vitest": "4.1.10",
+    "zod": "^3.25.76",
+    "@velajs/feature-flags": "2.0.0",
+    "@velajs/vela": "2.0.0"
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/feature-flags": "^0.1.0",
-    "@velajs/vela": ">=1.17.0",
-    "hono": ">=4"
+    "hono": ">=4",
+    "@velajs/feature-flags": "^2.0.0",
+    "@velajs/vela": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@velajs/feature-flags": {
       "optional": true
     }
   },
-  "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260624.1",
-    "@swc/cli": "^0.8.1",
-    "@swc/core": "^1.15.43",
-    "@velajs/feature-flags": "^0.1.0",
-    "@velajs/vela": "^1.17.0",
-    "hono": "^4.12.27",
-    "typescript": "^6.0.3",
-    "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.9"
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "build": "tsdown",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "test:workers": "vitest run --config vitest.config.workers.ts",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "publint": "publint",
+    "attw": "attw --pack . --profile esm-only",
+    "verify": "pnpm lint && pnpm format:check && pnpm build && pnpm typecheck && pnpm test && pnpm test:workers && pnpm publint && pnpm attw"
   }
 }

package/dist/binding-ref.d.ts

@@ -1,8 +0,0 @@
-export declare class BindingRef<T = unknown> {
-    readonly bindingName: string;
-    private _value;
-    constructor(bindingName: string);
-    get value(): T;
-    /** @internal — called by createCloudflareApp middleware */
-    _initialize(value: T): void;
-}

package/dist/binding-ref.js

@@ -1,19 +0,0 @@
-// Mutable holder for a Cloudflare binding value. Created by each module's
-// forRoot() and populated by createCloudflareApp's one-time middleware on
-// the first request. Services access the binding lazily via .value.
-export class BindingRef {
-    bindingName;
-    _value;
-    constructor(bindingName){
-        this.bindingName = bindingName;
-    }
-    get value() {
-        if (this._value === undefined) {
-            throw new Error(`Cloudflare binding '${this.bindingName}' not initialized. ` + `Ensure createCloudflareApp() is used and a request has been made.`);
-        }
-        return this._value;
-    }
-    /** @internal — called by createCloudflareApp middleware */ _initialize(value) {
-        this._value = value;
-    }
-}

package/dist/cloudflare-application.d.ts

@@ -1,125 +0,0 @@
-import type { Hono } from 'hono';
-import { type VelaApplication } from '@velajs/vela';
-import { type WsGatewayRoute } from './websocket/websocket-routing';
-import type { CloudflareEnv } from './types';
-/**
- * Options accepted by {@link CloudflareApplication.mountOpenApi}.
- *
- * Re-exposes vela's `MountOpenApiOptions` type — derived structurally from
- * the underlying `VelaApplication.mountOpenApi` signature so consumers don't
- * have to reach into vela's internal subpaths to type the argument.
- */
-export type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];
-/**
- * Wraps VelaApplication with Cloudflare-specific handlers:
- * - `fetch` — HTTP request handler (from Hono)
- * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
- *                 AND vela's own `@Cron()` jobs)
- * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
- * - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
- *                    the underlying Hono app
- *
- * @example
- * ```ts
- * const app = await createCloudflareApp(AppModule);
- * export default {
- *   fetch: app.fetch,
- *   scheduled: app.scheduled.bind(app),
- *   queue: app.queue.bind(app),
- * };
- * ```
- *
- * @example
- * ```ts
- * // Serve OpenAPI docs alongside your routes
- * const app = await createCloudflareApp(AppModule);
- * const document = createOpenApiDocument(AppModule);
- * app.mountOpenApi({ document, ui: 'scalar' });
- * // GET /openapi.json -> JSON document
- * // GET /scalar       -> Scalar UI (loads from CDN)
- * ```
- */
-export declare class CloudflareApplication {
-    private app;
-    private wsGatewayRoutes;
-    constructor(app: VelaApplication);
-    get fetch(): Hono['fetch'];
-    getHonoApp(): Hono;
-    /**
-     * Resolve a provider from the application's DI container (delegates to
-     * `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
-     * to use inside `createCloudflareApp({ middleware: [...] })` request middleware,
-     * which runs outside the DI request pipeline.
-     *
-     * @example
-     * ```ts
-     * const app = await createCloudflareApp(AppModule);
-     * const auth = app.get<BetterAuthService>(BetterAuthService);
-     * ```
-     */
-    get<T>(token: Parameters<VelaApplication['get']>[0]): T;
-    /**
-     * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
-     * underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
-     * so the JSON endpoint defaults to `/openapi.json` and the Scalar UI (when
-     * opted in) defaults to `/scalar`. Edge-safe — the UI HTML loads Scalar from
-     * a CDN at runtime, nothing is bundled server-side.
-     *
-     * @example
-     * ```ts
-     * import { createOpenApiDocument } from '@velajs/vela';
-     *
-     * const app = await createCloudflareApp(AppModule);
-     * const document = createOpenApiDocument(AppModule, {
-     *   info: { title: 'My API', version: '1.0.0' },
-     * });
-     * app.mountOpenApi({ document, ui: 'scalar' });
-     * // GET /openapi.json -> { openapi: '3.1.0', ... }
-     * // GET /scalar       -> Scalar UI HTML
-     * ```
-     */
-    mountOpenApi(options: MountOpenApiOptions): this;
-    /**
-     * @internal — scans instances for `@WebSocketGateway({ path, binding })`
-     * upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
-     * come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
-     * kinds) at dispatch time.
-     */
-    scanInstances(instances: unknown[]): void;
-    /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
-    getWsGatewayRoutes(): WsGatewayRoute[];
-    /**
-     * Handle Cloudflare scheduled (cron) events.
-     * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
-     * handlers read from `app.entrypoints`; each handler runs inside a fresh
-     * request-scoped child (request-scoped providers rebuild per tick).
-     */
-    scheduled(event: {
-        cron: string;
-        scheduledTime?: number;
-    }, env: CloudflareEnv, ctx: {
-        waitUntil: (promise: Promise<unknown>) => void;
-    }): Promise<void>;
-    /**
-     * Run one entrypoint handler inside a fresh request scope, through the
-     * shared guard → interceptor pipeline (components declared with
-     * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
-     * method). HTTP-global components deliberately do NOT apply — an HTTP auth
-     * guard has no business rejecting a queue batch. Unclaimed errors rethrow
-     * so the platform's retry semantics stay intact.
-     */
-    private dispatchEntrypoint;
-    /**
-     * Handle Cloudflare Queue consumer events.
-     * Matches the batch queue name to `@QueueConsumer()` handlers read from
-     * `app.entrypoints`; each batch is processed inside a fresh request-scoped
-     * child (request-scoped providers rebuild per batch — no boot-time captives).
-     */
-    queue(batch: {
-        queue: string;
-        messages: unknown[];
-    }, env: CloudflareEnv, ctx: {
-        waitUntil: (promise: Promise<unknown>) => void;
-    }): Promise<void>;
-    close(signal?: string): Promise<void>;
-}