rivetkit 2.3.0-rc.10 → 2.3.0-rc.12

package/dist/tsup/mod.js

@@ -2,13 +2,14 @@ import {
   ACTOR_CONTEXT_INTERNAL_SYMBOL,
   ActorConfigSchema,
   CONN_STATE_MANAGER_SYMBOL,
+  RAW_STATE_SYMBOL,
   getRunFunction,
   getRunInspectorConfig,
   getRunMetadata
-} from "./chunk-T6YVRM4K.js";
+} from "./chunk-WIMUFZVJ.js";
 import {
   decodeWorkflowHistoryTransport
-} from "./chunk-G34LIR7S.js";
+} from "./chunk-QKSGGKGQ.js";
 import {
   ALLOWED_PUBLIC_HEADERS,
   HEADER_CONN_PARAMS,
@@ -18,7 +19,7 @@ import {
   getDatacenters,
   tryParseEndpoint,
   updateRunnerConfig
-} from "./chunk-WU2O2KIE.js";
+} from "./chunk-7UZF56RS.js";
 import {
   KEYS,
   makePrefixedKey,
@@ -26,18 +27,19 @@ import {
   queueMetadataKey,
   removePrefixFromKey,
   workflowStoragePrefix
-} from "./chunk-3YY5S6TV.js";
+} from "./chunk-HXUEHHJF.js";
 import {
+  assertJsonCompatValue,
   decodeCborCompat,
-  decodeCborJsonCompat,
   encodeCborCompat
-} from "./chunk-BM3EOY7M.js";
-import "./chunk-PCBNKI2J.js";
-import "./chunk-6BI2MS3S.js";
+} from "./chunk-OOB32JVG.js";
+import "./chunk-JZ7TWV65.js";
+import "./chunk-VLXRFJ7P.js";
 import {
   LogLevelSchema,
   VERSION,
   deconstructError,
+  detectRuntime,
   getEnvUniversal,
   getLogger,
   getNodeEnv,
@@ -57,7 +59,7 @@ import {
   noopNext,
   stringifyError,
   toUint8Array
-} from "./chunk-KU6VKVEK.js";
+} from "./chunk-3EVVOYFD.js";
 import {
   INTERNAL_ERROR_CODE,
   RivetError,
@@ -68,7 +70,7 @@ import {
   isRivetErrorLike,
   toRivetError,
   unsupportedFeature
-} from "./chunk-KIWH5H3K.js";
+} from "./chunk-BRP62GZC.js";
 
 // src/actor/log.ts
 function loggerWithoutContext() {
@@ -140,7 +142,7 @@ function hasSchemaConfigKey(schemas, key) {
   if (!schemas) {
     return false;
   }
-  return Object.prototype.hasOwnProperty.call(schemas, key);
+  return Object.hasOwn(schemas, key);
 }
 function getEventCanSubscribe(schemas, key) {
   const schema = schemas == null ? void 0 : schemas[key];
@@ -201,8 +203,8 @@ function validateSchemaSync(schemas, key, data) {
 }
 
 // src/common/inline-websocket-adapter.ts
-import { WSContext } from "hono/ws";
 import { VirtualWebSocket } from "@rivetkit/virtual-websocket";
+import { WSContext } from "hono/ws";
 function logger() {
   return getLogger("inline-websocket-adapter");
 }
@@ -314,24 +316,24 @@ var InlineWebSocketAdapter = class {
       this.#close(1011, "Internal error during initialization");
     }
   }
-  #handleError(err) {
-    console.error("INLINE_WEBSOCKET_ADAPTER_ERROR", err);
+  #handleError(error) {
+    console.error("INLINE_WEBSOCKET_ADAPTER_ERROR", error);
     logger().error({
       msg: "error in websocket",
-      error: err,
-      errorMessage: err instanceof Error ? err.message : String(err),
-      stack: err instanceof Error ? err.stack : void 0
+      error,
+      errorMessage: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : void 0
     });
     try {
-      this.#handler.onError(err, this.#wsContext);
-    } catch (handlerErr) {
+      this.#handler.onError(error, this.#wsContext);
+    } catch (error2) {
       logger().error({
         msg: "error in onError handler",
-        error: handlerErr
+        error: error2
       });
     }
-    this.#clientWs.triggerError(err);
-    this.#actorWs.triggerError(err);
+    this.#clientWs.triggerError(error);
+    this.#actorWs.triggerError(error);
   }
   #close(code, reason) {
     if (this.#readyState === 3 || this.#readyState === 2) {
@@ -344,8 +346,8 @@ var InlineWebSocketAdapter = class {
         { code, reason, wasClean: true },
         this.#wsContext
       );
-    } catch (err) {
-      logger().error({ msg: "error closing websocket", error: err });
+    } catch (error) {
+      logger().error({ msg: "error closing websocket", error });
     } finally {
       this.#readyState = 3;
       this.#clientWs.triggerClose(code, reason);
@@ -354,6 +356,9 @@ var InlineWebSocketAdapter = class {
   }
 };
 
