@nice-code/action 0.8.0 → 0.9.0

package/build/types/ActionRuntime/Handler/Server/ActionServerHandler.d.ts

@@ -1,254 +0,0 @@
-import type { ClientCryptoKeyLink, TTypeAndId } from "@nice-code/util";
-import type { TDistributeActionPayload_Request } from "../../../ActionDefinition/Action/Action.combined.types";
-import type { IActionRouteItemHandler } from "../../../ActionDefinition/Action/Payload/ActionPayload.types";
-import { type TActionPayload_Any_Instance, type TActionPayload_Any_JsonObject } from "../../../ActionDefinition/Action/Payload/ActionPayload.types";
-import type { ActionPayload_Request } from "../../../ActionDefinition/Action/Payload/ActionPayload_Request";
-import { RunningAction } from "../../../ActionDefinition/Action/RunningAction";
-import type { ActionDomain } from "../../../ActionDefinition/Domain/ActionDomain";
-import type { IActionDomain } from "../../../ActionDefinition/Domain/ActionDomain.types";
-import { ActionRuntime } from "../../ActionRuntime";
-import { type IRuntimeCoordinate, RuntimeCoordinate } from "../../RuntimeCoordinate";
-import type { IHandleActionOptions } from "../ActionHandler.types";
-import { ActionExternalClientHandler } from "../ExternalClient/ActionExternalClientHandler";
-import { ESecurityLevel, type IClientVerifyKeyResolver, type IHandshakeEncryptionKeyMaterial } from "../ExternalClient/Transport/WebSocket/actionWsHandshake";
-import type { IActionTransportReadyData_Ws } from "../ExternalClient/Transport/WebSocket/TransportWebSocket.types";
-import { ActionLocalHandler } from "../Local/ActionLocalHandler";
-import type { THandleActionExecutionFn } from "../Local/ActionLocalHandler.types";
-import { type IWsConnectionStateStoreOptions, WsConnectionStateStore } from "./WsConnectionStateStore";
-/** The codec shape `ActionServerHandler` uses to pack/unpack frames — same as the WS transport's. */
-export type TActionChannelFormatMessage = NonNullable<IActionTransportReadyData_Ws["formatMessage"]>;
-/** How a connection encodes its frames, remembered so we answer each client in its own dialect. */
-export type TActionConnectionEncoding = "json" | "binary";
-/** A connection's restorable identity — what to persist so a binding survives transport eviction. */
-export interface IActionServerConnectionBinding {
-    /** Full client coordinate, so `originClient` can be re-injected into frames that omit it. */
-    client: IRuntimeCoordinate;
-    encoding: TActionConnectionEncoding;
-    /**
-     * Secure-session state (set once a connection's handshake completes). Persist it alongside the
-     * binding so an authenticated/encrypted connection resumes after eviction without re-handshaking —
-     * the `keyMaterial` lets the server re-derive the shared key from its own persisted identity.
-     */
-    secure?: {
-        securityLevel: ESecurityLevel;
-        linkedClientId: TTypeAndId;
-        keyMaterial?: IHandshakeEncryptionKeyMaterial;
-    };
-}
-/**
- * Server-side secure-channel config. When set, each connection negotiates a level from
- * {@link securityLevel}: an `authenticated`/`encrypted` client must complete the handshake (and is then
- * bound to its *authenticated* coordinate) before any action frame is accepted. A `none` client (only
- * when `none` is in the allowed set) is accepted as-is with a self-asserted identity. For the
- * `encrypted` level the codec source should be a session factory (`createFormatMessage`).
- */
-export interface IActionServerSecurity {
-    /**
-     * Accepted level(s). A single level is strict; an array is a negotiable allowed set — the server
-     * adopts whichever level each client requests (e.g. `[none, authenticated, encrypted]` serves all
-     * three over one endpoint).
-     */
-    securityLevel: ESecurityLevel | readonly ESecurityLevel[];
-    /** This server's crypto identity (verify + exchange key pairs, optionally persisted). */
-    link: ClientCryptoKeyLink;
-    /** This server's coordinate — its identity to clients during the handshake. */
-    localCoordinate: IRuntimeCoordinate;
-    /** Wire dictionary version; the handshake rejects a client on a mismatch. */
-    dictionaryVersion: string;
-    /** Trust decision for a client's verify key (defaults to in-memory TOFU inside the handshake). */
-    verifyKeyResolver?: IClientVerifyKeyResolver;
-}
-interface IActionServerHandlerBaseOptions<TConn> {
-    /**
-     * Coordinate of the *connecting clients* (typically env-only, e.g. `RuntimeCoordinate.env("web_app")`).
-     * The runtime's return-path dispatch scores incoming actions' `originClient` against this to pick
-     * this handler for sending results/pushes back over the right channel.
-     */
-    clientEnv: RuntimeCoordinate;
-    /** Write an encoded frame to a specific live connection (e.g. `(ws, frame) => ws.send(frame)`). */
-    send: (connection: TConn, frame: string | Uint8Array | ArrayBuffer) => void;
-    /**
-     * The runtime this handler belongs to. When set, {@link ActionServerHandler.broadcast} can be called
-     * without threading a runtime through each call. Optional — `pushToClient` still takes one explicitly.
-     */
-    runtime?: ActionRuntime;
-    /** Timeout (ms) applied to server-initiated actions awaiting a client response. */
-    defaultTimeout?: number;
-    /**
-     * Called once when a connection is first bound to a client identity. Use it to persist the binding
-     * for transports that can resume after eviction — e.g. a Durable Object's hibernatable WebSocket:
-     * `(ws, binding) => ws.serializeAttachment(binding)` — then replay it via {@link ActionServerHandler.rehydrateConnection}
-     * when the channel comes back.
-     */
-    onConnectionBound?: (connection: TConn, binding: IActionServerConnectionBinding) => void;
-    /**
-     * Enable the authenticated (optionally encrypted) handshake. When omitted, connections are trusted
-     * as-is (identity self-asserted) — fine for dev / trusted networks.
-     */
-    security?: IActionServerSecurity;
-}
-/**
- * Provide exactly one codec source:
- * - `formatMessage` — a single shared codec for every connection (stateless, e.g. `createBinaryWsAdapter`).
- * - `createFormatMessage` — a per-connection factory for stateful codecs (e.g.
- *   `createBinaryWsSessionFactory`, whose sessions hold correlation + identity state). Required for the
- *   leanest binary wire; the handler creates and caches one codec per connection.
- */
-export type IActionServerHandlerOptions<TConn> = IActionServerHandlerBaseOptions<TConn> & ({
-    formatMessage: TActionChannelFormatMessage;
-    createFormatMessage?: never;
-} | {
-    createFormatMessage: () => TActionChannelFormatMessage;
-    formatMessage?: never;
-});
-/**
- * A connection-aware execution case (see {@link ActionServerHandler.forConnectionDomainCases}). It
- * receives the primed request plus the originating client's live connection (already resolved from the
- * request's `originClient`, `undefined` if the socket is gone), and may return the action's raw output,
- * a result payload, or nothing (auto-wrapped as an empty success) — exactly like a local handler case.
- */
-export type TServerConnectionCaseFn<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string, TConn> = (action: TDistributeActionPayload_Request<DOM, ID>, connection: TConn | undefined) => ReturnType<THandleActionExecutionFn<DOM, ID>> | void;
-/**
- * Server-side handler for backends that accept many client connections over a single open channel
- * (WebSockets, Durable Objects, …). It is transport-agnostic: you feed it inbound frames with
- * {@link receive} and tell it how to write outbound frames via the `send` option.
- *
- * Add it alongside your local execution handler:
- * ```ts
- * const serverHandler = createServerHandler({ clientEnv, formatMessage, send: (ws, f) => ws.send(f) });
- * runtime.addHandlers([localHandler, serverHandler]);
- * // per inbound message (e.g. a Durable Object's webSocketMessage):
- * serverHandler.receive(ws, message);
- * ```
- *
- * Inbound requests route to your local handler; the runtime's return dispatch then calls this
- * handler back (it is an external handler keyed to `clientEnv`) to send the result to the originating
- * connection. The handler keeps a per-connection identity registry so each result lands on the right
- * socket, and remembers each connection's encoding so binary and JSON clients can share the channel.
- *
- * It registers an empty action router, so it is never chosen to *execute* an inbound request — only
- * to ferry results/pushes back out.
- */
-export declare class ActionServerHandler<TConn = unknown> extends ActionExternalClientHandler {
-    private readonly _formatMessage?;
-    private readonly _createFormatMessage?;
-    private readonly _send;
-    private readonly _runtime?;
-    private readonly _serverTimeout;
-    private _onConnectionBound?;
-    /** Incoming-data listeners installed by the runtime (`resolveIncomingActionPayload`). */
-    private readonly _incomingListeners;
-    private readonly _security?;
-    /** Normalized accepted levels; whether `none` (plain) is allowed; whether any level needs a handshake. */
-    private readonly _allowedLevels;
-    private readonly _noneAllowed;
-    private readonly _handshakeMode;
-    private readonly _connByClient;
-    private readonly _clientByConn;
-    private readonly _connEncoding;
-    private readonly _codecByConn;
-    private readonly _handshakeByConn;
-    private readonly _cryptoByConn;
-    private readonly _authedConns;
-    private readonly _plainConns;
-    private readonly _inboundChainByConn;
-    private readonly _outboundChainByConn;
-    constructor(options: IActionServerHandlerOptions<TConn>);
-    /**
-     * The codec for a connection: a per-connection session (cached) when a factory was provided, else
-     * the single shared `formatMessage`.
-     */
-    private _codecFor;
-    _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any>) => void): void;
-    /**
-     * Register (or replace) the connection-bound persistence callback after construction. Used by
-     * lifecycle helpers like {@link createHibernatableWsServerAdapter} so persistence and replay are
-     * owned by one place instead of being split across the constructor options.
-     */
-    setOnConnectionBound(onConnectionBound: (connection: TConn, binding: IActionServerConnectionBinding) => void): void;
-    /**
-     * Create a typed per-connection state store that co-owns the consumer's app state and this handler's
-     * routing binding in one attachment. It registers itself as the connection-bound persistence callback
-     * (so bindings are written without overwriting app state) and immediately replays every live
-     * connection's stored binding via {@link rehydrateConnection} — so on a transport that resumes after
-     * eviction (e.g. a Durable Object waking from hibernation) both the app identity and the action
-     * routing come back from a single attachment, with no storage reads and no hand-rolled merge.
-     *
-     * This supersedes {@link createHibernatableWsServerAdapter} for app code that also pins its own state
-     * to the connection. Construct it once when the handler is built, then `get`/`set` app state directly.
-     */
-    createConnectionState<TApp>(options: IWsConnectionStateStoreOptions<TConn, TApp>): WsConnectionStateStore<TConn, TApp>;
-    /**
-     * Feed one inbound frame from a connection into the runtime. Decodes text or binary, binds the
-     * connection to the requesting client's identity, then routes it (requests execute locally;
-     * results/progress resolve pending server-initiated actions).
-     */
-    receive(connection: TConn, frame: string | ArrayBuffer | Uint8Array): void;
-    private _receivePlain;
-    private _receiveSecure;
-    private _completeServerHandshake;
-    /**
-     * Ensure an inbound request carries the client's identity and that this connection is bound to it,
-     * so its result can be routed back. A session codec omits `originClient` after the first request, so
-     * when it's missing we restore it from the (possibly rehydrated) binding instead. (Plain mode only;
-     * secure mode binds the authenticated coordinate at handshake time.)
-     */
-    private _resolveRequestIdentity;
-    /**
-     * Restore a connection→client binding without an inbound frame — for transports that resume after
-     * eviction. Pair it with the {@link IActionServerHandlerOptions.onConnectionBound} hook: persist
-     * the binding there, then replay each live connection here when the channel comes back (e.g. a
-     * Durable Object iterating `ctx.getWebSockets()` as it wakes from hibernation).
-     */
-    rehydrateConnection(connection: TConn, binding: IActionServerConnectionBinding): void;
-    toHandlerRouteItem(): IActionRouteItemHandler;
-    /** Forget a connection (call on socket close) so stale entries don't misroute later results. */
-    dropConnection(connection: TConn): void;
-    /** Live connection for a client coordinate, if currently registered. */
-    getConnectionForClient(client: RuntimeCoordinate): TConn | undefined;
-    /**
-     * Send (and optionally await) a server-initiated action to a specific connected client. Pass the
-     * connection token directly (e.g. the `ws`) or a client `RuntimeCoordinate` to look one up.
-     */
-    pushToClient<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(runtime: ActionRuntime, target: TConn | RuntimeCoordinate, request: ActionPayload_Request<DOM, ID>, options?: {
-        timeout?: number;
-    }): RunningAction<DOM, ID>;
-    /**
-     * Build a local handler whose cases are connection-aware: each case receives the primed request and
-     * the originating client's live connection (resolved from `originClient`), so handlers don't repeat
-     * the `getConnectionForClient(action.context.originClient)` lookup. Cases may return raw output or
-     * nothing, just like {@link ActionLocalHandler.forDomainActionCases}. Add the returned handler to the
-     * runtime alongside this server handler:
-     * ```ts
-     * runtime.addHandlers([serverHandler.forConnectionDomainCases(domain, { … }), serverHandler]);
-     * ```
-     */
-    forConnectionDomainCases<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, cases: {
-        [ID in keyof FOR_DOM["actionSchema"] & string]?: TServerConnectionCaseFn<FOR_DOM, ID, TConn>;
-    }): ActionLocalHandler;
-    /**
-     * Fan a server-initiated request out to every currently-bound connection. A fresh request is built
-     * per connection (each push mutates its own action context) and dispatched fire-and-forget. Pass
-     * `except` to skip the originating socket and `where` to filter by connection (e.g. read its
-     * attachment for a role). Iterating bound connections (rather than every accepted socket) skips
-     * sockets that are still mid-handshake and so can't yet receive a frame.
-     */
-    broadcast<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(makeRequest: () => ActionPayload_Request<DOM, ID>, options?: {
-        runtime?: ActionRuntime;
-        except?: TConn | null;
-        where?: (connection: TConn) => boolean;
-        timeout?: number;
-        onError?: (error: unknown, connection: TConn) => void;
-    }): void;
-    sendReturnPayload(payload: TActionPayload_Any_Instance<any, any>, config: {
-        targetLocalRuntime: ActionRuntime;
-    }): Promise<boolean>;
-    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
-    private _dispatch;
-    private _sendPayload;
-    private _bindConnection;
-    private _resolveConnection;
-    private _resolveSingleConnection;
-}
-export declare const createServerHandler: <TConn = unknown>(options: IActionServerHandlerOptions<TConn>) => ActionServerHandler<TConn>;
-export {};

