@nice-code/action 0.23.0 → 0.24.0

package/build/advanced/index.d.mts

@@ -0,0 +1,344 @@
+import { $t as IActionTransportInitialized, An as TransportConnection, Bn as IHandshakeEncryptionKeyMaterial, Bt as IActionWireFormat, Cn as TSendActionDataMethod, Ct as createHibernatableWsServerAdapter, Dn as TTransportStatusInfo, Dt as createConnectionStateStore, En as TTransportInitializationFinishedInfo, Et as IConnectionStateStoreOptions, Fn as EHandshakeMessageType, Hn as IServerHandshakeConfig, In as ESecurityLevel, Jn as decodeHandshakeMessage, Jt as createConnectorHandler, Kn as createServerHandshake, Ln as IClientHandshakeConfig, Mn as Transport, Nn as ISecureAcceptorHandlerOptions, O as TActionPayload_Any_JsonObject, On as TTransportStatusInfo_GetTransport_Output, Pn as createSecureAcceptorHandler, Qt as IActionTransportDef, Rt as IBinaryWireSessionOptions, Sn as TOnResolveIncomingResponseJson, St as IHibernatableWsServerAdapterOptions, Tn as TTransportCache, Tt as IConnectionAttachment, Un as THandshakeMessage, Ut as IExchangeCarrier, Vn as IHandshakeResult, Vt as IDuplexCarrier, Wn as createClientHandshake, Xt as ETransportShape, Yn as encodeHandshakeMessage, Yt as PeerLinkHandler, Zt as ETransportStatus, _n as TOnResolveAnyIncomingActionData, a as TAcceptorConnectionCaseFn, an as ITransportDispatchAction, bn as TOnResolveIncomingRequestJson, c as createAcceptorHandler, cn as ITransportRouteClientParams, dn as ITransportStatusInfo_Failed, en as IActionTransportReady, fn as ITransportStatusInfo_Initializing, gn as TGetTransportFn, hn as IUpdateActionRunConfig_Output, hr as IRuntimeCoordinate, i as TAcceptorCaseFn, in as ISecureClientConfig, jn as ITransportConnectionContext, kn as TUpdateActionRunConfig, l as ActionDomain, ln as ITransportRouteInfo, mn as ITransportStatusInfo_Unsupported, n as IAcceptorConnectionBinding, nn as IActionTransportReadyData_Methods, o as TActionChannelFormatMessage, on as ITransportMethod_SendActionData_Input, pn as ITransportStatusInfo_Ready, qt as ConnectorHandler, r as IAcceptorHandlerOptions, rn as IActionTransportResolvers, s as TActionConnectionEncoding, sn as ITransportRouteActionParams, t as AcceptorHandler, tn as IActionTransportReadyData_Base, u as ActionRuntime, un as ITransportStatusInfo_Base, vn as TOnResolveAnyIncomingActionData_Json, wn as TSendReturnDataMethod, wt as ConnectionStateStore, xn as TOnResolveIncomingResponse, xt as IDuplexConnectionRouter, yn as TOnResolveIncomingRequest, zn as IClientVerifyKeyResolver, zt as createBinaryWireSessionFactory } from "../AcceptorHandler-11-QMdx2.mjs";
+import { ClientCryptoKeyLink, TTypeAndId } from "@nice-code/util";
+
+//#region src/ActionRuntime/Transport/SecureSession/exchangeAcceptor.d.ts
+/** Acceptor secure config for the exchange (HTTP) endpoint — same identity an `AcceptorHandler` uses. */
+interface IExchangeAcceptorSecurity {
+  /** This acceptor's crypto identity (verify + exchange key pairs, optionally persisted). */
+  link: ClientCryptoKeyLink;
+  /** This acceptor's coordinate — its identity to clients during the handshake. */
+  localCoordinate: IRuntimeCoordinate;
+  /** Wire dictionary version; the handshake rejects a client on a mismatch. */
+  dictionaryVersion: string;
+  /** Accepted level(s) — a single level is strict, an array is a negotiable allowed set. */
+  securityLevel: ESecurityLevel | readonly ESecurityLevel[];
+  /** Trust decision for a client's verify key (defaults to in-memory TOFU inside the handshake). */
+  verifyKeyResolver?: IClientVerifyKeyResolver;
+}
+interface IExchangeAcceptorConfig {
+  security: IExchangeAcceptorSecurity;
+  /** The runtime that executes an inbound action wire and produces its result. */
+  runtime: ActionRuntime;
+}
+/**
+ * Acceptor (accept-in) side of the secure exchange protocol — the HTTP counterpart to
+ * {@link AcceptorSecureSession}. Each POST body is one {@link decodeExchangeRequest} envelope; the
+ * acceptor drives the server handshake over the two `hs` POSTs (correlated by `hsid`, since stateless
+ * requests can't rely on channel ordering), mints a session **token** on accept, and on every later `act`
+ * POST resolves the session by token, decrypts the body (at `encrypted`), routes it through the runtime,
+ * and returns the (encrypted) result inline as the reply.
+ *
+ * Sessions and in-flight handshakes are held in memory — fine for a single-instance server. (Surviving a
+ * Durable-Object eviction would persist each token's `keyMaterial` and re-derive the key on a miss, the
+ * same primitive `AcceptorSecureSession.rehydrate` uses; left as a follow-up.)
+ */
+declare class ExchangeAcceptor {
+  private readonly _security;
+  private readonly _runtime;
+  private readonly _allowedLevels;
+  private readonly _noneAllowed;
+  private readonly _pendingHandshakes;
+  private readonly _sessions;
+  constructor(config: IExchangeAcceptorConfig);
+  /** Process one POST body (an exchange envelope), returning the reply body to send back. */
+  handlePost(body: string): Promise<string>;
+  private _handleHandshake;
+  private _handleAction;
+  private _err;
+}
+//#endregion
+//#region src/ActionRuntime/Handler/PeerLink/Acceptor/createActionFetchHandler.d.ts
+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;
+  /**
+   * Whether a request is a WebSocket upgrade for this endpoint, given the whole request (not just the
+   * URL). When set it *replaces* the default gate (an `Upgrade: websocket` header on an
+   * {@link isWebSocketPath} match) — use it when the discriminant needs a header or method, not only the
+   * path. Only consulted when {@link onWebSocketUpgrade} is present.
+   */
+  isWebSocketUpgrade?: (request: Request, 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;
+  /**
+   * Enable the secure exchange protocol (handshake + token sessions + body encryption) on the `/action`
+   * endpoint, mirroring an `AcceptorHandler`'s `security`. The matching connector is a secure HTTP
+   * transport (`connectChannel(..., { transports: [{ carrier: httpCarrier(...) }] })`). When omitted, the
+   * endpoint speaks the plain protocol (the raw action wire is POSTed and the result is the response body).
+   */
+  security?: IExchangeAcceptorSecurity;
+}
+/**
+ * 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); }
+ * ```
+ */
+declare function createActionFetchHandler(runtime: ActionRuntime, options?: IActionFetchHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/ActionRuntime/Transport/codec/createBinaryWireAdapter.d.ts
+/**
+ * Builds a *stateless* `formatMessage` pipeline for {@link LinkTransport}, packing action
+ * payloads into a compact msgpackr binary frame instead of JSON. The `domain`/`id` route collapses to
+ * a single integer drawn from a shared dictionary; `form`/`type`, the recomputable
+ * `inputHash`/`outputHash`, and the per-frame `context.routing`/`context.timeCreated` are all dropped
+ * (see {@link ENVELOPE}).
+ *
+ * No validation runs here: `incoming` blindly reconstructs the wire JSON shape and hands it back to
+ * the connection, which flows into `ActionRuntime` → `domain.hydrateAnyAction()` where the Valibot
+ * schemas validate it exactly as they would for a JSON frame.
+ *
+ * Both ends of the socket MUST construct the adapter with the same domains in the same order — the
+ * integer dictionary is positional. Mismatched dictionaries will route to the wrong action.
+ *
+ * Because `incoming` returns `undefined` for text frames, a binary server can still serve plain-JSON
+ * clients on the same runtime (the connection falls back to its built-in JSON parser).
+ */
+declare function createBinaryWireAdapter(domains: ActionDomain<any>[]): IActionWireFormat;
+//#endregion
+//#region src/ActionRuntime/Transport/crypto/actionFrameCrypto.d.ts
+/**
+ * Async AES-GCM transform for the `encrypted` security level. It wraps the opaque binary frame a
+ * session codec produces (it does NOT look inside it), encrypting on the way out and decrypting on the
+ * way in with the shared key established by the handshake.
+ *
+ * It is deliberately separate from the (synchronous) session `formatMessage`: WebCrypto is always
+ * Promise-based, so encryption has to happen at the transport's async I/O boundary — the connection
+ * encrypts after `session.outgoing()` and decrypts before `session.incoming()`. The `authenticated`
+ * and `none` levels use no crypto transform at all (frames go out as the session produced them).
+ *
+ * Wire shape of an encrypted frame: `pack([nonceBytes, ciphertextBytes])` — msgpack carries the two
+ * binary fields with a couple of bytes of overhead, no base64 inflation.
+ */
+interface IActionFrameCrypto {
+  /** Encrypt one session frame for sending. */
+  encryptFrame(frame: Uint8Array): Promise<Uint8Array>;
+  /** Decrypt one received frame back to the session frame. Throws on a non-binary / malformed /
+   * tampered frame — the caller (transport) decides how to react (drop / close). */
+  decryptFrame(frame: string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;
+}
+interface IActionFrameCryptoConfig {
+  link: ClientCryptoKeyLink;
+  /** The handshake-established link id for the remote (key + connection-registry id). */
+  linkedClientId: TTypeAndId;
+}
+/**
+ * Build the encrypt/decrypt transform for a connection whose handshake settled on the `encrypted`
+ * level. Keyed by the link + `linkedClientId`, so it reuses the cached shared AES-GCM key.
+ */
+declare function createActionFrameCrypto({
+  link,
+  linkedClientId
+}: IActionFrameCryptoConfig): IActionFrameCrypto;
+//#endregion
+//#region src/ActionRuntime/Transport/Exchange/TransportExchange.types.d.ts
+interface IActionTransportReadyData_Exchange extends IActionTransportReadyData_Base {
+  /** The live request/reply carrier this connection drives its session over. */
+  carrier: IExchangeCarrier;
+  /** Optional authenticated/encrypted config; the handshake runs once at bring-up when set. */
+  secureChannel?: ISecureClientConfig;
+}
+interface IActionTransportInitialized_Exchange extends IActionTransportInitialized<ITransportRouteActionParams, IActionTransportReadyData_Exchange> {}
+interface IActionTransportDef_Exchange extends IActionTransportDef<ETransportShape.exchange, IActionTransportInitialized_Exchange> {}
+//#endregion
+//#region src/ActionRuntime/Transport/Exchange/ExchangeConnection.d.ts
+/**
+ * Carrier-agnostic live connection for the exchange (request → single reply) shape — the HTTP
+ * counterpart to {@link LinkConnection}. It owns only the bring-up (run the secure handshake on first
+ * use); the request/reply lifecycle + crypto live in the shared `establishExchangeSession`.
+ */
+declare class ExchangeConnection extends TransportConnection<ETransportShape.exchange, ITransportRouteActionParams, IActionTransportReadyData_Exchange, IActionTransportInitialized_Exchange, IActionTransportDef_Exchange> {
+  constructor(def: Omit<IActionTransportDef_Exchange, "type">);
+  protected _getCacheKey(input: ITransportRouteActionParams): string;
+  protected _needsAsyncBringUp(data: IActionTransportReadyData_Exchange): boolean;
+  protected _finalizeReady(data: IActionTransportReadyData_Exchange): IActionTransportReadyData_Methods | Promise<IActionTransportReadyData_Methods>;
+  _finalizeTransportMethods(data: IActionTransportReadyData_Exchange): IActionTransportReadyData_Methods;
+  private _sessionContext;
+}
+//#endregion
+//#region src/ActionRuntime/Transport/Exchange/ExchangeTransport.d.ts
+interface IExchangeTransportOptions {
+  /** Open (or reuse) the exchange carrier for an action — e.g. `httpCarrier(...).open`. */
+  openCarrier: (input: ITransportRouteActionParams) => IExchangeCarrier;
+  /** Secure config; when set (and `securityLevel !== none`) the handshake runs once at bring-up. */
+  security?: ISecureClientConfig;
+  updateRunConfig?: TUpdateActionRunConfig;
+  /** Keys identifying a reusable session, so one carrier is shared across actions to the same peer. */
+  getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
+  /**
+   * Optional availability gate. When it returns `false`, the manager skips this transport for that action
+   * (reporting `unsupported`) and falls through to the next — without opening the carrier or computing its
+   * cache key. Re-evaluated per dispatch, so the transport can become available later with no reconnect.
+   */
+  available?: (input: ITransportRouteActionParams) => boolean;
+  /** Short label for the devtools chip (defaults to "exchange"). */
+  label?: string;
+  getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+}
+/**
+ * A carrier-agnostic exchange (request → single reply) transport: it drives nice-action's secure session
+ * over any {@link IExchangeCarrier} (HTTP being the one built-in). The duplex counterpart is
+ * {@link LinkTransport}; this is the no-push half — its reply rides the response to its own request, so it
+ * can't deliver an unsolicited frame (the runtime never picks it for the return path).
+ */
+declare class ExchangeTransport extends Transport<ETransportShape.exchange> {
+  private readonly options;
+  readonly type = ETransportShape.exchange;
+  constructor(options: IExchangeTransportOptions);
+  static create(options: IExchangeTransportOptions): ExchangeTransport;
+  _createConnection(_ctx: ITransportConnectionContext): ExchangeConnection;
+  getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
+}
+//#endregion
+//#region src/ActionRuntime/Transport/Link/TransportLink.types.d.ts
+/** The per-connection codec (positional binary wire / JSON fallback) the carrier's session uses. */
+type TLinkFormatMessage = IActionWireFormat;
+interface IActionTransportReadyData_Link extends IActionTransportReadyData_Base {
+  /** The live carrier this connection drives its session over. */
+  channel: IDuplexCarrier;
+  formatMessage?: TLinkFormatMessage;
+  /** Optional authenticated/encrypted channel; the connection runs the handshake during init. */
+  secureChannel?: ISecureClientConfig;
+}
+interface IActionTransportInitialized_Link extends IActionTransportInitialized<ITransportRouteActionParams, IActionTransportReadyData_Link> {}
+interface IActionTransportDef_Link extends IActionTransportDef<ETransportShape.duplex, IActionTransportInitialized_Link> {}
+//#endregion
+//#region src/ActionRuntime/Transport/Link/LinkConnection.d.ts
+/**
+ * Carrier-agnostic live connection. It owns only the *bring-up* (open the carrier, then run the secure
+ * session); the session itself — handshake, frame crypto, codec, send/receive — lives in the shared
+ * {@link finalizeSecureLinkMethods}/{@link finalizePlainLinkMethods}, so a WebSocket, a WebRTC data
+ * channel, a Bluetooth characteristic, and an in-memory pipe all run the identical secure layer.
+ */
+declare class LinkConnection extends TransportConnection<ETransportShape.duplex, ITransportRouteActionParams, IActionTransportReadyData_Link, IActionTransportInitialized_Link, IActionTransportDef_Link> {
+  private resolvers;
+  constructor(def: Omit<IActionTransportDef_Link, "type">, resolvers?: IActionTransportResolvers);
+  protected _getCacheKey(input: ITransportRouteActionParams): string;
+  protected _needsAsyncBringUp(): boolean;
+  protected _awaitCarrierReady(data: IActionTransportReadyData_Link): Promise<void>;
+  protected _finalizeReady(data: IActionTransportReadyData_Link): IActionTransportReadyData_Methods | Promise<IActionTransportReadyData_Methods>;
+  private _sessionContext;
+  _finalizeTransportMethods(data: IActionTransportReadyData_Link): IActionTransportReadyData_Methods;
+}
+//#endregion
+//#region src/ActionRuntime/Transport/Link/LinkTransport.d.ts
+interface ILinkTransportOptions {
+  /**
+   * Open (or reuse) the carrier for an action — a WebSocket adapter, a WebRTC data channel, a Bluetooth
+   * characteristic, an in-memory pipe, anything that satisfies {@link IDuplexCarrier}.
+   */
+  openChannel: (input: ITransportRouteActionParams) => IDuplexCarrier;
+  /** Shared codec for every channel (stateless). */
+  formatMessage?: TLinkFormatMessage;
+  /**
+   * Per-channel codec factory — called once per opened channel so stateful codecs (e.g. the binary
+   * session) get their own instance. Takes precedence over `formatMessage`.
+   */
+  createFormatMessage?: () => TLinkFormatMessage;
+  /** Secure-channel config; when set (and `securityLevel !== none`) the handshake runs on init. */
+  security?: ISecureClientConfig;
+  updateRunConfig?: TUpdateActionRunConfig;
+  /** Keys identifying a reusable channel, so one carrier is shared across actions to the same peer. */
+  getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
+  /**
+   * Optional availability gate. When it returns `false`, the manager skips this transport for that action
+   * (reporting `unsupported`) and falls through to the next — without opening the carrier or computing its
+   * cache key. Re-evaluated per dispatch, so the transport can become available later with no reconnect.
+   */
+  available?: (input: ITransportRouteActionParams) => boolean;
+  /** Short label for the devtools chip (defaults to "link"). */
+  label?: string;
+  getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+}
+/**
+ * A carrier-agnostic transport: it drives nice-action's secure session + action routing over any
+ * {@link IDuplexCarrier}. The WebSocket transport is the special case that opens a `WebSocket`;
+ * this opens whatever `openChannel` returns, so the identical secure layer works over WebRTC, Bluetooth,
+ * or an in-memory pipe. Reported with an overridable carrier label in the devtools (defaults to "link").
+ */
+declare class LinkTransport extends Transport<ETransportShape.duplex> {
+  private readonly options;
+  readonly type = ETransportShape.duplex;
+  constructor(options: ILinkTransportOptions);
+  static create(options: ILinkTransportOptions): LinkTransport;
+  _createConnection(ctx: ITransportConnectionContext): LinkConnection;
+  getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
+}
+//#endregion
+//#region src/ActionRuntime/Transport/SecureSession/exchangeProtocol.d.ts
+/**
+ * The application-level envelope for secure action traffic over an {@link IExchangeCarrier} (HTTP). An
+ * exchange carrier only moves one request frame → one reply frame with no unsolicited push, so the
+ * handshake and the per-action token + crypto all ride in this envelope (a JSON string body) rather than
+ * on a persistent channel. The three security levels share it:
+ *
+ * - `none` — no handshake, no token: an `act` envelope carries the plaintext wire both ways.
+ * - `authenticated` — a one-time handshake yields a session `token`; each later `act` carries it +
+ *   the plaintext wire.
+ * - `encrypted` — same, but the wire is AES-GCM ciphertext, base64 in the `c` field.
+ *
+ * The handshake runs as two `hs` exchanges (hello→welcome, prove→accept) correlated by a client-chosen
+ * `hsid`, since stateless requests can't rely on channel ordering. The `accept` reply carries the token.
+ */
+type TWireJson = TActionPayload_Any_JsonObject<any, any>;
+/** Connector → acceptor request envelope. */
+type TExchangeRequest = {
+  k: "hs";
+  hsid: string;
+  m: string;
+} | {
+  k: "act";
+  t?: string;
+  w: TWireJson;
+} | {
+  k: "act";
+  t?: string;
+  c: string;
+};
+/** Acceptor → connector reply envelope. */
+type TExchangeReply = {
+  k: "hs";
+  m: string;
+  t?: string;
+} | {
+  k: "act";
+  w: TWireJson;
+} | {
+  k: "act";
+  c: string;
+} | {
+  k: "err";
+  message: string;
+};
+declare function encodeExchange(envelope: TExchangeRequest | TExchangeReply): string;
+declare function decodeExchangeRequest(raw: string): TExchangeRequest | undefined;
+declare function decodeExchangeReply(raw: string): TExchangeReply | undefined;
+//#endregion
+export { AcceptorHandler, ConnectionStateStore, ConnectorHandler, EHandshakeMessageType, ETransportShape, ETransportStatus, ExchangeAcceptor, ExchangeTransport, type IAcceptorConnectionBinding, type IAcceptorHandlerOptions, type IActionFetchHandlerOptions, type IActionFrameCrypto, type IActionFrameCryptoConfig, IActionTransportDef, IActionTransportInitialized, IActionTransportReady, IActionTransportReadyData_Base, type IActionTransportReadyData_Exchange, type IActionTransportReadyData_Link, IActionTransportReadyData_Methods, IActionTransportResolvers, type IActionWireFormat, type IBinaryWireSessionOptions, type IClientHandshakeConfig, type IConnectionAttachment, type IConnectionStateStoreOptions, type IDuplexConnectionRouter, type IExchangeAcceptorConfig, type IExchangeAcceptorSecurity, type IExchangeTransportOptions, type IHandshakeEncryptionKeyMaterial, type IHandshakeResult, type IHibernatableWsServerAdapterOptions, type ILinkTransportOptions, type ISecureAcceptorHandlerOptions, ISecureClientConfig, type IServerHandshakeConfig, type ITransportConnectionContext, ITransportDispatchAction, ITransportMethod_SendActionData_Input, ITransportRouteActionParams, ITransportRouteClientParams, ITransportRouteInfo, ITransportStatusInfo_Base, ITransportStatusInfo_Failed, ITransportStatusInfo_Initializing, ITransportStatusInfo_Ready, ITransportStatusInfo_Unsupported, IUpdateActionRunConfig_Output, LinkTransport, PeerLinkHandler, type TAcceptorCaseFn, type TAcceptorConnectionCaseFn, type TActionChannelFormatMessage, type TActionConnectionEncoding, type TExchangeReply, type TExchangeRequest, TGetTransportFn, type THandshakeMessage, type TLinkFormatMessage, TOnResolveAnyIncomingActionData, TOnResolveAnyIncomingActionData_Json, TOnResolveIncomingRequest, TOnResolveIncomingRequestJson, TOnResolveIncomingResponse, TOnResolveIncomingResponseJson, TSendActionDataMethod, TSendReturnDataMethod, TTransportCache, TTransportInitializationFinishedInfo, TTransportStatusInfo, TTransportStatusInfo_GetTransport_Output, TUpdateActionRunConfig, Transport, createAcceptorHandler, createActionFetchHandler, createActionFrameCrypto, createBinaryWireAdapter, createBinaryWireSessionFactory, createClientHandshake, createConnectionStateStore, createConnectorHandler, createHibernatableWsServerAdapter, createSecureAcceptorHandler, createServerHandshake, decodeExchangeReply, decodeExchangeRequest, decodeHandshakeMessage, encodeExchange, encodeHandshakeMessage };
+//# sourceMappingURL=index.d.mts.map

package/build/advanced/index.mjs

@@ -0,0 +1,88 @@
+import { A as encodeHandshakeMessage, C as EHandshakeMessageType, D as createServerHandshake, F as ConnectorHandler, I as createConnectorHandler, L as PeerLinkHandler, R as ETransportShape, T as createClientHandshake, _ as extractWirePayload, a as ExchangeAcceptor, b as createAcceptorHandler, c as decodeExchangeReply, d as Transport, f as createBinaryWireSessionFactory, g as buildActionRouteDictionary, h as assembleWireJson, i as createActionFetchHandler, k as decodeHandshakeMessage, l as decodeExchangeRequest, m as ReversePayloadType, n as ConnectionStateStore, o as LinkTransport, p as PayloadTypeToInt, r as createConnectionStateStore, s as ExchangeTransport, t as createHibernatableWsServerAdapter, u as encodeExchange, v as createSecureAcceptorHandler, x as createActionFrameCrypto, y as AcceptorHandler, z as ETransportStatus } from "../createHibernatableWsServerAdapter-C07RfUTH.mjs";
+import { pack, unpack } from "msgpackr";
+//#region src/ActionRuntime/Transport/codec/createBinaryWireAdapter.ts
+/**
+* Positional layout of the stateless binary envelope. A flat tuple (rather than an object) strips the
+* repeated `domain`/`id`/`form`/`type` and context key names from every frame, and we carry only the
+* context fields the receiver can't recompute: `cuid` (correlation) and `originClient` (return
+* routing).
+*
+*   [ routeInt, typeInt, time, cuid, originClient, payloadData ]
+*
+* Dropped vs the JSON wire: `form`/`type` strings, `inputHash`/`outputHash` (recomputed on hydrate),
+* `context.timeCreated` (reconstructed from `time`) and `context.routing` (rebuilt empty — the
+* receiver re-stamps its own route items as it handles the action). For the leanest possible frames
+* (integer correlation, identity dropped after a handshake), use `createBinaryWireSessionFactory`.
+*/
+const ENVELOPE = {
+	route: 0,
+	type: 1,
+	time: 2,
+	cuid: 3,
+	originClient: 4,
+	payload: 5
+};
+const ENVELOPE_LENGTH = 6;
+/**
+* Builds a *stateless* `formatMessage` pipeline for {@link LinkTransport}, packing action
+* payloads into a compact msgpackr binary frame instead of JSON. The `domain`/`id` route collapses to
+* a single integer drawn from a shared dictionary; `form`/`type`, the recomputable
+* `inputHash`/`outputHash`, and the per-frame `context.routing`/`context.timeCreated` are all dropped
+* (see {@link ENVELOPE}).
+*
+* No validation runs here: `incoming` blindly reconstructs the wire JSON shape and hands it back to
+* the connection, which flows into `ActionRuntime` → `domain.hydrateAnyAction()` where the Valibot
+* schemas validate it exactly as they would for a JSON frame.
+*
+* Both ends of the socket MUST construct the adapter with the same domains in the same order — the
+* integer dictionary is positional. Mismatched dictionaries will route to the wrong action.
+*
+* Because `incoming` returns `undefined` for text frames, a binary server can still serve plain-JSON
+* clients on the same runtime (the connection falls back to its built-in JSON parser).
+*/
+function createBinaryWireAdapter(domains) {
+	const { routeToInt, intToRoute } = buildActionRouteDictionary(domains);
+	return {
+		outgoing: (input) => {
+			const json = input.action.toJsonObject();
+			const routeKey = `${json.domain}:${json.id}`;
+			const routeInt = routeToInt.get(routeKey);
+			if (routeInt == null) throw new Error(`[binary-wire] Cannot pack unregistered action route: ${routeKey}`);
+			const envelope = new Array(ENVELOPE_LENGTH);
+			envelope[ENVELOPE.route] = routeInt;
+			envelope[ENVELOPE.type] = PayloadTypeToInt[json.type];
+			envelope[ENVELOPE.time] = json.time;
+			envelope[ENVELOPE.cuid] = json.context.cuid;
+			envelope[ENVELOPE.originClient] = json.context.originClient;
+			envelope[ENVELOPE.payload] = extractWirePayload(json);
+			return pack(envelope);
+		},
+		incoming: (frame) => {
+			let buffer;
+			if (frame instanceof ArrayBuffer) buffer = new Uint8Array(frame);
+			else if (frame instanceof Uint8Array) buffer = frame;
+			else return;
+			try {
+				const envelope = unpack(buffer);
+				if (!Array.isArray(envelope) || envelope.length !== ENVELOPE_LENGTH) return void 0;
+				const routeMeta = intToRoute[envelope[ENVELOPE.route]];
+				const payloadType = ReversePayloadType[envelope[ENVELOPE.type]];
+				if (routeMeta == null || payloadType == null) return void 0;
+				const time = envelope[ENVELOPE.time];
+				return assembleWireJson(routeMeta, payloadType, time, {
+					cuid: envelope[ENVELOPE.cuid],
+					timeCreated: time,
+					routing: [],
+					originClient: envelope[ENVELOPE.originClient]
+				}, envelope[ENVELOPE.payload]);
+			} catch (e) {
+				console.error("[binary-wire] Failed to unpack binary action frame", e);
+				return;
+			}
+		}
+	};
+}
+//#endregion
+export { AcceptorHandler, ConnectionStateStore, ConnectorHandler, EHandshakeMessageType, ETransportShape, ETransportStatus, ExchangeAcceptor, ExchangeTransport, LinkTransport, PeerLinkHandler, Transport, createAcceptorHandler, createActionFetchHandler, createActionFrameCrypto, createBinaryWireAdapter, createBinaryWireSessionFactory, createClientHandshake, createConnectionStateStore, createConnectorHandler, createHibernatableWsServerAdapter, createSecureAcceptorHandler, createServerHandshake, decodeExchangeReply, decodeExchangeRequest, decodeHandshakeMessage, encodeExchange, encodeHandshakeMessage };
+
+//# sourceMappingURL=index.mjs.map

package/build/advanced/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/ActionRuntime/Transport/codec/createBinaryWireAdapter.ts"],"sourcesContent":["import { pack, unpack } from \"msgpackr\";\r\nimport type { ActionDomain } from \"../../../ActionDefinition/Domain/ActionDomain\";\r\nimport type { ITransportRouteActionParams } from \"../Transport.types\";\r\nimport {\r\n  assembleWireJson,\r\n  buildActionRouteDictionary,\r\n  extractWirePayload,\r\n  type IActionWireFormat,\r\n  PayloadTypeToInt,\r\n  ReversePayloadType,\r\n} from \"./actionWireCodec\";\r\n\r\n/**\r\n * Positional layout of the stateless binary envelope. A flat tuple (rather than an object) strips the\r\n * repeated `domain`/`id`/`form`/`type` and context key names from every frame, and we carry only the\r\n * context fields the receiver can't recompute: `cuid` (correlation) and `originClient` (return\r\n * routing).\r\n *\r\n *   [ routeInt, typeInt, time, cuid, originClient, payloadData ]\r\n *\r\n * Dropped vs the JSON wire: `form`/`type` strings, `inputHash`/`outputHash` (recomputed on hydrate),\r\n * `context.timeCreated` (reconstructed from `time`) and `context.routing` (rebuilt empty — the\r\n * receiver re-stamps its own route items as it handles the action). For the leanest possible frames\r\n * (integer correlation, identity dropped after a handshake), use `createBinaryWireSessionFactory`.\r\n */\r\nconst ENVELOPE = {\r\n  route: 0,\r\n  type: 1,\r\n  time: 2,\r\n  cuid: 3,\r\n  originClient: 4,\r\n  payload: 5,\r\n} as const;\r\nconst ENVELOPE_LENGTH = 6;\r\n\r\n/**\r\n * Builds a *stateless* `formatMessage` pipeline for {@link LinkTransport}, packing action\r\n * payloads into a compact msgpackr binary frame instead of JSON. The `domain`/`id` route collapses to\r\n * a single integer drawn from a shared dictionary; `form`/`type`, the recomputable\r\n * `inputHash`/`outputHash`, and the per-frame `context.routing`/`context.timeCreated` are all dropped\r\n * (see {@link ENVELOPE}).\r\n *\r\n * No validation runs here: `incoming` blindly reconstructs the wire JSON shape and hands it back to\r\n * the connection, which flows into `ActionRuntime` → `domain.hydrateAnyAction()` where the Valibot\r\n * schemas validate it exactly as they would for a JSON frame.\r\n *\r\n * Both ends of the socket MUST construct the adapter with the same domains in the same order — the\r\n * integer dictionary is positional. Mismatched dictionaries will route to the wrong action.\r\n *\r\n * Because `incoming` returns `undefined` for text frames, a binary server can still serve plain-JSON\r\n * clients on the same runtime (the connection falls back to its built-in JSON parser).\r\n */\r\nexport function createBinaryWireAdapter(domains: ActionDomain<any>[]): IActionWireFormat {\r\n  const { routeToInt, intToRoute } = buildActionRouteDictionary(domains);\r\n\r\n  return {\r\n    outgoing: (input: ITransportRouteActionParams): Uint8Array => {\r\n      const json = input.action.toJsonObject();\r\n      const routeKey = `${json.domain}:${json.id}`;\r\n      const routeInt = routeToInt.get(routeKey);\r\n\r\n      if (routeInt == null) {\r\n        throw new Error(`[binary-wire] Cannot pack unregistered action route: ${routeKey}`);\r\n      }\r\n\r\n      const envelope = new Array(ENVELOPE_LENGTH);\r\n      envelope[ENVELOPE.route] = routeInt;\r\n      envelope[ENVELOPE.type] = PayloadTypeToInt[json.type];\r\n      envelope[ENVELOPE.time] = json.time;\r\n      envelope[ENVELOPE.cuid] = json.context.cuid;\r\n      envelope[ENVELOPE.originClient] = json.context.originClient;\r\n      envelope[ENVELOPE.payload] = extractWirePayload(json);\r\n\r\n      return pack(envelope);\r\n    },\r\n\r\n    incoming: (frame: string | ArrayBuffer | Uint8Array | Blob) => {\r\n      // Only binary frames are ours. Text frames fall through to the JSON parser; Blobs should have\r\n      // been converted to a buffer by the connection before reaching us — if not, we can't unpack\r\n      // them synchronously, so defer.\r\n      let buffer: Uint8Array;\r\n      if (frame instanceof ArrayBuffer) {\r\n        buffer = new Uint8Array(frame);\r\n      } else if (frame instanceof Uint8Array) {\r\n        buffer = frame;\r\n      } else {\r\n        return undefined;\r\n      }\r\n\r\n      try {\r\n        const envelope = unpack(buffer);\r\n\r\n        if (!Array.isArray(envelope) || envelope.length !== ENVELOPE_LENGTH) return undefined;\r\n\r\n        const routeMeta = intToRoute[envelope[ENVELOPE.route]];\r\n        const payloadType = ReversePayloadType[envelope[ENVELOPE.type]];\r\n        if (routeMeta == null || payloadType == null) return undefined;\r\n\r\n        const time = envelope[ENVELOPE.time];\r\n        // Rebuild the context: `routing` starts empty (the receiver re-stamps its own hops) and\r\n        // `timeCreated` is approximated by the payload `time` — neither affects hydration/validation.\r\n        const context = {\r\n          cuid: envelope[ENVELOPE.cuid],\r\n          timeCreated: time,\r\n          routing: [],\r\n          originClient: envelope[ENVELOPE.originClient],\r\n        };\r\n\r\n        return assembleWireJson(routeMeta, payloadType, time, context, envelope[ENVELOPE.payload]);\r\n      } catch (e) {\r\n        console.error(\"[binary-wire] Failed to unpack binary action frame\", e);\r\n        return undefined;\r\n      }\r\n    },\r\n  };\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,MAAM,WAAW;CACf,OAAO;CACP,MAAM;CACN,MAAM;CACN,MAAM;CACN,cAAc;CACd,SAAS;AACX;AACA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;AAmBxB,SAAgB,wBAAwB,SAAiD;CACvF,MAAM,EAAE,YAAY,eAAe,2BAA2B,OAAO;CAErE,OAAO;EACL,WAAW,UAAmD;GAC5D,MAAM,OAAO,MAAM,OAAO,aAAa;GACvC,MAAM,WAAW,GAAG,KAAK,OAAO,GAAG,KAAK;GACxC,MAAM,WAAW,WAAW,IAAI,QAAQ;GAExC,IAAI,YAAY,MACd,MAAM,IAAI,MAAM,wDAAwD,UAAU;GAGpF,MAAM,WAAW,IAAI,MAAM,eAAe;GAC1C,SAAS,SAAS,SAAS;GAC3B,SAAS,SAAS,QAAQ,iBAAiB,KAAK;GAChD,SAAS,SAAS,QAAQ,KAAK;GAC/B,SAAS,SAAS,QAAQ,KAAK,QAAQ;GACvC,SAAS,SAAS,gBAAgB,KAAK,QAAQ;GAC/C,SAAS,SAAS,WAAW,mBAAmB,IAAI;GAEpD,OAAO,KAAK,QAAQ;EACtB;EAEA,WAAW,UAAoD;GAI7D,IAAI;GACJ,IAAI,iBAAiB,aACnB,SAAS,IAAI,WAAW,KAAK;QACxB,IAAI,iBAAiB,YAC1B,SAAS;QAET;GAGF,IAAI;IACF,MAAM,WAAW,OAAO,MAAM;IAE9B,IAAI,CAAC,MAAM,QAAQ,QAAQ,KAAK,SAAS,WAAW,iBAAiB,OAAO,KAAA;IAE5E,MAAM,YAAY,WAAW,SAAS,SAAS;IAC/C,MAAM,cAAc,mBAAmB,SAAS,SAAS;IACzD,IAAI,aAAa,QAAQ,eAAe,MAAM,OAAO,KAAA;IAErD,MAAM,OAAO,SAAS,SAAS;IAU/B,OAAO,iBAAiB,WAAW,aAAa,MAAM;KANpD,MAAM,SAAS,SAAS;KACxB,aAAa;KACb,SAAS,CAAC;KACV,cAAc,SAAS,SAAS;IAG0B,GAAG,SAAS,SAAS,QAAQ;GAC3F,SAAS,GAAG;IACV,QAAQ,MAAM,sDAAsD,CAAC;IACrE;GACF;EACF;CACF;AACF"}