+// src/registry/index.ts
+import { Hono } from "hono";
+
 // src/common/engine.ts
 var ENGINE_PORT = 6420;
 var ENGINE_ENDPOINT = `http://127.0.0.1:${ENGINE_PORT}`;
@@ -371,10 +376,13 @@ function sleep(ms) {
 }
 function configureTimeoutMs() {
   const value = process.env.RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS;
-  if (value === void 0 || value === "") return DEFAULT_CONFIGURE_TIMEOUT_MS;
+  if (value === void 0 || value === "")
+    return DEFAULT_CONFIGURE_TIMEOUT_MS;
   const parsed = Number(value);
   if (!Number.isFinite(parsed) || parsed < 0) {
-    throw new Error("RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS must be a finite non-negative number");
+    throw new Error(
+      "RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS must be a finite non-negative number"
+    );
   }
   return parsed;
 }
@@ -388,13 +396,19 @@ async function configureServerlessPool(config) {
     attempts += 1;
     try {
       if (!config.namespace) {
-        throw new Error("namespace is required for serverless configuration");
+        throw new Error(
+          "namespace is required for serverless configuration"
+        );
       }
       if (!config.endpoint) {
-        throw new Error("endpoint is required for serverless configuration");
+        throw new Error(
+          "endpoint is required for serverless configuration"
+        );
       }
       if (!config.configurePool) {
-        throw new Error("configurePool is required for serverless configuration");
+        throw new Error(
+          "configurePool is required for serverless configuration"
+        );
       }
       const customConfig = config.configurePool;
       const clientConfig = convertRegistryConfigToClientConfig(config);
@@ -450,6 +464,145 @@ async function configureServerlessPool(config) {
   throw lastError;
 }
 
+// src/utils/serve.ts
+import getPort from "get-port";
+var serveStaticLoaderPromises = {};
+async function crossPlatformServe(config, httpPort, app, runtime = detectRuntime()) {
+  logger2().debug({ msg: "detected runtime for serve", runtime });
+  switch (runtime) {
+    case "deno":
+      return serveDeno(config, httpPort, app);
+    case "bun":
+      return serveBun(config, httpPort, app);
+    case "node":
+      return serveNode(config, httpPort, app);
+    default:
+      return serveNode(config, httpPort, app);
+  }
+}
+async function loadRuntimeServeStatic(runtime) {
+  if (!serveStaticLoaderPromises[runtime]) {
+    if (runtime === "node") {
+      const nodeServeStaticModule = "@hono/node-server/serve-static";
+      serveStaticLoaderPromises[runtime] = import(
+        /* webpackIgnore: true */
+        nodeServeStaticModule
+      ).then((x) => x.serveStatic);
+    } else if (runtime === "bun") {
+      const bunModule = "hono/bun";
+      serveStaticLoaderPromises[runtime] = import(
+        /* webpackIgnore: true */
+        bunModule
+      ).then((x) => x.serveStatic);
+    } else if (runtime === "deno") {
+      const denoModule = "hono/deno";
+      serveStaticLoaderPromises[runtime] = import(
+        /* webpackIgnore: true */
+        denoModule
+      ).then((x) => x.serveStatic);
+    } else {
+      throw new Error(`unsupported runtime: ${runtime}`);
+    }
+  }
+  return await serveStaticLoaderPromises[runtime];
+}
+async function serveNode(config, httpPort, app) {
+  const nodeServerModule = "@hono/node-server";
+  let serve;
+  try {
+    const dep = await import(
+      /* webpackIgnore: true */
+      nodeServerModule
+    );
+    serve = dep.serve;
+  } catch (err) {
+    logger2().error({
+      msg: "failed to import @hono/node-server. please run 'npm install @hono/node-server @hono/node-ws'",
+      error: stringifyError(err)
+    });
+    process.exit(1);
+  }
+  const nodeWsModule = "@hono/node-ws";
+  let createNodeWebSocket;
+  try {
+    const dep = await import(
+      /* webpackIgnore: true */
+      nodeWsModule
+    );
+    createNodeWebSocket = dep.createNodeWebSocket;
+  } catch (err) {
+    logger2().error({
+      msg: "failed to import @hono/node-ws. please run 'npm install @hono/node-server @hono/node-ws'",
+      error: stringifyError(err)
+    });
+    process.exit(1);
+  }
+  const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({
+    app
+  });
+  const port = httpPort;
+  const hostname = config.httpHost;
+  const server = serve(
+    { fetch: app.fetch, port, hostname },
+    () => logger2().info({ msg: "server listening", port, hostname })
+  );
+  injectWebSocket(server);
+  const closeServer = () => {
+    server.close();
+  };
+  return { upgradeWebSocket, closeServer };
+}
+async function serveDeno(config, httpPort, app) {
+  const honoDenoModule = "hono/deno";
+  let upgradeWebSocket;
+  try {
+    const dep = await import(
+      /* webpackIgnore: true */
+      honoDenoModule
+    );
+    upgradeWebSocket = dep.upgradeWebSocket;
+  } catch (err) {
+    logger2().error({
+      msg: "failed to import hono/deno",
+      error: stringifyError(err)
+    });
+    process.exit(1);
+  }
+  const port = httpPort;
+  const hostname = config.httpHost;
+  Deno.serve({ port, hostname }, app.fetch);
+  logger2().info({ msg: "server listening", port, hostname });
+  return { upgradeWebSocket };
+}
+async function serveBun(config, httpPort, app) {
+  const honoBunModule = "hono/bun";
+  let createBunWebSocket;
+  try {
+    const dep = await import(
+      /* webpackIgnore: true */
+      honoBunModule
+    );
+    createBunWebSocket = dep.createBunWebSocket;
+  } catch (err) {
+    logger2().error({
+      msg: "failed to import hono/bun",
+      error: stringifyError(err)
+    });
+    process.exit(1);
+  }
+  const { websocket, upgradeWebSocket } = createBunWebSocket();
+  const port = httpPort;
+  const hostname = config.httpHost;
+  Bun.serve({
+    fetch: app.fetch,
+    port,
+    hostname,
+    websocket
+  });
+  logger2().info({ msg: "server listening", port, hostname });
+  return { upgradeWebSocket };
+}
+
 // src/registry/config/index.ts
 import { z as z3 } from "zod";
 
@@ -703,7 +856,7 @@ var RegistryConfigSchema = z3.object({
      * after calling `CoreRegistry::shutdown()`. Defaults to the
      * engine-provided actor stop threshold once the envoy connects.
      *
-     * Must be >= rivetkit-core's drain timeout (20s) + margin.
+     * Must be long enough for rivetkit-core to drain the envoy.
      */
     gracePeriodMs: z3.number().int().min(1e3).optional(),
     /**
@@ -1424,6 +1577,9 @@ var NapiCoreRuntime = class {
   async actorWaitForTrackedShutdownWork(ctx) {
     return await asNativeActorContext(ctx).waitForTrackedShutdownWork();
   }
+  async actorWaitForTrackedShutdownWorkUnbounded(ctx) {
+    await asNativeActorContext(ctx).waitForTrackedShutdownWorkUnbounded();
+  }
   actorKeepAwake(ctx, promise) {
     asNativeActorContext(ctx).keepAwake(promise);
   }
@@ -1535,8 +1691,12 @@ var NapiCoreRuntime = class {
       )
     );
   }
-  async actorQueueWaitForNamesAvailable(ctx, names, options) {
-    await asNativeActorContext(ctx).queue().waitForNamesAvailable(names, options);
+  async actorQueueWaitForNamesAvailable(ctx, names, options, signal) {
+    await asNativeActorContext(ctx).queue().waitForNamesAvailable(
+      names,
+      options,
+      signal ? asNativeCancellationToken(signal) : signal
+    );
   }
   async actorQueueEnqueueAndWait(ctx, name, body, options, signal) {
     return await asNativeActorContext(ctx).queue().enqueueAndWait(
@@ -1670,20 +1830,18 @@ function validateQueueComplete(schemas, name, response) {
     response
   );
   if (!result.success) {
-    throw validationError(`queue \`${name}\` completion response`, result.issues);
+    throw validationError(
+      `queue \`${name}\` completion response`,
+      result.issues
+    );
   }
   return result.data;
 }
 function validationError(target, issues) {
-  return new RivetError(
-    "actor",
-    "validation_error",
-    `Invalid ${target}`,
-    {
-      public: true,
-      metadata: { issues }
-    }
-  );
+  return new RivetError("actor", "validation_error", `Invalid ${target}`, {
+    public: true,
+    metadata: { issues }
+  });
 }
 
 // src/registry/wasm-runtime.ts
@@ -2007,6 +2165,12 @@ var WasmCoreRuntime = class {
       "waitForTrackedShutdownWork"
     );
   }
+  async actorWaitForTrackedShutdownWorkUnbounded(ctx) {
+    await callHandle(
+      asWasmActorContext(ctx),
+      "waitForTrackedShutdownWorkUnbounded"
+    );
+  }
   actorKeepAwake(ctx, promise) {
     const wasmCtx = asWasmActorContext(ctx);
     const regionId = callHandle(wasmCtx, "beginKeepAwake");
@@ -2154,9 +2318,15 @@ var WasmCoreRuntime = class {
       )
     );
   }
-  async actorQueueWaitForNamesAvailable(ctx, names, options) {
+  async actorQueueWaitForNamesAvailable(ctx, names, options, signal) {
     const queue2 = childHandle(asWasmActorContext(ctx), "queue");
-    await callHandleAsync(queue2, "waitForNamesAvailable", names, options);
+    await callHandleAsync(
+      queue2,
+      "waitForNamesAvailable",
+      names,
+      options,
+      signal
+    );
   }
   async actorQueueEnqueueAndWait(ctx, name, body, options, signal) {
     const queue2 = childHandle(asWasmActorContext(ctx), "queue");
@@ -2248,6 +2418,29 @@ async function loadWasmRuntime(config) {
   };
 }
 
+// src/registry/write-through-proxy.ts
+import onChange from "@rivetkit/on-change";
+function createWriteThroughProxy(value, commit, beforeChange) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return onChange(
+    value,
+    () => {
+      commit(value);
+    },
+    {
+      // Rejection is throw-based: beforeChange throws to prevent the
+      // mutation. We always return true so on-change applies the change
+      // if beforeChange did not throw.
+      onValidate(_path, newValue) {
+        beforeChange == null ? void 0 : beforeChange(newValue);
+        return true;
+      }
+    }
+  );
+}
+
 // src/registry/native.ts
 var textEncoder = new TextEncoder();
 var textDecoder = new TextDecoder();
@@ -2401,6 +2594,14 @@ function databaseNotConfiguredError() {
     { public: true }
   );
 }
+function databaseClientNotReadyError() {
+  return new RivetError(
+    "actor",
+    "database_client_not_ready",
+    "actor database client was not initialized before user code ran. this is an internal lifecycle error; the migration callback should have pre-warmed the client. file an issue if you can reproduce.",
+    { public: true }
+  );
+}
 function stateNotEnabledError() {
   return new RivetError(
     "actor",
@@ -2452,8 +2653,23 @@ function resolveNativeDestroy(runtime, ctx) {
 function clearNativeRuntimeState(runtime, ctx) {
   callNativeSync(() => runtime.actorClearRuntimeState(ctx));
 }
-async function cleanupNativeSleepRuntimeState(runtime, ctx) {
-  await runtime.actorWaitForTrackedShutdownWork(ctx);
+async function cleanupNativeSleepRuntimeState(runtime, ctx, afterTrackedWorkDrained) {
+  const drained = await runtime.actorWaitForTrackedShutdownWork(ctx);
+  if (!drained) {
+    await closeNativeDatabaseClient(runtime, ctx);
+    await closeNativeSqlDatabase(runtime, ctx);
+    void runtime.actorWaitForTrackedShutdownWorkUnbounded(ctx).then(async () => {
+      await (afterTrackedWorkDrained == null ? void 0 : afterTrackedWorkDrained());
+      clearNativeRuntimeState(runtime, ctx);
+    }).catch((error) => {
+      logger2().warn({
+        msg: "deferred native sleep cleanup failed",
+        error: stringifyError(error)
+      });
+    });
+    return;
+  }
+  await (afterTrackedWorkDrained == null ? void 0 : afterTrackedWorkDrained());
   await closeNativeDatabaseClient(runtime, ctx);
   await closeNativeSqlDatabase(runtime, ctx);
   clearNativeRuntimeState(runtime, ctx);
@@ -2558,7 +2774,7 @@ function decodeValue(value) {
   if (!value || value.length === 0) {
     return void 0;
   }
-  return decodeCborJsonCompat(value);
+  return decodeCborCompat(value);
 }
 function encodeValue(value) {
   return encodeCborCompat(value);
@@ -2618,12 +2834,6 @@ function callNativeSync(invoke) {
     throw normalizeNativeBridgeError(error);
   }
 }
-function actorAbortedError() {
-  return Object.assign(new Error("Actor aborted"), {
-    group: "actor",
-    code: "aborted"
-  });
-}
 function isClosedTaskRegistrationError(error) {
   const metadata = error instanceof RivetError ? error.metadata : void 0;
   const metadataError = metadata && typeof metadata === "object" && "error" in metadata ? metadata.error : void 0;
@@ -2756,7 +2966,7 @@ function serializeWorkflowHistoryForJson(data) {
     return null;
   }
   const history = decodeWorkflowHistoryTransport(data);
-  return {
+  return jsonSafe({
     nameRegistry: [...history.nameRegistry],
     entries: history.entries.map((entry) => ({
       id: entry.id,
@@ -2780,7 +2990,7 @@ function serializeWorkflowHistoryForJson(data) {
         ]
       )
     )
-  };
+  });
 }
 function toHttpJsonCompatible(value) {
   return JSON.parse(
@@ -2833,44 +3043,6 @@ function decodeArgs(value) {
   const decoded = decodeValue(value);
   return Array.isArray(decoded) ? decoded : decoded === void 0 ? [] : [decoded];
 }
-function createWriteThroughProxy(value, commit, beforeChange) {
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  const proxies = /* @__PURE__ */ new WeakMap();
-  const wrap = (target) => {
-    const cached = proxies.get(target);
-    if (cached) {
-      return cached;
-    }
-    const proxy = new Proxy(target, {
-      get(innerTarget, property, receiver) {
-        const result = Reflect.get(innerTarget, property, receiver);
-        return result && typeof result === "object" ? wrap(result) : result;
-      },
-      set(innerTarget, property, nextValue, receiver) {
-        beforeChange == null ? void 0 : beforeChange();
-        const updated = Reflect.set(
-          innerTarget,
-          property,
-          nextValue,
-          receiver
-        );
-        commit(value);
-        return updated;
-      },
-      deleteProperty(innerTarget, property) {
-        beforeChange == null ? void 0 : beforeChange();
-        const updated = Reflect.deleteProperty(innerTarget, property);
-        commit(value);
-        return updated;
-      }
-    });
-    proxies.set(target, proxy);
-    return proxy;
-  };
-  return wrap(value);
-}
 function buildRequest(init) {
   const url = init.uri.startsWith("http") ? init.uri : new URL(init.uri, "http://127.0.0.1").toString();
   const body = init.body && init.body.length > 0 ? runtimeBytesToArrayBuffer(init.body) : void 0;
@@ -2923,13 +3095,23 @@ var NativeConnAdapter = class {
       decodeValue(this.#runtime.connParams(this.#conn))
     );
   }
+  [RAW_STATE_SYMBOL]() {
+    return this.#readState();
+  }
   get state() {
     const nextState = this.#readState();
-    return createWriteThroughProxy(nextState, (nextValue) => {
-      this.#writeState(nextValue, { writeNative: true });
-    });
+    return createWriteThroughProxy(
+      nextState,
+      (nextValue) => {
+        this.#writeState(nextValue, { writeNative: true });
+      },
+      (newValue) => {
+        assertJsonCompatValue(newValue);
+      }
+    );
   }
   set state(value) {
+    assertJsonCompatValue(value);
     this.#writeState(value, { writeNative: true });
   }
   initializeState(value) {
@@ -3281,44 +3463,23 @@ var NativeQueueAdapter = class {
     }
   }
   async waitForNamesAvailable(names, options) {
-    if (!(options == null ? void 0 : options.signal)) {
+    const { token, cleanup } = await createCancellationTokenHandle(
+      this.#runtime,
+      options == null ? void 0 : options.signal
+    );
+    try {
       await callNative(
         () => this.#runtime.actorQueueWaitForNamesAvailable(
           this.#ctx,
           [...names],
           {
             timeoutMs: options == null ? void 0 : options.timeout
-          }
+          },
+          token
         )
       );
-      return;
-    }
-    const deadline = options.timeout === void 0 ? void 0 : Date.now() + options.timeout;
-    for (; ; ) {
-      if (options.signal.aborted) {
-        throw actorAbortedError();
-      }
-      const remainingTimeout = deadline === void 0 ? void 0 : Math.max(0, deadline - Date.now());
-      const sliceTimeout = remainingTimeout === void 0 ? 100 : Math.min(remainingTimeout, 100);
-      try {
-        await callNative(
-          () => this.#runtime.actorQueueWaitForNamesAvailable(
-            this.#ctx,
-            [...names],
-            {
-              timeoutMs: sliceTimeout
-            }
-          )
-        );
-        return;
-      } catch (error) {
-        if (error.group === "queue" && error.code === "timed_out") {
-          if (remainingTimeout === void 0 || remainingTimeout > 100) {
-            continue;
-          }
-        }
-        throw error;
-      }
+    } finally {
+      cleanup == null ? void 0 : cleanup();
     }
   }
   async enqueueAndWait(name, body, options) {
@@ -3753,6 +3914,68 @@ var TrackedWebSocketHandleAdapter = class {
     return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
   }
 };
+var NativeConnectionMap = class {
+  #runtime;
+  #ctx;
+  #schemas;
+  constructor(runtime, ctx, schemas) {
+    this.#runtime = runtime;
+    this.#ctx = ctx;
+    this.#schemas = schemas;
+  }
+  #connToAdapter(conn) {
+    return new NativeConnAdapter(
+      this.#runtime,
+      conn,
+      this.#schemas,
+      this.#ctx,
+      (connId) => callNativeSync(
+        () => this.#runtime.actorQueueHibernationRemoval(
+          this.#ctx,
+          connId
+        )
+      )
+    );
+  }
+  get size() {
+    return callNativeSync(() => this.#runtime.actorConns(this.#ctx)).length;
+  }
+  get(key) {
+    const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+    const conn = conns.find((c) => this.#runtime.connId(c) === key);
+    if (!conn) return void 0;
+    return this.#connToAdapter(conn);
+  }
+  has(key) {
+    const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+    return conns.some((c) => this.#runtime.connId(c) === key);
+  }
+  keys() {
+    const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+    return conns.map((c) => this.#runtime.connId(c))[Symbol.iterator]();
+  }
+  values() {
+    const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+    return conns.map((c) => this.#connToAdapter(c))[Symbol.iterator]();
+  }
+  entries() {
+    const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+    return conns.map(
+      (c) => [this.#runtime.connId(c), this.#connToAdapter(c)]
+    )[Symbol.iterator]();
+  }
+  forEach(callback, thisArg) {
+    const conns = callNativeSync(() => this.#runtime.actorConns(this.#ctx));
+    for (const conn of conns) {
+      const id = this.#runtime.connId(conn);
+      callback.call(thisArg, this.#connToAdapter(conn), id, this);
+    }
+  }
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+  [Symbol.toStringTag] = "NativeConnectionMap";
+};
 var ActorContextHandleAdapter = class {
   #runtime;
   #ctx;
@@ -3761,9 +3984,9 @@ var ActorContextHandleAdapter = class {
   #abortSignalCleanup;
   #client;
   #clientFactory;
+  #connMap;
   #databaseProvider;
   #db;
-  #dbProxy;
   #dispatchCancelToken;
   #kv;
   #queue;
@@ -3806,30 +4029,22 @@ var ActorContextHandleAdapter = class {
     if (!this.#databaseProvider) {
       throw databaseNotConfiguredError();
     }
-    if (!this.#dbProxy) {
-      this.#dbProxy = new Proxy(
-        {},
-        {
-          get: (_target, property) => {
-            if (property === "then") {
-              return void 0;
-            }
-            return async (...args) => {
-              const client = await this.ensureDatabaseClient();
-              const value = Reflect.get(
-                client,
-                property
-              );
-              if (typeof value !== "function") {
-                return value;
-              }
-              return await value.apply(client, args);
-            };
-          }
-        }
-      );
+    if (this.#db) {
+      return this.#db;
+    }
+    const runtimeState = getNativeRuntimeState(this.#runtime, this.#ctx);
+    const cachedClient = runtimeState.databaseClient;
+    if (cachedClient) {
+      this.#db = cachedClient.client;
+      return this.#db;
     }
-    return this.#dbProxy;
+    throw databaseClientNotReadyError();
+  }
+  [RAW_STATE_SYMBOL]() {
+    if (!this.#stateEnabled) {
+      throw stateNotEnabledError();
+    }
+    return this.#readState();
   }
   get state() {
     if (!this.#stateEnabled) {
@@ -3844,8 +4059,9 @@ var ActorContextHandleAdapter = class {
         (nextValue) => {
           this.#writeState(nextValue, { scheduleSave: true });
         },
-        () => {
+        (newValue) => {
           this.#assertCanMutateState();
+          assertJsonCompatValue(newValue);
         }
       );
     }
@@ -3856,6 +4072,7 @@ var ActorContextHandleAdapter = class {
       throw stateNotEnabledError();
     }
     this.#assertCanMutateState();
+    assertJsonCompatValue(value);
     this.#writeState(value, { scheduleSave: true });
   }
   initializeState(value) {
@@ -3912,25 +4129,14 @@ var ActorContextHandleAdapter = class {
     return callNativeSync(() => this.#runtime.actorRegion(this.#ctx));
   }
   get conns() {
-    return new Map(
-      callNativeSync(() => this.#runtime.actorConns(this.#ctx)).map(
-        (conn) => [
-          this.#runtime.connId(conn),
-          new NativeConnAdapter(
-            this.#runtime,
-            conn,
-            this.#schemas,
-            this.#ctx,
-            (connId) => callNativeSync(
-              () => this.#runtime.actorQueueHibernationRemoval(
-                this.#ctx,
-                connId
-              )
-            )
-          )
-        ]
-      )
-    );
+    if (!this.#connMap) {
+      this.#connMap = new NativeConnectionMap(
+        this.#runtime,
+        this.#ctx,
+        this.#schemas
+      );
+    }
+    return this.#connMap;
   }
   get log() {
     return logger2();
@@ -4207,6 +4413,7 @@ var ActorContextHandleAdapter = class {
     return false;
   }
   sleep() {
+    this.#flushStateChange();
     callNativeSync(() => this.#runtime.actorSleep(this.#ctx));
   }
   destroy() {
@@ -4687,6 +4894,10 @@ function buildNativeFactory(runtime, registryConfig, definition) {
             isWorkflowEnabled: getNativeWorkflowInspector(ctx) !== void 0
           });
         } catch (error) {
+          logger2().error({
+            msg: "error replaying workflow history",
+            error
+          });
           return errorResponse(error);
         }
       }
@@ -4838,6 +5049,10 @@ function buildNativeFactory(runtime, registryConfig, definition) {
           );
           return jsonResponse({ output });
         } catch (error) {
+          logger2().error({
+            msg: "Error handling inspector action request",
+            error
+          });
           return errorResponse(error);
         }
       }
@@ -4851,6 +5066,10 @@ function buildNativeFactory(runtime, registryConfig, definition) {
         { status: 404 }
       );
     } catch (error) {
+      logger2().error({
+        msg: "Error handling inspector request",
+        error
+      });
       return errorResponse(error);
     } finally {
       await actorCtx.dispose();
@@ -4973,24 +5192,30 @@ function buildNativeFactory(runtime, registryConfig, definition) {
       async (error, payload) => {
         const { ctx } = unwrapTsfnPayload(error, payload);
         const actorCtx = makeActorCtx(ctx);
+        const saveActorState = async () => {
+          if (runtime.kind === "wasm") {
+            await runtime.actorSaveState(
+              ctx,
+              actorCtx.serializeForTick("save")
+            );
+          } else {
+            await actorCtx.saveState({
+              immediate: true
+            });
+          }
+        };
         try {
           if (onSleep) {
-            try {
-              await onSleep(actorCtx);
-            } finally {
-              if (runtime.kind === "wasm") {
-                await runtime.actorSaveState(
-                  ctx,
-                  actorCtx.serializeForTick("save")
-                );
-              } else {
-                await actorCtx.saveState({ immediate: true });
-              }
-            }
+            await onSleep(actorCtx);
           }
+          await saveActorState();
         } finally {
           try {
-            await cleanupNativeSleepRuntimeState(runtime, ctx);
+            await cleanupNativeSleepRuntimeState(
+              runtime,
+              ctx,
+              saveActorState
+            );
           } finally {
             await actorCtx.dispose();
           }
@@ -5488,6 +5713,7 @@ function finishShutdownSignal(signal) {
 }
 var Registry = class {
   #config;
+  #buildConfiguredRegistry;
   routes;
   get config() {
     return this.#config;
@@ -5503,8 +5729,9 @@ var Registry = class {
   #shutdownInstalled = false;
   #shutdownInFlight = null;
   #signalHandlers = {};
-  constructor(config) {
+  constructor(config, deps) {
     this.#config = config;
+    this.#buildConfiguredRegistry = (deps == null ? void 0 : deps.buildConfiguredRegistry) ?? buildConfiguredRegistry;
     this.routes = {
       health: () => this.#healthRoute(),
       metadata: () => this.#metadataRoute(),
@@ -5514,12 +5741,12 @@ var Registry = class {
   #ensureServerlessPoolConfigured(config) {
     if (!config.configurePool) return void 0;
     if (!this.#configureServerlessPoolPromise) {
-      this.#configureServerlessPoolPromise = configureServerlessPool(config).catch(
-        (error) => {
-          this.#configureServerlessPoolPromise = void 0;
-          throw error;
-        }
-      );
+      this.#configureServerlessPoolPromise = configureServerlessPool(
+        config
+      ).catch((error) => {
+        this.#configureServerlessPoolPromise = void 0;
+        throw error;
+      });
       this.#configureServerlessPoolPromise.catch(() => {
       });
     }
@@ -5540,7 +5767,7 @@ var Registry = class {
     const config = this.parseConfig();
     this.#printWelcome(config, "serverless");
     if (!this.#runtimeServerlessPromise) {
-      this.#runtimeServerlessPromise = buildConfiguredRegistry(config);
+      this.#runtimeServerlessPromise = this.#buildConfiguredRegistry(config);
     }
     const { runtime, registry, serveConfig } = await this.#runtimeServerlessPromise;
     const isStartRequest = isServerlessStartRequest(
@@ -5555,7 +5782,7 @@ var Registry = class {
     if (isStartRequest) {
       try {
         await this.#ensureServerlessPoolConfigured(config);
-      } catch (error) {
+      } catch (_error) {
         return new Response(
           JSON.stringify({
             group: "guard",
@@ -5669,7 +5896,7 @@ var Registry = class {
     if (isMetadataRequest && !isEngineMetadataRequest) {
       try {
         await this.#ensureServerlessPoolConfigured(config);
-      } catch (error) {
+      } catch (_error) {
         return new Response(
           JSON.stringify({
             group: "guard",
@@ -5702,6 +5929,33 @@ var Registry = class {
       fetch: (request) => this.handler(request)
     };
   }
+  /**
+   * Starts an HTTP server that dispatches every request through the
+   * serverless handler. Uses `crossPlatformServe` to pick the right
+   * runtime (Node, Bun, Deno).
+   *
+   * @param opts.port      Port to listen on. Defaults to 3000.
+   * @param opts.publicDir If set, serves static files from this directory
+   *                       before falling through to the registry handler.
+   *
+   * @example
+   * ```ts
+   * await registry.listen();
+   * await registry.listen({ port: 8080, publicDir: "./public" });
+   * ```
+   */
+  async listen(opts = {}) {
+    const port = opts.port ?? 3e3;
+    const config = this.parseConfig();
+    const runtime = detectRuntime();
+    const app = new Hono();
+    if (opts.publicDir) {
+      const serveStatic = await loadRuntimeServeStatic(runtime);
+      app.use("*", serveStatic({ root: opts.publicDir }));
+    }
+    app.all("*", (c) => this.handler(c.req.raw));
+    await crossPlatformServe(config, port, app, runtime);
+  }
   /**
    * Returns a health response suitable for mounting in a user-owned router.
    */
@@ -5791,20 +6045,20 @@ var Registry = class {
    */
   #startEnvoy(config, printWelcome) {
     if (!this.#runtimeServePromise) {
-      const configuredRegistryPromise = buildConfiguredRegistry(config);
+      const configuredRegistryPromise = this.#buildConfiguredRegistry(config);
       this.#runtimeServeConfiguredPromise = configuredRegistryPromise;
       this.#runtimeServePromise = configuredRegistryPromise.then(async ({ runtime, registry, serveConfig }) => {
         await runtime.serveRegistry(registry, serveConfig);
-      }).catch((err) => {
-        logger2().warn({ err }, "runtime registry serve errored");
+      }).catch((error) => {
+        logger2().warn({ error }, "runtime registry serve errored");
       });
-      this.#installSignalHandlers(config, configuredRegistryPromise);
+      this.#installSignalHandlers(config);
     }
     if (printWelcome) {
       this.#printWelcome(config, "serverful");
     }
   }
-  #installSignalHandlers(config, configuredRegistryPromise) {
+  #installSignalHandlers(config) {
     var _a;
     if (this.#shutdownInstalled) return;
     if ((_a = config.shutdown) == null ? void 0 : _a.disableSignalHandlers) return;
@@ -5813,58 +6067,86 @@ var Registry = class {
     }
     this.#shutdownInstalled = true;
     const install = (signal) => {
-      const handler = () => this.#onShutdownSignal(
-        signal,
-        config,
-        configuredRegistryPromise
-      );
+      const handler = () => this.#onShutdownSignal(signal, config);
       this.#signalHandlers[signal] = handler;
       process.on(signal, handler);
     };
     install("SIGINT");
     install("SIGTERM");
   }
-  #onShutdownSignal(signal, config, configuredRegistryPromise) {
+  #onShutdownSignal(signal, config) {
     if (this.#shutdownInFlight !== null) {
       this.#removeSignalHandlers();
       finishShutdownSignal(signal);
       return;
     }
-    this.#shutdownInFlight = this.#runShutdown(
-      signal,
-      config,
-      configuredRegistryPromise
-    ).catch((err) => {
+    this.#shutdownInFlight = this.#drain(config).catch((err) => {
+      logger2().warn({ err }, "shutdown error");
+    }).then(() => {
+      this.#removeSignalHandlers();
+      finishShutdownSignal(signal);
+    });
+  }
+  /**
+   * Gracefully drains all live registries.
+   *
+   * Programmatic counterpart to the SIGINT/SIGTERM handlers: tears down
+   * every live `CoreRegistry` (both `start()` and `handler()` modes) and
+   * waits for the serve promise to resolve, all bounded by the shutdown
+   * grace period. Unlike a signal-driven shutdown, this does not re-raise a
+   * signal or exit the process. The caller owns process lifetime.
+   *
+   * Idempotent: concurrent or repeated calls share a single drain. Safe to
+   * call even if nothing has been started.
+   *
+   * @example
+   * ```ts
+   * const registry = setup({ use: { counter } });
+   * registry.start();
+   * // ...later, on your own shutdown trigger:
+   * await registry.shutdown();
+   * ```
+   */
+  async shutdown() {
+    if (this.#shutdownInFlight !== null) return this.#shutdownInFlight;
+    const config = this.parseConfig();
+    this.#removeSignalHandlers();
+    this.#shutdownInFlight = this.#drain(config).catch((err) => {
       logger2().warn({ err }, "shutdown error");
     });
+    return this.#shutdownInFlight;
   }
-  async #runShutdown(signal, config, configuredRegistryPromise) {
+  async #drain(config) {
     var _a;
-    const gracePeriodMs = ((_a = config.shutdown) == null ? void 0 : _a.gracePeriodMs) ?? await this.#actorStopThresholdMs(configuredRegistryPromise) ?? 30 * 60 * 1e3;
+    const modeAPromise = this.#runtimeServeConfiguredPromise;
+    const modeBPromise = this.#runtimeServerlessPromise;
+    const gracePeriodMs = ((_a = config.shutdown) == null ? void 0 : _a.gracePeriodMs) ?? await this.#actorStopThresholdMs(modeAPromise ?? modeBPromise) ?? 30 * 60 * 1e3;
     const drain = async () => {
-      const registries = [
-        (async () => {
-          try {
-            const { runtime, registry } = await configuredRegistryPromise;
-            await runtime.shutdownRegistry(registry);
-          } catch (err) {
-            logger2().warn(
-              { err },
-              "runtime registry shutdown errored (mode A)"
-            );
-          }
-        })()
-      ];
-      const runtimeServerlessPromise = this.#runtimeServerlessPromise;
-      if (runtimeServerlessPromise !== void 0) {
+      const registries = [];
+      if (modeAPromise !== void 0) {
         registries.push(
           (async () => {
             try {
-              const { runtime, registry } = await runtimeServerlessPromise;
+              const { runtime, registry } = await modeAPromise;
               await runtime.shutdownRegistry(registry);
             } catch (err) {
               logger2().warn(
                 { err },
+                "runtime registry shutdown errored (mode A)"
+              );
+            }
+          })()
+        );
+      }
+      if (modeBPromise !== void 0) {
+        registries.push(
+          (async () => {
+            try {
+              const { runtime, registry } = await modeBPromise;
+              await runtime.shutdownRegistry(registry);
+            } catch (err) {
+              logger2().warn(
+                { error: err },
                 "runtime registry shutdown errored (mode B)"
               );
             }
@@ -5886,11 +6168,10 @@ var Registry = class {
         }
       )
     ]);
-    this.#removeSignalHandlers();
-    finishShutdownSignal(signal);
   }
   async #actorStopThresholdMs(configuredRegistryPromise) {
     var _a;
+    if (configuredRegistryPromise === void 0) return void 0;
     try {
       const { runtime, registry } = await configuredRegistryPromise;
       const thresholdMs = await ((_a = runtime.registryActorStopThresholdMs) == null ? void 0 : _a.call(runtime, registry));