package/build/types/ActionRuntime/Handler/Server/WsConnectionStateStore.d.ts

@@ -1,61 +0,0 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { IActionServerConnectionBinding } from "./ActionServerHandler";
-/**
- * The composite value persisted to a connection's attachment: the consumer's own app state plus the
- * {@link ActionServerHandler} routing binding. Co-storing them in one slot means a transport whose
- * sockets outlive process eviction (e.g. a Durable Object's hibernatable WebSocket) recovers both the
- * application identity *and* the action routing from a single attachment after a wake — no storage reads.
- */
-export interface IConnectionAttachment<TApp> {
-    app?: TApp;
-    binding?: IActionServerConnectionBinding;
-}
-export interface IWsConnectionStateStoreOptions<TConn, TApp> {
-    /** Read a connection's raw attachment (e.g. `(ws) => ws.deserializeAttachment()`). */
-    read: (connection: TConn) => unknown;
-    /** Persist a connection's attachment (e.g. `(ws, value) => ws.serializeAttachment(value)`). */
-    write: (connection: TConn, value: IConnectionAttachment<TApp>) => void;
-    /**
-     * All currently-live connections (e.g. `() => ctx.getWebSockets()`). Used to replay routing bindings
-     * after a wake (via {@link ActionServerHandler.createConnectionState}) and to enumerate app state in
-     * {@link WsConnectionStateStore.entries}.
-     */
-    getConnections: () => TConn[];
-    /**
-     * Optional Standard Schema (valibot, zod, …) validating the *app* portion on read. A value that
-     * fails validation reads back as `null` — the same lenient behavior as a hand-written safeParse
-     * helper. The binding is the library's own shape and is never validated.
-     */
-    schema?: StandardSchemaV1<unknown, TApp>;
-}
-/**
- * A typed per-connection state store that co-owns the app state and the server handler's routing
- * binding in one attachment, so neither the consumer nor the handler has to hand-merge the two. Create
- * it through {@link ActionServerHandler.createConnectionState} (which also wires binding persistence and
- * replays surviving connections after a wake), then `get`/`set`/`clearApp` the app state directly.
- *
- * ```ts
- * const players = serverHandler.createConnectionState({
- *   schema: vs_player,
- *   read: (ws) => ws.deserializeAttachment(),
- *   write: (ws, v) => ws.serializeAttachment(v),
- *   getConnections: () => ctx.getWebSockets(),
- * });
- * players.set(ws, player); // binding is preserved automatically
- * const player = players.get(ws);
- * ```
- */
-export declare class WsConnectionStateStore<TConn, TApp> {
-    private readonly options;
-    constructor(options: IWsConnectionStateStoreOptions<TConn, TApp>);
-    /** The validated app state for a connection, or `null` if unset / invalid. */
-    get(connection: TConn): TApp | null;
-    /** Set the app state, preserving the runtime binding already pinned to the connection. */
-    set(connection: TConn, app: TApp): void;
-    /** Clear the app state but keep the binding (e.g. a spectator that stopped watching). */
-    clearApp(connection: TConn): void;
-    /** Every live connection paired with its (validated) app state — for rebuilding in-memory state after a wake. */
-    entries(): [TConn, TApp | null][];
-    private _readAttachment;
-    private _validateApp;
-}

