rivetkit 0.0.0-runner-config-drain-grace-threshold.e1be3d6 → 0.0.0-sql-metrics.eac581d

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';
@@ -23,6 +23,35 @@ interface SqliteExecuteResult extends SqliteQueryResult {
     changes: number;
     lastInsertRowId?: number | null;
 }
+interface SqliteBatchStatement {
+    sql: string;
+    params?: SqliteBindings;
+}
+interface SqliteTransactionOptions {
+    /** Static operation name used to aggregate transaction performance. */
+    name?: string;
+    /** Deadlock-safety timeout in milliseconds. */
+    timeout?: number;
+}
+/**
+ * SQLite profiling configuration.
+ *
+ * @experimental This entire configuration surface is experimental and subject
+ * to change without notice.
+ */
+interface SqliteProfilingOptions {
+    enabled?: boolean;
+    maxTrackedStatementFingerprints?: number;
+    maxTrackedTransactionFingerprints?: number;
+    maxPrometheusSeries?: number;
+    maxStatementsPerTransactionTrace?: number;
+    maxGetPagesRequestsPerTrace?: number;
+    maxTransactionNameBytes?: number;
+    slowOperationThresholdMs?: number;
+    baselineSampleRate?: number;
+    maxDiagnosticEventsPerMinute?: number;
+    diagnosticEventQueueCapacity?: number;
+}
 interface SqliteNativeMetrics {
     requestBuildNs: number;
     serializeNs: number;
@@ -39,12 +68,19 @@ interface SqliteNativeMetrics {
 interface SqliteDatabase {
     exec(sql: string, callback?: (row: unknown[], columns: string[]) => void): Promise<void>;
     execute(sql: string, params?: SqliteBindings): Promise<SqliteExecuteResult>;
+    executeBatch(statements: SqliteBatchStatement[]): Promise<SqliteExecuteResult[]>;
+    beginTransaction(timeoutMs?: number, name?: string): Promise<SqliteTransactionDatabase>;
     run(sql: string, params?: SqliteBindings): Promise<void>;
     query(sql: string, params?: SqliteBindings): Promise<SqliteQueryResult>;
-    writeMode<T>(callback: () => Promise<T>): Promise<T>;
     nativeMetrics?(): SqliteNativeMetrics | Promise<SqliteNativeMetrics | null> | null;
     close(): Promise<void>;
 }
+interface SqliteTransactionDatabase {
+    exec(sql: string, callback?: (row: unknown[], columns: string[]) => void): Promise<void>;
+    execute(sql: string, params?: SqliteBindings): Promise<SqliteExecuteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
 /**
  * Provider for opening native databases from the active runtime.
  */
@@ -88,6 +124,13 @@ interface DatabaseProviderContext {
     nativeDatabaseProvider?: NativeDatabaseProvider;
 }
 type DatabaseProvider<DB extends RawAccess> = {
+    /**
+     * Local SQLite profiling controls consumed by the actor runtime.
+     *
+     * @experimental This entire configuration surface is experimental and
+     * subject to change without notice.
+     */
+    sqliteProfiling?: SqliteProfilingOptions;
     /**
      * Creates a new database client for the actor.
      * The result is passed to the actor context as `c.db`.
@@ -104,14 +147,15 @@ 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;
+    /** Runs a callback in an isolated SQLite transaction. */
+    transaction: <T>(callback: (tx: RawAccess) => Promise<T> | T, options?: SqliteTransactionOptions) => Promise<T>;
     /**
      * Returns native SQLite metrics when the active runtime supports them.
      */
@@ -151,6 +195,7 @@ declare const CreateRequestSchema: z.ZodObject<{
     key: z.ZodArray<z.ZodString>;
     input: z.ZodOptional<z.ZodUnknown>;
     region: z.ZodOptional<z.ZodString>;
+    poolName: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const ActorQuerySchema: z.ZodUnion<readonly [z.ZodObject<{
     getForId: z.ZodObject<{
@@ -168,6 +213,7 @@ declare const ActorQuerySchema: z.ZodUnion<readonly [z.ZodObject<{
         key: z.ZodArray<z.ZodString>;
         input: z.ZodOptional<z.ZodUnknown>;
         region: z.ZodOptional<z.ZodString>;
+        poolName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     create: z.ZodObject<{
@@ -175,6 +221,7 @@ declare const ActorQuerySchema: z.ZodUnion<readonly [z.ZodObject<{
         key: z.ZodArray<z.ZodString>;
         input: z.ZodOptional<z.ZodUnknown>;
         region: z.ZodOptional<z.ZodString>;
+        poolName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>]>;
 type ActorQuery = z.infer<typeof ActorQuerySchema>;
@@ -183,6 +230,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;
@@ -191,6 +276,7 @@ interface DeconstructedError {
     code: string;
     message: string;
     metadata?: unknown;
+    actor?: ActorSpecifier;
 }
 
 interface RivetErrorOptions extends ErrorOptions {
@@ -200,6 +286,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 {
     /**
@@ -218,6 +312,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;
@@ -230,44 +325,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;
 
@@ -297,11 +354,6 @@ interface EngineControlClient {
      * Test-only helper that simulates an abrupt actor crash.
      */
     hardCrashActor?(actorId: string): Promise<void>;
-    kvGet(actorId: string, key: Uint8Array): Promise<string | null>;
-    kvBatchGet(actorId: string, keys: Uint8Array[]): Promise<(Uint8Array | null)[]>;
-    kvBatchPut(actorId: string, entries: [Uint8Array, Uint8Array][]): Promise<void>;
-    kvBatchDelete(actorId: string, keys: Uint8Array[]): Promise<void>;
-    kvDeleteRange(actorId: string, start: Uint8Array, end: Uint8Array): Promise<void>;
 }
 interface RuntimeDisplayInformation {
     properties: Record<string, string>;
@@ -323,6 +375,8 @@ interface GetOrCreateWithKeyInput {
     input?: unknown;
     region?: string;
     crashPolicy?: CrashPolicy;
+    /** Overrides the client's configured pool name for this actor. */
+    poolName?: string;
 }
 interface CreateInput {
     c?: Context | undefined;
@@ -331,6 +385,8 @@ interface CreateInput {
     input?: unknown;
     region?: string;
     crashPolicy?: CrashPolicy;
+    /** Overrides the client's configured pool name for this actor. */
+    poolName?: string;
 }
 interface ListActorsInput {
     c?: Context | undefined;
@@ -375,6 +431,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>> : NonNullable<R>[K] extends Record<string, unknown> ? ActorActionMap<NonNullable<R>[K]> : 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;
 }
@@ -387,9 +449,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>;
@@ -400,13 +460,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 {
 }
@@ -815,6 +893,11 @@ interface GetOrCreateOptions extends QueryOptions {
     createInRegion?: string;
     /** Input data to pass to the actor. */
     createWithInput?: unknown;
+    /**
+     * Name of the envoy pool to select for this actor if it is created.
+     * Overrides the client's configured `poolName` for this call.
+     */
+    poolName?: string;
 }
 /**
  * Options for creating a actor.
@@ -826,6 +909,11 @@ interface CreateOptions extends QueryOptions {
     region?: string;
     /** Input data to pass to the actor. */
     input?: unknown;
+    /**
+     * Name of the envoy pool to select for this actor.
+     * Overrides the client's configured `poolName` for this call.
+     */
+    poolName?: string;
 }
 /**
  * Represents a region to connect to.
@@ -920,6 +1008,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;
@@ -952,6 +1041,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>;
@@ -966,10 +1059,76 @@ interface ActorKv {
     [key: string]: any;
 }
 interface ActorSchedule {
-    after(duration: number, action: string, ...args: unknown[]): Promise<void>;
-    at(timestamp: number, action: string, ...args: unknown[]): Promise<void>;
+    after(duration: number, action: string, ...args: unknown[]): Promise<string>;
+    at(timestamp: number, action: string, ...args: unknown[]): Promise<string>;
+    cancel(id: string): Promise<boolean>;
+    get(id: string): Promise<ScheduledEventInfo | undefined>;
+    list(): Promise<ScheduledEventInfo[]>;
+    [key: string]: any;
+}
+interface ActorCronSetOptions {
+    name: string;
+    expression: string;
+    action: string;
+    args?: unknown[];
+    timezone?: string;
+    /** Defaults to 100. Set to 0 to disable and clear history. Maximum 1,000. */
+    maxHistory?: number;
+}
+interface ActorCronEveryOptions {
+    name: string;
+    /** Fixed interval in milliseconds. Minimum 5,000. */
+    interval: number;
+    action: string;
+    args?: unknown[];
+    /** Defaults to 100. Set to 0 to disable and clear history. Maximum 1,000. */
+    maxHistory?: number;
+}
+interface ActorCron {
+    set(options: ActorCronSetOptions): Promise<void>;
+    every(options: ActorCronEveryOptions): Promise<void>;
+    get(name: string): Promise<CronJobInfo | undefined>;
+    list(): Promise<CronJobInfo[]>;
+    delete(name: string): Promise<boolean>;
+    history(name: string, options?: {
+        limit?: number;
+    }): Promise<CronFire[]>;
     [key: string]: any;
 }
+interface ScheduledEventInfo {
+    id: string;
+    action: string;
+    args: unknown[];
+    runAt: number;
+}
+type CronJobInfo = {
+    name: string;
+    action: string;
+    args: unknown[];
+    nextRunAt: number;
+    lastRunAt?: number;
+    maxHistory: number;
+} & ({
+    kind: "cron";
+    expression: string;
+    timezone: string;
+} | {
+    kind: "every";
+    interval: number;
+});
+interface CronFire {
+    action: string;
+    scheduledAt: number;
+    firedAt: number;
+    finishedAt?: number;
+    result: "running" | "ok" | "error" | "skipped";
+    error?: {
+        group: string;
+        code: string;
+        message: string;
+        metadata?: unknown;
+    };
+}
 type QueueMessageOf<Name extends string, Body> = {
     id: number | bigint;
     name: Name;
@@ -1028,7 +1187,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;
@@ -1039,16 +1198,27 @@ 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;
+    readonly cron: ActorCron;
     readonly queue: ActorQueue<TQueues>;
     readonly actorId: string;
     readonly name: string;
     readonly key: string[];
     readonly region: string;
+    /** Provisions the experimental Actor Runtime Socket for this actor generation. */
+    actorRuntimeSocket(): Promise<{
+        path: string;
+    }>;
     readonly conns: Map<string, Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>>;
     readonly log: ActorLogger;
     readonly abortSignal: AbortSignal;
@@ -1130,7 +1300,7 @@ declare const ActorConfigSchema: z.ZodObject<{
     onBeforeActionResponse: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>;
     onRequest: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>;
     onWebSocket: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>;
-    actions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>>;
+    actions: z.ZodDefault<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
     actionInputSchemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     connParamsSchema: z.ZodOptional<z.ZodAny>;
     events: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1145,6 +1315,7 @@ declare const ActorConfigSchema: z.ZodObject<{
     options: z.ZodPrefault<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         icon: z.ZodOptional<z.ZodString>;
+        enableActorRuntimeSocket: z.ZodDefault<z.ZodBoolean>;
         canHibernateWebSocket: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<(request: Request) => boolean, (request: Request) => boolean>]>>;
         createVarsTimeout: z.ZodDefault<z.ZodNumber>;
         createConnStateTimeout: z.ZodDefault<z.ZodNumber>;
@@ -1161,12 +1332,33 @@ declare const ActorConfigSchema: z.ZodObject<{
         noSleep: z.ZodDefault<z.ZodBoolean>;
         sleepTimeout: z.ZodDefault<z.ZodNumber>;
         maxQueueSize: z.ZodDefault<z.ZodNumber>;
+        maxSchedules: z.ZodDefault<z.ZodNumber>;
         maxQueueMessageSize: z.ZodDefault<z.ZodNumber>;
         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";
+                schedules: "schedules";
+                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>;
@@ -1179,7 +1371,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
      */
@@ -1191,7 +1383,10 @@ type CreateVars<TState, TConnParams, TConnState, TVars, TInput, TDatabase extend
     createVars: (c: CreateVarsContext<TState, TInput, TDatabase, TEvents, TQueues>, driverCtx: any) => TVars | Promise<TVars>;
 } | Record<never, never>;
 interface Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> {
-    [Action: string]: (c: ActionContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>, ...args: any[]) => any;
+    [Action: string]: ((c: ActionContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>, ...args: any[]) => any) | Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>;
+}
+interface ActionInputSchemas {
+    [Action: string]: PrimitiveSchema | ActionInputSchemas;
 }
 interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig, TQueues extends QueueSchemaConfig, TActions extends Actions<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>> {
     /**
@@ -1276,10 +1471,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>;
@@ -1287,7 +1483,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
@@ -1341,9 +1538,10 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
     onWebSocket?: (c: WebSocketContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>, websocket: UniversalWebSocket) => void | Promise<void>;
     actions?: TActions;
     /**
-     * Optional schema map for validating action argument tuples in native runtimes.
+     * Optional schemas for validating action argument tuples in native runtimes.
+     * May mirror nested action groups or use dot-separated low-level action names.
      */
-    actionInputSchemas?: Record<string, PrimitiveSchema>;
+    actionInputSchemas?: ActionInputSchemas;
     /**
      * Optional schema for validating connection params in native runtimes.
      */
@@ -1363,19 +1561,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>>;
@@ -1395,11 +1595,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<{
-            module_or_path: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput>;
-        } | _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined, {
-            module_or_path: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput>;
-        } | _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined>>;
+        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";
@@ -1436,6 +1632,8 @@ 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>;
@@ -1460,7 +1658,7 @@ 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<{
@@ -1490,9 +1688,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     runtime: "auto" | "native" | "wasm";
     wasm: {
         bindings?: typeof _rivetkit_rivetkit_wasm | undefined;
-        initInput?: {
-            module_or_path: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput>;
-        } | _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
+        initInput?: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
     };
     noWelcome: boolean;
     logging: {
@@ -1503,6 +1699,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;
@@ -1511,8 +1709,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;
@@ -1537,9 +1735,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     runtime: "auto" | "native" | "wasm";
     wasm: {
         bindings?: typeof _rivetkit_rivetkit_wasm | undefined;
-        initInput?: {
-            module_or_path: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput>;
-        } | _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
+        initInput?: _rivetkit_rivetkit_wasm.InitInput | Promise<_rivetkit_rivetkit_wasm.InitInput> | undefined;
     };
     sqlite: {
         backend: "local" | "remote";
@@ -1556,6 +1752,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;
@@ -1570,8 +1768,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;
@@ -1591,19 +1789,450 @@ 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 SqliteTransactionHandle = OpaqueHandle<"sqliteTransaction">;
+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 RuntimeWorkflowKvWrite {
+    key: RuntimeBytes;
+    value: RuntimeBytes;
+}
+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 RuntimeScheduledEventInfo {
+    id: string;
+    action: string;
+    args: RuntimeBytes;
+    runAt: number;
+}
+interface RuntimeCronJobInfo {
+    name: string;
+    kind: "cron" | "every";
+    action: string;
+    args: RuntimeBytes;
+    nextRunAt: number;
+    lastRunAt?: number;
+    expression?: string;
+    timezone?: string;
+    intervalMs?: number;
+    maxHistory: number;
+}
+interface RuntimeScheduleErrorInfo {
+    group: string;
+    code: string;
+    message: string;
+    metadata?: unknown;
+}
+interface RuntimeCronFire {
+    action: string;
+    scheduledAt: number;
+    firedAt: number;
+    finishedAt?: number;
+    result: "running" | "ok" | "error" | "skipped";
+    error?: RuntimeScheduleErrorInfo;
+}
+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 RuntimeActorRuntimeSocketEndpointInfo {
+    path: string;
+}
+interface RuntimeSqlQueryResult {
+    columns: string[];
+    rows: unknown[][];
+}
+type RuntimeSqlExecResult = RuntimeSqlQueryResult;
+interface RuntimeSqlExecuteResult extends RuntimeSqlQueryResult {
+    changes: number;
+    lastInsertRowId?: number | null;
+}
+interface RuntimeSqlBatchStatement {
+    sql: string;
+    params?: RuntimeSqlBindParams;
+}
+interface RuntimeSqlRunResult {
+    changes: number;
+}
+interface RuntimeActorConfig {
+    name?: string;
+    icon?: string;
+    hasDatabase?: boolean;
+    remoteSqlite?: boolean;
+    sqliteProfiling?: SqliteProfilingOptions;
+    enableActorRuntimeSocket?: 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;
+    maxSchedules?: 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;
+    application?: RuntimeApplicationFetch;
+}
+interface RuntimeServerlessRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: RuntimeBytes;
+}
+interface RuntimeApplicationResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: RuntimeBytes;
+}
+type RuntimeApplicationFetch = (request: RuntimeServerlessRequest) => Promise<RuntimeApplicationResponse>;
+interface RuntimeApplicationListenerConfig extends RuntimeListenerConfig {
+    application: RuntimeApplicationFetch;
+}
+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>;
+    waitRegistryReady(registry: RegistryHandle): 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>;
+    serveApplicationListener(registry: RegistryHandle, listener: RuntimeApplicationListenerConfig, 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>;
+    actorSaveStateAndWorkflowBatch(ctx: ActorContextHandle, writes: RuntimeWorkflowKvWrite[]): 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>;
+    actorSqlExecuteBatch(ctx: ActorContextHandle, statements: RuntimeSqlBatchStatement[]): Promise<RuntimeSqlExecuteResult[]>;
+    actorSqlBeginTransaction(ctx: ActorContextHandle, timeoutMs?: number, name?: string): Promise<SqliteTransactionHandle>;
+    actorSqlTransactionExec(transaction: SqliteTransactionHandle, sql: string): Promise<RuntimeSqlExecResult>;
+    actorSqlTransactionExecute(transaction: SqliteTransactionHandle, sql: string, params?: RuntimeSqlBindParams): Promise<RuntimeSqlExecuteResult>;
+    actorSqlTransactionCommit(transaction: SqliteTransactionHandle): Promise<void>;
+    actorSqlTransactionRollback(transaction: SqliteTransactionHandle): Promise<void>;
+    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>;
+    actorRuntimeSocketProvision(ctx: ActorContextHandle): Promise<RuntimeActorRuntimeSocketEndpointInfo>;
+    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[]>;
+    actorQueueReset(ctx: ActorContextHandle): Promise<void>;
+    actorScheduleAfter(ctx: ActorContextHandle, durationMs: number, actionName: string, args: RuntimeBytes): Promise<string>;
+    actorScheduleAt(ctx: ActorContextHandle, timestampMs: number, actionName: string, args: RuntimeBytes): Promise<string>;
+    actorScheduleCancel(ctx: ActorContextHandle, id: string): Promise<boolean>;
+    actorScheduleGet(ctx: ActorContextHandle, id: string): Promise<RuntimeScheduledEventInfo | undefined>;
+    actorScheduleList(ctx: ActorContextHandle): Promise<RuntimeScheduledEventInfo[]>;
+    actorCronSet(ctx: ActorContextHandle, name: string, expression: string, timezone: string | undefined, actionName: string, args: RuntimeBytes, maxHistory: number | undefined): Promise<void>;
+    actorCronEvery(ctx: ActorContextHandle, name: string, intervalMs: number, actionName: string, args: RuntimeBytes, maxHistory: number | undefined): Promise<void>;
+    actorCronGet(ctx: ActorContextHandle, name: string): Promise<RuntimeCronJobInfo | undefined>;
+    actorCronList(ctx: ActorContextHandle): Promise<RuntimeCronJobInfo[]>;
+    actorCronDelete(ctx: ActorContextHandle, name: string): Promise<boolean>;
+    actorCronHistory(ctx: ActorContextHandle, name: string, limit: number | undefined): Promise<RuntimeCronFire[]>;
+    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 RegistryDiagnostics {
-    mode: string;
-    envoyActiveActorCount?: number | null;
+interface RegistryApplication {
+    fetch: FetchHandler;
+}
+interface RegistryListenOptions {
+    port?: number;
+    host?: string;
+    publicDir?: string;
+    application?: RegistryApplication;
+}
+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.
      *
@@ -1624,11 +2253,64 @@ declare class Registry<A extends RegistryActors> {
      * ```
      */
     serve(): ServerlessHandler;
-    diagnostics(): Promise<RegistryDiagnostics>;
+    /**
+     * 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.
+     * @param opts.application If set, handles requests that do not match a
+     *                         framework route.
+     *
+     * @example
+     * ```ts
+     * await registry.listen();
+     * await registry.listen({ application: app });
+     * ```
+     */
+    listen(opts?: RegistryListenOptions): 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 serverful registry if needed and waits until its envoy has
+     * registered with the Engine. Repeated and concurrent calls share one
+     * startup lifecycle and readiness promise.
+     *
+     * Unlike {@link start}, this reports startup failures and does not resolve
+     * merely because an HTTP health endpoint is listening.
+     */
+    startAndWait(): Promise<void>;
     /**
      * 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
      * const registry = setup({ use: { counter } });