@nimbus-sh/worker 0.1.0

package/dist/real-vite-bundle.generated.js

@@ -0,0 +1,53 @@
+/**
+ * real-vite-bundle.generated.ts — AUTO-GENERATED by scripts/bundle-real-vite.mjs
+ * DO NOT EDIT.
+ *
+ * Bundled Vite 6.4.2 with native-binding stubs (rolldown,
+ * lightningcss, etc.). Consumed by src/cirrus-real.ts at facet spawn time.
+ *
+ * [sdk-phase-1] The large strings (REAL_VITE_BUNDLE, ROLLUP_WASM_BASE64)
+ * now ship via the ASSETS binding rather than inline. Use the async
+ * getters below. Constants + browser-runtime mjs files remain inline
+ * since they're small enough to not warrant a network round-trip.
+ */
+import { loadAssetText, loadAssetBytes } from './runtime/assets-loader.js';
+export const REAL_VITE_VERSION = "6.4.2";
+/** Asset path for the bundled Vite source. Use {@link getRealViteBundle}. */
+export const REAL_VITE_BUNDLE_PATH = "/_assets/real-vite-bundle.js";
+/** Asset path for the rollup wasm bytes. Use {@link getRollupWasmBase64}. */
+export const ROLLUP_WASM_PATH = "/_assets/rollup.wasm";
+/**
+ * Fetch the bundled Vite JS from the ASSETS binding. Cached per-isolate.
+ *
+ * @param env Object exposing the `ASSETS` binding (Fetcher).
+ * @returns The Vite bundle as a UTF-8 string.
+ * @throws {NimbusAssetLoadError} when the binding is missing or fetch fails.
+ */
+export function getRealViteBundle(env) {
+    return loadAssetText(env.ASSETS, REAL_VITE_BUNDLE_PATH);
+}
+/**
+ * Fetch the rollup wasm bytes + base64-encode for the synthetic-fs
+ * pre-seed. Cached per-isolate; the base64 string ends up the same on
+ * every call.
+ *
+ * @returns base64-encoded rollup wasm bytes.
+ */
+export async function getRollupWasmBase64(env) {
+    const bytes = await loadAssetBytes(env.ASSETS, ROLLUP_WASM_PATH);
+    // btoa(String.fromCharCode(...bytes)) blows the stack on 1 MB inputs.
+    // Build the binary string in 8 KiB chunks.
+    let binary = '';
+    const CHUNK = 8192;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode.apply(null, bytes.subarray(i, Math.min(i + CHUNK, bytes.length)));
+    }
+    return btoa(binary);
+}
+/**
+ * Vite's browser-side HMR runtime. Served to the browser at
+ * /@vite/client and /@vite/env during dev. Unlike the server
+ * bundle, these are tiny ESM files that run in-page — keep inline.
+ */
+export const VITE_CLIENT_MJS = "import '@vite/env';\n\nclass HMRContext {\n  constructor(hmrClient, ownerPath) {\n    this.hmrClient = hmrClient;\n    this.ownerPath = ownerPath;\n    if (!hmrClient.dataMap.has(ownerPath)) {\n      hmrClient.dataMap.set(ownerPath, {});\n    }\n    const mod = hmrClient.hotModulesMap.get(ownerPath);\n    if (mod) {\n      mod.callbacks = [];\n    }\n    const staleListeners = hmrClient.ctxToListenersMap.get(ownerPath);\n    if (staleListeners) {\n      for (const [event, staleFns] of staleListeners) {\n        const listeners = hmrClient.customListenersMap.get(event);\n        if (listeners) {\n          hmrClient.customListenersMap.set(\n            event,\n            listeners.filter((l) => !staleFns.includes(l))\n          );\n        }\n      }\n    }\n    this.newListeners = /* @__PURE__ */ new Map();\n    hmrClient.ctxToListenersMap.set(ownerPath, this.newListeners);\n  }\n  get data() {\n    return this.hmrClient.dataMap.get(this.ownerPath);\n  }\n  accept(deps, callback) {\n    if (typeof deps === \"function\" || !deps) {\n      this.acceptDeps([this.ownerPath], ([mod]) => deps?.(mod));\n    } else if (typeof deps === \"string\") {\n      this.acceptDeps([deps], ([mod]) => callback?.(mod));\n    } else if (Array.isArray(deps)) {\n      this.acceptDeps(deps, callback);\n    } else {\n      throw new Error(`invalid hot.accept() usage.`);\n    }\n  }\n  // export names (first arg) are irrelevant on the client side, they're\n  // extracted in the server for propagation\n  acceptExports(_, callback) {\n    this.acceptDeps([this.ownerPath], ([mod]) => callback?.(mod));\n  }\n  dispose(cb) {\n    this.hmrClient.disposeMap.set(this.ownerPath, cb);\n  }\n  prune(cb) {\n    this.hmrClient.pruneMap.set(this.ownerPath, cb);\n  }\n  // Kept for backward compatibility (#11036)\n  // eslint-disable-next-line @typescript-eslint/no-empty-function\n  decline() {\n  }\n  invalidate(message) {\n    const firstInvalidatedBy = this.hmrClient.currentFirstInvalidatedBy ?? this.ownerPath;\n    this.hmrClient.notifyListeners(\"vite:invalidate\", {\n      path: this.ownerPath,\n      message,\n      firstInvalidatedBy\n    });\n    this.send(\"vite:invalidate\", {\n      path: this.ownerPath,\n      message,\n      firstInvalidatedBy\n    });\n    this.hmrClient.logger.debug(\n      `invalidate ${this.ownerPath}${message ? `: ${message}` : \"\"}`\n    );\n  }\n  on(event, cb) {\n    const addToMap = (map) => {\n      const existing = map.get(event) || [];\n      existing.push(cb);\n      map.set(event, existing);\n    };\n    addToMap(this.hmrClient.customListenersMap);\n    addToMap(this.newListeners);\n  }\n  off(event, cb) {\n    const removeFromMap = (map) => {\n      const existing = map.get(event);\n      if (existing === void 0) {\n        return;\n      }\n      const pruned = existing.filter((l) => l !== cb);\n      if (pruned.length === 0) {\n        map.delete(event);\n        return;\n      }\n      map.set(event, pruned);\n    };\n    removeFromMap(this.hmrClient.customListenersMap);\n    removeFromMap(this.newListeners);\n  }\n  send(event, data) {\n    this.hmrClient.send({ type: \"custom\", event, data });\n  }\n  acceptDeps(deps, callback = () => {\n  }) {\n    const mod = this.hmrClient.hotModulesMap.get(this.ownerPath) || {\n      id: this.ownerPath,\n      callbacks: []\n    };\n    mod.callbacks.push({\n      deps,\n      fn: callback\n    });\n    this.hmrClient.hotModulesMap.set(this.ownerPath, mod);\n  }\n}\nclass HMRClient {\n  constructor(logger, transport, importUpdatedModule) {\n    this.logger = logger;\n    this.transport = transport;\n    this.importUpdatedModule = importUpdatedModule;\n    this.hotModulesMap = /* @__PURE__ */ new Map();\n    this.disposeMap = /* @__PURE__ */ new Map();\n    this.pruneMap = /* @__PURE__ */ new Map();\n    this.dataMap = /* @__PURE__ */ new Map();\n    this.customListenersMap = /* @__PURE__ */ new Map();\n    this.ctxToListenersMap = /* @__PURE__ */ new Map();\n    this.updateQueue = [];\n    this.pendingUpdateQueue = false;\n  }\n  async notifyListeners(event, data) {\n    const cbs = this.customListenersMap.get(event);\n    if (cbs) {\n      await Promise.allSettled(cbs.map((cb) => cb(data)));\n    }\n  }\n  send(payload) {\n    this.transport.send(payload).catch((err) => {\n      this.logger.error(err);\n    });\n  }\n  clear() {\n    this.hotModulesMap.clear();\n    this.disposeMap.clear();\n    this.pruneMap.clear();\n    this.dataMap.clear();\n    this.customListenersMap.clear();\n    this.ctxToListenersMap.clear();\n  }\n  // After an HMR update, some modules are no longer imported on the page\n  // but they may have left behind side effects that need to be cleaned up\n  // (e.g. style injections)\n  async prunePaths(paths) {\n    await Promise.all(\n      paths.map((path) => {\n        const disposer = this.disposeMap.get(path);\n        if (disposer) return disposer(this.dataMap.get(path));\n      })\n    );\n    paths.forEach((path) => {\n      const fn = this.pruneMap.get(path);\n      if (fn) {\n        fn(this.dataMap.get(path));\n      }\n    });\n  }\n  warnFailedUpdate(err, path) {\n    if (!(err instanceof Error) || !err.message.includes(\"fetch\")) {\n      this.logger.error(err);\n    }\n    this.logger.error(\n      `Failed to reload ${path}. This could be due to syntax errors or importing non-existent modules. (see errors above)`\n    );\n  }\n  /**\n   * buffer multiple hot updates triggered by the same src change\n   * so that they are invoked in the same order they were sent.\n   * (otherwise the order may be inconsistent because of the http request round trip)\n   */\n  async queueUpdate(payload) {\n    this.updateQueue.push(this.fetchUpdate(payload));\n    if (!this.pendingUpdateQueue) {\n      this.pendingUpdateQueue = true;\n      await Promise.resolve();\n      this.pendingUpdateQueue = false;\n      const loading = [...this.updateQueue];\n      this.updateQueue = [];\n      (await Promise.all(loading)).forEach((fn) => fn && fn());\n    }\n  }\n  async fetchUpdate(update) {\n    const { path, acceptedPath, firstInvalidatedBy } = update;\n    const mod = this.hotModulesMap.get(path);\n    if (!mod) {\n      return;\n    }\n    let fetchedModule;\n    const isSelfUpdate = path === acceptedPath;\n    const qualifiedCallbacks = mod.callbacks.filter(\n      ({ deps }) => deps.includes(acceptedPath)\n    );\n    if (isSelfUpdate || qualifiedCallbacks.length > 0) {\n      const disposer = this.disposeMap.get(acceptedPath);\n      if (disposer) await disposer(this.dataMap.get(acceptedPath));\n      try {\n        fetchedModule = await this.importUpdatedModule(update);\n      } catch (e) {\n        this.warnFailedUpdate(e, acceptedPath);\n      }\n    }\n    return () => {\n      try {\n        this.currentFirstInvalidatedBy = firstInvalidatedBy;\n        for (const { deps, fn } of qualifiedCallbacks) {\n          fn(\n            deps.map(\n              (dep) => dep === acceptedPath ? fetchedModule : void 0\n            )\n          );\n        }\n        const loggedPath = isSelfUpdate ? path : `${acceptedPath} via ${path}`;\n        this.logger.debug(`hot updated: ${loggedPath}`);\n      } finally {\n        this.currentFirstInvalidatedBy = void 0;\n      }\n    };\n  }\n}\n\n/* @ts-self-types=\"./index.d.ts\" */\nlet urlAlphabet =\n  'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';\nlet nanoid = (size = 21) => {\n  let id = '';\n  let i = size | 0;\n  while (i--) {\n    id += urlAlphabet[(Math.random() * 64) | 0];\n  }\n  return id\n};\n\ntypeof process !== \"undefined\" && process.platform === \"win32\";\nfunction promiseWithResolvers() {\n  let resolve;\n  let reject;\n  const promise = new Promise((_resolve, _reject) => {\n    resolve = _resolve;\n    reject = _reject;\n  });\n  return { promise, resolve, reject };\n}\n\nfunction reviveInvokeError(e) {\n  const error = new Error(e.message || \"Unknown invoke error\");\n  Object.assign(error, e, {\n    // pass the whole error instead of just the stacktrace\n    // so that it gets formatted nicely with console.log\n    runnerError: new Error(\"RunnerError\")\n  });\n  return error;\n}\nconst createInvokeableTransport = (transport) => {\n  if (transport.invoke) {\n    return {\n      ...transport,\n      async invoke(name, data) {\n        const result = await transport.invoke({\n          type: \"custom\",\n          event: \"vite:invoke\",\n          data: {\n            id: \"send\",\n            name,\n            data\n          }\n        });\n        if (\"error\" in result) {\n          throw reviveInvokeError(result.error);\n        }\n        return result.result;\n      }\n    };\n  }\n  if (!transport.send || !transport.connect) {\n    throw new Error(\n      \"transport must implement send and connect when invoke is not implemented\"\n    );\n  }\n  const rpcPromises = /* @__PURE__ */ new Map();\n  return {\n    ...transport,\n    connect({ onMessage, onDisconnection }) {\n      return transport.connect({\n        onMessage(payload) {\n          if (payload.type === \"custom\" && payload.event === \"vite:invoke\") {\n            const data = payload.data;\n            if (data.id.startsWith(\"response:\")) {\n              const invokeId = data.id.slice(\"response:\".length);\n              const promise = rpcPromises.get(invokeId);\n              if (!promise) return;\n              if (promise.timeoutId) clearTimeout(promise.timeoutId);\n              rpcPromises.delete(invokeId);\n              const { error, result } = data.data;\n              if (error) {\n                promise.reject(error);\n              } else {\n                promise.resolve(result);\n              }\n              return;\n            }\n          }\n          onMessage(payload);\n        },\n        onDisconnection\n      });\n    },\n    disconnect() {\n      rpcPromises.forEach((promise) => {\n        promise.reject(\n          new Error(\n            `transport was disconnected, cannot call ${JSON.stringify(promise.name)}`\n          )\n        );\n      });\n      rpcPromises.clear();\n      return transport.disconnect?.();\n    },\n    send(data) {\n      return transport.send(data);\n    },\n    async invoke(name, data) {\n      const promiseId = nanoid();\n      const wrappedData = {\n        type: \"custom\",\n        event: \"vite:invoke\",\n        data: {\n          name,\n          id: `send:${promiseId}`,\n          data\n        }\n      };\n      const sendPromise = transport.send(wrappedData);\n      const { promise, resolve, reject } = promiseWithResolvers();\n      const timeout = transport.timeout ?? 6e4;\n      let timeoutId;\n      if (timeout > 0) {\n        timeoutId = setTimeout(() => {\n          rpcPromises.delete(promiseId);\n          reject(\n            new Error(\n              `transport invoke timed out after ${timeout}ms (data: ${JSON.stringify(wrappedData)})`\n            )\n          );\n        }, timeout);\n        timeoutId?.unref?.();\n      }\n      rpcPromises.set(promiseId, { resolve, reject, name, timeoutId });\n      if (sendPromise) {\n        sendPromise.catch((err) => {\n          clearTimeout(timeoutId);\n          rpcPromises.delete(promiseId);\n          reject(err);\n        });\n      }\n      try {\n        return await promise;\n      } catch (err) {\n        throw reviveInvokeError(err);\n      }\n    }\n  };\n};\nconst normalizeModuleRunnerTransport = (transport) => {\n  const invokeableTransport = createInvokeableTransport(transport);\n  let isConnected = !invokeableTransport.connect;\n  let connectingPromise;\n  return {\n    ...transport,\n    ...invokeableTransport.connect ? {\n      async connect(onMessage) {\n        if (isConnected) return;\n        if (connectingPromise) {\n          await connectingPromise;\n          return;\n        }\n        const maybePromise = invokeableTransport.connect({\n          onMessage: onMessage ?? (() => {\n          }),\n          onDisconnection() {\n            isConnected = false;\n          }\n        });\n        if (maybePromise) {\n          connectingPromise = maybePromise;\n          await connectingPromise;\n          connectingPromise = void 0;\n        }\n        isConnected = true;\n      }\n    } : {},\n    ...invokeableTransport.disconnect ? {\n      async disconnect() {\n        if (!isConnected) return;\n        if (connectingPromise) {\n          await connectingPromise;\n        }\n        isConnected = false;\n        await invokeableTransport.disconnect();\n      }\n    } : {},\n    async send(data) {\n      if (!invokeableTransport.send) return;\n      if (!isConnected) {\n        if (connectingPromise) {\n          await connectingPromise;\n        } else {\n          throw new Error(\"send was called before connect\");\n        }\n      }\n      await invokeableTransport.send(data);\n    },\n    async invoke(name, data) {\n      if (!isConnected) {\n        if (connectingPromise) {\n          await connectingPromise;\n        } else {\n          throw new Error(\"invoke was called before connect\");\n        }\n      }\n      return invokeableTransport.invoke(name, data);\n    }\n  };\n};\nconst createWebSocketModuleRunnerTransport = (options) => {\n  const pingInterval = options.pingInterval ?? 3e4;\n  let ws;\n  let pingIntervalId;\n  return {\n    async connect({ onMessage, onDisconnection }) {\n      const socket = options.createConnection();\n      socket.addEventListener(\"message\", async ({ data }) => {\n        onMessage(JSON.parse(data));\n      });\n      let isOpened = socket.readyState === socket.OPEN;\n      if (!isOpened) {\n        await new Promise((resolve, reject) => {\n          socket.addEventListener(\n            \"open\",\n            () => {\n              isOpened = true;\n              resolve();\n            },\n            { once: true }\n          );\n          socket.addEventListener(\"close\", async () => {\n            if (!isOpened) {\n              reject(new Error(\"WebSocket closed without opened.\"));\n              return;\n            }\n            onMessage({\n              type: \"custom\",\n              event: \"vite:ws:disconnect\",\n              data: { webSocket: socket }\n            });\n            onDisconnection();\n          });\n        });\n      }\n      onMessage({\n        type: \"custom\",\n        event: \"vite:ws:connect\",\n        data: { webSocket: socket }\n      });\n      ws = socket;\n      pingIntervalId = setInterval(() => {\n        if (socket.readyState === socket.OPEN) {\n          socket.send(JSON.stringify({ type: \"ping\" }));\n        }\n      }, pingInterval);\n    },\n    disconnect() {\n      clearInterval(pingIntervalId);\n      ws?.close();\n    },\n    send(data) {\n      ws.send(JSON.stringify(data));\n    }\n  };\n};\n\nfunction createHMRHandler(handler) {\n  const queue = new Queue();\n  return (payload) => queue.enqueue(() => handler(payload));\n}\nclass Queue {\n  constructor() {\n    this.queue = [];\n    this.pending = false;\n  }\n  enqueue(promise) {\n    return new Promise((resolve, reject) => {\n      this.queue.push({\n        promise,\n        resolve,\n        reject\n      });\n      this.dequeue();\n    });\n  }\n  dequeue() {\n    if (this.pending) {\n      return false;\n    }\n    const item = this.queue.shift();\n    if (!item) {\n      return false;\n    }\n    this.pending = true;\n    item.promise().then(item.resolve).catch(item.reject).finally(() => {\n      this.pending = false;\n      this.dequeue();\n    });\n    return true;\n  }\n}\n\nconst hmrConfigName = __HMR_CONFIG_NAME__;\nconst base$1 = __BASE__ || \"/\";\nfunction h(e, attrs = {}, ...children) {\n  const elem = document.createElement(e);\n  for (const [k, v] of Object.entries(attrs)) {\n    elem.setAttribute(k, v);\n  }\n  elem.append(...children);\n  return elem;\n}\nconst templateStyle = (\n  /*css*/\n  `\n:host {\n  position: fixed;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  z-index: 99999;\n  --monospace: 'SFMono-Regular', Consolas,\n  'Liberation Mono', Menlo, Courier, monospace;\n  --red: #ff5555;\n  --yellow: #e2aa53;\n  --purple: #cfa4ff;\n  --cyan: #2dd9da;\n  --dim: #c9c9c9;\n\n  --window-background: #181818;\n  --window-color: #d8d8d8;\n}\n\n.backdrop {\n  position: fixed;\n  z-index: 99999;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  overflow-y: scroll;\n  margin: 0;\n  background: rgba(0, 0, 0, 0.66);\n}\n\n.window {\n  font-family: var(--monospace);\n  line-height: 1.5;\n  max-width: 80vw;\n  color: var(--window-color);\n  box-sizing: border-box;\n  margin: 30px auto;\n  padding: 2.5vh 4vw;\n  position: relative;\n  background: var(--window-background);\n  border-radius: 6px 6px 8px 8px;\n  box-shadow: 0 19px 38px rgba(0,0,0,0.30), 0 15px 12px rgba(0,0,0,0.22);\n  overflow: hidden;\n  border-top: 8px solid var(--red);\n  direction: ltr;\n  text-align: left;\n}\n\npre {\n  font-family: var(--monospace);\n  font-size: 16px;\n  margin-top: 0;\n  margin-bottom: 1em;\n  overflow-x: scroll;\n  scrollbar-width: none;\n}\n\npre::-webkit-scrollbar {\n  display: none;\n}\n\npre.frame::-webkit-scrollbar {\n  display: block;\n  height: 5px;\n}\n\npre.frame::-webkit-scrollbar-thumb {\n  background: #999;\n  border-radius: 5px;\n}\n\npre.frame {\n  scrollbar-width: thin;\n}\n\n.message {\n  line-height: 1.3;\n  font-weight: 600;\n  white-space: pre-wrap;\n}\n\n.message-body {\n  color: var(--red);\n}\n\n.plugin {\n  color: var(--purple);\n}\n\n.file {\n  color: var(--cyan);\n  margin-bottom: 0;\n  white-space: pre-wrap;\n  word-break: break-all;\n}\n\n.frame {\n  color: var(--yellow);\n}\n\n.stack {\n  font-size: 13px;\n  color: var(--dim);\n}\n\n.tip {\n  font-size: 13px;\n  color: #999;\n  border-top: 1px dotted #999;\n  padding-top: 13px;\n  line-height: 1.8;\n}\n\ncode {\n  font-size: 13px;\n  font-family: var(--monospace);\n  color: var(--yellow);\n}\n\n.file-link {\n  text-decoration: underline;\n  cursor: pointer;\n}\n\nkbd {\n  line-height: 1.5;\n  font-family: ui-monospace, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace;\n  font-size: 0.75rem;\n  font-weight: 700;\n  background-color: rgb(38, 40, 44);\n  color: rgb(166, 167, 171);\n  padding: 0.15rem 0.3rem;\n  border-radius: 0.25rem;\n  border-width: 0.0625rem 0.0625rem 0.1875rem;\n  border-style: solid;\n  border-color: rgb(54, 57, 64);\n  border-image: initial;\n}\n`\n);\nconst createTemplate = () => h(\n  \"div\",\n  { class: \"backdrop\", part: \"backdrop\" },\n  h(\n    \"div\",\n    { class: \"window\", part: \"window\" },\n    h(\n      \"pre\",\n      { class: \"message\", part: \"message\" },\n      h(\"span\", { class: \"plugin\", part: \"plugin\" }),\n      h(\"span\", { class: \"message-body\", part: \"message-body\" })\n    ),\n    h(\"pre\", { class: \"file\", part: \"file\" }),\n    h(\"pre\", { class: \"frame\", part: \"frame\" }),\n    h(\"pre\", { class: \"stack\", part: \"stack\" }),\n    h(\n      \"div\",\n      { class: \"tip\", part: \"tip\" },\n      \"Click outside, press \",\n      h(\"kbd\", {}, \"Esc\"),\n      \" key, or fix the code to dismiss.\",\n      h(\"br\"),\n      \"You can also disable this overlay by setting \",\n      h(\"code\", { part: \"config-option-name\" }, \"server.hmr.overlay\"),\n      \" to \",\n      h(\"code\", { part: \"config-option-value\" }, \"false\"),\n      \" in \",\n      h(\"code\", { part: \"config-file-name\" }, hmrConfigName),\n      \".\"\n    )\n  ),\n  h(\"style\", {}, templateStyle)\n);\nconst fileRE = /(?:[a-zA-Z]:\\\\|\\/).*?:\\d+:\\d+/g;\nconst codeframeRE = /^(?:>?\\s*\\d+\\s+\\|.*|\\s+\\|\\s*\\^.*)\\r?\\n/gm;\nconst { HTMLElement = class {\n} } = globalThis;\nclass ErrorOverlay extends HTMLElement {\n  constructor(err, links = true) {\n    super();\n    this.root = this.attachShadow({ mode: \"open\" });\n    this.root.appendChild(createTemplate());\n    codeframeRE.lastIndex = 0;\n    const hasFrame = err.frame && codeframeRE.test(err.frame);\n    const message = hasFrame ? err.message.replace(codeframeRE, \"\") : err.message;\n    if (err.plugin) {\n      this.text(\".plugin\", `[plugin:${err.plugin}] `);\n    }\n    this.text(\".message-body\", message.trim());\n    const [file] = (err.loc?.file || err.id || \"unknown file\").split(`?`);\n    if (err.loc) {\n      this.text(\".file\", `${file}:${err.loc.line}:${err.loc.column}`, links);\n    } else if (err.id) {\n      this.text(\".file\", file);\n    }\n    if (hasFrame) {\n      this.text(\".frame\", err.frame.trim());\n    }\n    this.text(\".stack\", err.stack, links);\n    this.root.querySelector(\".window\").addEventListener(\"click\", (e) => {\n      e.stopPropagation();\n    });\n    this.addEventListener(\"click\", () => {\n      this.close();\n    });\n    this.closeOnEsc = (e) => {\n      if (e.key === \"Escape\" || e.code === \"Escape\") {\n        this.close();\n      }\n    };\n    document.addEventListener(\"keydown\", this.closeOnEsc);\n  }\n  text(selector, text, linkFiles = false) {\n    const el = this.root.querySelector(selector);\n    if (!linkFiles) {\n      el.textContent = text;\n    } else {\n      let curIndex = 0;\n      let match;\n      fileRE.lastIndex = 0;\n      while (match = fileRE.exec(text)) {\n        const { 0: file, index } = match;\n        const frag = text.slice(curIndex, index);\n        el.appendChild(document.createTextNode(frag));\n        const link = document.createElement(\"a\");\n        link.textContent = file;\n        link.className = \"file-link\";\n        link.onclick = () => {\n          fetch(\n            new URL(\n              `${base$1}__open-in-editor?file=${encodeURIComponent(file)}`,\n              import.meta.url\n            )\n          );\n        };\n        el.appendChild(link);\n        curIndex += frag.length + file.length;\n      }\n    }\n  }\n  close() {\n    this.parentNode?.removeChild(this);\n    document.removeEventListener(\"keydown\", this.closeOnEsc);\n  }\n}\nconst overlayId = \"vite-error-overlay\";\nconst { customElements } = globalThis;\nif (customElements && !customElements.get(overlayId)) {\n  customElements.define(overlayId, ErrorOverlay);\n}\n\nconsole.debug(\"[vite] connecting...\");\nconst importMetaUrl = new URL(import.meta.url);\nconst serverHost = __SERVER_HOST__;\nconst socketProtocol = __HMR_PROTOCOL__ || (importMetaUrl.protocol === \"https:\" ? \"wss\" : \"ws\");\nconst hmrPort = __HMR_PORT__;\nconst socketHost = `${__HMR_HOSTNAME__ || importMetaUrl.hostname}:${hmrPort || importMetaUrl.port}${__HMR_BASE__}`;\nconst directSocketHost = __HMR_DIRECT_TARGET__;\nconst base = __BASE__ || \"/\";\nconst hmrTimeout = __HMR_TIMEOUT__;\nconst wsToken = __WS_TOKEN__;\nconst transport = normalizeModuleRunnerTransport(\n  (() => {\n    let wsTransport = createWebSocketModuleRunnerTransport({\n      createConnection: () => new WebSocket(\n        `${socketProtocol}://${socketHost}?token=${wsToken}`,\n        \"vite-hmr\"\n      ),\n      pingInterval: hmrTimeout\n    });\n    return {\n      async connect(handlers) {\n        try {\n          await wsTransport.connect(handlers);\n        } catch (e) {\n          if (!hmrPort) {\n            wsTransport = createWebSocketModuleRunnerTransport({\n              createConnection: () => new WebSocket(\n                `${socketProtocol}://${directSocketHost}?token=${wsToken}`,\n                \"vite-hmr\"\n              ),\n              pingInterval: hmrTimeout\n            });\n            try {\n              await wsTransport.connect(handlers);\n              console.info(\n                \"[vite] Direct websocket connection fallback. Check out https://vite.dev/config/server-options.html#server-hmr to remove the previous connection error.\"\n              );\n            } catch (e2) {\n              if (e2 instanceof Error && e2.message.includes(\"WebSocket closed without opened.\")) {\n                const currentScriptHostURL = new URL(import.meta.url);\n                const currentScriptHost = currentScriptHostURL.host + currentScriptHostURL.pathname.replace(/@vite\\/client$/, \"\");\n                console.error(\n                  `[vite] failed to connect to websocket.\nyour current setup:\n  (browser) ${currentScriptHost} <--[HTTP]--> ${serverHost} (server)\n  (browser) ${socketHost} <--[WebSocket (failing)]--> ${directSocketHost} (server)\nCheck out your Vite / network configuration and https://vite.dev/config/server-options.html#server-hmr .`\n                );\n              }\n            }\n            return;\n          }\n          console.error(`[vite] failed to connect to websocket (${e}). `);\n          throw e;\n        }\n      },\n      async disconnect() {\n        await wsTransport.disconnect();\n      },\n      send(data) {\n        wsTransport.send(data);\n      }\n    };\n  })()\n);\nlet willUnload = false;\nif (typeof window !== \"undefined\") {\n  window.addEventListener(\"beforeunload\", () => {\n    willUnload = true;\n  });\n}\nfunction cleanUrl(pathname) {\n  const url = new URL(pathname, \"http://vite.dev\");\n  url.searchParams.delete(\"direct\");\n  return url.pathname + url.search;\n}\nlet isFirstUpdate = true;\nconst outdatedLinkTags = /* @__PURE__ */ new WeakSet();\nconst debounceReload = (time) => {\n  let timer;\n  return () => {\n    if (timer) {\n      clearTimeout(timer);\n      timer = null;\n    }\n    timer = setTimeout(() => {\n      location.reload();\n    }, time);\n  };\n};\nconst pageReload = debounceReload(50);\nconst hmrClient = new HMRClient(\n  {\n    error: (err) => console.error(\"[vite]\", err),\n    debug: (...msg) => console.debug(\"[vite]\", ...msg)\n  },\n  transport,\n  async function importUpdatedModule({\n    acceptedPath,\n    timestamp,\n    explicitImportRequired,\n    isWithinCircularImport\n  }) {\n    const [acceptedPathWithoutQuery, query] = acceptedPath.split(`?`);\n    const importPromise = import(\n      /* @vite-ignore */\n      base + acceptedPathWithoutQuery.slice(1) + `?${explicitImportRequired ? \"import&\" : \"\"}t=${timestamp}${query ? `&${query}` : \"\"}`\n    );\n    if (isWithinCircularImport) {\n      importPromise.catch(() => {\n        console.info(\n          `[hmr] ${acceptedPath} failed to apply HMR as it's within a circular import. Reloading page to reset the execution order. To debug and break the circular import, you can run \\`vite --debug hmr\\` to log the circular dependency path if a file change triggered it.`\n        );\n        pageReload();\n      });\n    }\n    return await importPromise;\n  }\n);\ntransport.connect(createHMRHandler(handleMessage));\nasync function handleMessage(payload) {\n  switch (payload.type) {\n    case \"connected\":\n      console.debug(`[vite] connected.`);\n      break;\n    case \"update\":\n      await hmrClient.notifyListeners(\"vite:beforeUpdate\", payload);\n      if (hasDocument) {\n        if (isFirstUpdate && hasErrorOverlay()) {\n          location.reload();\n          return;\n        } else {\n          if (enableOverlay) {\n            clearErrorOverlay();\n          }\n          isFirstUpdate = false;\n        }\n      }\n      await Promise.all(\n        payload.updates.map(async (update) => {\n          if (update.type === \"js-update\") {\n            return hmrClient.queueUpdate(update);\n          }\n          const { path, timestamp } = update;\n          const searchUrl = cleanUrl(path);\n          const el = Array.from(\n            document.querySelectorAll(\"link\")\n          ).find(\n            (e) => !outdatedLinkTags.has(e) && cleanUrl(e.href).includes(searchUrl)\n          );\n          if (!el) {\n            return;\n          }\n          const newPath = `${base}${searchUrl.slice(1)}${searchUrl.includes(\"?\") ? \"&\" : \"?\"}t=${timestamp}`;\n          return new Promise((resolve) => {\n            const newLinkTag = el.cloneNode();\n            newLinkTag.href = new URL(newPath, el.href).href;\n            const removeOldEl = () => {\n              el.remove();\n              console.debug(`[vite] css hot updated: ${searchUrl}`);\n              resolve();\n            };\n            newLinkTag.addEventListener(\"load\", removeOldEl);\n            newLinkTag.addEventListener(\"error\", removeOldEl);\n            outdatedLinkTags.add(el);\n            el.after(newLinkTag);\n          });\n        })\n      );\n      await hmrClient.notifyListeners(\"vite:afterUpdate\", payload);\n      break;\n    case \"custom\": {\n      await hmrClient.notifyListeners(payload.event, payload.data);\n      if (payload.event === \"vite:ws:disconnect\") {\n        if (hasDocument && !willUnload) {\n          console.log(`[vite] server connection lost. Polling for restart...`);\n          const socket = payload.data.webSocket;\n          const url = new URL(socket.url);\n          url.search = \"\";\n          await waitForSuccessfulPing(url.href);\n          location.reload();\n        }\n      }\n      break;\n    }\n    case \"full-reload\":\n      await hmrClient.notifyListeners(\"vite:beforeFullReload\", payload);\n      if (hasDocument) {\n        if (payload.path && payload.path.endsWith(\".html\")) {\n          const pagePath = decodeURI(location.pathname);\n          const payloadPath = base + payload.path.slice(1);\n          if (pagePath === payloadPath || payload.path === \"/index.html\" || pagePath.endsWith(\"/\") && pagePath + \"index.html\" === payloadPath) {\n            pageReload();\n          }\n          return;\n        } else {\n          pageReload();\n        }\n      }\n      break;\n    case \"prune\":\n      await hmrClient.notifyListeners(\"vite:beforePrune\", payload);\n      await hmrClient.prunePaths(payload.paths);\n      break;\n    case \"error\": {\n      await hmrClient.notifyListeners(\"vite:error\", payload);\n      if (hasDocument) {\n        const err = payload.err;\n        if (enableOverlay) {\n          createErrorOverlay(err);\n        } else {\n          console.error(\n            `[vite] Internal Server Error\n${err.message}\n${err.stack}`\n          );\n        }\n      }\n      break;\n    }\n    case \"ping\":\n      break;\n    default: {\n      const check = payload;\n      return check;\n    }\n  }\n}\nconst enableOverlay = __HMR_ENABLE_OVERLAY__;\nconst hasDocument = \"document\" in globalThis;\nfunction createErrorOverlay(err) {\n  clearErrorOverlay();\n  const { customElements } = globalThis;\n  if (customElements) {\n    const ErrorOverlayConstructor = customElements.get(overlayId);\n    document.body.appendChild(new ErrorOverlayConstructor(err));\n  }\n}\nfunction clearErrorOverlay() {\n  document.querySelectorAll(overlayId).forEach((n) => n.close());\n}\nfunction hasErrorOverlay() {\n  return document.querySelectorAll(overlayId).length;\n}\nasync function waitForSuccessfulPing(socketUrl, ms = 1e3) {\n  async function ping() {\n    const socket = new WebSocket(socketUrl, \"vite-ping\");\n    return new Promise((resolve) => {\n      function onOpen() {\n        resolve(true);\n        close();\n      }\n      function onError() {\n        resolve(false);\n        close();\n      }\n      function close() {\n        socket.removeEventListener(\"open\", onOpen);\n        socket.removeEventListener(\"error\", onError);\n        socket.close();\n      }\n      socket.addEventListener(\"open\", onOpen);\n      socket.addEventListener(\"error\", onError);\n    });\n  }\n  if (await ping()) {\n    return;\n  }\n  await wait(ms);\n  while (true) {\n    if (document.visibilityState === \"visible\") {\n      if (await ping()) {\n        break;\n      }\n      await wait(ms);\n    } else {\n      await waitForWindowShow();\n    }\n  }\n}\nfunction wait(ms) {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\nfunction waitForWindowShow() {\n  return new Promise((resolve) => {\n    const onChange = async () => {\n      if (document.visibilityState === \"visible\") {\n        resolve();\n        document.removeEventListener(\"visibilitychange\", onChange);\n      }\n    };\n    document.addEventListener(\"visibilitychange\", onChange);\n  });\n}\nconst sheetsMap = /* @__PURE__ */ new Map();\nif (\"document\" in globalThis) {\n  document.querySelectorAll(\"style[data-vite-dev-id]\").forEach((el) => {\n    sheetsMap.set(el.getAttribute(\"data-vite-dev-id\"), el);\n  });\n}\nconst cspNonce = \"document\" in globalThis ? document.querySelector(\"meta[property=csp-nonce]\")?.nonce : void 0;\nlet lastInsertedStyle;\nfunction updateStyle(id, content) {\n  let style = sheetsMap.get(id);\n  if (!style) {\n    style = document.createElement(\"style\");\n    style.setAttribute(\"type\", \"text/css\");\n    style.setAttribute(\"data-vite-dev-id\", id);\n    style.textContent = content;\n    if (cspNonce) {\n      style.setAttribute(\"nonce\", cspNonce);\n    }\n    if (!lastInsertedStyle) {\n      document.head.appendChild(style);\n      setTimeout(() => {\n        lastInsertedStyle = void 0;\n      }, 0);\n    } else {\n      lastInsertedStyle.insertAdjacentElement(\"afterend\", style);\n    }\n    lastInsertedStyle = style;\n  } else {\n    style.textContent = content;\n  }\n  sheetsMap.set(id, style);\n}\nfunction removeStyle(id) {\n  const style = sheetsMap.get(id);\n  if (style) {\n    document.head.removeChild(style);\n    sheetsMap.delete(id);\n  }\n}\nfunction createHotContext(ownerPath) {\n  return new HMRContext(hmrClient, ownerPath);\n}\nfunction injectQuery(url, queryToInject) {\n  if (url[0] !== \".\" && url[0] !== \"/\") {\n    return url;\n  }\n  const pathname = url.replace(/[?#].*$/, \"\");\n  const { search, hash } = new URL(url, \"http://vite.dev\");\n  return `${pathname}?${queryToInject}${search ? `&` + search.slice(1) : \"\"}${hash || \"\"}`;\n}\n\nexport { ErrorOverlay, createHotContext, injectQuery, removeStyle, updateStyle };\n";
+export const VITE_ENV_MJS = "const context = (() => {\n  if (typeof globalThis !== \"undefined\") {\n    return globalThis;\n  } else if (typeof self !== \"undefined\") {\n    return self;\n  } else if (typeof window !== \"undefined\") {\n    return window;\n  } else {\n    return Function(\"return this\")();\n  }\n})();\nconst defines = __DEFINES__;\nObject.keys(defines).forEach((key) => {\n  const segments = key.split(\".\");\n  let target = context;\n  for (let i = 0; i < segments.length; i++) {\n    const segment = segments[i];\n    if (i === segments.length - 1) {\n      target[segment] = defines[key];\n    } else {\n      target = target[segment] || (target[segment] = {});\n    }\n  }\n});\n";