package/build/types/ActionRuntime/Handler/Server/createActionFetchHandler.d.ts

@@ -1,40 +0,0 @@
-import type { ActionRuntime } from "../../ActionRuntime";
-export interface IActionFetchHandlerOptions {
-    /**
-     * CORS headers merged onto every response (a preflight `OPTIONS` is answered `204` with them).
-     * Defaults to permissive `*`; pass `false` to attach no CORS headers at all.
-     */
-    cors?: Record<string, string> | false;
-    /** Which requests carry an action wire on `POST`. Default: pathname ends with `/action`. */
-    isActionPath?: (url: URL) => boolean;
-    /** Which requests are WebSocket upgrades. Default: pathname ends with `/ws`. */
-    isWebSocketPath?: (url: URL) => boolean;
-    /**
-     * Perform the transport-specific WebSocket upgrade (e.g. a Durable Object's
-     * `new WebSocketPair()` + `ctx.acceptWebSocket()` returning a `101`). Omit for HTTP-only endpoints.
-     * Its response is returned as-is — a `101` upgrade carries no CORS headers.
-     */
-    onWebSocketUpgrade?: (request: Request, url: URL) => Response | Promise<Response>;
-    /** Forwarded to `ActionPayload_Result.toHttpResponse` — use the error's HTTP status (default true). */
-    useErrorStatus?: boolean;
-}
-/**
- * Build the `fetch` handler a server/Durable-Object exposes for action traffic, folding in the
- * boilerplate every endpoint repeats: CORS (incl. the `OPTIONS` preflight), routing the `/action`
- * `POST` body through the runtime (`handleActionPayloadWire` → `waitForResultPayload` →
- * `toHttpResponse`), an optional WebSocket-upgrade hook, and a `404` fallback.
- *
- * It only touches web-standard `Request`/`Response`, so it stays transport-agnostic — the one
- * environment-specific bit (the WS upgrade) is injected via {@link IActionFetchHandlerOptions.onWebSocketUpgrade}:
- * ```ts
- * this.fetchHandler = createActionFetchHandler(this.runtime, {
- *   onWebSocketUpgrade: () => {
- *     const pair = new WebSocketPair();
- *     this.ctx.acceptWebSocket(pair[1]);
- *     return new Response(null, { status: 101, webSocket: pair[0] });
- *   },
- * });
- * // async fetch(request) { return this.fetchHandler(request); }
- * ```
- */
-export declare function createActionFetchHandler(runtime: ActionRuntime, options?: IActionFetchHandlerOptions): (request: Request) => Promise<Response>;

