rivetkit 0.0.0-main.9809768 → 0.0.0-main.9d355a2

package/dist/browser/client.d.ts

@@ -1,26 +1,17 @@
+import * as _rivetkit_rivetkit_wasm from '@rivetkit/rivetkit-wasm';
 import { z as z$2 } from 'zod';
 import z$1, { z } from 'zod/v4';
-import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
 import { Context, Handler, Hono } from 'hono';
+import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ContentfulStatusCode } from 'hono/utils/http-status';
 import { Logger } from 'pino';
 
-interface SqliteVfsMetrics {
-    requestBuildNs: number;
-    serializeNs: number;
-    transportNs: number;
-    stateUpdateNs: number;
-    totalNs: number;
-    commitCount: number;
-}
-
 type AnyDatabaseProvider = DatabaseProvider<any> | undefined;
 interface ActorMetricsLike {
     totalKvReads: number;
     totalKvWrites: number;
     trackSql(query: string, durationMs: number): void;
-    setSqliteVfsMetricsSource(source?: () => SqliteVfsMetrics | null): void;
 }
 type InferDatabaseClient<DBProvider extends AnyDatabaseProvider> = DBProvider extends DatabaseProvider<any> ? Awaited<ReturnType<DBProvider["createClient"]>> : never;
 type SqliteBindings = unknown[] | Record<string, unknown>;
@@ -28,11 +19,29 @@ interface SqliteQueryResult {
     columns: string[];
     rows: unknown[][];
 }
+interface SqliteExecuteResult extends SqliteQueryResult {
+    changes: number;
+    lastInsertRowId?: number | null;
+}
+interface SqliteNativeMetrics {
+    requestBuildNs: number;
+    serializeNs: number;
+    transportNs: number;
+    stateUpdateNs: number;
+    totalNs: number;
+    commitCount: number;
+    pageCacheEntries: number;
+    pageCacheWeightedSize: number;
+    pageCacheCapacityPages: number;
+    writeBufferDirtyPages: number;
+    dbSizePages: number;
+}
 interface SqliteDatabase {
     exec(sql: string, callback?: (row: unknown[], columns: string[]) => void): Promise<void>;
+    execute(sql: string, params?: SqliteBindings): Promise<SqliteExecuteResult>;
     run(sql: string, params?: SqliteBindings): Promise<void>;
     query(sql: string, params?: SqliteBindings): Promise<SqliteQueryResult>;
-    getSqliteVfsMetrics?: () => SqliteVfsMetrics | null;
+    nativeMetrics?(): SqliteNativeMetrics | Promise<SqliteNativeMetrics | null> | null;
     close(): Promise<void>;
 }
 /**
@@ -94,14 +103,17 @@ type DatabaseProvider<DB extends RawAccess> = {
 /**
  * Drizzle database client interface (will be extended by drizzle-orm types)
  */