package/dist/replica/routing.d.ts

@@ -0,0 +1,171 @@
+/**
+ * replica-routing.ts — W12 — DO read replica routing primitives.
+ *
+ * Pure module (no `cloudflare:workers` import) so it can be unit-tested
+ * under Bun. NimbusSession wraps these helpers in its constructor and
+ * `_handleFetch` preflight; everything else is plumbing.
+ *
+ * Background:
+ *   - CF research §G.4 / §J.7.1: DO read replicas (wiki SPEC: STOR/Durable
+ *     Objects read replication API). Replicas serve cross-region read-mostly
+ *     traffic; writes always run on the primary. The runtime exposes:
+ *
+ *       ctx.storage.enableReplicas()                — wiki SPEC API
+ *       ctx.storage.configureReadReplication(opts)  — alternate API name
+ *                                                     observed in J.7.1 sketch
+ *       ctx.storage.primary                         — RpcStub-like; undefined
+ *                                                     on the primary itself,
+ *                                                     defined on replicas
+ *       ctx.storage.getCurrentBookmark()            — opaque bookmark for
+ *                                                     read-your-writes
+ *
+ *     We probe each defensively at runtime so this module is forward- and
+ *     backward-compatible: pre-GA runtimes lacking the API surface get
+ *     `state: 'unsupported'` and the DO behaves exactly as before W12.
+ *
+ *   - CF docs (workers/configuration/placement/): Smart Placement applies
+ *     to fetch handlers, NOT RPC. So Smart Placement on the gateway Worker
+ *     pins it near the DO; RPC into the DO is unaffected. DOs themselves
+ *     don't move.
+ *
+ *   - ~lambros/Feedback for DO read replication API: replicas error with
+ *     "Network connection lost" during high-volume writes. Mitigation:
+ *     suspend replicas during npm install / git clone bursts (the
+ *     suspension state lives in `replica-suspension.ts`).
+ */
+/** Result of `classifyReplicaPolicy(pathname, method)`. */
+export type ReplicaPolicy = 
+/** Always safe on a replica (idempotent reads of soft state). */
+'replica-ok'
+/** Safe on a replica IFF the in-memory state needed is already warm. */
+ | 'replica-warm-only'
+/** Replica must forward to primary. */
+ | 'primary-only'
+/** Replica must forward; the route is a WS upgrade and the replica must
+ *  not subscribe its own hibernation handler to a stream the primary
+ *  appends to. */
+ | 'primary-only-ws';
+/** Eventual-consistency tolerance in ms (replica-eligible routes only). */
+export interface RoutePolicy {
+    policy: ReplicaPolicy;
+    /** Max acceptable replication lag for this route, in ms. `null` for
+     *  primary-only routes (not replicable). */
+    toleranceMs: number | null;
+}
+/**
+ * Pure routing decision. Mirrors the route table in W12-plan §2.
+ * Methods other than GET/HEAD on a replica-eligible route escape to
+ * primary-only — read replicas only make sense for reads.
+ */
+export declare function classifyReplicaPolicy(pathname: string, method: string): ReplicaPolicy;
+/**
+ * Eventual-consistency tolerance per route (in ms).
+ *
+ * Returns `null` for primary-only routes (not replicable) and a numeric
+ * tolerance for replica-eligible routes. The probe
+ * `eventual-consistency-window-ms.mjs` enforces that every eligible route
+ * has a tolerance ≤ 2000ms.
+ *
+ * The 2-second budget aligns with D1 read-replication best practice
+ * (D1 docs § "Replica lag and consistency model"); DO replicas are
+ * the same architectural pattern.
+ */
+export declare function getEventualConsistencyToleranceMs(pathname: string): number | null;
+/** Tolerance lookup table (for diagnostics / observability surfaces). */
+export declare const REPLICA_POLICIES: Record<string, RoutePolicy>;
+export type ReplicasState = 'enabled' | 'enabled-via-configure' | 'unsupported' | 'error';
+export interface TryEnableReplicasResult {
+    state: ReplicasState;
+    error: string | null;
+}
+/**
+ * Best-effort: enable read replicas on this DO instance. Safe to call from
+ * the constructor — pre-GA runtimes that lack the API surface no-op.
+ *
+ * Operators reading `getReplicaState()` (exposed via /api/_diag/memory)
+ * see which path was taken.
+ */
+export declare function tryEnableReplicas(ctx: any): TryEnableReplicasResult;
+export interface ReplicaStateInspect {
+    isReplica: boolean;
+    primary: any | null;
+    bookmark: string | null;
+}
+/**
+ * Inspect this isolate's replica state.
+ *
+ *   - `isReplica` is `true` when `ctx.storage.primary` is defined. (Per
+ *     the wiki SPEC: the primary's `storage.primary` is `undefined`;
+ *     replica isolates get an RPC stub to the primary here.)
+ *   - `primary` is a stub-shaped object on replicas, `null` on primary.
+ *   - `bookmark` is `getCurrentBookmark()` if the API is present; `null`
+ *     otherwise. Used to thread read-your-writes via headers/cookies
+ *     when the SPEC's `waitForBookmark` lands.
+ */
+export declare function inspectReplicaState(ctx: any): ReplicaStateInspect;
+/**
+ * Capture the current bookmark immediately after a write completes on
+ * the primary. The caller (e.g. /api/write-file) can stash the result in
+ * a response header / cookie so the next read-your-writes call from the
+ * same client can wait for the replica to catch up before responding.
+ *
+ * Phase 1 of W12 surfaces this as observability only (visible via
+ * /api/_diag/memory.replica.bookmark). Phase 2 (W12.5 if measured demand)
+ * wires the wait-for-bookmark contract end-to-end.
+ */
+export declare function captureBookmarkAfterWrite(ctx: any): string | null;
+export interface DelegationInputs {
+    isReplica: boolean;
+    policy: ReplicaPolicy;
+    /** Whether this isolate has the in-memory state needed to serve a
+     *  `replica-warm-only` route (e.g. ViteDevServer.isRunning). */
+    isWarm: boolean;
+    /** Whether replicas are globally suspended (npm install / git clone
+     *  in flight). When true, replicas always delegate. */
+    suspended?: boolean;
+}
+/**
+ * Pure decision: should this isolate forward the Request to the primary
+ * via `ctx.storage.primary.fetch(request)`?
+ *
+ * `false` means "handle locally" (works on both primary and replica).
+ * `true` means "delegate" (replica-only; the caller is responsible for
+ * actually invoking `ctx.storage.primary.fetch(...)`).
+ */
+export declare function shouldDelegateToPrimary(inputs: DelegationInputs): boolean;
+/** Result of `handleReplicaPreflight`. */
+export interface PreflightResult {
+    /** True iff the caller should NOT invoke the local route handlers and
+     *  return `response` as-is. False means "fall through to local handling
+     *  as today." */
+    delegated: boolean;
+    /** When `delegated === true`, the Response from the primary. When
+     *  `delegated === false`, `null`. */
+    response: Response | null;
+    /** The decision inputs, surfaced for diagnostic logging / tests. */
+    decision: DelegationInputs & {
+        pathname: string;
+        method: string;
+    };
+}
+/**
+ * High-level preflight: classify the request, decide whether to delegate,
+ * and (if so) actually call `ctx.storage.primary.fetch(request)` and
+ * return the response.
+ *
+ * Caller pattern in NimbusSession._handleFetch:
+ *
+ *   const pre = await handleReplicaPreflight(this.ctx, request, {
+ *     isWarm: this.viteDevServer?.isRunning ?? false,
+ *   });
+ *   if (pre.delegated) return pre.response!;
+ *   // … existing route handlers …
+ *
+ * Note: the request is forwarded by reference (Request objects are
+ * single-consumption — the caller MUST NOT have read the body already).
+ */
+export declare function handleReplicaPreflight(ctx: any, request: Request, opts: {
+    isWarm: boolean;
+    suspended?: boolean;
+}): Promise<PreflightResult>;
+//# sourceMappingURL=routing.d.ts.map