package/build/types/ActionRuntime/Handler/Server/createSecureActionServer.d.ts

@@ -1,71 +0,0 @@
-import { type StorageAdapter } from "@nice-code/util";
-import type { ActionRuntime } from "../../ActionRuntime";
-import type { RuntimeCoordinate } from "../../RuntimeCoordinate";
-import { ESecurityLevel, type IClientVerifyKeyResolver } from "../ExternalClient/Transport/WebSocket/actionWsHandshake";
-import type { ISecureWsChannel } from "../ExternalClient/Transport/WebSocket/secureWsChannel";
-import { ActionServerHandler, type IActionServerConnectionBinding } from "./ActionServerHandler";
-export interface ISecureActionServerHandlerOptions<TConn> {
-    /** The shared channel identity (codec + dictionary version) — same one the clients use. */
-    channel: ISecureWsChannel;
-    /**
-     * Coordinate of the *connecting clients* (typically env-only, e.g. `RuntimeCoordinate.env("web_app")`),
-     * used to route results/pushes back over this handler.
-     */
-    clientEnv: RuntimeCoordinate;
-    /** This server's runtime — its coordinate is the server identity presented in the handshake. */
-    runtime: ActionRuntime;
-    /**
-     * One backing store for the server's crypto identity *and* its trust-on-first-use verify-key pins.
-     * Their keys don't collide, so a single adapter is enough; back it with persistent storage (e.g. a
-     * Durable Object's storage) so identity and pins survive eviction.
-     */
-    storageAdapter: StorageAdapter;
-    /** Write an encoded frame to a specific live connection (e.g. `(ws, frame) => ws.send(frame)`). */
-    send: (connection: TConn, frame: string | Uint8Array | ArrayBuffer) => void;
-    /** Accepted level(s); defaults to negotiating any of none/authenticated/encrypted. */
-    securityLevel?: ESecurityLevel | readonly ESecurityLevel[];
-    /** Trust decision for a client's verify key; defaults to storage-backed TOFU over `storageAdapter`. */
-    verifyKeyResolver?: IClientVerifyKeyResolver;
-    /** Timeout (ms) applied to server-initiated actions awaiting a client response. */
-    defaultTimeout?: number;
-}
-/**
- * Build an {@link ActionServerHandler} for the secure binary channel with the boilerplate folded in:
- * it creates the {@link ClientCryptoKeyLink} and the storage-backed TOFU resolver from a single
- * `storageAdapter`, installs the channel's per-connection codec, and assembles the `security` block
- * from the runtime coordinate + channel version (accepting all three levels by default).
- *
- * For a hibernatable transport (e.g. a Durable Object), pair it with
- * {@link createHibernatableWsServerAdapter} to wire persistence + replay.
- */
-export declare function createSecureActionServerHandler<TConn = unknown>(options: ISecureActionServerHandlerOptions<TConn>): ActionServerHandler<TConn>;
-export interface IHibernatableWsServerAdapterOptions<TConn> {
-    /** The handler to drive (from {@link createSecureActionServerHandler} or `createServerHandler`). */
-    handler: ActionServerHandler<TConn>;
-    /** All currently-live connections — replayed on construction to rebuild bindings after a wake. */
-    getWebSockets: () => TConn[];
-    /** Read a connection's persisted binding (e.g. `(ws) => ws.deserializeAttachment()`). */
-    getAttachment: (connection: TConn) => IActionServerConnectionBinding | undefined;
-    /** Persist a connection's binding when it is bound (e.g. `(ws, b) => ws.serializeAttachment(b)`). */
-    setAttachment: (connection: TConn, binding: IActionServerConnectionBinding) => void;
-}
-export interface IHibernatableWsServerAdapter<TConn> {
-    /** Feed one inbound frame from a connection into the handler. */
-    receive: (connection: TConn, frame: string | ArrayBuffer | Uint8Array) => void;
-    /** Forget a connection (call on socket close/error). */
-    drop: (connection: TConn) => void;
-}
-/**
- * Wire the hibernation lifecycle for a server handler on a transport whose sockets outlive process
- * eviction (e.g. a Durable Object's hibernatable WebSockets). It owns persistence end to end:
- * registers `setAttachment` as the handler's connection-bound callback and immediately replays every
- * live connection's stored binding via `getAttachment`, so results/pushes still route after a wake.
- *
- * Construct it once when the handler is built, then forward socket events:
- * ```ts
- * const wsServer = createHibernatableWsServerAdapter({ handler, getWebSockets, getAttachment, setAttachment });
- * // webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
- * // webSocketClose/Error(ws)  => wsServer.drop(ws);
- * ```
- */
-export declare function createHibernatableWsServerAdapter<TConn>(options: IHibernatableWsServerAdapterOptions<TConn>): IHibernatableWsServerAdapter<TConn>;