-interface DrizzleDatabaseClient {
-}
+type DrizzleDatabaseClient = {};
 type ExecuteFunction = <TRow extends Record<string, unknown> = Record<string, unknown>>(query: string, ...args: unknown[]) => Promise<TRow[]>;
 type RawAccess = {
     /**
      * Executes a raw SQL query.
      */
     execute: ExecuteFunction;
+    /**
+     * Returns native SQLite metrics when the active runtime supports them.
+     */
+    nativeMetrics?: () => SqliteNativeMetrics | Promise<SqliteNativeMetrics | null> | null;
     /**
      * Closes the database connection and releases resources.
      */
@@ -169,6 +181,44 @@ type ActorQuery = z.infer<typeof ActorQuerySchema>;
  */
 type CreateRequest = z.infer<typeof CreateRequestSchema>;
 
+type SchemaHookResult = boolean | Promise<boolean>;
+type SchemaHook<TContext = any> = (ctx: TContext) => SchemaHookResult;
+interface EventTypeToken<T, TContext = any> {
+    readonly _eventType?: T;
+    readonly canSubscribe?: SchemaHook<TContext>;
+    readonly schema?: PrimitiveSchema;
+}
+interface QueueTypeToken<TMessage, TComplete = never, TContext = any> {
+    readonly _queueMessage?: TMessage;
+    readonly _queueComplete?: TComplete;
+    readonly canPublish?: SchemaHook<TContext>;
+    readonly message?: PrimitiveSchema;
+    readonly complete?: PrimitiveSchema;
+}
+type PrimitiveSchema = StandardSchemaV1 | EventTypeToken<unknown, any>;
+interface EventSchemaDefinition<TContext = any> {
+    schema: PrimitiveSchema;
+    canSubscribe?: SchemaHook<TContext>;
+}
+interface QueueSchemaDefinition<TContext = any> {
+    message: PrimitiveSchema;
+    complete?: PrimitiveSchema;
+    canPublish?: SchemaHook<TContext>;
+}
+type EventSchema<TContext = any> = PrimitiveSchema | EventSchemaDefinition<TContext>;
+type QueueSchema = PrimitiveSchema | QueueSchemaDefinition<any> | QueueTypeToken<unknown, unknown, any>;
+type EventSchemaConfig<TContext = any> = Record<string, EventSchema<TContext>>;
+type QueueSchemaConfig<_TContext = any> = Record<string, QueueSchema>;
+type InferSchema<T> = T extends QueueSchemaDefinition<any> ? InferSchema<T["message"]> : T extends QueueTypeToken<infer M, unknown, any> ? M : T extends EventSchemaDefinition<any> ? InferSchema<T["schema"]> : T extends StandardSchemaV1<any, infer O> ? O : T extends EventTypeToken<infer R, any> ? R : never;
+type InferSchemaMap<T extends Record<string, unknown>> = {
+    [K in keyof T]: InferSchema<T[K]>;
+};
+type InferQueueComplete<T> = T extends QueueTypeToken<unknown, infer C, any> ? [C] extends [never] ? never : C : T extends QueueSchemaDefinition<any> ? T["complete"] extends PrimitiveSchema ? InferSchema<T["complete"]> : never : never;
+type InferQueueCompleteMap<T extends QueueSchemaConfig> = {
+    [K in keyof T]: InferQueueComplete<T[K]>;
+};
+type InferEventArgs<T> = T extends readonly unknown[] ? number extends T["length"] ? [T] : T : [T];
+
 interface DeconstructedError {
     __type: "ActorError";
     statusCode: ContentfulStatusCode;
@@ -177,6 +227,7 @@ interface DeconstructedError {
     code: string;
     message: string;
     metadata?: unknown;
+    actor?: ActorSpecifier;
 }
 
 interface RivetErrorOptions extends ErrorOptions {
@@ -186,6 +237,14 @@ interface RivetErrorOptions extends ErrorOptions {
     metadata?: unknown;
     /** Explicit HTTP status override for router responses. */
     statusCode?: number;
+    /** Actor context associated with this error. */
+    actor?: ActorSpecifier;
+}
+/** Identifies the actor that was handling work when an error was produced. */
+interface ActorSpecifier {
+    actorId: string;
+    generation: number;
+    key?: string;
 }
 interface UserErrorOptions extends ErrorOptions {
     /**
@@ -204,6 +263,7 @@ declare class RivetError extends Error {
     public: boolean;
     metadata?: unknown;
     statusCode: number;
+    actor?: ActorSpecifier;
     readonly group: string;
     readonly code: string;
     static isRivetError(error: unknown): error is RivetError | DeconstructedError;
@@ -216,61 +276,26 @@ declare class UserError extends RivetError {
     constructor(message: string, options?: UserErrorOptions);
 }
 
-type SchemaHookResult = boolean | Promise<boolean>;
-type SchemaHook<TContext = any> = (ctx: TContext) => SchemaHookResult;
-interface EventTypeToken<T, TContext = any> {
-    readonly _eventType?: T;
-    readonly canSubscribe?: SchemaHook<TContext>;
-    readonly schema?: PrimitiveSchema;
-}
-interface QueueTypeToken<TMessage, TComplete = never, TContext = any> {
-    readonly _queueMessage?: TMessage;
-    readonly _queueComplete?: TComplete;
-    readonly canPublish?: SchemaHook<TContext>;
-    readonly message?: PrimitiveSchema;
-    readonly complete?: PrimitiveSchema;
-}
-type PrimitiveSchema = StandardSchemaV1 | EventTypeToken<unknown, any>;
-interface EventSchemaDefinition<TContext = any> {
-    schema: PrimitiveSchema;
-    canSubscribe?: SchemaHook<TContext>;
-}
-interface QueueSchemaDefinition<TContext = any> {
-    message: PrimitiveSchema;
-    complete?: PrimitiveSchema;
-    canPublish?: SchemaHook<TContext>;
-}
-type EventSchema<TContext = any> = PrimitiveSchema | EventSchemaDefinition<TContext>;
-type QueueSchema = PrimitiveSchema | QueueSchemaDefinition<any> | QueueTypeToken<unknown, unknown, any>;
-type EventSchemaConfig<TContext = any> = Record<string, EventSchema<TContext>>;
-type QueueSchemaConfig<TContext = any> = Record<string, QueueSchema>;
-type InferSchema<T> = T extends QueueSchemaDefinition<any> ? InferSchema<T["message"]> : T extends QueueTypeToken<infer M, unknown, any> ? M : T extends EventSchemaDefinition<any> ? InferSchema<T["schema"]> : T extends StandardSchemaV1<any, infer O> ? O : T extends EventTypeToken<infer R, any> ? R : never;
-type InferSchemaMap<T extends Record<string, unknown>> = {
-    [K in keyof T]: InferSchema<T[K]>;
-};
-type InferQueueComplete<T> = T extends QueueTypeToken<unknown, infer C, any> ? [C] extends [never] ? never : C : T extends QueueSchemaDefinition<any> ? T["complete"] extends PrimitiveSchema ? InferSchema<T["complete"]> : never : never;
-type InferQueueCompleteMap<T extends QueueSchemaConfig> = {
-    [K in keyof T]: InferQueueComplete<T[K]>;
-};
-type InferEventArgs<T> = T extends readonly unknown[] ? number extends T["length"] ? [T] : T : [T];
-
 type UpgradeWebSocket = (createEvents: (c: Context) => any) => Handler;
 type GetUpgradeWebSocket = () => UpgradeWebSocket;
 
 type GatewayTarget = {
     directId: string;
 } | ActorQuery;
+interface GatewayRequestOptions {
+    skipReadyWait?: boolean;
+}
 interface EngineControlClient {
     getForId(input: GetForIdInput): Promise<ActorOutput | undefined>;
     getWithKey(input: GetWithKeyInput): Promise<ActorOutput | undefined>;
     getOrCreateWithKey(input: GetOrCreateWithKeyInput): Promise<ActorOutput>;
     createActor(input: CreateInput): Promise<ActorOutput>;
     listActors(input: ListActorsInput): Promise<ActorOutput[]>;
-    sendRequest(target: GatewayTarget, actorRequest: Request): Promise<Response>;
-    openWebSocket(path: string, target: GatewayTarget, encoding: Encoding, params: unknown): Promise<UniversalWebSocket>;
+    sendRequest(target: GatewayTarget, actorRequest: Request, options?: GatewayRequestOptions): Promise<Response>;
+    openWebSocket(path: string, target: GatewayTarget, encoding: Encoding, params: unknown, options?: GatewayRequestOptions): Promise<UniversalWebSocket>;
     proxyRequest(c: Context, actorRequest: Request, actorId: string): Promise<Response>;
     proxyWebSocket(c: Context, path: string, actorId: string, encoding: Encoding, params: unknown): Promise<Response>;
-    buildGatewayUrl(target: GatewayTarget): Promise<string>;
+    buildGatewayUrl(target: GatewayTarget, options?: GatewayRequestOptions): Promise<string>;
     displayInformation(): RuntimeDisplayInformation;
     extraStartupLog?: () => Record<string, unknown>;
     modifyRuntimeRouter?: (config: RegistryConfig, router: Hono) => void;
@@ -358,12 +383,25 @@ interface QueueSendResult<TResponse = unknown> {
  * @returns {Promise<Response>}
  */
 type ActorActionFunction<Args extends Array<unknown> = unknown[], Response = unknown> = (...args: Args extends [unknown, ...infer Rest] ? Rest : Args) => Promise<Response>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type LooseEventSubscribe = (eventName: string, callback: (...args: any[]) => void) => () => void;
+type ActorActionMap<R> = {
+    [K in keyof NonNullable<R>]: NonNullable<R>[K] extends (...args: infer Args) => infer Return ? ActorActionFunction<Args, Awaited<Return>> : never;
+};
+type ActionsOf<AD extends AnyActorDefinition> = AD extends BaseActorDefinition<any, any, any, any, any, any, any, any, infer R> ? R : never;
+interface ActorGatewayOptions {
+    skipReadyWait?: boolean;
+}
+interface ActorActionOptions extends ActorGatewayOptions {
+    signal?: AbortSignal;
+}
+type ActorConnectOptions = ActorGatewayOptions;
+type ActorFetchInit = RequestInit & ActorGatewayOptions;
+type ActorWebSocketOptions = ActorGatewayOptions;
 /**
  * Maps action methods from actor definition to typed function signatures.
  */
-type ActorDefinitionActions<AD extends AnyActorDefinition> = AD extends BaseActorDefinition<any, any, any, any, any, any, any, any, infer R> ? {
-    [K in keyof R]: R[K] extends (...args: infer Args) => infer Return ? ActorActionFunction<Args, Return> : never;
-} : never;
+type ActorDefinitionActions<AD extends AnyActorDefinition> = IsAny<AD> extends true ? Record<string, ActorActionFunction<any[], any>> : ActorActionMap<ActionsOf<AD>>;
 type ActorQueueSend<TQueues extends QueueSchemaConfig> = {
     <K extends keyof TQueues & string>(name: K, body: InferSchemaMap<TQueues>[K], options: QueueSendWaitOptions): Promise<QueueSendResult<InferQueueCompleteMap<TQueues>[K]>>;
     <K extends keyof TQueues & string>(name: K, body: InferSchemaMap<TQueues>[K], options?: QueueSendNoWaitOptions): Promise<void>;
@@ -374,13 +412,31 @@ type ActorEventSubscribe<TEvents extends EventSchemaConfig> = {
     <K extends keyof TEvents & string>(eventName: K, callback: (...args: InferEventArgs<InferSchemaMap<TEvents>[K]>) => void): () => void;
     (eventName: keyof TEvents extends never ? string : never, callback: (...args: any[]) => void): () => void;
 };
-type ActorDefinitionQueueSend<AD extends AnyActorDefinition> = AD extends BaseActorDefinition<any, any, any, any, any, any, any, infer Q, any> ? Q extends QueueSchemaConfig ? {
+type ActorDefinitionQueueSend<AD extends AnyActorDefinition> = IsAny<AD> extends true ? {
+    send: ActorQueueSend<Record<string, any>>;
+} : AD extends {
+    config: {
+        queues?: infer Q;
+    };
+} ? Q extends QueueSchemaConfig ? {
+    send: ActorQueueSend<Q>;
+} : {} : AD extends BaseActorDefinition<any, any, any, any, any, any, any, infer Q, any> ? Q extends QueueSchemaConfig ? {
     send: ActorQueueSend<Q>;
-} : never : never;
-type ActorDefinitionEventSubscriptions<AD extends AnyActorDefinition> = AD extends BaseActorDefinition<any, any, any, any, any, any, infer E, any, any> ? E extends EventSchemaConfig ? {
+} : {} : {};
+type ActorDefinitionEventSubscriptions<AD extends AnyActorDefinition> = IsAny<AD> extends true ? {
+    on: LooseEventSubscribe;
+    once: LooseEventSubscribe;
+} : AD extends {
+    config: {
+        events?: infer E;
+    };
+} ? E extends EventSchemaConfig ? {
     on: ActorEventSubscribe<E>;
     once: ActorEventSubscribe<E>;
-} : never : never;
+} : {} : AD extends BaseActorDefinition<any, any, any, any, any, any, infer E, any, any> ? E extends EventSchemaConfig ? {
+    on: ActorEventSubscribe<E>;
+    once: ActorEventSubscribe<E>;
+} : {} : {};
 
 declare class ActorClientError extends Error {
 }
@@ -445,7 +501,7 @@ declare class ActorConnRaw {
      *
      * @protected
      */
-    constructor(client: ClientRaw, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState);
+    constructor(client: ClientRaw, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions);
     send(name: string, body: unknown, options: QueueSendWaitOptions): Promise<QueueSendResult>;
     send(name: string, body: unknown, options?: QueueSendNoWaitOptions): Promise<void>;
     /**
@@ -510,6 +566,10 @@ declare class ActorConnRaw {
      * @returns {boolean} - True if the connection is open, false otherwise.
      */
     get isConnected(): boolean;
+    /**
+     * Resolves when this connection first reaches the connected state.
+     */
+    get ready(): Promise<void>;
     /**
      * Subscribes to connection open events.
      *
@@ -577,7 +637,7 @@ declare class ActorHandleRaw {
      *
      * @protected
      */
-    constructor(client: any, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState);
+    constructor(client: any, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions);
     send(name: string, body: unknown, options: QueueSendWaitOptions): Promise<QueueSendResult>;
     send(name: string, body: unknown, options?: QueueSendNoWaitOptions): Promise<void>;
     /**
@@ -590,24 +650,23 @@ declare class ActorHandleRaw {
     action<Args extends Array<unknown> = unknown[], Response = unknown>(opts: {
         name: string;
         args: Args;
-        signal?: AbortSignal;
-    }): Promise<Response>;
+    } & ActorActionOptions): Promise<Response>;
     /**
      * Establishes a persistent connection to the actor.
      *
      * @template AD The actor class that this connection is for.
      * @returns {ActorConn<AD>} A connection to the actor.
      */
-    connect(params?: unknown): ActorConn<AnyActorDefinition>;
+    connect(params?: unknown, options?: ActorConnectOptions): ActorConn<AnyActorDefinition>;
     /**
      * Fetches a resource from this actor via the /request endpoint. This is a
      * convenience wrapper around the raw HTTP API.
      */
-    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    fetch(input: string | URL | Request, init?: ActorFetchInit): Promise<Response>;
     /**
      * Opens a raw WebSocket connection to this actor.
      */
-    webSocket(path?: string, protocols?: string | string[]): Promise<any>;
+    webSocket(path?: string, protocols?: string | string[], options?: ActorWebSocketOptions): Promise<any>;
     /**
      * Resolves the actor to get its unique actor ID.
      */
@@ -635,7 +694,7 @@ declare class ActorHandleRaw {
  * @see {@link ActorHandleRaw}
  */
 type ActorHandle<AD extends AnyActorDefinition> = Omit<ActorHandleRaw, "connect" | "send"> & {
-    connect(params?: unknown): ActorConn<AD>;
+    connect(params?: unknown, options?: ActorConnectOptions): ActorConn<AD>;
     resolve(): Promise<string>;
 } & ActorDefinitionQueueSend<AD> & ActorDefinitionActions<AD>;
 
@@ -650,6 +709,9 @@ declare const ClientConfigSchema: z$1.ZodPipe<z$1.ZodObject<{
         bare: "bare";
     }>>;
     headers: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>>;
+    gateway: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodObject<{
+        skipReadyWait: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+    }, z$1.core.$strip>>>;
     getUpgradeWebSocket: z$1.ZodOptional<z$1.ZodCustom<GetUpgradeWebSocket, GetUpgradeWebSocket>>;
     disableMetadataLookup: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
     maxInputSize: z$1.ZodDefault<z$1.ZodNumber>;
@@ -661,6 +723,9 @@ declare const ClientConfigSchema: z$1.ZodPipe<z$1.ZodObject<{
     poolName: string;
     encoding: "json" | "cbor" | "bare";
     headers: Record<string, string>;
+    gateway: {
+        skipReadyWait: boolean;
+    };
     disableMetadataLookup: boolean;
     maxInputSize: number;
     devtools: boolean;
@@ -672,6 +737,9 @@ declare const ClientConfigSchema: z$1.ZodPipe<z$1.ZodObject<{
     poolName: string;
     encoding: "json" | "cbor" | "bare";
     headers: Record<string, string>;
+    gateway: {
+        skipReadyWait: boolean;
+    };
     disableMetadataLookup: boolean;
     maxInputSize: number;
     devtools: boolean;
@@ -821,7 +889,7 @@ declare class ClientRaw {
     /**
      * Creates an instance of Client.
      */
-    constructor(driver: EngineControlClient, encoding: Encoding | undefined);
+    constructor(driver: EngineControlClient, encoding: Encoding | undefined, gatewayOptions?: ActorGatewayOptions);
     /**
      * Gets a stateless handle to a actor by its ID.
      *
@@ -882,6 +950,7 @@ type Client<A extends Registry<any>> = ClientRaw & {
 };
 
 declare const ACTOR_CONTEXT_INTERNAL_SYMBOL: unique symbol;
+declare const RAW_STATE_SYMBOL: unique symbol;
 interface ActorLogger {
     level: any;
     fatal: any;
@@ -914,6 +983,10 @@ type ActorKvListOptions<T extends ActorKvValueType = "text", K extends ActorKvKe
     limit?: number;
 };
 type ActorClientFor<T> = T extends Registry<any> ? Client<T> : T;
+/**
+ * @deprecated Actor KV is deprecated. Use embedded SQLite (`c.db` / `c.sql`)
+ * or actor state instead.
+ */
 interface ActorKv {
     get<T extends ActorKvValueType = "text">(key: Uint8Array | string, options?: ActorKvValueOptions<T>): Promise<ActorKvValueTypeMap[T] | null>;
     put<T extends ActorKvValueType = "text">(key: Uint8Array | string, value: Uint8Array | string | ArrayBuffer, options?: ActorKvValueOptions<T>): Promise<void>;
@@ -990,7 +1063,7 @@ interface ActorQueue<TQueues extends QueueSchemaConfig = Record<never, never>> {
     iter<const TName extends QueueFilterName<TQueues>, const TCompletable extends boolean = false>(opts?: QueueIterOptions<TName, TCompletable>): AsyncIterable<any>;
     [key: string]: any;
 }
-interface Conn<TState = unknown, TConnParams = unknown, TConnState = unknown, TVars = unknown, TInput = unknown, TDatabase extends AnyDatabaseProvider = AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> {
+interface Conn<_TState = unknown, TConnParams = unknown, TConnState = unknown, _TVars = unknown, _TInput = unknown, _TDatabase extends AnyDatabaseProvider = AnyDatabaseProvider, _TEvents extends EventSchemaConfig = Record<never, never>, _TQueues extends QueueSchemaConfig = Record<never, never>> {
     id: string;
     params: TConnParams;
     state: TConnState;
@@ -1001,8 +1074,14 @@ interface Conn<TState = unknown, TConnParams = unknown, TConnState = unknown, TV
 }
 interface ActorContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> {
     [ACTOR_CONTEXT_INTERNAL_SYMBOL]?: unknown;
+    /** Returns the raw unwrapped state without the write-through proxy. */
+    [RAW_STATE_SYMBOL](): TState;
     state: TState;
     vars: TVars;
+    /**
+     * @deprecated Actor KV is deprecated. Use embedded SQLite (`db` / `sql`)
+     * or actor state instead.
+     */
     readonly kv: ActorKv;
     readonly db: InferDatabaseClient<TDatabase>;
     readonly schedule: ActorSchedule;
@@ -1127,8 +1206,27 @@ declare const ActorConfigSchema: z.ZodObject<{
         preloadMaxWorkflowBytes: z.ZodOptional<z.ZodNumber>;
         preloadMaxConnectionsBytes: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    inspector: z.ZodOptional<z.ZodObject<{
+        tabs: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            source: z.ZodString;
+            icon: z.ZodOptional<z.ZodString>;
+            hidden: z.ZodOptional<z.ZodLiteral<false>>;
+        }, z.core.$strict>, z.ZodObject<{
+            id: z.ZodEnum<{
+                state: "state";
+                workflow: "workflow";
+                database: "database";
+                queue: "queue";
+                connections: "connections";
+                console: "console";
+            }>;
+            hidden: z.ZodLiteral<true>;
+        }, z.core.$strict>]>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
-type CreateState<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig, TQueues extends QueueSchemaConfig> = {
+type CreateState<TState, _TConnParams, _TConnState, _TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig, TQueues extends QueueSchemaConfig> = {
     state: TState;
 } | {
     createState: (c: CreateContext<TState, TInput, TDatabase, TEvents, TQueues>, input: TInput) => TState | Promise<TState>;
@@ -1141,7 +1239,7 @@ type CreateConnState<TState, TConnParams, TConnState, TVars, TInput, TDatabase e
 /**
  * @experimental
  */
-type CreateVars<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig, TQueues extends QueueSchemaConfig> = {
+type CreateVars<TState, _TConnParams, _TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig, TQueues extends QueueSchemaConfig> = {
     /**
      * @experimental
      */
@@ -1209,7 +1307,7 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
      * shutdown window (`sleepGracePeriod`) cover deferred work.
      *
      * The handler receives an abort signal via `c.abortSignal` and a
-     * `c.aborted` alias for loop checks. Use these to gracefully exit.
+     * `c.aborted` alias. Use these to gracefully exit when shutdown starts.
      *
      * If this handler exits, the actor will follow the normal idle sleep timeout
      * once it becomes idle.
@@ -1238,10 +1336,11 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
      * Called before a client connects to the actor.
      *
      * Use this hook to determine if a connection should be accepted
-     * and to initialize connection-specific state.
+     * and to validate client-provided parameters. The pending connection
+     * is not visible in `c.conns` while this hook runs.
      *
      * @param opts Connection parameters including client-provided data
-     * @returns The initial connection state or a Promise that resolves to it
+     * @returns Void or a Promise.
      * @throws Throw an error to reject the connection
      */
     onBeforeConnect?: (c: BeforeConnectContext<TState, TVars, TInput, TDatabase, TEvents, TQueues>, params: TConnParams) => void | Promise<void>;
@@ -1249,7 +1348,8 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
      * Called when a client successfully connects to the actor.
      *
      * Use this hook to perform actions when a connection is established,
-     * such as sending initial data or updating the actor's state.
+     * such as sending initial data or updating the actor's state. The
+     * connection is visible in `c.conns` before this hook runs.
      *
      * @param conn The connection object
      * @returns Void or a Promise that resolves when connection handling is complete
@@ -1325,27 +1425,55 @@ type ActorDatabaseConfig<TDatabase extends AnyDatabaseProvider> = {
      */
     db: TDatabase;
 } | Record<never, never>;
-type ActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> = Omit<z.infer<typeof ActorConfigSchema>, "actions" | "events" | "queues" | "onCreate" | "onDestroy" | "onMigrate" | "onWake" | "onSleep" | "run" | "onStateChange" | "onBeforeConnect" | "onConnect" | "onDisconnect" | "onBeforeActionResponse" | "onRequest" | "onWebSocket" | "state" | "createState" | "connState" | "createConnState" | "vars" | "createVars" | "db"> & BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues, Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>> & CreateState<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & CreateConnState<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & CreateVars<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & ActorDatabaseConfig<TDatabase>;
+type ActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>, TActions extends Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> = Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>> = Omit<z.infer<typeof ActorConfigSchema>, "actions" | "events" | "queues" | "onCreate" | "onDestroy" | "onMigrate" | "onWake" | "onSleep" | "run" | "onStateChange" | "onBeforeConnect" | "onConnect" | "onDisconnect" | "onBeforeActionResponse" | "onRequest" | "onWebSocket" | "state" | "createState" | "connState" | "createConnState" | "vars" | "createVars" | "db"> & BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues, TActions> & CreateState<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & CreateConnState<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & CreateVars<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & ActorDatabaseConfig<TDatabase>;
 
-interface BaseActorDefinition<S, CP, CS, V, I, DB extends AnyDatabaseProvider, E extends EventSchemaConfig = Record<never, never>, Q extends QueueSchemaConfig = Record<never, never>, R extends Actions<S, CP, CS, V, I, DB, E, Q> = Actions<S, CP, CS, V, I, DB, E, Q>> {
-    readonly config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+interface BaseActorDefinition<S, CP, CS, V, I, DB extends AnyDatabaseProvider, E extends EventSchemaConfig = Record<never, never>, Q extends QueueSchemaConfig = Record<never, never>, _R extends Actions<S, CP, CS, V, I, DB, E, Q> = Actions<S, CP, CS, V, I, DB, E, Q>> {
+    readonly config: ActorConfig<S, CP, CS, V, I, DB, E, Q, _R>;
+}
+interface AnyActorDefinition {
+    readonly config: any;
 }
-type AnyActorDefinition = BaseActorDefinition<any, any, any, any, any, any, any, any, any>;
 declare class ActorDefinition<S, CP, CS, V, I, DB extends AnyDatabaseProvider, E extends EventSchemaConfig = Record<never, never>, Q extends QueueSchemaConfig = Record<never, never>, R extends Actions<S, CP, CS, V, I, DB, E, Q> = Actions<S, CP, CS, V, I, DB, E, Q>> implements BaseActorDefinition<S, CP, CS, V, I, DB, E, Q, R> {
     #private;
-    constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q>);
-    get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+    constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q, R>);
+    get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q, R>;
 }
 
-declare const ActorsSchema: z$2.ZodRecord<z$2.ZodString, z$2.ZodCustom<BaseActorDefinition<any, any, any, any, any, any, any, any, any>, BaseActorDefinition<any, any, any, any, any, any, any, any, any>>>;
+declare const ActorsSchema: z$2.ZodRecord<z$2.ZodString, z$2.ZodCustom<AnyActorDefinition, AnyActorDefinition>>;
 type RegistryActors = z$2.infer<typeof ActorsSchema>;
 declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     use: z$2.ZodRecord<z$2.ZodString, z$2.ZodCustom<AnyActorDefinition, AnyActorDefinition>>;
     test: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodObject<{
-        enabled: z$2.ZodBoolean;
+        enabled: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodBoolean>>;
+        sqliteBackend: z$2.ZodOptional<z$2.ZodEnum<{
+            local: "local";
+            remote: "remote";
+        }>>;
     }, z$2.core.$strip>>>;
     maxIncomingMessageSize: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodNumber>>;
     maxOutgoingMessageSize: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodNumber>>;
+    runtime: z$2.ZodPipe<z$2.ZodOptional<z$2.ZodEnum<{
+        auto: "auto";
+        native: "native";
+        wasm: "wasm";
+    }>>, z$2.ZodTransform<"auto" | "native" | "wasm", "auto" | "native" | "wasm" | undefined>>;
+    wasm: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodObject<{
+        bindings: z$2.ZodOptional<z$2.ZodCustom<typeof _rivetkit_rivetkit_wasm, typeof _rivetkit_rivetkit_wasm>>;
+        initInput: z$2.ZodOptional<z$2.ZodCustom<_rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined, _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined>>;
+    }, z$2.core.$strip>>>;
+    sqlite: z$2.ZodPipe<z$2.ZodOptional<z$2.ZodUnion<readonly [z$2.ZodEnum<{
+        local: "local";
+        remote: "remote";
+    }>, z$2.ZodObject<{
+        backend: z$2.ZodEnum<{
+            local: "local";
+            remote: "remote";
+        }>;
+    }, z$2.core.$strip>]>>, z$2.ZodTransform<{
+        backend: "local" | "remote";
+    } | undefined, "local" | "remote" | {
+        backend: "local" | "remote";
+    } | undefined>>;
     noWelcome: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodBoolean>>;
     logging: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodObject<{
         baseLogger: z$2.ZodOptional<z$2.ZodCustom<Logger, Logger>>;
@@ -1368,12 +1496,15 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     httpPort: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodNumber>>;
     httpHost: z$2.ZodOptional<z$2.ZodString>;
     startEngine: z$2.ZodDefault<z$2.ZodBoolean>;
+    engineHost: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodString>>;
+    enginePort: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodNumber>>;
     engineVersion: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodString>>;
     configurePool: z$2.ZodOptional<z$2.ZodOptional<z$2.ZodObject<{
         name: z$2.ZodOptional<z$2.ZodString>;
         url: z$2.ZodString;
         headers: z$2.ZodOptional<z$2.ZodRecord<z$2.ZodString, z$2.ZodString>>;
         requestLifespan: z$2.ZodOptional<z$2.ZodNumber>;
+        drainGracePeriod: z$2.ZodOptional<z$2.ZodNumber>;
         metadata: z$2.ZodOptional<z$2.ZodRecord<z$2.ZodString, z$2.ZodUnknown>>;
         metadataPollInterval: z$2.ZodOptional<z$2.ZodNumber>;
         drainOnVersionUpgrade: z$2.ZodOptional<z$2.ZodBoolean>;
@@ -1391,10 +1522,13 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
         envoyKey: z$2.ZodOptional<z$2.ZodString>;
     }, z$2.core.$strip>>>;
     shutdown: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodObject<{
-        gracePeriodMs: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodNumber>>;
+        gracePeriodMs: z$2.ZodOptional<z$2.ZodNumber>;
         disableSignalHandlers: z$2.ZodDefault<z$2.ZodOptional<z$2.ZodBoolean>>;
     }, z$2.core.$strip>>>;
 }, z$2.core.$strip>, z$2.ZodTransform<{
+    sqlite: {
+        backend: "local" | "remote";
+    } | undefined;
     endpoint: string | undefined;
     namespace: string;
     token: string | undefined;
@@ -1411,9 +1545,15 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     use: Record<string, AnyActorDefinition>;
     test: {
         enabled: boolean;
+        sqliteBackend?: "local" | "remote" | undefined;
     };
     maxIncomingMessageSize: number;
     maxOutgoingMessageSize: number;
+    runtime: "auto" | "native" | "wasm";
+    wasm: {
+        bindings?: typeof _rivetkit_rivetkit_wasm | undefined;
+        initInput?: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
+    };
     noWelcome: boolean;
     logging: {
         baseLogger?: Logger | undefined;
@@ -1423,6 +1563,8 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     httpBasePath: string;
     httpPort: number;
     startEngine: boolean;
+    engineHost: string;
+    enginePort: number;
     engineVersion: string;
     envoy: {
         poolName: string;
@@ -1431,8 +1573,8 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
         envoyKey?: string | undefined;
     };
     shutdown: {
-        gracePeriodMs: number;
         disableSignalHandlers: boolean;
+        gracePeriodMs?: number | undefined;
     };
     staticDir?: string | undefined;
     httpHost?: string | undefined;
@@ -1441,6 +1583,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
         name?: string | undefined;
         headers?: Record<string, string> | undefined;
         requestLifespan?: number | undefined;
+        drainGracePeriod?: number | undefined;
         metadata?: Record<string, unknown> | undefined;
         metadataPollInterval?: number | undefined;
         drainOnVersionUpgrade?: boolean | undefined;
@@ -1449,9 +1592,18 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     use: Record<string, AnyActorDefinition>;
     test: {
         enabled: boolean;
+        sqliteBackend?: "local" | "remote" | undefined;
     };
     maxIncomingMessageSize: number;
     maxOutgoingMessageSize: number;
+    runtime: "auto" | "native" | "wasm";
+    wasm: {
+        bindings?: typeof _rivetkit_rivetkit_wasm | undefined;
+        initInput?: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
+    };
+    sqlite: {
+        backend: "local" | "remote";
+    } | undefined;
     noWelcome: boolean;
     logging: {
         baseLogger?: Logger | undefined;
@@ -1464,6 +1616,8 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     httpBasePath: string;
     httpPort: number;
     startEngine: boolean;
+    engineHost: string;
+    enginePort: number;
     engineVersion: string;
     serverless: {
         basePath: string;
@@ -1478,8 +1632,8 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
         envoyKey?: string | undefined;
     };
     shutdown: {
-        gracePeriodMs: number;
         disableSignalHandlers: boolean;
+        gracePeriodMs?: number | undefined;
     };
     staticDir?: string | undefined;
     httpHost?: string | undefined;
@@ -1488,6 +1642,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
         name?: string | undefined;
         headers?: Record<string, string> | undefined;
         requestLifespan?: number | undefined;
+        drainGracePeriod?: number | undefined;
         metadata?: Record<string, unknown> | undefined;
         metadataPollInterval?: number | undefined;
         drainOnVersionUpgrade?: boolean | undefined;
@@ -1498,15 +1653,364 @@ type RegistryConfigInput<A extends RegistryActors> = Omit<z$2.input<typeof Regis
     use: A;
 };
 
+declare const handleBrand: unique symbol;
+type OpaqueHandle<Name extends string> = {
+    readonly [handleBrand]: Name;
+};
+type RegistryHandle = OpaqueHandle<"registry">;
+type ActorFactoryHandle = OpaqueHandle<"actorFactory">;
+type ActorContextHandle = OpaqueHandle<"actorContext">;
+type ConnHandle = OpaqueHandle<"conn">;
+type WebSocketHandle = OpaqueHandle<"webSocket">;
+type CancellationTokenHandle = OpaqueHandle<"cancellationToken">;
+type RuntimeBytes = Uint8Array;
+interface RuntimeActorKeySegment {
+    kind: string;
+    stringValue?: string;
+    numberValue?: number;
+}
+interface RuntimeHttpRequest {
+    method: string;
+    uri: string;
+    headers?: Record<string, string>;
+    body?: RuntimeBytes;
+}
+interface RuntimeStateDeltaPayload {
+    state?: RuntimeBytes;
+    connHibernation: Array<{
+        connId: string;
+        bytes: RuntimeBytes;
+    }>;
+    connHibernationRemoved: string[];
+}
+interface RuntimeRequestSaveOpts {
+    immediate?: boolean;
+    maxWaitMs?: number;
+}
+interface RuntimeInspectorSnapshot {
+    stateRevision: number;
+    connectionsRevision: number;
+    queueRevision: number;
+    activeConnections: number;
+    queueSize: number;
+    connectedClients: number;
+}
+interface RuntimeQueueMessage {
+    id(): bigint;
+    name(): string;
+    body(): RuntimeBytes;
+    createdAt(): number;
+    isCompletable(): boolean;
+    complete(response?: RuntimeBytes | undefined | null): Promise<void>;
+}
+interface RuntimeQueueInspectMessage {
+    id: number;
+    name: string;
+    createdAtMs: number;
+}
+interface RuntimeQueueNextBatchOptions {
+    names?: string[];
+    count?: number;
+    timeoutMs?: number;
+    completable?: boolean;
+}
+interface RuntimeQueueWaitOptions {
+    timeoutMs?: number;
+    completable?: boolean;
+}
+interface RuntimeQueueEnqueueAndWaitOptions {
+    timeoutMs?: number;
+}
+interface RuntimeQueueTryNextBatchOptions {
+    names?: string[];
+    count?: number;
+    completable?: boolean;
+}
+interface RuntimeKvListOptions {
+    reverse?: boolean;
+    limit?: number;
+}
+interface RuntimeKvEntry {
+    key: RuntimeBytes;
+    value: RuntimeBytes;
+}
+type RuntimeSqlBindNoValues = {
+    intValue?: never;
+    floatValue?: never;
+    textValue?: never;
+    blobValue?: never;
+};
+type RuntimeSqlBindParam = ({
+    kind: "null";
+} & RuntimeSqlBindNoValues) | {
+    kind: "int";
+    intValue: number;
+    floatValue?: never;
+    textValue?: never;
+    blobValue?: never;
+} | {
+    kind: "float";
+    intValue?: never;
+    floatValue: number;
+    textValue?: never;
+    blobValue?: never;
+} | {
+    kind: "text";
+    intValue?: never;
+    floatValue?: never;
+    textValue: string;
+    blobValue?: never;
+} | {
+    kind: "blob";
+    intValue?: never;
+    floatValue?: never;
+    textValue?: never;
+    blobValue: RuntimeBytes;
+};
+type RuntimeSqlBindParams = RuntimeSqlBindParam[] | null;
+interface RuntimeSqlQueryResult {
+    columns: string[];
+    rows: unknown[][];
+}
+type RuntimeSqlExecResult = RuntimeSqlQueryResult;
+interface RuntimeSqlExecuteResult extends RuntimeSqlQueryResult {
+    changes: number;
+    lastInsertRowId?: number | null;
+}
+interface RuntimeSqlRunResult {
+    changes: number;
+}
+interface RuntimeActorConfig {
+    name?: string;
+    icon?: string;
+    hasDatabase?: boolean;
+    remoteSqlite?: boolean;
+    hasState?: boolean;
+    canHibernateWebsocket?: boolean;
+    stateSaveIntervalMs?: number;
+    createStateTimeoutMs?: number;
+    onCreateTimeoutMs?: number;
+    createVarsTimeoutMs?: number;
+    createConnStateTimeoutMs?: number;
+    onBeforeConnectTimeoutMs?: number;
+    onConnectTimeoutMs?: number;
+    onMigrateTimeoutMs?: number;
+    onWakeTimeoutMs?: number;
+    onBeforeActorStartTimeoutMs?: number;
+    actionTimeoutMs?: number;
+    onRequestTimeoutMs?: number;
+    sleepTimeoutMs?: number;
+    noSleep?: boolean;
+    sleepGracePeriodMs?: number;
+    connectionLivenessTimeoutMs?: number;
+    connectionLivenessIntervalMs?: number;
+    maxQueueSize?: number;
+    maxQueueMessageSize?: number;
+    maxIncomingMessageSize?: number;
+    maxOutgoingMessageSize?: number;
+    preloadMaxWorkflowBytes?: number;
+    preloadMaxConnectionsBytes?: number;
+    actions?: Array<{
+        name: string;
+    }>;
+    inspectorTabs?: Array<RuntimeInspectorTabEntry>;
+}
+interface RuntimeInspectorTabEntry {
+    id: string;
+    /** Required for custom entries; omitted for built-in hides. */
+    label?: string;
+    /**
+     * Required for custom entries — absolute path to the source directory.
+     * Resolved on the TS side before being handed to the runtime.
+     */
+    source?: string;
+    /** Optional icon id for custom entries. */
+    icon?: string;
+    /** Set to true for built-in hide entries. */
+    hidden?: boolean;
+}
+interface RuntimeServeConfig {
+    version: number;
+    endpoint: string;
+    token?: string;
+    namespace: string;
+    poolName: string;
+    engineBinaryPath?: string;
+    engineHost?: string;
+    enginePort?: number;
+    handleInspectorHttpInRuntime?: boolean;
+    inspectorTestToken?: string;
+    serverlessBasePath?: string;
+    serverlessPackageVersion: string;
+    serverlessClientEndpoint?: string;
+    serverlessClientNamespace?: string;
+    serverlessClientToken?: string;
+    serverlessValidateEndpoint: boolean;
+    serverlessMaxStartPayloadBytes: number;
+}
+interface RuntimeListenerConfig {
+    port: number;
+    host?: string;
+    publicDir?: string;
+}
+interface RuntimeServerlessRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: RuntimeBytes;
+}
+interface RuntimeServerlessResponseHead {
+    status: number;
+    headers: Record<string, string>;
+}
+interface RuntimeRegistryRouteResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: RuntimeBytes;
+}
+type RuntimeServerlessStreamEvent = {
+    kind: "chunk";
+    chunk?: RuntimeBytes;
+} | {
+    kind: "end";
+    error?: {
+        group: string;
+        code: string;
+        message: string;
+    };
+};
+type RuntimeServerlessStreamCallback = (error: unknown, event?: RuntimeServerlessStreamEvent) => unknown;
+type RuntimeWebSocketEvent = {
+    kind: "message";
+    data: string | RuntimeBytes;
+    binary: boolean;
+    messageIndex?: number;
+} | {
+    kind: "close";
+    code: number;
+    reason: string;
+    wasClean: boolean;
+};
+interface CoreRuntime {
+    readonly kind: "napi" | "wasm";
+    createRegistry(): RegistryHandle;
+    registerActor(registry: RegistryHandle, name: string, factory: ActorFactoryHandle): void;
+    serveRegistry(registry: RegistryHandle, config: RuntimeServeConfig): Promise<void>;
+    shutdownRegistry(registry: RegistryHandle): Promise<void>;
+    registryActorStopThresholdMs?(registry: RegistryHandle): Promise<number | undefined>;
+    handleServerlessRequest(registry: RegistryHandle, req: RuntimeServerlessRequest, onStreamEvent: RuntimeServerlessStreamCallback, cancelToken: CancellationTokenHandle, config: RuntimeServeConfig): Promise<RuntimeServerlessResponseHead>;
+    serveListener(registry: RegistryHandle, listener: RuntimeListenerConfig, config: RuntimeServeConfig): Promise<void>;
+    registryHealth?(registry: RegistryHandle): Promise<RuntimeRegistryRouteResponse>;
+    registryMetadata?(registry: RegistryHandle): Promise<RuntimeRegistryRouteResponse>;
+    registryMetrics?(registry: RegistryHandle): Promise<RuntimeRegistryRouteResponse>;
+    createActorFactory(callbacks: object, config?: RuntimeActorConfig | undefined | null): ActorFactoryHandle;
+    createCancellationToken(): CancellationTokenHandle;
+    cancellationTokenAborted(token: CancellationTokenHandle): boolean;
+    cancelCancellationToken(token: CancellationTokenHandle): void;
+    onCancellationTokenCancelled(token: CancellationTokenHandle, callback: (...args: unknown[]) => unknown): void;
+    actorState(ctx: ActorContextHandle): RuntimeBytes;
+    actorBeginOnStateChange(ctx: ActorContextHandle): void;
+    actorEndOnStateChange(ctx: ActorContextHandle): void;
+    actorSetAlarm(ctx: ActorContextHandle, timestampMs?: number | undefined | null): void;
+    actorRequestSave(ctx: ActorContextHandle, opts?: RuntimeRequestSaveOpts | undefined | null): void;
+    actorRequestSaveAndWait(ctx: ActorContextHandle, opts?: RuntimeRequestSaveOpts | undefined | null): Promise<void>;
+    actorInspectorSnapshot(ctx: ActorContextHandle): RuntimeInspectorSnapshot;
+    actorDecodeInspectorRequest(ctx: ActorContextHandle, bytes: RuntimeBytes, advertisedVersion: number): RuntimeBytes;
+    actorEncodeInspectorResponse(ctx: ActorContextHandle, bytes: RuntimeBytes, targetVersion: number): RuntimeBytes;
+    actorVerifyInspectorAuth(ctx: ActorContextHandle, bearerToken?: string | undefined | null): Promise<void>;
+    actorQueueHibernationRemoval(ctx: ActorContextHandle, connId: string): void;
+    actorTakePendingHibernationChanges(ctx: ActorContextHandle): string[];
+    actorDirtyHibernatableConns(ctx: ActorContextHandle): ConnHandle[];
+    actorSaveState(ctx: ActorContextHandle, payload: RuntimeStateDeltaPayload): Promise<void>;
+    actorId(ctx: ActorContextHandle): string;
+    actorName(ctx: ActorContextHandle): string;
+    actorKey(ctx: ActorContextHandle): RuntimeActorKeySegment[];
+    actorRegion(ctx: ActorContextHandle): string;
+    actorSleep(ctx: ActorContextHandle): void;
+    actorDestroy(ctx: ActorContextHandle): void;
+    actorAbortSignal(ctx: ActorContextHandle): AbortSignal;
+    actorConns(ctx: ActorContextHandle): ConnHandle[];
+    actorConnectConn(ctx: ActorContextHandle, params: RuntimeBytes, request?: RuntimeHttpRequest | undefined | null): Promise<ConnHandle>;
+    actorBroadcast(ctx: ActorContextHandle, name: string, args: RuntimeBytes): void;
+    actorWaitUntil(ctx: ActorContextHandle, promise: Promise<unknown>): void;
+    actorWaitForTrackedShutdownWork(ctx: ActorContextHandle): Promise<boolean>;
+    actorWaitForTrackedShutdownWorkUnbounded(ctx: ActorContextHandle): Promise<void>;
+    actorKeepAwake(ctx: ActorContextHandle, promise: Promise<unknown>): void;
+    actorBeginKeepAwake(ctx: ActorContextHandle): number;
+    actorEndKeepAwake(ctx: ActorContextHandle, regionId: number): void;
+    actorRegisterTask(ctx: ActorContextHandle, promise: Promise<unknown>): void;
+    actorRuntimeState(ctx: ActorContextHandle): object;
+    actorClearRuntimeState(ctx: ActorContextHandle): void;
+    actorRestartRunHandler(ctx: ActorContextHandle): void;
+    actorBeginWebsocketCallback(ctx: ActorContextHandle): number;
+    actorEndWebsocketCallback(ctx: ActorContextHandle, regionId: number): void;
+    actorKvGet(ctx: ActorContextHandle, key: RuntimeBytes): Promise<RuntimeBytes | null>;
+    actorKvPut(ctx: ActorContextHandle, key: RuntimeBytes, value: RuntimeBytes): Promise<void>;
+    actorKvDelete(ctx: ActorContextHandle, key: RuntimeBytes): Promise<void>;
+    actorKvDeleteRange(ctx: ActorContextHandle, start: RuntimeBytes, end: RuntimeBytes): Promise<void>;
+    actorKvListPrefix(ctx: ActorContextHandle, prefix: RuntimeBytes, options?: RuntimeKvListOptions | undefined | null): Promise<RuntimeKvEntry[]>;
+    actorKvListRange(ctx: ActorContextHandle, start: RuntimeBytes, end: RuntimeBytes, options?: RuntimeKvListOptions | undefined | null): Promise<RuntimeKvEntry[]>;
+    actorKvBatchGet(ctx: ActorContextHandle, keys: RuntimeBytes[]): Promise<Array<RuntimeBytes | undefined | null>>;
+    actorKvBatchPut(ctx: ActorContextHandle, entries: RuntimeKvEntry[]): Promise<void>;
+    actorKvBatchDelete(ctx: ActorContextHandle, keys: RuntimeBytes[]): Promise<void>;
+    actorSqlExec(ctx: ActorContextHandle, sql: string): Promise<RuntimeSqlExecResult>;
+    actorSqlExecute(ctx: ActorContextHandle, sql: string, params?: RuntimeSqlBindParams): Promise<RuntimeSqlExecuteResult>;
+    actorSqlQuery(ctx: ActorContextHandle, sql: string, params?: RuntimeSqlBindParams): Promise<RuntimeSqlQueryResult>;
+    actorSqlRun(ctx: ActorContextHandle, sql: string, params?: RuntimeSqlBindParams): Promise<RuntimeSqlRunResult>;
+    actorSqlMetrics(ctx: ActorContextHandle): SqliteNativeMetrics | null;
+    actorSqlTakeLastKvError(ctx: ActorContextHandle): string | null;
+    actorSqlClose(ctx: ActorContextHandle): Promise<void>;
+    actorQueueSend(ctx: ActorContextHandle, name: string, body: RuntimeBytes): Promise<RuntimeQueueMessage>;
+    actorQueueNextBatch(ctx: ActorContextHandle, options?: RuntimeQueueNextBatchOptions | undefined | null, signal?: CancellationTokenHandle | undefined | null): Promise<RuntimeQueueMessage[]>;
+    actorQueueWaitForNames(ctx: ActorContextHandle, names: string[], options?: RuntimeQueueWaitOptions | undefined | null, signal?: CancellationTokenHandle | undefined | null): Promise<RuntimeQueueMessage>;
+    actorQueueWaitForNamesAvailable(ctx: ActorContextHandle, names: string[], options?: RuntimeQueueWaitOptions | undefined | null, signal?: CancellationTokenHandle | undefined | null): Promise<void>;
+    actorQueueEnqueueAndWait(ctx: ActorContextHandle, name: string, body: RuntimeBytes, options?: RuntimeQueueEnqueueAndWaitOptions | undefined | null, signal?: CancellationTokenHandle | undefined | null): Promise<RuntimeBytes | null>;
+    actorQueueTryNextBatch(ctx: ActorContextHandle, options?: RuntimeQueueTryNextBatchOptions | undefined | null): RuntimeQueueMessage[];
+    actorQueueMaxSize(ctx: ActorContextHandle): number;
+    actorQueueInspectMessages(ctx: ActorContextHandle): Promise<RuntimeQueueInspectMessage[]>;
+    actorScheduleAfter(ctx: ActorContextHandle, durationMs: number, actionName: string, args: RuntimeBytes): void;
+    actorScheduleAt(ctx: ActorContextHandle, timestampMs: number, actionName: string, args: RuntimeBytes): void;
+    connId(conn: ConnHandle): string;
+    connParams(conn: ConnHandle): RuntimeBytes;
+    connState(conn: ConnHandle): RuntimeBytes;
+    connSetState(conn: ConnHandle, state: RuntimeBytes): void;
+    connIsHibernatable(conn: ConnHandle): boolean;
+    connSend(conn: ConnHandle, name: string, args: RuntimeBytes): void;
+    connDisconnect(conn: ConnHandle, reason?: string | undefined | null): Promise<void>;
+    webSocketSend(ws: WebSocketHandle, data: RuntimeBytes, binary: boolean): void;
+    webSocketClose(ws: WebSocketHandle, code?: number | undefined | null, reason?: string | undefined | null): Promise<void>;
+    webSocketSetEventCallback(ws: WebSocketHandle, callback: (event: RuntimeWebSocketEvent) => void): void;
+}
+
+declare function buildConfiguredRegistry(config: RegistryConfig): Promise<{
+    runtime: CoreRuntime;
+    registry: RegistryHandle;
+    serveConfig: RuntimeServeConfig;
+}>;
+
 type FetchHandler = (request: Request, ...args: any) => Response | Promise<Response>;
 interface ServerlessHandler {
     fetch: FetchHandler;
 }
+interface RegistryRoutes {
+    health(): Promise<Response>;
+    metadata(): Promise<Response>;
+    prometheusMetrics(request?: Request): Promise<Response>;
+}
+/**
+ * Injectable dependencies for {@link Registry}. Production code uses the
+ * defaults. Tests override `buildConfiguredRegistry` to drive lifecycle
+ * orchestration against a fake `CoreRuntime` without an engine.
+ */
+interface RegistryDeps {
+    buildConfiguredRegistry: typeof buildConfiguredRegistry;
+}
 declare class Registry<A extends RegistryActors> {
     #private;
+    readonly routes: RegistryRoutes;
     get config(): RegistryConfigInput<A>;
     parseConfig(): RegistryConfig;
-    constructor(config: RegistryConfigInput<A>);
+    constructor(config: RegistryConfigInput<A>, deps?: Partial<RegistryDeps>);
     /**
      * Handle an incoming HTTP request for serverless deployments.
      *
@@ -1527,9 +2031,56 @@ declare class Registry<A extends RegistryActors> {
      * ```
      */
     serve(): ServerlessHandler;
+    /**
+     * Bind an HTTP listener provided by the native (Rust) runtime and serve
+     * the registry's serverless endpoints over it. Resolves only after the
+     * registry is shut down (SIGINT/SIGTERM or `nativeRegistry.shutdown()`).
+     *
+     * @param opts.port      Port to listen on. Defaults to `process.env.RIVET_PORT`
+     *                       if set, otherwise 3000.
+     * @param opts.host      Address to bind. Defaults to `0.0.0.0`.
+     * @param opts.publicDir If set, serves static files from this directory
+     *                       as a fallback below the framework routes.
+     *
+     * @example
+     * ```ts
+     * await registry.listen();
+     * await registry.listen({ port: 8080, publicDir: "./public" });
+     * ```
+     */
+    listen(opts?: {
+        port?: number;
+        host?: string;
+        publicDir?: string;
+    }): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    shutdown(): Promise<void>;
     startEnvoy(): void;
     /**
-     * Starts the native actor envoy for standalone server deployments.
+     * Starts the actor envoy for standalone server deployments.
+     *
+     * Set `RIVETKIT_RUNTIME_MODE=serverless` to instead bind an HTTP listener
+     * via `listen()` (Mode B). Mode A (envoy) and Mode B (listener) are
+     * mutually exclusive per registry instance.
      *
      * @example
      * ```ts
@@ -1545,4 +2096,4 @@ declare class Registry<A extends RegistryActors> {
  */
 declare function createClient<A extends Registry<any>>(endpointOrConfig?: string | ClientConfigInput): Client<A>;
 
-export { type ActorAccessor, type ActorActionFunction, ActorClientError, type ActorConn, ActorConnDisposed, ActorConnRaw, type ActorConnStatus, ActorDefinition, RivetError as ActorError, type ActorHandle, ActorHandleRaw, type AnyActorDefinition, type Client, type ClientConfigInput, ClientRaw, type ConnectionStateCallback, type CreateOptions, type CreateRequest, type Encoding, type EventUnsubscribe, type ExtractActorsFromRegistry, type ExtractRegistryFromClient, type GetOptions, type GetWithIdOptions, MalformedResponseMessage, ManagerError, type QueryOptions, type Region, RivetError, type StatusChangeCallback, UserError, createClient };
+export { type ActorAccessor, type ActorActionFunction, type ActorActionOptions, ActorClientError, type ActorConn, ActorConnDisposed, ActorConnRaw, type ActorConnStatus, type ActorConnectOptions, ActorDefinition, RivetError as ActorError, type ActorGatewayOptions, type ActorHandle, ActorHandleRaw, type AnyActorDefinition, type Client, type ClientConfigInput, ClientRaw, type ConnectionStateCallback, type CreateOptions, type CreateRequest, type Encoding, type EventUnsubscribe, type ExtractActorsFromRegistry, type ExtractRegistryFromClient, type GetOptions, type GetWithIdOptions, MalformedResponseMessage, ManagerError, type QueryOptions, type Region, RivetError, type StatusChangeCallback, UserError, createClient };