package/dist/replica/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/replica/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,aAAa;AACvB,iEAAiE;AAC/D,YAAY;AACd,wEAAwE;GACtE,mBAAmB;AACrB,uCAAuC;GACrC,cAAc;AAChB;;kBAEkB;GAChB,iBAAiB,CAAC;AAEtB,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB;gDAC4C;IAC5C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,aAAa,CAkDf;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMjF;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAaxD,CAAC;AAMF,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,uBAAuB,GACvB,aAAa,GACb,OAAO,CAAC;AAEZ,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,uBAAuB,CAgBnE;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,mBAAmB,CAgBjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAEjE;AAMD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;IACtB;oEACgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB;2DACuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAoBzE;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B;;qBAEiB;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB;yCACqC;IACrC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,EAAE,gBAAgB,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C,OAAO,CAAC,eAAe,CAAC,CA6B1B"}

package/dist/replica/routing.js

@@ -0,0 +1,288 @@
+/**
+ * replica-routing.ts — W12 — DO read replica routing primitives.
+ *
+ * Pure module (no `cloudflare:workers` import) so it can be unit-tested
+ * under Bun. NimbusSession wraps these helpers in its constructor and
+ * `_handleFetch` preflight; everything else is plumbing.
+ *
+ * Background:
+ *   - CF research §G.4 / §J.7.1: DO read replicas (wiki SPEC: STOR/Durable
+ *     Objects read replication API). Replicas serve cross-region read-mostly
+ *     traffic; writes always run on the primary. The runtime exposes:
+ *
+ *       ctx.storage.enableReplicas()                — wiki SPEC API
+ *       ctx.storage.configureReadReplication(opts)  — alternate API name
+ *                                                     observed in J.7.1 sketch
+ *       ctx.storage.primary                         — RpcStub-like; undefined
+ *                                                     on the primary itself,
+ *                                                     defined on replicas
+ *       ctx.storage.getCurrentBookmark()            — opaque bookmark for
+ *                                                     read-your-writes
+ *
+ *     We probe each defensively at runtime so this module is forward- and
+ *     backward-compatible: pre-GA runtimes lacking the API surface get
+ *     `state: 'unsupported'` and the DO behaves exactly as before W12.
+ *
+ *   - CF docs (workers/configuration/placement/): Smart Placement applies
+ *     to fetch handlers, NOT RPC. So Smart Placement on the gateway Worker
+ *     pins it near the DO; RPC into the DO is unaffected. DOs themselves
+ *     don't move.
+ *
+ *   - ~lambros/Feedback for DO read replication API: replicas error with
+ *     "Network connection lost" during high-volume writes. Mitigation:
+ *     suspend replicas during npm install / git clone bursts (the
+ *     suspension state lives in `replica-suspension.ts`).
+ */
+const PROCESSES_LOGS_RE = /^\/api\/processes\/\d+\/logs$/;
+const PORT_RE = /^\/port\/\d+(\/.*)?$/;
+const TWO_SECONDS = 2000;
+/**
+ * Pure routing decision. Mirrors the route table in W12-plan §2.
+ * Methods other than GET/HEAD on a replica-eligible route escape to
+ * primary-only — read replicas only make sense for reads.
+ */
+export function classifyReplicaPolicy(pathname, method) {
+    // ── WS upgrades — must land on primary so hibernation subscriptions
+    //    follow the primary's append stream. (Replica acceptWebSocket
+    //    would subscribe a doomed replica handler.)
+    if (pathname === '/ws')
+        return 'primary-only-ws';
+    if (PROCESSES_LOGS_RE.test(pathname))
+        return 'primary-only-ws';
+    if (pathname === '/preview/__nimbus_hmr' || pathname.startsWith('/preview/__nimbus_hmr/')) {
+        return 'primary-only-ws';
+    }
+    // ── Worker / port routes — facets are owned by the primary; no
+    //    replica representation. Always primary-only.
+    //
+    // Primitives wave: `/__nimbus/worker/*` is the canonical route;
+    // `/worker/*` is the deprecated legacy form, kept here for back-
+    // compat (one release sunset; see routes.ts for the Deprecation
+    // header). Both classify the same way.
+    if (pathname === '/__nimbus/worker' || pathname.startsWith('/__nimbus/worker/'))
+        return 'primary-only';
+    if (pathname === '/worker' || pathname.startsWith('/worker/'))
+        return 'primary-only';
+    if (PORT_RE.test(pathname))
+        return 'primary-only';
+    // ── /preview/* — read-mostly after warm. Cold-warm distinction
+    //    handled by shouldDelegateToPrimary's `isWarm` input.
+    if (pathname === '/preview' || pathname.startsWith('/preview/')) {
+        if (!isReadMethod(method))
+            return 'primary-only';
+        return 'replica-warm-only';
+    }
+    // ── /api/_test/* — test-only endpoints, predictable behaviour > latency.
+    if (pathname.startsWith('/api/_test/'))
+        return 'primary-only';
+    // ── /api/* read endpoints (replica-ok)
+    if (isReadMethod(method)) {
+        if (pathname === '/api/memory')
+            return 'replica-ok';
+        if (pathname === '/api/_diag/memory')
+            return 'replica-ok';
+        if (pathname.startsWith('/api/_diag/'))
+            return 'replica-ok';
+        if (pathname === '/api/processes')
+            return 'replica-ok';
+        if (pathname === '/api/stats')
+            return 'replica-ok';
+    }
+    // ── Known write endpoints — primary-only.
+    if (pathname === '/api/write-file')
+        return 'primary-only';
+    if (pathname === '/api/mkdir')
+        return 'primary-only';
+    if (pathname === '/api/start-vite')
+        return 'primary-only';
+    if (pathname === '/api/supervisor-rpc')
+        return 'primary-only';
+    // Default: anything we don't recognize on a replica goes to primary.
+    // Safety > latency. New routes added must be classified explicitly
+    // (and the eventual-consistency-window-ms.mjs probe enforces that).
+    return 'primary-only';
+}
+function isReadMethod(method) {
+    return method === 'GET' || method === 'HEAD';
+}
+/**
+ * Eventual-consistency tolerance per route (in ms).
+ *
+ * Returns `null` for primary-only routes (not replicable) and a numeric
+ * tolerance for replica-eligible routes. The probe
+ * `eventual-consistency-window-ms.mjs` enforces that every eligible route
+ * has a tolerance ≤ 2000ms.
+ *
+ * The 2-second budget aligns with D1 read-replication best practice
+ * (D1 docs § "Replica lag and consistency model"); DO replicas are
+ * the same architectural pattern.
+ */
+export function getEventualConsistencyToleranceMs(pathname) {
+    // Re-classify with a synthetic GET to figure out replica eligibility.
+    const policy = classifyReplicaPolicy(pathname, 'GET');
+    if (policy === 'replica-ok')
+        return TWO_SECONDS;
+    if (policy === 'replica-warm-only')
+        return TWO_SECONDS;
+    return null;
+}
+/** Tolerance lookup table (for diagnostics / observability surfaces). */
+export const REPLICA_POLICIES = {
+    '/api/memory': { policy: 'replica-ok', toleranceMs: TWO_SECONDS },
+    '/api/_diag/memory': { policy: 'replica-ok', toleranceMs: TWO_SECONDS },
+    '/api/processes': { policy: 'replica-ok', toleranceMs: TWO_SECONDS },
+    '/api/stats': { policy: 'replica-ok', toleranceMs: TWO_SECONDS },
+    '/preview/': { policy: 'replica-warm-only', toleranceMs: TWO_SECONDS },
+    '/ws': { policy: 'primary-only-ws', toleranceMs: null },
+    '/api/write-file': { policy: 'primary-only', toleranceMs: null },
+    '/api/mkdir': { policy: 'primary-only', toleranceMs: null },
+    '/api/start-vite': { policy: 'primary-only', toleranceMs: null },
+    '/api/supervisor-rpc': { policy: 'primary-only', toleranceMs: null },
+    '/worker/': { policy: 'primary-only', toleranceMs: null },
+    '/__nimbus/worker/': { policy: 'primary-only', toleranceMs: null },
+};
+/**
+ * Best-effort: enable read replicas on this DO instance. Safe to call from
+ * the constructor — pre-GA runtimes that lack the API surface no-op.
+ *
+ * Operators reading `getReplicaState()` (exposed via /api/_diag/memory)
+ * see which path was taken.
+ */
+export function tryEnableReplicas(ctx) {
+    if (!ctx || !ctx.storage)
+        return { state: 'unsupported', error: null };
+    const s = ctx.storage;
+    try {
+        if (typeof s.enableReplicas === 'function') {
+            s.enableReplicas();
+            return { state: 'enabled', error: null };
+        }
+        if (typeof s.configureReadReplication === 'function') {
+            s.configureReadReplication({ mode: 'auto' });
+            return { state: 'enabled-via-configure', error: null };
+        }
+        return { state: 'unsupported', error: null };
+    }
+    catch (e) {
+        return { state: 'error', error: e?.message ?? String(e) };
+    }
+}
+/**
+ * Inspect this isolate's replica state.
+ *
+ *   - `isReplica` is `true` when `ctx.storage.primary` is defined. (Per
+ *     the wiki SPEC: the primary's `storage.primary` is `undefined`;
+ *     replica isolates get an RPC stub to the primary here.)
+ *   - `primary` is a stub-shaped object on replicas, `null` on primary.
+ *   - `bookmark` is `getCurrentBookmark()` if the API is present; `null`
+ *     otherwise. Used to thread read-your-writes via headers/cookies
+ *     when the SPEC's `waitForBookmark` lands.
+ */
+export function inspectReplicaState(ctx) {
+    if (!ctx || !ctx.storage)
+        return { isReplica: false, primary: null, bookmark: null };
+    const s = ctx.storage;
+    const isReplica = typeof s.primary !== 'undefined' && s.primary !== null;
+    let bookmark = null;
+    try {
+        if (typeof s.getCurrentBookmark === 'function') {
+            const v = s.getCurrentBookmark();
+            // The SPEC describes getCurrentBookmark as returning Promise<string>.
+            // J.7.1 uses it synchronously — accept either. We only surface
+            // string-on-fast-path; promises get null + the operator falls back
+            // to the async getReplicaState() variant if needed.
+            if (typeof v === 'string')
+                bookmark = v;
+        }
+    }
+    catch { /* best-effort */ }
+    return { isReplica, primary: isReplica ? s.primary : null, bookmark };
+}
+/**
+ * Capture the current bookmark immediately after a write completes on
+ * the primary. The caller (e.g. /api/write-file) can stash the result in
+ * a response header / cookie so the next read-your-writes call from the
+ * same client can wait for the replica to catch up before responding.
+ *
+ * Phase 1 of W12 surfaces this as observability only (visible via
+ * /api/_diag/memory.replica.bookmark). Phase 2 (W12.5 if measured demand)
+ * wires the wait-for-bookmark contract end-to-end.
+ */
+export function captureBookmarkAfterWrite(ctx) {
+    return inspectReplicaState(ctx).bookmark;
+}
+/**
+ * Pure decision: should this isolate forward the Request to the primary
+ * via `ctx.storage.primary.fetch(request)`?
+ *
+ * `false` means "handle locally" (works on both primary and replica).
+ * `true` means "delegate" (replica-only; the caller is responsible for
+ * actually invoking `ctx.storage.primary.fetch(...)`).
+ */
+export function shouldDelegateToPrimary(inputs) {
+    // Primary never delegates to itself.
+    if (!inputs.isReplica)
+        return false;
+    // Suspended (write-burst window) — replicas defer everything to primary
+    // to avoid the SPEC's "Network connection lost" replication error.
+    if (inputs.suspended === true)
+        return true;
+    switch (inputs.policy) {
+        case 'replica-ok':
+            return false;
+        case 'replica-warm-only':
+            return !inputs.isWarm;
+        case 'primary-only':
+        case 'primary-only-ws':
+            return true;
+        default:
+            // Defensive: unknown policies fail closed → primary-only.
+            return true;
+    }
+}
+/**
+ * High-level preflight: classify the request, decide whether to delegate,
+ * and (if so) actually call `ctx.storage.primary.fetch(request)` and
+ * return the response.
+ *
+ * Caller pattern in NimbusSession._handleFetch:
+ *
+ *   const pre = await handleReplicaPreflight(this.ctx, request, {
+ *     isWarm: this.viteDevServer?.isRunning ?? false,
+ *   });
+ *   if (pre.delegated) return pre.response!;
+ *   // … existing route handlers …
+ *
+ * Note: the request is forwarded by reference (Request objects are
+ * single-consumption — the caller MUST NOT have read the body already).
+ */
+export async function handleReplicaPreflight(ctx, request, opts) {
+    const url = new URL(request.url);
+    const pathname = url.pathname;
+    const method = request.method;
+    const policy = classifyReplicaPolicy(pathname, method);
+    const inspect = inspectReplicaState(ctx);
+    const decision = {
+        isReplica: inspect.isReplica,
+        policy,
+        isWarm: opts.isWarm,
+        suspended: opts.suspended ?? false,
+        pathname,
+        method,
+    };
+    const delegate = shouldDelegateToPrimary(decision);
+    if (!delegate) {
+        return { delegated: false, response: null, decision };
+    }
+    const primary = inspect.primary;
+    if (!primary || typeof primary.fetch !== 'function') {
+        // We claimed isReplica but the primary stub isn't usable — fall back
+        // to local handling (correctness > performance). Document via
+        // decision.suspended for diagnostic surfaces.
+        return { delegated: false, response: null, decision };
+    }
+    // Single intra-region RPC hop. The replica was placed near the primary
+    // so this is fast; the user's RTT-to-replica-edge is short anyway.
+    const response = await primary.fetch(request);
+    return { delegated: true, response, decision };
+}