package/build/types/ActionRuntime/HandlerCallStack.d.ts

@@ -1,3 +0,0 @@
-export declare function pushHandlerCuid(cuid: string): void;
-export declare function popHandlerCuid(): void;
-export declare function peekHandlerCuid(): string | undefined;

package/build/types/ActionRuntime/Routing/ActionRouter.d.ts

@@ -1,55 +0,0 @@
-import type { INiceActionIdAndDomain } from "../../ActionDefinition/Action/ActionBase.types";
-import type { ActionCore } from "../../ActionDefinition/Action/Core/ActionCore";
-import type { ActionDomain } from "../../ActionDefinition/Domain/ActionDomain";
-import type { IActionDomain } from "../../ActionDefinition/Domain/ActionDomain.types";
-import { ActionDomainManager } from "../ActionDomainManager";
-import type { IHandleActionOptions } from "../Handler/ActionHandler.types";
-import { type IActionRouterContext, type TMatchHandlerKey } from "./ActionRouter.types";
-export declare class ActionRouter<DATA> {
-    readonly domainManager: ActionDomainManager;
-    private actionRouteData;
-    private _context;
-    constructor(context: IActionRouterContext);
-    /** Copy all routes from another router into this one, replacing any overlapping keys. */
-    mergeRouter(actionRouter: ActionRouter<DATA>): void;
-    addDomainsFromOther(actionRouter: ActionRouter<DATA>): void;
-    /** All FNs registered for an action, ID-specific entries first then domain wildcard. */
-    getRouteDataEntriesForAction(action: {
-        domain: string;
-        id: string;
-    }): DATA[];
-    /** First FN registered for an action (ID-specific beats domain wildcard). */
-    getRouteDataForAction(action: INiceActionIdAndDomain): DATA | undefined;
-    private throwNoHandlerForAction;
-    getRouteDataEntriesForActionOrThrow(action: INiceActionIdAndDomain, context: IHandleActionOptions): DATA[];
-    getRouteDataForActionOrThrow(action: INiceActionIdAndDomain, context: IHandleActionOptions): DATA;
-    /** All FNs stored under an exact match key. */
-    getForKey(key: TMatchHandlerKey): readonly DATA[];
-    /** Every match key that has at least one registered FN. */
-    getRegisteredKeys(): TMatchHandlerKey[];
-    getDomains(): ActionDomain[];
-    /** Register a handler for all actions in a domain, replacing any existing one. */
-    forDomain<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, routeData: DATA): this;
-    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(action: ActionCore<ACT_DOM, ID>, routeData: DATA): this;
-    /** Register a handler for a specific action, replacing any existing one. */
-    forActionId<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(domain: ActionDomain<ACT_DOM>, id: ID, routeData: DATA): this;
-    /** Register one handler for several action IDs, replacing any existing ones. */
-    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, routeData: DATA): this;
-    /** Register per-action handlers from a cases map, replacing any existing ones. */
-    forDomainActionCases<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, cases: {
-        [ID in keyof FOR_DOM["actionSchema"] & string]?: DATA;
-    }): this;
-    /** Append a handler for all actions in a domain (accumulates alongside existing). */
-    addForDomain<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, routeData: DATA): this;
-    /** Append a handler for a specific action (accumulates alongside existing). */
-    addForAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(domain: ActionDomain<ACT_DOM>, id: ID, routeData: DATA): this;
-    /** Append one handler for several action IDs (accumulates alongside existing). */
-    addForActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, routeData: DATA): this;
-    /** Append per-action handlers from a cases map (accumulates alongside existing). */
-    addForDomainActionCases<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, cases: {
-        [ID in keyof FOR_DOM["actionSchema"] & string]?: DATA;
-    }): this;
-    /** Append a handler directly by its raw match key (used when the key is known ahead of time). */
-    addForKey(key: TMatchHandlerKey, routeData: DATA): this;
-    private _push;
-}

