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

package/dist/browser/client.d.ts

@@ -1,8 +1,8 @@
 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';
@@ -103,8 +103,7 @@ 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 = {
     /**
@@ -182,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;
@@ -239,44 +276,6 @@ 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;
 
@@ -384,6 +383,12 @@ 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;
 }
@@ -396,9 +401,7 @@ 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>;
@@ -409,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>;
-} : never : never;
-type ActorDefinitionEventSubscriptions<AD extends AnyActorDefinition> = AD extends BaseActorDefinition<any, any, any, any, any, any, infer E, any, any> ? E extends EventSchemaConfig ? {
+} : {} : AD extends BaseActorDefinition<any, any, any, any, any, any, any, infer Q, any> ? Q extends QueueSchemaConfig ? {
+    send: ActorQueueSend<Q>;
+} : {} : {};
+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 {
 }
@@ -929,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;
@@ -1037,7 +1059,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;
@@ -1048,6 +1070,8 @@ 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;
     readonly kv: ActorKv;
@@ -1175,7 +1199,7 @@ declare const ActorConfigSchema: z.ZodObject<{
         preloadMaxConnectionsBytes: z.ZodOptional<z.ZodNumber>;
     }, 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>;
@@ -1188,7 +1212,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
      */
@@ -1374,19 +1398,21 @@ 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>>;
@@ -1406,7 +1432,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     }>>, 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<any, any>>;
+        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";
@@ -1497,7 +1523,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     runtime: "auto" | "native" | "wasm";
     wasm: {
         bindings?: typeof _rivetkit_rivetkit_wasm | undefined;
-        initInput?: any;
+        initInput?: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
     };
     noWelcome: boolean;
     logging: {
@@ -1542,7 +1568,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     runtime: "auto" | "native" | "wasm";
     wasm: {
         bindings?: typeof _rivetkit_rivetkit_wasm | undefined;
-        initInput?: any;
+        initInput?: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
     };
     sqlite: {
         backend: "local" | "remote";
@@ -1594,6 +1620,318 @@ 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;
+    }>;
+}
+interface RuntimeServeConfig {
+    version: number;
+    endpoint: string;
+    token?: string;
+    namespace: string;
+    poolName: string;
+    engineBinaryPath?: string;
+    handleInspectorHttpInRuntime?: boolean;
+    inspectorTestToken?: string;
+    serverlessBasePath?: string;
+    serverlessPackageVersion: string;
+    serverlessClientEndpoint?: string;
+    serverlessClientNamespace?: string;
+    serverlessClientToken?: string;
+    serverlessValidateEndpoint: boolean;
+    serverlessMaxStartPayloadBytes: number;
+}
+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>;
+    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;
@@ -1603,12 +1941,20 @@ interface RegistryRoutes {
     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.
      *
@@ -1629,6 +1975,46 @@ declare class Registry<A extends RegistryActors> {
      * ```
      */
     serve(): ServerlessHandler;
+    /**
+     * 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" });
+     * ```
+     */
+    listen(opts?: {
+        port?: number;
+        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 actor envoy for standalone server deployments.