package/dist/replica/suspension.d.ts

@@ -0,0 +1,36 @@
+/**
+ * replica-suspension.ts — W12 — global replica-suspension counter.
+ *
+ * Per [~lambros/Feedback for DO read replication API](https://wiki.cfdata.org/display/~lambros/Feedback+for+DO+read+replication+API+based+on+D1+read+replication+beta)
+ * (cited in CF research §G.4), DO read replicas error with "Network
+ * connection lost" during high-volume writes. The recommended mitigation
+ * is to disable replicas before a write burst (npm install, git clone)
+ * and re-enable after.
+ *
+ * This module exposes a refcount-style suspend/release API. The counter
+ * is checked by `shouldDelegateToPrimary` (in `replica-routing.ts`):
+ * when `replicasSuspended() === true`, the replica forwards everything
+ * to the primary regardless of route policy.
+ *
+ * Phase 1 of W12 ships the module + the in-DO consultation. Phase 2
+ * (W12.5 if measured demand) wires the npm-installer / git-clone hooks.
+ * Today's behaviour: counter stays at 0 → replicas serve normally; the
+ * SPEC error path is observed as a graceful-degrade (replica's primary
+ * stub returns the error and the user sees a 5xx, same as today's
+ * single-region behaviour).
+ */
+/**
+ * Increment the suspension count. Returns a release function that
+ * decrements once (subsequent calls are no-ops). Suspends are nestable;
+ * any holder keeping the count > 0 keeps replicas suspended.
+ */
+export declare function suspendReplicas(): () => void;
+/** Are any holders currently suspending replicas? */
+export declare function replicasSuspended(): boolean;
+/**
+ * Test-only escape hatch. Resets the counter to 0. Production code MUST
+ * NOT call this — use only the suspend/release pair to keep semantics
+ * tight. Exported under a `_` prefix and namespaced for tests.
+ */
+export declare function _resetSuspensionForTests(): void;
+//# sourceMappingURL=suspension.d.ts.map

package/dist/replica/suspension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspension.d.ts","sourceRoot":"","sources":["../../src/replica/suspension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,IAAI,CAQ5C;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}