package/build/types/ActionRuntime/Routing/ActionRouter.types.d.ts

@@ -1,20 +0,0 @@
-import type { ActionRuntime } from "../ActionRuntime";
-import type { TActionHandler } from "../Handler/ActionHandler.types";
-/**
- * Format: `dom[${domainName}]id[${actionId | "_"}]`
- * The wildcard `_` matches any action ID within a domain.
- */
-export type TMatchHandlerKey = `${"dom"}[${string}]id[${string | "_"}]`;
-export declare enum EActionRouterContextType {
-    runtime_to_handler = "runtime_to_handler",
-    handler_route = "handler_route"
-}
-export interface IActionRouterContext_HandlerRoute {
-    contextType: EActionRouterContextType.handler_route;
-    handler: TActionHandler;
-}
-export interface IActionRouterContext_RuntimeToHandler {
-    contextType: EActionRouterContextType.runtime_to_handler;
-    runtime: ActionRuntime;
-}
-export type IActionRouterContext = IActionRouterContext_HandlerRoute | IActionRouterContext_RuntimeToHandler;

package/build/types/ActionRuntime/RuntimeCoordinate.d.ts

@@ -1,58 +0,0 @@
-export interface IRuntimeCoordinateSpecifics {
-    /**
-     * A unique and persistent client ID (should stay the same between runtime instance reloads)
-     */
-    perId?: string;
-    /**
-     * A unique instance (or "memory-only") ID (unique for each instance of an action runtime, which should generally
-     * not persist between reloads, depending on the architecture)
-     */
-    insId?: string;
-}
-export interface IRuntimeCoordinate extends IRuntimeCoordinateSpecifics {
-    /**
-     * A static runtime environment identifier (e.g. "web_app_v1", "backend_analytics")
-     */
-    envId: string;
-}
-export type TRuntimeCoordinateEnvId = `envId[${string}]`;
-export type TRuntimeCoordinateStringId = `${TRuntimeCoordinateEnvId}perId[${string | "_"}]:insId[${string | "_"}]`;
-export interface IRuntimeFullCoordinates extends Required<IRuntimeCoordinate> {
-}
-export declare class RuntimeCoordinate implements IRuntimeCoordinate {
-    readonly envId: string;
-    readonly perId?: string;
-    readonly insId?: string;
-    static get unknown(): RuntimeCoordinate;
-    static env(envId: string): RuntimeCoordinate;
-    withPersistentId(perId: string): RuntimeCoordinate;
-    constructor({ envId, perId, insId }: IRuntimeCoordinate);
-    specify(specifics: IRuntimeCoordinateSpecifics): RuntimeCoordinate;
-    specifyIfUnset(specifics: IRuntimeCoordinateSpecifics): RuntimeCoordinate;
-    toJsonObject(): IRuntimeCoordinate;
-    isExactlySame(other: IRuntimeCoordinate): boolean;
-    isSameFor(other: IRuntimeCoordinate): {
-        id: boolean;
-        perId: boolean;
-        insId: boolean;
-    };
-    similarityLevel(other: IRuntimeCoordinate): number;
-    get stringId(): TRuntimeCoordinateStringId;
-    /**
-     * Takes the "Runtime Coordinate" and generates a list of full coordinate IDs representing the runtime
-     * with decreasing levels of specificity.
-     *
-     * The first full coordinate ID is the most specific (including instance ID), while the last ID is
-     * the least specific (only environment ID).
-     *
-     * Example output for a RuntimeCoordinate with envId "web_app", perId "user123", and insId "instance456":
-     * [
-     *   "envId[web_app]perId[user123]:insId[instance456]",
-     *   "envId[web_app]perId[user123]:insId[_]",
-     *   "envId[web_app]perId[_]:insId[_]"
-     * ]
-     *
-     * @returns a list of "full" runtime coordinate IDs with decreasing accuracy for targeting a runtime.
-     */
-    toStringIds(): TRuntimeCoordinateStringId[];
-}