@nice-code/action 0.10.0 → 0.12.0

package/build/index.cjs

@@ -0,0 +1,4045 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_RunningAction_types = require("./RunningAction.types-DjCX1xp5.cjs");
+let nanoid = require("nanoid");
+let _nice_code_error = require("@nice-code/error");
+let std_env = require("std-env");
+let _nice_code_common_errors = require("@nice-code/common-errors");
+let msgpackr = require("msgpackr");
+let _nice_code_util = require("@nice-code/util");
+let valibot = require("valibot");
+valibot = __toESM(valibot, 1);
+const UNSET_RUNTIME_ENV_ID = "_unset_";
+//#endregion
+//#region src/ActionRuntime/utils/runtimeCoordinateToStringIds.ts
+function runtimeCoordinateToStringIds(coordinate) {
+	return [
+		`envId[${coordinate.envId}]perId[${coordinate.perId ?? "_"}]:insId[${coordinate.insId ?? "_"}]`,
+		`envId[${coordinate.envId}]perId[${coordinate.perId ?? "_"}]:insId[_]`,
+		`envId[${coordinate.envId}]perId[_]:insId[_]`
+	];
+}
+//#endregion
+//#region src/ActionRuntime/RuntimeCoordinate.ts
+var RuntimeCoordinate = class RuntimeCoordinate {
+	envId;
+	perId;
+	insId;
+	static get unknown() {
+		return new RuntimeCoordinate({ envId: UNSET_RUNTIME_ENV_ID });
+	}
+	static env(envId) {
+		return new RuntimeCoordinate({ envId });
+	}
+	withPersistentId(perId) {
+		return this.specify({ perId });
+	}
+	constructor({ envId, perId, insId }) {
+		this.envId = envId;
+		this.perId = perId;
+		this.insId = insId;
+	}
+	specify(specifics) {
+		return new RuntimeCoordinate({
+			envId: this.envId,
+			perId: this.perId,
+			insId: this.insId,
+			...specifics
+		});
+	}
+	specifyIfUnset(specifics) {
+		return new RuntimeCoordinate({
+			envId: this.envId,
+			perId: this.perId ?? specifics.perId,
+			insId: this.insId ?? specifics.insId
+		});
+	}
+	toJsonObject() {
+		return {
+			envId: this.envId,
+			perId: this.perId,
+			insId: this.insId
+		};
+	}
+	isExactlySame(other) {
+		return this.envId === other.envId && this.perId === other.perId && this.insId === other.insId;
+	}
+	isSameFor(other) {
+		return {
+			id: this.envId === other.envId,
+			perId: this.envId === other.envId && this.perId === other.perId,
+			insId: this.envId === other.envId && this.perId === other.perId && this.insId === other.insId
+		};
+	}
+	similarityLevel(other) {
+		const sameFor = this.isSameFor(other);
+		if (sameFor.insId) return 3;
+		if (sameFor.perId) return 2;
+		if (sameFor.id) return 1;
+		return 0;
+	}
+	get stringId() {
+		return `envId[${this.envId}]perId[${this.perId ?? "_"}]:insId[${this.insId ?? "_"}]`;
+	}
+	/**
+	* 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() {
+		return runtimeCoordinateToStringIds(this);
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/ActionBase.ts
+var ActionBase = class {
+	form;
+	_domain;
+	id;
+	domain;
+	allDomains;
+	schema;
+	constructor(form, _domain, id) {
+		this.form = form;
+		this._domain = _domain;
+		this.id = id;
+		this.domain = _domain.domain;
+		this.allDomains = _domain.allDomains;
+		this.schema = _domain.actionSchema[id];
+	}
+	toJsonObject() {
+		return {
+			form: this.form,
+			domain: this.domain,
+			allDomains: this.allDomains,
+			id: this.id
+		};
+	}
+	toJsonString() {
+		return JSON.stringify(this.toJsonObject());
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/Context/ActionContext.ts
+var ActionContext = class extends ActionBase {
+	_domain;
+	form = "context";
+	_routing;
+	timeCreated;
+	cuid;
+	originClient;
+	constructor(_domain, id, hydrationData) {
+		super("context", _domain, id);
+		this._domain = _domain;
+		this.timeCreated = hydrationData.timeCreated;
+		this.cuid = hydrationData.cuid;
+		this._routing = hydrationData.routing;
+		this.originClient = hydrationData.originClient;
+	}
+	_setOriginClient(client) {
+		this.originClient = client;
+	}
+	toJsonString() {
+		return JSON.stringify(this.toJsonObject());
+	}
+	toContextDataJsonObject() {
+		return {
+			timeCreated: this.timeCreated,
+			cuid: this.cuid,
+			routing: this.routing.map((item) => ({
+				runtime: item.runtime.toJsonObject(),
+				handler: item.handler,
+				time: item.time
+			})),
+			originClient: this.originClient.toJsonObject()
+		};
+	}
+	toJsonObject() {
+		return {
+			...super.toJsonObject(),
+			...this.toContextDataJsonObject()
+		};
+	}
+	get routing() {
+		return this._routing;
+	}
+	addRouteItem(item) {
+		this._routing.push(item);
+	}
+	deserializeInput(serialized) {
+		return this.schema.deserializeInput(serialized);
+	}
+	serializeInput(raw) {
+		return this.schema.serializeInput(raw);
+	}
+	validateInput(input) {
+		return this.schema.validateInput(input, {
+			domain: this.domain,
+			actionId: this.id
+		});
+	}
+	validateOutput(output) {
+		return this.schema.validateOutput(output, {
+			domain: this.domain,
+			actionId: this.id
+		});
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/Payload/ActionPayload.ts
+var ActionPayload = class extends ActionBase {
+	form = "data";
+	type;
+	context;
+	time;
+	constructor(context, type, data) {
+		super("data", context._domain, context.id);
+		this.context = context;
+		this.type = type;
+		this.time = data.time;
+	}
+	toBaseJsonObject() {
+		return {
+			...super.toJsonObject(),
+			type: this.type,
+			context: this.context.toContextDataJsonObject(),
+			time: this.time
+		};
+	}
+};
+//#endregion
+//#region src/utils/hashPayloadData.ts
+function stableStringify(value) {
+	if (value === null || value === void 0) return String(value);
+	if (typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return "{" + Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",") + "}";
+}
+function fnv1a32(str) {
+	let hash = 2166136261;
+	for (let i = 0; i < str.length; i++) hash = (hash ^ str.charCodeAt(i)) * 16777619 >>> 0;
+	return hash.toString(16).padStart(8, "0");
+}
+/**
+* Produces a deterministic 8-char hex hash of any JSON-serializable value.
+* Useful for grouping/comparing action inputs, outputs, and progress payloads.
+*/
+function hashPayloadData(data) {
+	return fnv1a32(stableStringify(data));
+}
+//#endregion
+//#region src/ActionDefinition/Action/Payload/ActionPayload.types.ts
+let EActionPayloadType = /* @__PURE__ */ function(EActionPayloadType) {
+	EActionPayloadType["request"] = "request";
+	EActionPayloadType["progress"] = "progress";
+	EActionPayloadType["result"] = "result";
+	EActionPayloadType["stream"] = "stream";
+	EActionPayloadType["push"] = "push";
+	return EActionPayloadType;
+}({});
+/**
+*
+*  [ PROGRESS ]
+*
+*/
+let EActionProgressType = /* @__PURE__ */ function(EActionProgressType) {
+	EActionProgressType["none"] = "none";
+	EActionProgressType["percentage"] = "percentage";
+	EActionProgressType["custom"] = "custom";
+	return EActionProgressType;
+}({});
+//#endregion
+//#region src/ActionDefinition/Action/Payload/ActionPayload_Progress.ts
+var ActionPayload_Progress = class extends ActionPayload {
+	progress;
+	constructor(params, progress, data) {
+		super(params.context, "progress", data);
+		this.progress = progress;
+	}
+	toJsonObject() {
+		return {
+			...this.toBaseJsonObject(),
+			progress: this.progress
+		};
+	}
+	toJsonString() {
+		return JSON.stringify(this.toJsonObject());
+	}
+	toHttpResponse() {
+		return new Response(this.toJsonString(), {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/Payload/ActionPayload_Result.ts
+var ActionPayload_Result = class extends ActionPayload {
+	result;
+	outputHash;
+	constructor(params, result, data) {
+		super(params.context, "result", data);
+		this.result = result;
+		this.outputHash = result.ok ? hashPayloadData(this.context.schema.serializeOutput(result.output)) : hashPayloadData(result.error.message);
+	}
+	toJsonObject() {
+		const wireResult = this.result.ok ? {
+			ok: true,
+			output: this.context.schema.serializeOutput(this.result.output)
+		} : this.result;
+		return {
+			...this.toBaseJsonObject(),
+			result: wireResult,
+			outputHash: this.outputHash
+		};
+	}
+	toJsonString() {
+		return JSON.stringify(this.toJsonObject());
+	}
+	toHttpResponse({ useErrorStatus = true } = {}) {
+		return new Response(this.toJsonString(), {
+			status: this.result.ok ? 200 : useErrorStatus ? this.result.error.httpStatusCode : 500,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/Payload/ActionPayload_Request.ts
+var ActionPayload_Request = class extends ActionPayload {
+	input;
+	inputHash;
+	_callSite;
+	constructor(params, input, data) {
+		super(params.context, "request", data);
+		this.input = input;
+		this.inputHash = hashPayloadData(this.context.schema.serializeInput(input));
+	}
+	successResult(...args) {
+		const output = args[0];
+		const finalOutput = this.context.schema.validateOutput(output, {
+			domain: this.domain,
+			actionId: this.id
+		});
+		return new ActionPayload_Result(this, {
+			ok: true,
+			output: finalOutput
+		}, { time: Date.now() });
+	}
+	errorResult(err) {
+		return new ActionPayload_Result(this, {
+			ok: false,
+			error: err
+		}, { time: Date.now() });
+	}
+	progress(progress) {
+		return new ActionPayload_Progress(this, progress, { time: Date.now() });
+	}
+	toJsonObject() {
+		return {
+			...super.toBaseJsonObject(),
+			input: this.context.schema.serializeInput(this.input),
+			inputHash: this.inputHash
+		};
+	}
+	toJsonString() {
+		return JSON.stringify(this.toJsonObject());
+	}
+	async runToOutput(options) {
+		const result = await (await this.run(options)).waitForResultPayload();
+		if (result.result.ok) return result.result.output;
+		throw result.result.error;
+	}
+	async runToResultPayload(options) {
+		return (await this.run(options)).waitForResultPayload();
+	}
+	async run(options) {
+		if (this._callSite == null) this._callSite = (/* @__PURE__ */ new Error()).stack;
+		return this._domain.runAction(this, options);
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/Core/ActionCore.ts
+var ActionCore = class extends ActionBase {
+	_domain;
+	form = "core";
+	constructor(_domain, id) {
+		super("core", _domain, id);
+		this._domain = _domain;
+	}
+	is(action) {
+		return action instanceof ActionPayload && action.domain === this.domain && action.id === this.id;
+	}
+	toJsonObject() {
+		return {
+			id: this.id,
+			form: this.form,
+			domain: this.domain,
+			allDomains: this.allDomains
+		};
+	}
+	request(...args) {
+		const input = args[0];
+		const validatedInput = this.schema.validateInput(input, {
+			actionId: this.id,
+			domain: this.domain
+		});
+		return new ActionPayload_Request({ context: new ActionContext(this._domain, this.id, {
+			cuid: (0, nanoid.nanoid)(),
+			timeCreated: Date.now(),
+			routing: [],
+			originClient: RuntimeCoordinate.unknown
+		}) }, validatedInput, { time: Date.now() });
+	}
+	deserializeInput(serialized) {
+		return this.schema.deserializeInput(serialized);
+	}
+	serializeInput(raw) {
+		return this.schema.serializeInput(raw);
+	}
+	validateInput(input) {
+		return this.schema.validateInput(input, {
+			domain: this.domain,
+			actionId: this.id
+		});
+	}
+	validateOutput(output) {
+		return this.schema.validateOutput(output, {
+			domain: this.domain,
+			actionId: this.id
+		});
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Action/RunningAction.ts
+var RunningAction = class {
+	_state;
+	context;
+	cuid;
+	id;
+	_domain;
+	domain;
+	allDomains;
+	parentCuid;
+	callSite;
+	_resultPayloadPromise;
+	_resolveResult;
+	_rejectResult;
+	_isAborted = false;
+	_updates = [];
+	_updateListeners = [];
+	constructor(initialState) {
+		this.context = initialState.context;
+		this.cuid = initialState.context.cuid;
+		this.id = initialState.context.id;
+		this.domain = initialState.context.domain;
+		this.allDomains = initialState.context.allDomains;
+		this._domain = initialState.context._domain;
+		this.parentCuid = initialState.parentCuid;
+		this.callSite = initialState.callSite;
+		this._resultPayloadPromise = new Promise((resolve, reject) => {
+			this._resolveResult = resolve;
+			this._rejectResult = reject;
+		});
+		this._resultPayloadPromise.catch(() => {});
+		this._state = {
+			request: initialState.request,
+			progress: initialState.progress ?? [],
+			result: initialState.result
+		};
+		this._sendUpdate({
+			type: "started",
+			runningAction: this,
+			time: Date.now()
+		});
+	}
+	get state() {
+		return this._state;
+	}
+	abort(reason) {
+		this._abort(reason);
+	}
+	addUpdateListeners(listeners) {
+		this._updateListeners.push(...listeners);
+		for (const event of this._updates) for (const listener of listeners) listener(event);
+		return () => {
+			for (const listener of listeners) {
+				const i = this._updateListeners.indexOf(listener);
+				if (i !== -1) this._updateListeners.splice(i, 1);
+			}
+		};
+	}
+	async *iterateUpdates() {
+		const queue = [];
+		let resolveWaiter = null;
+		const unsubscribe = this.addUpdateListeners([(event) => {
+			queue.push(event);
+			if (resolveWaiter) {
+				resolveWaiter();
+				resolveWaiter = null;
+			}
+		}]);
+		try {
+			while (true) {
+				if (queue.length === 0) await new Promise((resolve) => {
+					resolveWaiter = resolve;
+				});
+				const event = queue.shift();
+				yield event;
+				if (event.type === "finished") break;
+			}
+		} finally {
+			unsubscribe();
+		}
+	}
+	_sendUpdate(update) {
+		this._updates.push(update);
+		for (const listener of this._updateListeners) listener(update);
+	}
+	_completeWithResult(result) {
+		if (this._state.result != null || this._isAborted) return false;
+		this._state = {
+			request: this._state.request,
+			progress: this._state.progress,
+			result
+		};
+		this._resolveResult(result);
+		this._sendUpdate({
+			type: "finished",
+			finishType: "success",
+			runningAction: this,
+			time: Date.now(),
+			response: result
+		});
+		return true;
+	}
+	_abort(reason) {
+		if (this._state.result != null || this._isAborted) return false;
+		this._isAborted = true;
+		this._rejectResult(reason);
+		this._sendUpdate({
+			type: "finished",
+			finishType: "aborted",
+			runningAction: this,
+			time: Date.now(),
+			reason
+		});
+		return true;
+	}
+	_failWithError(error) {
+		if (this._state.result != null || this._isAborted) return false;
+		this._isAborted = true;
+		this._rejectResult(error);
+		this._sendUpdate({
+			type: "finished",
+			finishType: "failed",
+			runningAction: this,
+			time: Date.now(),
+			error
+		});
+		return true;
+	}
+	_updateProgress(progress) {
+		if (this._state.result != null || this._isAborted) return;
+		this._state.progress.push(progress);
+		this._sendUpdate({
+			type: "progress",
+			runningAction: this,
+			time: Date.now(),
+			progress: progress.progress
+		});
+	}
+	waitForResultPayload() {
+		return this._resultPayloadPromise;
+	}
+	_resolveFromJson(resultJson) {
+		if (this._state.result != null || this._isAborted) return false;
+		const result = this._domain.hydrateResultPayload(resultJson);
+		return this._completeWithResult(result);
+	}
+};
+//#endregion
+//#region src/errors/err_nice_action.ts
+let EErrId_NiceAction = /* @__PURE__ */ function(EErrId_NiceAction) {
+	EErrId_NiceAction["not_implemented"] = "not_implemented";
+	EErrId_NiceAction["action_id_not_in_domain"] = "action_id_not_in_domain";
+	EErrId_NiceAction["domain_already_exists_in_hierarchy"] = "domain_already_exists_in_hierarchy";
+	EErrId_NiceAction["domain_no_handler"] = "domain_no_handler";
+	EErrId_NiceAction["hydration_domain_mismatch"] = "hydration_domain_mismatch";
+	EErrId_NiceAction["hydration_action_state_mismatch"] = "hydration_action_state_mismatch";
+	EErrId_NiceAction["hydration_action_id_not_found"] = "hydration_action_id_not_found";
+	EErrId_NiceAction["no_action_execution_handler"] = "no_action_execution_handler";
+	EErrId_NiceAction["wire_action_not_payload"] = "wire_action_not_payload";
+	EErrId_NiceAction["wire_not_action_data"] = "wire_not_action_data";
+	EErrId_NiceAction["client_runtime_already_registered"] = "client_runtime_already_registered";
+	EErrId_NiceAction["client_runtime_not_registered"] = "client_runtime_not_registered";
+	EErrId_NiceAction["runtime_reset"] = "runtime_reset";
+	EErrId_NiceAction["no_client_runtimes_registered"] = "no_client_runtimes_registered";
+	EErrId_NiceAction["action_input_validation_failed"] = "action_input_validation_failed";
+	EErrId_NiceAction["action_input_validation_promise"] = "action_input_validation_promise";
+	EErrId_NiceAction["action_output_validation_failed"] = "action_output_validation_failed";
+	EErrId_NiceAction["action_output_validation_promise"] = "action_output_validation_promise";
+	return EErrId_NiceAction;
+}({});
+const err_nice_action = _nice_code_error.err_nice.createChildDomain({
+	domain: "err_nice_action",
+	defaultHttpStatusCode: 500,
+	schema: {
+		["not_implemented"]: (0, _nice_code_error.err)({ message: ({ label }) => `The "${label}" functionality is not implemented yet.` }),
+		["action_id_not_in_domain"]: (0, _nice_code_error.err)({ message: ({ actionId, domain }) => `Action with id "${actionId}" does not exist in domain "${domain}".` }),
+		["domain_already_exists_in_hierarchy"]: (0, _nice_code_error.err)({ message: ({ domain, allParentDomains, parentDomain }) => `Domain "${domain}" already exists in the hierarchy under the parent "${parentDomain}". All parent domains ["${allParentDomains.join(", ")}"]` }),
+		["domain_no_handler"]: (0, _nice_code_error.err)({ message: ({ domain }) => `Domain "${domain}" has no action handler registered.` }),
+		["hydration_domain_mismatch"]: (0, _nice_code_error.err)({ message: ({ expected, received }) => `Cannot hydrate action: domain mismatch. Expected "${expected}", got "${received}".` }),
+		["hydration_action_state_mismatch"]: (0, _nice_code_error.err)({ message: ({ expected, received }) => `Cannot hydrate action: action state type mismatch. Expected "${expected}", got "${received}".` }),
+		["hydration_action_id_not_found"]: (0, _nice_code_error.err)({ message: ({ domain, actionId }) => `Cannot hydrate action: id "${actionId}" does not exist in domain "${domain}".` }),
+		["no_action_execution_handler"]: (0, _nice_code_error.err)({ message: ({ domain, actionId, specifiedClient }) => `${specifiedClient ? ` The targeted client runtime [${specifiedClient.stringId}] has no` : "No"} action handler registered for "${actionId}" in domain "${domain}".` }),
+		["wire_action_not_payload"]: (0, _nice_code_error.err)({ message: ({ domain, actionId, actionState }) => `Cannot handle wire for action "${actionId}" in domain "${domain}": expected action form of "data" and type of "request", "progress" or "result", got "${actionState}".` }),
+		["wire_not_action_data"]: (0, _nice_code_error.err)({ message: () => `Cannot handle wire for action: expected an object with a "domain" property of type string, a "form" property of "data" and a "type" property of "request", "progress" or "result".` }),
+		["runtime_reset"]: (0, _nice_code_error.err)({ message: () => `Runtime has been reset.` }),
+		["client_runtime_already_registered"]: (0, _nice_code_error.err)({ message: ({ context, client }) => `Environment is already registered${context?.domain ? ` on domain "${context.domain}"` : ""} for client [${client.stringId}]. Each client specifier (exact match on all properties) may only be registered once.` }),
+		["client_runtime_not_registered"]: (0, _nice_code_error.err)({ message: ({ context, clientStringId }) => `No runtime registered${context?.domain ? ` on domain "${context.domain}"` : ""} for client [${clientStringId}].` }),
+		["no_client_runtimes_registered"]: (0, _nice_code_error.err)({ message: ({ context }) => `No runtimes registered${context?.domain ? ` on domain "${context.domain}"` : ""}. Add handlers to a runtime via runtime.addHandlers([handler]) before executing actions.` }),
+		["action_input_validation_failed"]: (0, _nice_code_error.err)({
+			message: ({ domain, actionId, validationMessage }) => `Input validation failed for action "${actionId}" in domain "${domain}":\n${validationMessage}`,
+			httpStatusCode: 400
+		}),
+		["action_input_validation_promise"]: (0, _nice_code_error.err)({
+			message: ({ domain, actionId }) => `Input validation for action "${actionId}" in domain "${domain}" returned a promise, which is not supported.`,
+			httpStatusCode: 400
+		}),
+		["action_output_validation_failed"]: (0, _nice_code_error.err)({
+			message: ({ domain, actionId, validationMessage }) => `Output validation failed for action "${actionId}" in domain "${domain}":\n${validationMessage}`,
+			httpStatusCode: 500
+		}),
+		["action_output_validation_promise"]: (0, _nice_code_error.err)({
+			message: ({ domain, actionId }) => `Output validation for action "${actionId}" in domain "${domain}" returned a promise, which is not supported.`,
+			httpStatusCode: 500
+		})
+	}
+});
+//#endregion
+//#region src/utils/isAction_Base_JsonObject.ts
+const isAction_Base_JsonObject = (obj) => {
+	return typeof obj === "object" && obj !== null && typeof obj.domain === "string" && typeof obj.id === "string" && typeof obj.form === "string";
+};
+//#endregion
+//#region src/utils/isActionPayload_Result_JsonObject.ts
+const isActionPayload_Result_JsonObject = (obj) => {
+	return isAction_Base_JsonObject(obj) && obj.result != null && obj.form === "data" && obj.type === "result";
+};
+//#endregion
+//#region src/utils/getAssumedRuntimeEnvironment.ts
+const getAssumedRuntimeInfo = () => {
+	return {
+		assumed: true,
+		runtimeName: std_env.runtime
+	};
+};
+//#endregion
+//#region src/utils/isActionPayload_Progress_JsonObject.ts
+const isActionPayload_Progress_JsonObject = (obj) => {
+	return isAction_Base_JsonObject(obj) && "progress" in obj && obj.form === "data" && obj.type === "progress";
+};
+//#endregion
+//#region src/utils/isActionPayload_Request_JsonObject.ts
+const isActionPayload_Request_JsonObject = (obj) => {
+	return isAction_Base_JsonObject(obj) && "input" in obj && obj.form === "data" && obj.type === "request";
+};
+//#endregion
+//#region src/utils/isActionPayload_Any_JsonObject.ts
+function isActionPayload_Any_JsonObject(obj) {
+	return isActionPayload_Request_JsonObject(obj) || isActionPayload_Result_JsonObject(obj) || isActionPayload_Progress_JsonObject(obj);
+}
+//#endregion
+//#region src/ActionRuntime/HandlerCallStack.ts
+const _stack = [];
+function pushHandlerCuid(cuid) {
+	_stack.push(cuid);
+}
+function popHandlerCuid() {
+	_stack.pop();
+}
+function peekHandlerCuid() {
+	return _stack[_stack.length - 1];
+}
+//#endregion
+//#region src/ActionRuntime/ActionDomainManager.ts
+var ActionDomainManager = class {
+	_domains = /* @__PURE__ */ new Map();
+	addDomain(domain) {
+		this._domains.set(domain.domain, domain);
+	}
+	getDomains() {
+		return [...this._domains.values()];
+	}
+	verifyIsActionJson(action) {
+		if (typeof action.domain !== "string" || typeof action.id !== "string") throw err_nice_action.fromId("wire_not_action_data");
+	}
+	getActionDomain(action) {
+		this.verifyIsActionJson(action);
+		const domain = this._domains.get(action.domain);
+		if (!domain) return;
+		return domain;
+	}
+	getActionDomainOrThrow(action) {
+		this.verifyIsActionJson(action);
+		const domain = this._domains.get(action.domain);
+		if (!domain) throw err_nice_action.fromId("domain_no_handler", { domain: action.domain });
+		return domain;
+	}
+	hydrateActionPayload(actionJson) {
+		return this.getActionDomainOrThrow(actionJson).hydrateAnyAction(actionJson);
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Routing/ActionRouter.ts
+var ActionRouter = class {
+	domainManager = new ActionDomainManager();
+	actionRouteData = /* @__PURE__ */ new Map();
+	_context;
+	constructor(context) {
+		this._context = context;
+	}
+	/** Copy all routes from another router into this one, replacing any overlapping keys. */
+	mergeRouter(actionRouter) {
+		for (const domain of actionRouter.getDomains()) this.domainManager.addDomain(domain);
+		for (const [matchKey, routeDataEntries] of actionRouter.actionRouteData.entries()) this.actionRouteData.set(matchKey, [...routeDataEntries]);
+	}
+	addDomainsFromOther(actionRouter) {
+		for (const domain of actionRouter.getDomains()) this.domainManager.addDomain(domain);
+	}
+	/** All FNs registered for an action, ID-specific entries first then domain wildcard. */
+	getRouteDataEntriesForAction(action) {
+		const idKey = `dom[${action.domain}]id[${action.id}]`;
+		const domKey = `dom[${action.domain}]id[_]`;
+		return [...this.actionRouteData.get(idKey) ?? [], ...this.actionRouteData.get(domKey) ?? []];
+	}
+	/** First FN registered for an action (ID-specific beats domain wildcard). */
+	getRouteDataForAction(action) {
+		return this.getRouteDataEntriesForAction(action)[0];
+	}
+	throwNoHandlerForAction(action, context) {
+		if (this._context.contextType === "handler_route") throw err_nice_action.fromId("no_action_execution_handler", {
+			domain: action.domain,
+			actionId: action.id,
+			specifiedClient: context.targetLocalRuntime?.coordinate
+		});
+		if (this._context.contextType === "runtime_to_handler") throw err_nice_action.fromId("no_action_execution_handler", {
+			domain: action.domain,
+			actionId: action.id,
+			specifiedClient: this._context.runtime.coordinate
+		});
+		throw err_nice_action.fromId("no_action_execution_handler", {
+			domain: action.domain,
+			actionId: action.id
+		});
+	}
+	getRouteDataEntriesForActionOrThrow(action, context) {
+		const entries = this.getRouteDataEntriesForAction(action);
+		if (entries.length === 0) this.throwNoHandlerForAction(action, context);
+		return entries;
+	}
+	getRouteDataForActionOrThrow(action, context) {
+		const routeData = this.getRouteDataForAction(action);
+		if (!routeData) this.throwNoHandlerForAction(action, context);
+		return routeData;
+	}
+	/** All FNs stored under an exact match key. */
+	getForKey(key) {
+		return this.actionRouteData.get(key) ?? [];
+	}
+	/** Every match key that has at least one registered FN. */
+	getRegisteredKeys() {
+		return [...this.actionRouteData.keys()];
+	}
+	getDomains() {
+		return this.domainManager.getDomains();
+	}
+	/** Register a handler for all actions in a domain, replacing any existing one. */
+	forDomain(domain, routeData) {
+		this.domainManager.addDomain(domain);
+		this.actionRouteData.set(`dom[${domain.domain}]id[_]`, [routeData]);
+		return this;
+	}
+	forAction(action, routeData) {
+		return this.forActionId(action._domain, action.id, routeData);
+	}
+	/** Register a handler for a specific action, replacing any existing one. */
+	forActionId(domain, id, routeData) {
+		this.domainManager.addDomain(domain);
+		this.actionRouteData.set(`dom[${domain.domain}]id[${id}]`, [routeData]);
+		return this;
+	}
+	/** Register one handler for several action IDs, replacing any existing ones. */
+	forActionIds(domain, ids, routeData) {
+		this.domainManager.addDomain(domain);
+		for (const id of ids) this.forActionId(domain, id, routeData);
+		return this;
+	}
+	/** Register per-action handlers from a cases map, replacing any existing ones. */
+	forDomainActionCases(domain, cases) {
+		this.domainManager.addDomain(domain);
+		for (const id of Object.keys(cases)) {
+			const routeData = cases[id];
+			if (routeData != null) this.actionRouteData.set(`dom[${domain.domain}]id[${id}]`, [routeData]);
+		}
+		return this;
+	}
+	/** Append a handler for all actions in a domain (accumulates alongside existing). */
+	addForDomain(domain, routeData) {
+		this.domainManager.addDomain(domain);
+		this._push(`dom[${domain.domain}]id[_]`, routeData);
+		return this;
+	}
+	/** Append a handler for a specific action (accumulates alongside existing). */
+	addForAction(domain, id, routeData) {
+		this.domainManager.addDomain(domain);
+		this._push(`dom[${domain.domain}]id[${id}]`, routeData);
+		return this;
+	}
+	/** Append one handler for several action IDs (accumulates alongside existing). */
+	addForActionIds(domain, ids, routeData) {
+		this.domainManager.addDomain(domain);
+		for (const id of ids) this.addForAction(domain, id, routeData);
+		return this;
+	}
+	/** Append per-action handlers from a cases map (accumulates alongside existing). */
+	addForDomainActionCases(domain, cases) {
+		this.domainManager.addDomain(domain);
+		for (const id of Object.keys(cases)) {
+			const routeData = cases[id];
+			if (routeData != null) this._push(`dom[${domain.domain}]id[${id}]`, routeData);
+		}
+		return this;
+	}
+	/** Append a handler directly by its raw match key (used when the key is known ahead of time). */
+	addForKey(key, routeData) {
+		this._push(key, routeData);
+		return this;
+	}
+	_push(key, routeData) {
+		const existing = this.actionRouteData.get(key);
+		if (existing != null) existing.push(routeData);
+		else this.actionRouteData.set(key, [routeData]);
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ActionHandler.ts
+var ActionHandler = class {
+	cuid;
+	constructor() {
+		this.cuid = (0, nanoid.nanoid)();
+	}
+	getActionRouter() {
+		return this.actionRouter;
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/err_nice_external_client.ts
+const err_nice_external_client = err_nice_action.createChildDomain({
+	domain: "err_nice_external_client",
+	schema: {}
+});
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/err_nice_transport.ts
+let EErrId_NiceTransport = /* @__PURE__ */ function(EErrId_NiceTransport) {
+	EErrId_NiceTransport["timeout"] = "timeout";
+	EErrId_NiceTransport["not_found"] = "not_found";
+	EErrId_NiceTransport["unsupported"] = "unsupported";
+	EErrId_NiceTransport["initialization_failed"] = "initialization_failed";
+	EErrId_NiceTransport["send_failed"] = "send_failed";
+	EErrId_NiceTransport["invalid_action_response"] = "invalid_action_response";
+	return EErrId_NiceTransport;
+}({});
+const err_nice_transport = err_nice_external_client.createChildDomain({
+	domain: "err_nice_transport",
+	schema: {
+		["timeout"]: (0, _nice_code_error.err)({ message: ({ timeout }) => `ActionConnect transport timed out after ${timeout}ms.` }),
+		["not_found"]: (0, _nice_code_error.err)({ message: ({ actionId }) => `No connected transport found for action "${actionId}".` }),
+		["unsupported"]: (0, _nice_code_error.err)({ message: ({ transportTypes }) => `${transportTypes.length} Transport(s) [${transportTypes.join(", ")}] found but returned "unsupported" status.` }),
+		["initialization_failed"]: (0, _nice_code_error.err)({ message: ({ actionId }) => `Transports found for action "${actionId}", but none are ready.` }),
+		["send_failed"]: (0, _nice_code_error.err)({
+			message: ({ actionId, httpStatusCode, message }) => `Failed to send action "${actionId}" [${httpStatusCode ?? "Unknown status"}]: ${message ?? "Unknown error"}.`,
+			httpStatusCode: ({ httpStatusCode }) => httpStatusCode ?? 500
+		}),
+		["invalid_action_response"]: (0, _nice_code_error.err)({ message: ({ actionId }) => `Invalid action response JSON structure for action "${actionId}"` })
+	}
+});
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/Transport.types.ts
+let ETransportType = /* @__PURE__ */ function(ETransportType) {
+	ETransportType["ws"] = "ws";
+	ETransportType["http"] = "http";
+	ETransportType["custom"] = "custom";
+	return ETransportType;
+}({});
+/**
+*
+*  TRANSPORT READINESS RESPONSE
+*
+*/
+let ETransportStatus = /* @__PURE__ */ function(ETransportStatus) {
+	ETransportStatus["uninitialized"] = "uninitialized";
+	ETransportStatus["unsupported"] = "unsupported";
+	ETransportStatus["initializing"] = "initializing";
+	ETransportStatus["ready"] = "ready";
+	ETransportStatus["failed"] = "failed";
+	return ETransportStatus;
+}({});
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/ConnectionTransportManager.ts
+var ConnectionTransportManager = class {
+	_cache;
+	_transports = [];
+	constructor(_cache) {
+		this._cache = _cache;
+	}
+	addTransport(transport) {
+		this._transports.push(transport);
+	}
+	/**
+	* The highest-priority transport (first declared). Used to label an action's route *before* the
+	* transport has finished connecting — so a still-connecting action shows its (expected) destination
+	* instead of an "unknown" hop. {@link getReadyTransport} still decides the real winner, and the
+	* caller corrects the hop if a lower-priority transport ends up serving the action.
+	*/
+	getPreferredTransport() {
+		return this._transports[0];
+	}
+	async getReadyTransport(routeActionParams) {
+		const action = routeActionParams.action;
+		const candidates = [];
+		const unavailableTransports = [];
+		for (const transport of this._transports) {
+			const cacheKey = transport.getCacheKey(routeActionParams);
+			if (cacheKey != null) {
+				const cached = this._cache.get(cacheKey);
+				if (cached != null) {
+					if (cached instanceof Promise) {
+						candidates.push(cached);
+						continue;
+					}
+					candidates.push(Promise.resolve({
+						...cached,
+						transport
+					}));
+					break;
+				}
+			}
+			const statusInfo = transport.getTransport(routeActionParams);
+			if (statusInfo.status === "ready") {
+				const readyData = statusInfo.readyData;
+				if (cacheKey != null) {
+					const entry = {
+						methods: readyData,
+						transport
+					};
+					this._cache.set(cacheKey, entry);
+					readyData.addOnDisconnectListener?.(() => {
+						if (this._cache.get(cacheKey) === entry) this._cache.delete(cacheKey);
+					});
+				}
+				candidates.push(Promise.resolve({
+					methods: readyData,
+					transport
+				}));
+				break;
+			}
+			if (statusInfo.status === "unsupported") {
+				unavailableTransports.push(transport);
+				continue;
+			}
+			if (statusInfo.status === "initializing") {
+				const promise = statusInfo.initializationPromise.then((info) => {
+					if (info.status === "failed") throw info.error;
+					if (info.status === "unsupported") throw err_nice_transport.fromId("unsupported", { transportTypes: [transport.type] });
+					const readyData = info.readyData;
+					const entry = {
+						methods: readyData,
+						transport
+					};
+					if (cacheKey != null) if (this._cache.get(cacheKey) === promise) {
+						this._cache.set(cacheKey, entry);
+						readyData.addOnDisconnectListener?.(() => {
+							if (this._cache.get(cacheKey) === entry) this._cache.delete(cacheKey);
+						});
+					} else readyData.disconnect?.();
+					return entry;
+				}).catch((e) => {
+					if (cacheKey != null && this._cache.get(cacheKey) === promise) this._cache.delete(cacheKey);
+					throw e;
+				});
+				if (cacheKey != null) this._cache.set(cacheKey, promise);
+				candidates.push(promise);
+			}
+		}
+		if (candidates.length === 0) {
+			if (unavailableTransports.length > 0) throw err_nice_transport.fromId("unsupported", { transportTypes: unavailableTransports.map((t) => t.type) });
+			throw err_nice_transport.fromId("not_found", { actionId: action.id });
+		}
+		let lastError;
+		for (const candidate of candidates) try {
+			return await candidate;
+		} catch (e) {
+			lastError = e;
+		}
+		throw err_nice_transport.fromId("initialization_failed", { actionId: action.id }).withOriginError(lastError);
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/ActionExternalClientHandler.ts
+var ActionExternalClientHandler = class extends ActionHandler {
+	externalClient;
+	handlerType = "external";
+	cuid;
+	_defaultTimeout;
+	_transportCache = /* @__PURE__ */ new Map();
+	transportManager = new ConnectionTransportManager(this._transportCache);
+	_incomingActionDataListeners = [];
+	actionRouter = new ActionRouter({
+		contextType: "handler_route",
+		handler: this
+	});
+	constructor({ runtimeCoordinate: externalClientSpecifier, transports, defaultTimeout }) {
+		super();
+		this.externalClient = externalClientSpecifier;
+		this.cuid = (0, nanoid.nanoid)();
+		this._defaultTimeout = defaultTimeout ?? 1e4;
+		for (const transport of transports) {
+			const connection = transport._createConnection({ resolvers: { onIncomingActionDataJson: (json) => {
+				for (const l of this._incomingActionDataListeners) l(json);
+			} } });
+			connection.definition = transport;
+			this.transportManager.addTransport(connection);
+		}
+	}
+	forDomain(domain) {
+		this.actionRouter.forDomain(domain, true);
+		return this;
+	}
+	forAction(action) {
+		this.actionRouter.forAction(action, true);
+		return this;
+	}
+	forActionIds(domain, ids) {
+		this.actionRouter.forActionIds(domain, ids, true);
+		return this;
+	}
+	_setIncomingActionDataListener(listener) {
+		this._incomingActionDataListeners.push(listener);
+	}
+	async handleActionRequest(action, config) {
+		const localRuntime = config?.targetLocalRuntime ?? ActionRuntime.getDefault();
+		const localClient = localRuntime.coordinate;
+		const incomingTimeout = config?.timeout ?? this._defaultTimeout;
+		const parentCuid = peekHandlerCuid();
+		const callSite = action._callSite ?? (/* @__PURE__ */ new Error()).stack;
+		const routeParams = {
+			action,
+			localClient,
+			externalClient: this.externalClient
+		};
+		const preferredTransport = this.transportManager.getPreferredTransport();
+		const routeItem = preferredTransport != null ? {
+			runtime: localClient,
+			handler: this.toHandlerRouteItem(preferredTransport, routeParams),
+			time: Date.now()
+		} : void 0;
+		if (routeItem != null) action.context.addRouteItem(routeItem);
+		const runningAction = new RunningAction({
+			context: action.context,
+			request: action,
+			parentCuid,
+			callSite
+		});
+		localRuntime.registerRunningAction(runningAction);
+		this._dispatchWhenTransportReady(runningAction, routeParams, routeItem, incomingTimeout);
+		return runningAction;
+	}
+	async _dispatchWhenTransportReady(runningAction, routeParams, routeItem, incomingTimeout) {
+		const action = routeParams.action;
+		try {
+			const { methods, transport } = await this.transportManager.getReadyTransport(routeParams);
+			const handlerRouteItem = this.toHandlerRouteItem(transport, routeParams);
+			if (routeItem != null) {
+				routeItem.handler = handlerRouteItem;
+				routeItem.time = Date.now();
+			} else action.context.addRouteItem({
+				runtime: routeParams.localClient,
+				handler: handlerRouteItem,
+				time: Date.now()
+			});
+			const sendInput = {
+				...routeParams,
+				runningAction,
+				timeout: incomingTimeout
+			};
+			if (action.type === "request" && methods.updateRunConfig != null) sendInput.timeout = methods.updateRunConfig(sendInput)?.timeout ?? incomingTimeout;
+			methods.sendActionData(sendInput);
+		} catch (err) {
+			runningAction._abort(err);
+		}
+	}
+	/**
+	* Dispatch a result or progress payload directly back to the external client via the best
+	* available bidirectional transport (WebSocket / Custom). Used for return-path routing when the
+	* local runtime recognises that it has a direct channel to the action's originClient.
+	*
+	* Returns `true` if the payload was sent, `false` if no suitable transport was available.
+	*/
+	async sendReturnPayload(payload, config) {
+		const localClient = config.targetLocalRuntime.coordinate;
+		try {
+			const { methods } = await this.transportManager.getReadyTransport({
+				action: payload,
+				localClient,
+				externalClient: this.externalClient
+			});
+			if (methods.sendReturnData == null) return false;
+			methods.sendReturnData(payload, {
+				localClient,
+				externalClient: this.externalClient
+			});
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	toJsonObject() {
+		return {
+			type: this.handlerType,
+			client: this.externalClient
+		};
+	}
+	toHandlerRouteItem(transport, input) {
+		return {
+			type: this.handlerType,
+			client: this.externalClient,
+			transOrd: transport.transOrd,
+			transType: transport.type,
+			transInfo: transport.getRouteInfo(input)
+		};
+	}
+	clearTransportCache() {
+		for (const entry of this._transportCache.values()) if (entry instanceof Promise) entry.then((ready) => ready.methods.disconnect?.()).catch(() => {});
+		else entry.methods.disconnect?.();
+		this._transportCache.clear();
+	}
+};
+const createExternalClientHandler = (config) => {
+	return new ActionExternalClientHandler(config);
+};
+//#endregion
+//#region src/ActionRuntime/ActionRuntime.ts
+var ActionRuntime = class {
+	_coordinate;
+	timeCreated;
+	runtimeInfo = getAssumedRuntimeInfo();
+	actionRouter;
+	_pendingRunningActions = /* @__PURE__ */ new Map();
+	_registeredExternalHandlers = [];
+	_applied = false;
+	static getDefault() {
+		return getDefaultActionRuntime();
+	}
+	constructor(coordinate) {
+		this._coordinate = coordinate.specifyIfUnset({ insId: (0, nanoid.nanoid)(14) });
+		this.timeCreated = Date.now();
+		this.actionRouter = new ActionRouter({
+			contextType: "runtime_to_handler",
+			runtime: this
+		});
+	}
+	get coordinate() {
+		return this._coordinate;
+	}
+	specifyRuntimeCoordinate(specifics) {
+		if (specifics.envId != null && this._coordinate.envId !== specifics.envId) throw err_nice_action.fromId("not_implemented", { label: `updating RuntimeCoordinate with a different "envId" ("${this._coordinate.envId}" → "${specifics.envId}")` });
+		this._coordinate = this._coordinate.specify(specifics);
+		this.apply();
+	}
+	registerRunningAction(ra) {
+		this._pendingRunningActions.set(ra.cuid, ra);
+		ra.addUpdateListeners([(update) => {
+			if (update.type === "finished") this._pendingRunningActions.delete(ra.cuid);
+		}]);
+	}
+	resolveIncomingActionPayload(json) {
+		if (json.type === "request") {
+			this.handleActionPayloadWire(json).catch((err) => {
+				console.error(`[ActionRuntime] Incoming action [${json.domain}:${json.id}:${json.form}:${json.type}] unhandled:`, err);
+			});
+			return;
+		}
+		this._pendingRunningActions.get(json.context.cuid)?._resolveFromJson(json);
+	}
+	async handleActionPayloadWire(wire) {
+		let action;
+		if (isActionPayload_Any_JsonObject(wire)) action = this.actionRouter.domainManager.getActionDomainOrThrow(wire).hydrateAnyAction(wire);
+		if (action == null) throw err_nice_action.fromId("wire_not_action_data");
+		return this.handleActionPayload(action);
+	}
+	async handleActionPayload(action, options) {
+		if (action.type === "request") {
+			const observers = action.context._domain._collectActionObservers();
+			let handlerForAction;
+			try {
+				handlerForAction = this.getHandlerForActionOrThrow(action, options);
+			} catch (err) {
+				const runningAction = new RunningAction({
+					context: action.context,
+					request: action
+				});
+				runningAction.addUpdateListeners(observers);
+				runningAction._completeWithResult(action.errorResult((0, _nice_code_error.castNiceError)(err)));
+				return runningAction;
+			}
+			const runningAction = await handlerForAction.handleActionRequest(action, {
+				...options,
+				targetLocalRuntime: this
+			});
+			runningAction.addUpdateListeners(observers);
+			this._trySetupReturnDispatch(runningAction);
+			return runningAction;
+		}
+		throw err_nice_action.fromId("not_implemented", { label: `Handling incoming action payloads of type "${action.type}"` });
+	}
+	/**
+	* @internal
+	*
+	* Return the first handler registered for the given action, or `undefined`
+	* if none has been registered (action-ID-specific beats domain-wildcard).
+	*/
+	_getHandlerForAction(action, options) {
+		const handlers = this.actionRouter.getRouteDataEntriesForAction(action);
+		const targetExternalClient = options?.targetExternalClient;
+		const possibleHandlers = handlers.filter((handler) => {
+			if (handler.handlerType === "external") {
+				if (targetExternalClient && !targetExternalClient.isSameFor(handler.externalClient).id) return false;
+				return true;
+			}
+			if (targetExternalClient != null) return false;
+			if (action.type === "request") return true;
+			return false;
+		});
+		if (possibleHandlers.length === 0) return;
+		const scoringExternalClient = targetExternalClient ?? RuntimeCoordinate.unknown;
+		let handlerScore = -1;
+		let handler;
+		for (const possibleHandler of possibleHandlers) {
+			if (possibleHandler.handlerType === "local" && handler == null) return possibleHandler;
+			if (possibleHandler.handlerType === "external") {
+				const score = scoringExternalClient.similarityLevel(possibleHandler.externalClient);
+				if (score > handlerScore) {
+					handlerScore = score;
+					handler = possibleHandler;
+				}
+			}
+		}
+		return handler;
+	}
+	getHandlerForActionOrThrow(action, options) {
+		const handler = this._getHandlerForAction(action, options);
+		if (handler == null) throw err_nice_action.fromId("no_action_execution_handler", {
+			actionId: action.id,
+			domain: action.domain,
+			specifiedClient: options?.targetExternalClient
+		});
+		return handler;
+	}
+	/**
+	* Register one or more handlers. Each handler's own `actionRouter` defines
+	* which domains/actions it handles — those routing keys are mirrored into
+	* this runtime's router so the same action can be served by multiple handlers.
+	* Duplicate registrations (same handler cuid for the same key) are skipped.
+	*/
+	addHandlers(handlers) {
+		for (const handler of handlers) {
+			if (handler.handlerType === "external") {
+				handler._setIncomingActionDataListener((json) => this.resolveIncomingActionPayload(json));
+				this._registeredExternalHandlers.push(handler);
+			}
+			const handlerRouter = handler.getActionRouter();
+			this.actionRouter.addDomainsFromOther(handlerRouter);
+			if (this._applied) this.apply();
+			for (const key of handlerRouter.getRegisteredKeys()) if (!this.actionRouter.getForKey(key).some((h) => h.cuid === handler.cuid)) this.actionRouter.addForKey(key, handler);
+		}
+		return this;
+	}
+	/**
+	* Declare an external "backend client" in one call: build an
+	* {@link ActionExternalClientHandler} for `externalCoordinate` carrying the given
+	* `transports`, route the listed `domains`/`actions` to it, register it (plus any
+	* `localHandlers` — e.g. server→client push handlers that share the same channel)
+	* on this runtime, and `apply()`. Returns the external handler so the caller can
+	* later `clearTransportCache()` it.
+	*
+	* Sugar over `new ActionExternalClientHandler(...).forDomain(...)` + `addHandlers([...])`,
+	* so a single runtime can host one handler per backend target with its transports
+	* declared once and reused across every action routed to that backend.
+	*/
+	connectTo(externalCoordinate, options) {
+		const handler = new ActionExternalClientHandler({
+			runtimeCoordinate: externalCoordinate,
+			transports: options.transports,
+			defaultTimeout: options.defaultTimeout
+		});
+		for (const domain of options.domains ?? []) handler.forDomain(domain);
+		for (const action of options.actions ?? []) handler.forAction(action);
+		this.addHandlers([handler, ...options.localHandlers ?? []]);
+		this.apply();
+		return handler;
+	}
+	applyRuntimeForDomain(domain) {
+		const rootDomain = domain.rootDomain;
+		if (!rootDomain._hasRuntime(this)) rootDomain._registerRuntime(this);
+	}
+	/**
+	* Register this runtime with all root domains covered by its currently-added handlers,
+	* making it eligible to execute actions dispatched from those domains.
+	* After apply() is called, any subsequent addHandlers() calls also auto-register.
+	*/
+	apply() {
+		this._applied = true;
+		for (const domain of this.actionRouter.getDomains()) this.applyRuntimeForDomain(domain);
+		return this;
+	}
+	/**
+	* Find the best registered external handler that can reach `originClient` directly.
+	* Used to locate the return-path channel for dispatching results back to the action origin.
+	* Returns `undefined` if no handler matches (score > 0 required, i.e. at least id must match).
+	*/
+	getReturnHandlerForOrigin(originClient) {
+		if (originClient.envId === "_unset_") return void 0;
+		let bestScore = -1;
+		let bestHandler;
+		for (const handler of this._registeredExternalHandlers) {
+			const score = originClient.similarityLevel(handler.externalClient);
+			if (score > bestScore) {
+				bestScore = score;
+				bestHandler = handler;
+			}
+		}
+		return bestScore > 0 ? bestHandler : void 0;
+	}
+	resetRuntime() {
+		for (const ra of this._pendingRunningActions.values()) ra._abort(err_nice_action.fromId("runtime_reset"));
+		for (const handler of this._registeredExternalHandlers) handler.clearTransportCache();
+	}
+	_trySetupReturnDispatch(runningAction) {
+		const originClient = runningAction.context.originClient;
+		if (originClient.envId === "_unset_" || originClient.isSameFor(this._coordinate).id) return;
+		runningAction.addUpdateListeners([(update) => {
+			if (update.type === "finished" && update.finishType === "success") this.getReturnHandlerForOrigin(originClient)?.sendReturnPayload(update.response, { targetLocalRuntime: this }).catch(() => {});
+		}]);
+	}
+};
+const runtimeState = {
+	defaultLocalRuntime: void 0,
+	assumedRuntimeInfo: void 0
+};
+function getDefaultActionRuntime() {
+	if (runtimeState.assumedRuntimeInfo == null) runtimeState.assumedRuntimeInfo = getAssumedRuntimeInfo();
+	if (runtimeState.defaultLocalRuntime == null) runtimeState.defaultLocalRuntime = new ActionRuntime(RuntimeCoordinate.unknown.specify({ perId: `${runtimeState.assumedRuntimeInfo?.runtimeName ?? "unknown"}-runtime` }));
+	return runtimeState.defaultLocalRuntime;
+}
+//#endregion
+//#region src/ActionRuntime/Handler/Local/ActionLocalHandler.ts
+var ActionLocalHandler = class extends ActionHandler {
+	handlerType = "local";
+	actionRouter = new ActionRouter({
+		contextType: "handler_route",
+		handler: this
+	});
+	constructor() {
+		super();
+	}
+	/**
+	* Register a handler for all actions in a domain.
+	* Receives the full primed action — use `matchAction()` to narrow to a specific action id.
+	* Useful for forwarding all domain actions to a remote endpoint.
+	* Lower priority than `forAction`.
+	*/
+	forDomain(domain, handler) {
+		this.actionRouter.forDomain(domain, handler);
+		return this;
+	}
+	/**
+	* Register a handler for a base action instance. Takes priority over domain-wide handlers.
+	* Receives the full primed action with narrowed input type.
+	* Useful for handling specific actions locally while forwarding the rest of the domain. For example, a local "ping" action that checks connectivity without needing a round trip.
+	*/
+	forAction(action, handler) {
+		this.actionRouter.forAction(action, handler);
+		return this;
+	}
+	/**
+	* Register a handler for multiple action IDs (first-match-wins among cases).
+	* Receives the full primed action narrowed to the union of those IDs.
+	* Use `act.coreAction.id` to branch on which action was dispatched.
+	*/
+	forActionIds(domain, ids, handler) {
+		this.actionRouter.forActionIds(domain, ids, handler);
+		return this;
+	}
+	/**
+	* Register per-action handlers for a domain using a single map, without needing
+	* separate `forAction` calls. Unregistered action IDs are unaffected.
+	*
+	* @example
+	* ```ts
+	* handler.forDomainActionCases(userDomain, {
+	*   getUser:    (primed) => db.getUser(primed.input.userId),
+	*   deleteUser: (primed) => db.deleteUser(primed.input.userId),
+	* });
+	* ```
+	*/
+	forDomainActionCases(domain, cases) {
+		this.actionRouter.forDomainActionCases(domain, cases);
+		return this;
+	}
+	async handleActionRequest(action, config) {
+		const targetLocalRuntime = config?.targetLocalRuntime ?? ActionRuntime.getDefault();
+		const handler = this.actionRouter.getRouteDataForActionOrThrow(action, { targetLocalRuntime });
+		action.context.addRouteItem({
+			runtime: targetLocalRuntime.coordinate,
+			handler: this.toHandlerRouteItem(),
+			time: Date.now()
+		});
+		const runningAction = new RunningAction({
+			context: action.context,
+			request: action,
+			parentCuid: peekHandlerCuid(),
+			callSite: action._callSite ?? (/* @__PURE__ */ new Error()).stack
+		});
+		this._handleRunningAction(handler, runningAction).catch((err) => {
+			if (err instanceof _nice_code_error.NiceError) runningAction._completeWithResult(action.errorResult(err));
+			else if ((0, _nice_code_error.isNiceErrorObject)(err)) runningAction._completeWithResult(action.errorResult((0, _nice_code_error.castNiceError)(err)));
+			else runningAction._abort(err);
+		});
+		return runningAction;
+	}
+	async _handleRunningAction(handler, runningAction) {
+		const state = runningAction.state;
+		if (state.result != null) return;
+		await Promise.resolve();
+		pushHandlerCuid(runningAction.cuid);
+		try {
+			const rawResult = await handler(state.request);
+			let result;
+			if (rawResult instanceof ActionPayload_Result) result = rawResult;
+			else if (rawResult != null && isActionPayload_Result_JsonObject(rawResult)) result = this.actionRouter.domainManager.getActionDomainOrThrow(state.request).hydrateResultPayload(rawResult);
+			else result = state.request.successResult(rawResult);
+			runningAction._completeWithResult(result);
+		} finally {
+			popHandlerCuid();
+		}
+	}
+	async handlePayloadWireOrThrow(wire, config) {
+		const hydratedAction = this.actionRouter.domainManager.hydrateActionPayload(wire);
+		if (!(hydratedAction instanceof ActionPayload_Request)) throw err_nice_action.fromId("wire_action_not_payload", {
+			domain: hydratedAction.domain,
+			actionId: hydratedAction.id,
+			actionState: hydratedAction.type ?? hydratedAction.form
+		});
+		return await this.handleActionRequest(hydratedAction, config);
+	}
+	toJsonObject() {
+		return { type: this.handlerType };
+	}
+	toHandlerRouteItem() {
+		return { type: this.handlerType };
+	}
+};
+const createLocalHandler = () => {
+	return new ActionLocalHandler();
+};
+//#endregion
+//#region src/utils/isAction_Context_JsonObject.ts
+const isAction_Context_JsonObject = (obj) => {
+	return isAction_Base_JsonObject(obj) && obj.form === "context";
+};
+//#endregion
+//#region src/utils/isAction_Core_JsonObject.ts
+const isAction_Core_JsonObject = (obj) => {
+	return isAction_Base_JsonObject(obj) && obj.form === "core";
+};
+//#endregion
+//#region src/utils/isAction_Any_JsonObject.ts
+function isAction_Any_JsonObject(obj) {
+	return isActionPayload_Any_JsonObject(obj) || isAction_Context_JsonObject(obj) || isAction_Core_JsonObject(obj);
+}
+//#endregion
+//#region src/utils/assertIsActionJson.ts
+function assertIsActionJson(obj) {
+	if (!isAction_Any_JsonObject(obj)) throw err_nice_action.fromId("wire_not_action_data");
+}
+//#endregion
+//#region src/utils/isAction_Any_Instance.ts
+function isAction_Any_Instance(value) {
+	return value instanceof ActionCore || value instanceof ActionPayload || value instanceof ActionContext;
+}
+//#endregion
+//#region src/ActionDefinition/Domain/ActionDomainBase.ts
+var ActionDomainBase = class {
+	domain;
+	allDomains;
+	actionSchema;
+	_listeners = [];
+	constructor(definition) {
+		this.domain = definition.domain;
+		this.allDomains = definition.allDomains;
+		this.actionSchema = definition.actionSchema;
+	}
+	/**
+	* Add an observer that is called after every action dispatched through this domain.
+	* Returns an unsubscribe function — call it to remove the listener.
+	*/
+	addActionListener(listener) {
+		this._listeners.push(listener);
+		return () => {
+			this._listeners = this._listeners.filter((l) => l !== listener);
+		};
+	}
+	/**
+	* @internal
+	* Observers registered directly on this domain via {@link addActionListener}.
+	* Used to wire observers (e.g. devtools) onto RunningActions that aren't created
+	* through the local-dispatch path — notably inbound actions pushed from a backend
+	* or another client over a bidirectional transport.
+	*/
+	_getActionObservers() {
+		return this._listeners;
+	}
+};
+//#endregion
+//#region src/ActionRuntime/ActionRuntimeManager.ts
+var ActionRuntimeManager = class {
+	_runtimes = /* @__PURE__ */ new Map();
+	_preferredRuntimeClientId = null;
+	_context;
+	constructor(context) {
+		this._context = context ?? {};
+	}
+	registerRuntime(runtime) {
+		const runtimeId = runtime.coordinate.stringId;
+		if (this._runtimes.has(runtimeId)) throw err_nice_action.fromId("client_runtime_already_registered", {
+			context: this._context,
+			client: runtime.coordinate
+		});
+		for (const id of runtime.coordinate.toStringIds()) {
+			if (this._runtimes.has(id)) continue;
+			this._runtimes.set(id, runtime);
+		}
+	}
+	getRuntimeAndHandlerForAction(action, options, throwOnIssue) {
+		const localRuntime = options?.targetLocalRuntime;
+		if (localRuntime != null) {
+			const runtime = throwOnIssue ? this.getBestRuntimeOrThrow(options?.targetLocalRuntime?.coordinate) : this.getBestRuntime(options?.targetLocalRuntime?.coordinate);
+			if (runtime == null) return;
+			const handler = runtime._getHandlerForAction(action, options);
+			if (handler != null) return {
+				handler,
+				runtime
+			};
+			if (throwOnIssue) throw err_nice_action.fromId("no_action_execution_handler", {
+				domain: action.domain,
+				actionId: action.id,
+				specifiedClient: localRuntime.coordinate
+			});
+		}
+		for (const runtime of this._runtimes.values()) {
+			const handler = runtime._getHandlerForAction(action);
+			if (handler) return {
+				handler,
+				runtime
+			};
+		}
+		if (throwOnIssue) throw err_nice_action.fromId("no_action_execution_handler", {
+			domain: action.domain,
+			actionId: action.id,
+			specifiedClient: options?.targetLocalRuntime?.coordinate
+		});
+	}
+	getRuntimeAndHandlerForActionOrThrow(action, options) {
+		return this.getRuntimeAndHandlerForAction(action, options, true);
+	}
+	setPreferredRuntime(runtime) {
+		const runtimeId = runtime.coordinate.stringId;
+		this._preferredRuntimeClientId = runtimeId;
+	}
+	getPreferredRuntime() {
+		if (this._preferredRuntimeClientId) {
+			const runtime = this._runtimes.get(this._preferredRuntimeClientId);
+			if (runtime) return runtime;
+		}
+		return this._runtimes.values().next().value;
+	}
+	getBestRuntimeForSpecifier(clientSpecifier) {
+		const ids = new RuntimeCoordinate(clientSpecifier).toStringIds();
+		for (const id of ids) {
+			const runtime = this._runtimes.get(id);
+			if (runtime) return runtime;
+		}
+	}
+	getBestRuntime(clientSpecifier) {
+		return clientSpecifier != null ? this.getBestRuntimeForSpecifier(clientSpecifier) : this.getPreferredRuntime();
+	}
+	hasRuntime(runtime) {
+		return this._runtimes.has(runtime.coordinate.stringId);
+	}
+	getBestRuntimeOrThrow(specifier) {
+		const runtime = this.getBestRuntime(specifier);
+		if (!runtime) {
+			if (specifier == null) throw err_nice_action.fromId("no_client_runtimes_registered", { context: this._context });
+			throw err_nice_action.fromId("client_runtime_not_registered", {
+				context: this._context,
+				clientStringId: runtimeCoordinateToStringIds(specifier)[0]
+			});
+		}
+		return runtime;
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Domain/ActionRootDomain.ts
+var ActionRootDomain = class extends ActionDomainBase {
+	domainDefinition;
+	_actionRuntimeManager;
+	constructor(domainDefinition) {
+		const domainId = domainDefinition.domain;
+		super({
+			domain: domainId,
+			allDomains: [domainId],
+			actionSchema: {}
+		});
+		this.domainDefinition = domainDefinition;
+		this._actionRuntimeManager = new ActionRuntimeManager({ domain: domainId });
+	}
+	createChildDomain(subDomainDef) {
+		if (this.allDomains.includes(subDomainDef.domain)) throw err_nice_action.fromId("domain_already_exists_in_hierarchy", {
+			domain: subDomainDef.domain,
+			allParentDomains: this.allDomains,
+			parentDomain: this.domain
+		});
+		return new ActionDomain({
+			allDomains: [...this.allDomains, subDomainDef.domain],
+			domain: subDomainDef.domain,
+			actionSchema: subDomainDef.actions
+		}, { rootDomain: this });
+	}
+	_registerRuntime(runtime) {
+		this._actionRuntimeManager.registerRuntime(runtime);
+	}
+	_hasRuntime(runtime) {
+		return this._actionRuntimeManager.hasRuntime(runtime);
+	}
+	getRuntime(clientSpecifier) {
+		return this._actionRuntimeManager.getBestRuntimeForSpecifier(clientSpecifier);
+	}
+	async _runAction(actionPayload, options) {
+		const allListeners = [...this._listeners, ...options?.listeners ?? []];
+		let handlerAndRuntime;
+		try {
+			handlerAndRuntime = this._actionRuntimeManager.getRuntimeAndHandlerForActionOrThrow(actionPayload, options);
+		} catch (err) {
+			const runningAction = new RunningAction({
+				context: actionPayload.context,
+				request: actionPayload,
+				callSite: actionPayload._callSite
+			});
+			runningAction.addUpdateListeners(allListeners);
+			runningAction._failWithError(err);
+			throw err;
+		}
+		const { handler, runtime } = handlerAndRuntime;
+		actionPayload.context._setOriginClient(runtime.coordinate);
+		const runningAction = await handler.handleActionRequest(actionPayload, { targetLocalRuntime: runtime });
+		runningAction.addUpdateListeners(allListeners);
+		return runningAction;
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Domain/ActionDomain.ts
+var ActionDomain = class ActionDomain extends ActionDomainBase {
+	_rootDomain;
+	_actionMap;
+	constructor(definition, { rootDomain }) {
+		super(definition);
+		this._rootDomain = rootDomain;
+		this._actionMap = this.createActionMap();
+	}
+	get rootDomain() {
+		return this._rootDomain;
+	}
+	/**
+	* @internal
+	* All action observers that should see actions on this domain: the root domain's
+	* observers plus this subdomain's own. Mirrors the listener set the local-dispatch
+	* path assembles in `runAction`/`_runAction`, so inbound actions (pushed from a
+	* backend or another client) can be wired up identically and surface in devtools.
+	*/
+	_collectActionObservers() {
+		return [...this._rootDomain._getActionObservers(), ...this._getActionObservers()];
+	}
+	_registerRuntime(runtime) {
+		this._rootDomain._registerRuntime(runtime);
+	}
+	createChildDomain(subDomainDef) {
+		if (this.allDomains.includes(subDomainDef.domain)) throw err_nice_action.fromId("domain_already_exists_in_hierarchy", {
+			domain: subDomainDef.domain,
+			allParentDomains: this.allDomains,
+			parentDomain: this.domain
+		});
+		return new ActionDomain({
+			allDomains: [...this.allDomains, subDomainDef.domain],
+			domain: subDomainDef.domain,
+			actionSchema: subDomainDef.actions
+		}, { rootDomain: this._rootDomain });
+	}
+	get action() {
+		return this._actionMap;
+	}
+	actionsMap() {
+		return this._actionMap;
+	}
+	actionForId(id) {
+		if (!this.actionSchema[id]) throw err_nice_action.fromId("action_id_not_in_domain", {
+			domain: this.domain,
+			actionId: id
+		});
+		return new ActionCore(this, id);
+	}
+	wrapAsPartialLocalHandler(wrappedActionExecutor) {
+		const _handler = new ActionLocalHandler();
+		const executor = wrappedActionExecutor;
+		for (const actionKey in wrappedActionExecutor) {
+			if (!this.actionSchema[actionKey]) continue;
+			_handler.forAction(this.actionForId(actionKey), (request) => executor[request.id](request.input));
+		}
+		return _handler;
+	}
+	wrapAsLocalHandler(wrappedActionExecutor) {
+		const _handler = new ActionLocalHandler();
+		const executor = wrappedActionExecutor;
+		return _handler.forDomain(this, (request) => executor[request.id](request.input));
+	}
+	hydrateContext(id, contextData) {
+		return new ActionContext(this, id, {
+			timeCreated: contextData.timeCreated,
+			cuid: contextData.cuid,
+			routing: contextData.routing.map((item) => {
+				return {
+					runtime: new RuntimeCoordinate(item.runtime),
+					handler: item.handler,
+					time: item.time
+				};
+			}),
+			originClient: contextData.originClient ? new RuntimeCoordinate(contextData.originClient) : RuntimeCoordinate.unknown
+		});
+	}
+	isDomainAction(action) {
+		return isAction_Any_Instance(action) && action.domain === this.domain;
+	}
+	hydrateRequestPayload(serialized) {
+		if (serialized.type !== "request") throw err_nice_action.fromId("hydration_action_state_mismatch", {
+			expected: "request",
+			received: serialized.type
+		});
+		if (serialized.domain !== this.domain) throw err_nice_action.fromId("hydration_domain_mismatch", {
+			expected: this.domain,
+			received: serialized.domain
+		});
+		const id = serialized.id;
+		if (!this.actionSchema[id]) throw err_nice_action.fromId("hydration_action_id_not_found", {
+			domain: this.domain,
+			actionId: serialized.id
+		});
+		const contextAction = this.hydrateContext(id, serialized.context);
+		return new ActionPayload_Request({ context: contextAction }, contextAction.deserializeInput(serialized.input), { time: serialized.time });
+	}
+	hydrateResultPayload(serialized) {
+		if (serialized.type !== "result") throw err_nice_action.fromId("hydration_action_state_mismatch", {
+			expected: "result",
+			received: serialized.type
+		});
+		if (serialized.domain !== this.domain) throw err_nice_action.fromId("hydration_domain_mismatch", {
+			expected: this.domain,
+			received: serialized.domain
+		});
+		const id = serialized.id;
+		if (!this.actionSchema[id]) throw err_nice_action.fromId("hydration_action_id_not_found", {
+			domain: this.domain,
+			actionId: serialized.id
+		});
+		const contextAction = this.hydrateContext(id, serialized.context);
+		const result = serialized.result.ok ? {
+			ok: true,
+			output: contextAction.schema.deserializeOutput(serialized.result.output)
+		} : serialized.result;
+		return new ActionPayload_Result({ context: contextAction }, result, { time: serialized.time });
+	}
+	hydrateAnyAction(actionJson) {
+		assertIsActionJson(actionJson);
+		if (actionJson.form === "data") {
+			if (actionJson.type === "request") return this.hydrateRequestPayload(actionJson);
+			if (actionJson.type === "result") return this.hydrateResultPayload(actionJson);
+		}
+		return this.actionForId(actionJson.id);
+	}
+	async runAction(request, options) {
+		const allListeners = [...options?.listeners ?? [], ...this._listeners];
+		return this._rootDomain._runAction(request, {
+			...options,
+			listeners: allListeners
+		});
+	}
+	createActionMap() {
+		const map = {};
+		for (const id in this.actionSchema) map[id] = new ActionCore(this, id);
+		return map;
+	}
+};
+//#endregion
+//#region src/ActionDefinition/Domain/helpers/createRootActionDomain.ts
+const createActionRootDomain = (definition) => {
+	return new ActionRootDomain(definition);
+};
+//#endregion
+//#region src/ActionDefinition/Schema/ActionSchema.ts
+var ActionSchema = class {
+	_errorDeclarations = [];
+	inputOptions;
+	outputOptions;
+	get inputSchema() {
+		return this.inputOptions?.schema;
+	}
+	get outputSchema() {
+		return this.outputOptions?.schema;
+	}
+	/**
+	* Declare the input schema (JSON-native or with explicit SERDE type param).
+	* For non-JSON-native inputs, prefer the 3-argument form below to avoid
+	* needing explicit type parameters.
+	*/
+	input(options) {
+		this.inputOptions = options;
+		return this;
+	}
+	/**
+	* Declare the output schema (JSON-native or with explicit SERDE type param).
+	* For non-JSON-native outputs, prefer the 3-argument form below to avoid
+	* needing explicit type parameters.
+	*/
+	output(options) {
+		this.outputOptions = options;
+		return this;
+	}
+	throws(domain, ids) {
+		this._errorDeclarations.push({
+			_domain: domain,
+			_ids: ids
+		});
+		return this;
+	}
+	/**
+	* Serialize raw input to a JSON-serializable form.
+	* Uses the schema's serialization.serialize if defined; otherwise the input
+	* is already JSON-native and is returned as-is.
+	*/
+	serializeInput(rawInput) {
+		if (this.inputOptions?.serialization) return this.inputOptions.serialization.serialize(rawInput);
+		return rawInput;
+	}
+	/**
+	* Deserialize a JSON value back into the raw input type.
+	* Uses serialization.deserialize if defined; otherwise the value is cast
+	* directly (it's already in the correct shape).
+	*/
+	deserializeInput(serialized) {
+		if (this.inputOptions?.serialization) return this.inputOptions.serialization.deserialize(serialized);
+		return serialized;
+	}
+	/**
+	* Validate raw input against the schema defined via `.input({ schema })`.
+	* Throws `action_input_validation_failed` if validation fails.
+	* Returns the validated (and possibly coerced) value on success.
+	* If no input schema was declared, the value is passed through as-is.
+	*/
+	validateInput(value, meta) {
+		if (this.inputOptions?.schema == null) return value;
+		const result = this.inputOptions.schema["~standard"].validate(value);
+		if (result instanceof Promise) throw err_nice_action.fromId("action_input_validation_promise", {
+			domain: meta.domain,
+			actionId: meta.actionId
+		});
+		if (result.issues != null) throw err_nice_action.fromId("action_input_validation_failed", {
+			domain: meta.domain,
+			actionId: meta.actionId,
+			validationMessage: (0, _nice_code_common_errors.extractMessageFromStandardSchema)(result)
+		});
+		return result.value;
+	}
+	validateOutput(value, meta) {
+		if (this.outputOptions?.schema == null) return value;
+		const result = this.outputOptions.schema["~standard"].validate(value);
+		if (result instanceof Promise) throw err_nice_action.fromId("action_output_validation_promise", {
+			domain: meta.domain,
+			actionId: meta.actionId
+		});
+		if (result.issues != null) throw err_nice_action.fromId("action_output_validation_failed", {
+			domain: meta.domain,
+			actionId: meta.actionId,
+			validationMessage: (0, _nice_code_common_errors.extractMessageFromStandardSchema)(result)
+		});
+		return result.value;
+	}
+	/**
+	* Serialize raw output to a JSON-serializable form.
+	*/
+	serializeOutput(rawOutput) {
+		if (this.outputOptions?.serialization) return this.outputOptions.serialization.serialize(rawOutput);
+		return rawOutput;
+	}
+	/**
+	* Deserialize a JSON value back into the raw output type.
+	*/
+	deserializeOutput(serialized) {
+		if (this.outputOptions?.serialization) return this.outputOptions.serialization.deserialize(serialized);
+		return serialized;
+	}
+};
+const actionSchema = () => {
+	return new ActionSchema();
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/Transport.ts
+/**
+* Reusable transport definition. Devs construct these (`HttpTransport.create({ createRequest })`,
+* `WebSocketTransport.create({ createWebSocket })`, …) and pass them to an
+* `ActionExternalClientHandler`. A single
+* definition can be shared across multiple handlers — each handler builds its own live
+* {@link TransportConnection} via {@link TransportConnection._createConnection}.
+*/
+var Transport = class {};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/helpers/addTransportStatusMetadata.ts
+function addTransportStatusMetadata(transportStatus) {
+	if (transportStatus.status === "ready") return {
+		status: "ready",
+		readyData: transportStatus.readyData
+	};
+	if (transportStatus.status === "initializing") return {
+		status: "initializing",
+		initializationPromise: transportStatus.initializationPromise,
+		timeStarted: Date.now()
+	};
+	if (transportStatus.status === "failed") return {
+		status: "failed",
+		error: transportStatus.error,
+		timeFailed: Date.now()
+	};
+	if (transportStatus.status === "unsupported") return { status: "unsupported" };
+	return { status: "uninitialized" };
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/TransportConnection.ts
+let transportOrd = 0;
+/**
+* Live, per-handler transport runtime built from a reusable {@link Transport} definition. Holds the
+* connection-scoped state (ordinal, initialized config, sockets / abort sets) that must not be shared
+* across handlers. Construct these via `definition._createConnection(...)`, never directly.
+*/
+var TransportConnection = class {
+	def;
+	transOrd = transportOrd++;
+	type;
+	initialized;
+	/** Backref to the public definition that created this connection (used for devtools route info). */
+	definition;
+	constructor(def) {
+		this.def = def;
+		this.type = def.type;
+		this.initialized = def.initialize();
+	}
+	/**
+	* Devtools route info for an action routed through this live connection. Defaults to the stateless
+	* {@link definition}'s info; connections override to enrich it from live state (e.g. the actual
+	* resolved socket URL) when the definition couldn't resolve it on its own.
+	*/
+	getRouteInfo(input) {
+		return this.definition?.getRouteInfo(input);
+	}
+	_getCacheKey(input) {
+		const parts = this.initialized.getTransportCacheKey?.(input);
+		if (parts == null) return null;
+		return parts.join("\0");
+	}
+	getCacheKey(input) {
+		const inner = this._getCacheKey(input);
+		if (inner == null) return null;
+		return `${this.transOrd}:${inner}`;
+	}
+	getTransport(input) {
+		return this._processTransportStatus(input);
+	}
+	_processTransportStatus(input) {
+		const transportStatusInfo = addTransportStatusMetadata(this.initialized.getTransport(input));
+		if (transportStatusInfo.status !== "initializing" && transportStatusInfo.status !== "ready") return transportStatusInfo;
+		if (transportStatusInfo.status === "initializing") {
+			const promiseForReadyData = transportStatusInfo.initializationPromise.then((result) => {
+				if (result.status === "ready") return {
+					status: "ready",
+					readyData: this._finalizeTransportMethods(result.readyData)
+				};
+				return result;
+			});
+			return {
+				status: "initializing",
+				timeStarted: transportStatusInfo.timeStarted,
+				initializationPromise: promiseForReadyData
+			};
+		}
+		return {
+			status: "ready",
+			readyData: this._finalizeTransportMethods(transportStatusInfo.readyData)
+		};
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/Custom/CustomConnection.ts
+var CustomConnection = class extends TransportConnection {
+	constructor(def) {
+		super({
+			...def,
+			type: "custom"
+		});
+	}
+	_finalizeTransportMethods(inputs) {
+		return {
+			sendActionData: inputs.sendActionData,
+			sendReturnData: inputs.sendReturnData,
+			updateRunConfig: inputs.updateRunConfig
+		};
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/Custom/CustomTransport.ts
+/**
+* Reusable custom transport definition for channels nice-action doesn't model natively. Create one
+* with `CustomTransport.create({ sendActionData })` for the simple case, or
+* `CustomTransport.createAdvanced({ getTransport })` for full control over the lifecycle.
+*/
+var CustomTransport = class CustomTransport extends Transport {
+	options;
+	type = "custom";
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	static create(options) {
+		return new CustomTransport({
+			...options,
+			mode: "send"
+		});
+	}
+	static createAdvanced(options) {
+		return new CustomTransport({
+			...options,
+			mode: "advanced"
+		});
+	}
+	_createConnection(_ctx) {
+		const options = this.options;
+		let getTransport;
+		if (options.mode === "advanced") getTransport = options.getTransport;
+		else getTransport = () => ({
+			status: "ready",
+			readyData: {
+				sendActionData: options.sendActionData,
+				sendReturnData: options.sendReturnData,
+				updateRunConfig: options.updateRunConfig,
+				closeTransport: options.closeTransport ?? (() => {})
+			}
+		});
+		return new CustomConnection({ initialize: () => ({
+			getTransportCacheKey: options.getTransportCacheKey,
+			getTransport
+		}) });
+	}
+	getRouteInfo(input) {
+		if (this.options.getRouteInfo != null) return this.options.getRouteInfo(input);
+		return {
+			type: "custom",
+			summary: this.options.label ?? "custom"
+		};
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/err_nice_transport_ws.ts
+let EErrId_NiceTransport_WebSocket = /* @__PURE__ */ function(EErrId_NiceTransport_WebSocket) {
+	EErrId_NiceTransport_WebSocket["ws_disconnected"] = "ws_disconnected";
+	EErrId_NiceTransport_WebSocket["ws_create_failed"] = "ws_create_failed";
+	EErrId_NiceTransport_WebSocket["ws_error"] = "ws_error";
+	return EErrId_NiceTransport_WebSocket;
+}({});
+const err_nice_transport_ws = err_nice_transport.createChildDomain({
+	domain: "ws_transport",
+	schema: {
+		["ws_disconnected"]: (0, _nice_code_error.err)({ message: () => `WebSocket transport disconnected.` }),
+		["ws_create_failed"]: (0, _nice_code_error.err)({ message: ({ originalError }) => `Failed to create WebSocket transport.${originalError ? ` Original error: ${originalError.message}` : ""}` }),
+		["ws_error"]: (0, _nice_code_error.err)({ message: ({ originalError }) => `WebSocket transport error.${originalError ? ` Original error: ${originalError.message}` : ""}` })
+	}
+});
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpConnection.ts
+var HttpConnection = class extends TransportConnection {
+	constructor(def) {
+		super({
+			...def,
+			type: "http"
+		});
+	}
+	_finalizeTransportMethods(methods) {
+		return {
+			sendActionData: (input) => {
+				const request = methods.createRequest(input);
+				this.send({
+					...input,
+					params: { request },
+					runningAction: input.runningAction
+				}).catch((err) => input.runningAction._abort(err));
+			},
+			updateRunConfig: methods.updateRunConfig
+		};
+	}
+	async send(input) {
+		const { action, runningAction, timeout, params: { request } } = input;
+		const wire = action.toJsonObject();
+		const ac = new AbortController();
+		let timedOut = false;
+		const timeoutId = setTimeout(() => {
+			timedOut = true;
+			ac.abort();
+		}, timeout);
+		const unsubscribe = input.runningAction.addUpdateListeners([(update) => {
+			if (update.type === "finished") {
+				clearTimeout(timeoutId);
+				ac.abort();
+			}
+		}]);
+		try {
+			const res = await fetch(request.url, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...request.headers
+				},
+				body: request.body ?? JSON.stringify(wire),
+				signal: ac.signal
+			});
+			if (!res.ok) {
+				if (action.type === "request") try {
+					const jsonData = await res.json();
+					if (isActionPayload_Result_JsonObject(jsonData)) runningAction._completeWithResult(action._domain.hydrateResultPayload(jsonData));
+					else if ((0, _nice_code_error.isNiceErrorObject)(jsonData)) runningAction._completeWithResult(action.errorResult((0, _nice_code_error.castNiceError)(jsonData)));
+					else runningAction._completeWithResult(action.errorResult(err_nice_transport.fromId("invalid_action_response", { actionId: action.id })));
+				} catch (e) {
+					throw err_nice_transport.fromId("send_failed", {
+						actionState: action.type,
+						actionId: action.id,
+						httpStatusCode: res.status,
+						message: e.message
+					}).withOriginError(e);
+				}
+				else {
+					let text;
+					try {
+						text = await res.text();
+					} catch (e) {
+						console.warn(`Failed to read error response body for failed HTTP request in HttpConnection:`, e);
+					}
+					throw err_nice_transport.fromId("send_failed", {
+						actionState: action.type,
+						actionId: action.id,
+						httpStatusCode: res.status,
+						message: text ?? `HTTP error with status ${res.status}`
+					});
+				}
+				return;
+			}
+			if (action.type === "request") {
+				const json = await res.json();
+				if (!isActionPayload_Result_JsonObject(json)) throw err_nice_transport.fromId("invalid_action_response", { actionId: action.id });
+				runningAction._completeWithResult(action._domain.hydrateResultPayload(json));
+			}
+		} catch (err) {
+			if (timedOut) throw err_nice_transport.fromId("timeout", { timeout });
+			if (err instanceof _nice_code_error.NiceError) throw err;
+			throw err_nice_transport.fromId("send_failed", {
+				actionState: action.type,
+				actionId: action.id,
+				message: err instanceof Error ? err.message : String(err)
+			}).withOriginError(err instanceof Error ? err : void 0);
+		} finally {
+			clearTimeout(timeoutId);
+			unsubscribe();
+		}
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport.ts
+function shortPath(url) {
+	try {
+		return new URL(url).pathname || url;
+	} catch {
+		return url;
+	}
+}
+/**
+* Reusable HTTP transport definition. Create one with `HttpTransport.create({ createRequest })` — the
+* single `createRequest` function lets you keep it simple (`() => ({ url })`) or derive the request
+* per action.
+*/
+var HttpTransport = class HttpTransport extends Transport {
+	options;
+	type = "http";
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	static create(options) {
+		return new HttpTransport(options);
+	}
+	_createConnection(_ctx) {
+		return new HttpConnection({ initialize: () => ({
+			getTransportCacheKey: this.options.getTransportCacheKey,
+			getTransport: () => ({
+				status: "ready",
+				readyData: {
+					createRequest: this.options.createRequest,
+					updateRunConfig: this.options.updateRunConfig
+				}
+			})
+		}) });
+	}
+	getRouteInfo(input) {
+		const { url } = this.options.createRequest(input);
+		return {
+			type: "http",
+			method: "POST",
+			url,
+			summary: `POST ${shortPath(url)}`
+		};
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionFrameCrypto.ts
+const ENCRYPTED_ENVELOPE_LENGTH = 2;
+/**
+* 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.
+*/
+function createActionFrameCrypto({ link, linkedClientId }) {
+	return {
+		async encryptFrame(frame) {
+			const { nonce, ciphertext } = await link.encryptBytesForLinkedClient({
+				linkedClientId,
+				dataToEncrypt: frame
+			});
+			return (0, msgpackr.pack)([nonce, ciphertext]);
+		},
+		async decryptFrame(frame) {
+			if (typeof frame === "string") throw new Error("[ws-crypto] expected an encrypted binary frame, received text");
+			const envelope = (0, msgpackr.unpack)(frame instanceof ArrayBuffer ? new Uint8Array(frame) : frame);
+			if (!Array.isArray(envelope) || envelope.length !== ENCRYPTED_ENVELOPE_LENGTH) throw new Error("[ws-crypto] malformed encrypted frame envelope");
+			const [nonce, ciphertext] = envelope;
+			if (!(nonce instanceof Uint8Array) || !(ciphertext instanceof Uint8Array)) throw new Error("[ws-crypto] malformed encrypted frame fields");
+			return await link.decryptBytesFromLinkedClient({
+				linkedClientId,
+				dataToDecrypt: {
+					nonce,
+					ciphertext
+				}
+			});
+		}
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionWsHandshake.ts
+/**
+* Authenticated handshake for the WebSocket channel. Run once per connection, before any action
+* frames flow, it:
+* - exchanges each side's {@link RuntimeCoordinate} + public keys,
+* - checks both ends share the same wire dictionary version (closes the positional-dictionary footgun),
+* - has the client prove control of its verify (Ed25519) key by signing a fresh challenge that binds
+*   both nonces, both identities, the dictionary version, the level, and every exchanged public key,
+* - establishes a `ClientCryptoKeyLink` link on both sides (so the server can verify the signature and,
+*   for the `encrypted` level, both can derive a shared AES-GCM key with the verify keys folded in).
+*
+* This module is transport-agnostic: it produces/consumes message objects. The transport + server
+* handler drive the I/O and the connection phase (Step 4). Keep `none`-level connections from ever
+* reaching here — they skip the handshake entirely.
+*/
+const HANDSHAKE_PROTOCOL = "nice-ws-hs/1";
+/** How much the channel protects after the handshake — chosen by the consumer (perf vs security). */
+let ESecurityLevel = /* @__PURE__ */ function(ESecurityLevel) {
+	/** No handshake; identity is self-asserted (fastest, dev / trusted networks). */
+	ESecurityLevel["none"] = "none";
+	/** Handshake authenticates identity (sign/verify + key pin); frames stay plaintext over TLS. */
+	ESecurityLevel["authenticated"] = "authenticated";
+	/** Authenticated handshake + every frame AES-GCM encrypted with the derived shared key. */
+	ESecurityLevel["encrypted"] = "encrypted";
+	return ESecurityLevel;
+}({});
+let EHandshakeMessageType = /* @__PURE__ */ function(EHandshakeMessageType) {
+	EHandshakeMessageType["hello"] = "hello";
+	EHandshakeMessageType["welcome"] = "welcome";
+	EHandshakeMessageType["prove"] = "prove";
+	EHandshakeMessageType["accept"] = "accept";
+	EHandshakeMessageType["reject"] = "reject";
+	return EHandshakeMessageType;
+}({});
+const vEd25519Raw = valibot.custom((val) => typeof val === "string" && val.startsWith("ed25519::raw_base64::"));
+const vX25519Raw = valibot.custom((val) => typeof val === "string" && val.startsWith("x25519::raw_base64::"));
+const vCoordinate = valibot.object({
+	envId: valibot.string(),
+	perId: valibot.optional(valibot.string()),
+	insId: valibot.optional(valibot.string())
+});
+const vSecurityLevel = valibot.picklist([
+	"none",
+	"authenticated",
+	"encrypted"
+]);
+const vHsHello = valibot.object({
+	t: valibot.literal("hello"),
+	protocol: valibot.string(),
+	securityLevel: vSecurityLevel,
+	dictionaryVersion: valibot.string(),
+	client: vCoordinate,
+	clientNonce: valibot.string(),
+	verifyPublicKey: vEd25519Raw,
+	exchangePublicKey: valibot.optional(vX25519Raw)
+});
+const vHsWelcome = valibot.object({
+	t: valibot.literal("welcome"),
+	securityLevel: vSecurityLevel,
+	dictionaryVersion: valibot.string(),
+	server: vCoordinate,
+	serverNonce: valibot.string(),
+	verifyPublicKey: vEd25519Raw,
+	exchangePublicKey: valibot.optional(vX25519Raw)
+});
+const vHsProve = valibot.object({
+	t: valibot.literal("prove"),
+	signatureBase64: valibot.string()
+});
+const vHsAccept = valibot.object({
+	t: valibot.literal("accept"),
+	signatureBase64: valibot.optional(valibot.string())
+});
+const vHsReject = valibot.object({
+	t: valibot.literal("reject"),
+	reason: valibot.string()
+});
+const vHandshakeMessage = valibot.variant("t", [
+	vHsHello,
+	vHsWelcome,
+	vHsProve,
+	vHsAccept,
+	vHsReject
+]);
+/** Serialize a handshake message for the wire (handshake frames are JSON — they aren't the hot path). */
+function encodeHandshakeMessage(message) {
+	return JSON.stringify(message);
+}
+/** Parse + structurally validate an incoming handshake frame; `undefined` if it isn't one. */
+function decodeHandshakeMessage(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	const result = valibot.safeParse(vHandshakeMessage, parsed);
+	return result.success ? result.output : void 0;
+}
+/** Stable link id for a runtime coordinate — the key both the crypto link and the connection use. */
+function runtimeLinkId(coordinate) {
+	return `runtime::${new RuntimeCoordinate(coordinate).stringId}`;
+}
+function coordId(coordinate) {
+	return new RuntimeCoordinate(coordinate).stringId;
+}
+function sessionSalt(clientNonce, serverNonce) {
+	return `${clientNonce}::${serverNonce}`;
+}
+function handshakeInfo(dictionaryVersion) {
+	return `${HANDSHAKE_PROTOCOL}::${dictionaryVersion}`;
+}
+/**
+* The exact string both sides sign/verify. JSON-encoded ordered array so field boundaries are
+* unambiguous; binds identities, nonces (freshness), version, level, and all exchanged public keys
+* (authenticating the keys via the signature, complementing `bindVerifyKeysIntoDerivation`).
+*/
+function buildHandshakeChallenge(parts) {
+	return JSON.stringify([
+		HANDSHAKE_PROTOCOL,
+		parts.securityLevel,
+		parts.dictionaryVersion,
+		parts.clientCoordId,
+		parts.serverCoordId,
+		parts.clientNonce,
+		parts.serverNonce,
+		parts.clientVerifyKey,
+		parts.serverVerifyKey,
+		parts.clientExchangeKey ?? "_",
+		parts.serverExchangeKey ?? "_"
+	]);
+}
+function reject(reason) {
+	return {
+		t: "reject",
+		reason
+	};
+}
+function tofuPinKey(client) {
+	return `${client.envId}::${client.perId ?? client.insId ?? "_"}`;
+}
+/**
+* In-memory trust-on-first-use resolver: trusts (and pins) the first verify key seen for a client
+* identity, then rejects a different key for that identity. The default; replace with a storage-backed
+* resolver for cross-restart pinning (see Step 5).
+*/
+function createInMemoryTofuVerifyKeyResolver() {
+	const pinned = /* @__PURE__ */ new Map();
+	return { async resolve({ client, verifyPublicKey }) {
+		const key = tofuPinKey(client);
+		const existing = pinned.get(key);
+		if (existing == null) {
+			pinned.set(key, verifyPublicKey);
+			return { trusted: true };
+		}
+		if (existing === verifyPublicKey) return { trusted: true };
+		return {
+			trusted: false,
+			reason: "verify key changed for client identity (pin mismatch)"
+		};
+	} };
+}
+/**
+* Storage-backed trust-on-first-use resolver: pins survive process restarts / Durable Object eviction
+* (e.g. back it with `createDurableObjectStorageAdapter`). Same policy as the in-memory variant — trust
+* + pin the first verify key per client identity, reject a different one thereafter.
+*/
+function createStorageTofuVerifyKeyResolver(storageAdapter) {
+	const storage = (0, _nice_code_util.createTypedStorage)({ storageAdapter });
+	return { async resolve({ client, verifyPublicKey }) {
+		const key = tofuPinKey(client);
+		const existing = (await storage.getJson("pins"))?.[key];
+		if (existing == null) {
+			await storage.updateJsonWithDef("pins", {}, (current) => ({
+				...current,
+				[key]: verifyPublicKey
+			}));
+			return { trusted: true };
+		}
+		if (existing === verifyPublicKey) return { trusted: true };
+		return {
+			trusted: false,
+			reason: "verify key changed for client identity (pin mismatch)"
+		};
+	} };
+}
+function createClientHandshake(config) {
+	const { link, localCoordinate, dictionaryVersion, securityLevel } = config;
+	const wantsEncryption = securityLevel === "encrypted";
+	const clientNonce = (0, nanoid.nanoid)();
+	let pending;
+	return {
+		async createHello() {
+			return {
+				t: "hello",
+				protocol: HANDSHAKE_PROTOCOL,
+				securityLevel,
+				dictionaryVersion,
+				client: localCoordinate,
+				clientNonce,
+				verifyPublicKey: await link.getLocalVerifyPublicKey(),
+				exchangePublicKey: wantsEncryption ? await link.getLocalExchangePublicKey() : void 0
+			};
+		},
+		async onWelcome(welcome) {
+			if (welcome.dictionaryVersion !== dictionaryVersion) throw new Error("[ws-handshake] server dictionary version mismatch");
+			if (welcome.securityLevel !== securityLevel) throw new Error("[ws-handshake] server security level mismatch");
+			if (wantsEncryption && welcome.exchangePublicKey == null) throw new Error("[ws-handshake] server did not provide an exchange key for encryption");
+			const linkedServerId = runtimeLinkId(welcome.server);
+			await link.linkClient({
+				linkedClientId: linkedServerId,
+				verifyPublicKey: welcome.verifyPublicKey,
+				...wantsEncryption ? {
+					exchangePublicKey: welcome.exchangePublicKey,
+					saltString: sessionSalt(clientNonce, welcome.serverNonce),
+					infoString: handshakeInfo(dictionaryVersion),
+					bindVerifyKeysIntoDerivation: true
+				} : {}
+			});
+			const challenge = buildHandshakeChallenge({
+				securityLevel,
+				dictionaryVersion,
+				clientCoordId: coordId(localCoordinate),
+				serverCoordId: coordId(welcome.server),
+				clientNonce,
+				serverNonce: welcome.serverNonce,
+				clientVerifyKey: await link.getLocalVerifyPublicKey(),
+				serverVerifyKey: welcome.verifyPublicKey,
+				clientExchangeKey: wantsEncryption ? await link.getLocalExchangePublicKey() : void 0,
+				serverExchangeKey: welcome.exchangePublicKey
+			});
+			pending = {
+				linkedServerId,
+				server: welcome.server,
+				challenge
+			};
+			return {
+				t: "prove",
+				signatureBase64: (await link.signChallenge([challenge])).signatureBase64
+			};
+		},
+		async onAccept(accept) {
+			if (pending == null) throw new Error("[ws-handshake] accept before welcome");
+			if (accept.signatureBase64 != null) {
+				if (!await link.verifyChallengeFromLinkedClient({
+					linkedClientId: pending.linkedServerId,
+					challenge: pending.challenge,
+					signatureBase64: accept.signatureBase64
+				})) throw new Error("[ws-handshake] server signature invalid");
+			}
+			return {
+				linkedClientId: pending.linkedServerId,
+				remote: pending.server,
+				securityLevel
+			};
+		}
+	};
+}
+function createServerHandshake(config) {
+	const { link, localCoordinate, dictionaryVersion } = config;
+	const allowedLevels = Array.isArray(config.securityLevel) ? config.securityLevel : [config.securityLevel];
+	const verifyKeyResolver = config.verifyKeyResolver ?? createInMemoryTofuVerifyKeyResolver();
+	const serverNonce = (0, nanoid.nanoid)();
+	let pending;
+	let result;
+	return {
+		async onHello(hello) {
+			if (hello.protocol !== HANDSHAKE_PROTOCOL) return reject("unsupported handshake protocol");
+			if (hello.dictionaryVersion !== dictionaryVersion) return reject("dictionary version mismatch");
+			const negotiatedLevel = hello.securityLevel;
+			if (negotiatedLevel === "none" || !allowedLevels.includes(negotiatedLevel)) return reject("security level not allowed");
+			const wantsEncryption = negotiatedLevel === "encrypted";
+			if (wantsEncryption && hello.exchangePublicKey == null) return reject("missing exchange key for encryption");
+			const linkedClientId = runtimeLinkId(hello.client);
+			await link.linkClient({
+				linkedClientId,
+				verifyPublicKey: hello.verifyPublicKey,
+				...wantsEncryption ? {
+					exchangePublicKey: hello.exchangePublicKey,
+					saltString: sessionSalt(hello.clientNonce, serverNonce),
+					infoString: handshakeInfo(dictionaryVersion),
+					bindVerifyKeysIntoDerivation: true
+				} : {}
+			});
+			const serverVerifyKey = await link.getLocalVerifyPublicKey();
+			const serverExchangeKey = wantsEncryption ? await link.getLocalExchangePublicKey() : void 0;
+			const keyMaterial = wantsEncryption && hello.exchangePublicKey != null ? {
+				verifyPublicKey: hello.verifyPublicKey,
+				exchangePublicKey: hello.exchangePublicKey,
+				saltString: sessionSalt(hello.clientNonce, serverNonce),
+				infoString: handshakeInfo(dictionaryVersion),
+				bindVerifyKeysIntoDerivation: true
+			} : void 0;
+			pending = {
+				client: hello.client,
+				linkedClientId,
+				clientVerifyKey: hello.verifyPublicKey,
+				negotiatedLevel,
+				keyMaterial,
+				challenge: buildHandshakeChallenge({
+					securityLevel: negotiatedLevel,
+					dictionaryVersion,
+					clientCoordId: coordId(hello.client),
+					serverCoordId: coordId(localCoordinate),
+					clientNonce: hello.clientNonce,
+					serverNonce,
+					clientVerifyKey: hello.verifyPublicKey,
+					serverVerifyKey,
+					clientExchangeKey: hello.exchangePublicKey,
+					serverExchangeKey
+				})
+			};
+			return {
+				t: "welcome",
+				securityLevel: negotiatedLevel,
+				dictionaryVersion,
+				server: localCoordinate,
+				serverNonce,
+				verifyPublicKey: serverVerifyKey,
+				exchangePublicKey: serverExchangeKey
+			};
+		},
+		async onProve(prove) {
+			if (pending == null) return reject("prove before hello");
+			if (!await link.verifyChallengeFromLinkedClient({
+				linkedClientId: pending.linkedClientId,
+				challenge: pending.challenge,
+				signatureBase64: prove.signatureBase64
+			})) return reject("invalid client signature");
+			const trust = await verifyKeyResolver.resolve({
+				client: pending.client,
+				verifyPublicKey: pending.clientVerifyKey
+			});
+			if (!trust.trusted) return reject(trust.reason ?? "client verify key not trusted");
+			result = {
+				linkedClientId: pending.linkedClientId,
+				remote: pending.client,
+				securityLevel: pending.negotiatedLevel,
+				encryptionKeyMaterial: pending.keyMaterial
+			};
+			return {
+				t: "accept",
+				signatureBase64: (await link.signChallenge([pending.challenge])).signatureBase64
+			};
+		},
+		/** The completed handshake result once `onProve` has accepted, else `undefined`. */
+		getResult() {
+			return result;
+		}
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionWireCodec.ts
+/**
+* Shared building blocks for the binary action codecs (the stateless {@link createBinaryWsAdapter} and
+* the per-connection `createBinaryWsSessionFactory`). Both map a `domain:id` route to a tiny integer
+* and reduce the verbose JSON wire to a positional tuple — they only differ in how much context they
+* carry per frame, so the dictionary + payload (de)assembly live here.
+*/
+/**
+* Tiny integer codes for the payload type, so the verbose `"request"`/`"result"`/`"progress"`
+* strings never hit the wire. The index in {@link ReversePayloadType} must line up with the value.
+*/
+const PayloadTypeToInt = {
+	["request"]: 0,
+	["result"]: 1,
+	["progress"]: 2
+};
+const ReversePayloadType = [
+	"request",
+	"result",
+	"progress"
+];
+/**
+* Build the positional `domain:id` ↔ integer dictionary. Both ends of a channel MUST build it from
+* the same domains in the same order — the mapping is positional, so a mismatch routes to the wrong
+* action. Add new transported domains to the end of the list.
+*/
+function buildActionRouteDictionary(domains) {
+	const routeToInt = /* @__PURE__ */ new Map();
+	const intToRoute = [];
+	for (const dom of domains) for (const actionId of Object.keys(dom.actionSchema)) {
+		const routeKey = `${dom.domain}:${actionId}`;
+		if (routeToInt.has(routeKey)) continue;
+		routeToInt.set(routeKey, intToRoute.length);
+		intToRoute.push({
+			domain: dom.domain,
+			id: actionId,
+			allDomains: dom.allDomains
+		});
+	}
+	return {
+		routeToInt,
+		intToRoute
+	};
+}
+/** Pull the type-specific payload (`input` / `result` / `progress`) out of a wire JSON object. */
+function extractWirePayload(json) {
+	if (json.type === "request") return json.input;
+	if (json.type === "result") return json.result;
+	if (json.type === "progress") return json.progress;
+}
+/**
+* Reassemble a full wire JSON object from its decoded parts. `inputHash`/`outputHash` are emitted
+* empty — the hydration constructors recompute them — and the result still satisfies
+* `isActionPayload_Any_JsonObject` so it flows through validation like a JSON frame.
+*/
+function assembleWireJson(routeMeta, payloadType, time, context, payloadData) {
+	const base = {
+		form: "data",
+		domain: routeMeta.domain,
+		id: routeMeta.id,
+		allDomains: routeMeta.allDomains,
+		time,
+		context
+	};
+	if (payloadType === "request") return {
+		...base,
+		type: "request",
+		input: payloadData,
+		inputHash: ""
+	};
+	if (payloadType === "result") return {
+		...base,
+		type: "result",
+		result: payloadData,
+		outputHash: ""
+	};
+	return {
+		...base,
+		type: "progress",
+		progress: payloadData
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsAdapter.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 `createBinaryWsSessionFactory`.
+*/
+const ENVELOPE$1 = {
+	route: 0,
+	type: 1,
+	time: 2,
+	cuid: 3,
+	originClient: 4,
+	payload: 5
+};
+const ENVELOPE_LENGTH$1 = 6;
+/**
+* Builds a *stateless* `formatMessage` pipeline for {@link WebSocketTransport}, 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 createBinaryWsAdapter(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-ws] Cannot pack unregistered action route: ${routeKey}`);
+			const envelope = new Array(ENVELOPE_LENGTH$1);
+			envelope[ENVELOPE$1.route] = routeInt;
+			envelope[ENVELOPE$1.type] = PayloadTypeToInt[json.type];
+			envelope[ENVELOPE$1.time] = json.time;
+			envelope[ENVELOPE$1.cuid] = json.context.cuid;
+			envelope[ENVELOPE$1.originClient] = json.context.originClient;
+			envelope[ENVELOPE$1.payload] = extractWirePayload(json);
+			return (0, msgpackr.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 = (0, msgpackr.unpack)(buffer);
+				if (!Array.isArray(envelope) || envelope.length !== ENVELOPE_LENGTH$1) return void 0;
+				const routeMeta = intToRoute[envelope[ENVELOPE$1.route]];
+				const payloadType = ReversePayloadType[envelope[ENVELOPE$1.type]];
+				if (routeMeta == null || payloadType == null) return void 0;
+				const time = envelope[ENVELOPE$1.time];
+				return assembleWireJson(routeMeta, payloadType, time, {
+					cuid: envelope[ENVELOPE$1.cuid],
+					timeCreated: time,
+					routing: [],
+					originClient: envelope[ENVELOPE$1.originClient]
+				}, envelope[ENVELOPE$1.payload]);
+			} catch (e) {
+				console.error("[binary-ws] Failed to unpack binary action frame", e);
+				return;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsSessionFactory.ts
+/**
+* Positional layout of the *session* binary envelope — the leanest frame. Compared to the stateless
+* adapter it replaces the 21-char `cuid` with a small per-connection integer and only carries
+* `originClient` on the very first request of each direction (the peer remembers it afterwards).
+*
+*   [ routeInt, typeInt, corrId, time, originClient?, payloadData ]
+*/
+const ENVELOPE = {
+	route: 0,
+	type: 1,
+	corr: 2,
+	time: 3,
+	originClient: 4,
+	payload: 5
+};
+const ENVELOPE_LENGTH = 6;
+/**
+* How long a pending correlation entry is kept before it's swept. A correlation only matters until its
+* action resolves or times out, so anything older than the longest realistic action timeout can be
+* dropped — this bounds memory when requests time out or a connection dies mid-flight (their replies
+* would never arrive, leaving the entry orphaned). Generous default so live correlations are never
+* pruned (the default transport timeout is 10s).
+*/
+const DEFAULT_CORRELATION_TTL_MS = 5 * 6e4;
+function isKnownIdentity(coordinate) {
+	return coordinate != null && coordinate.envId !== "_unset_";
+}
+/**
+* Drop entries older than `ttlMs`. Maps keep insertion order and entries are inserted in time order,
+* so the oldest are first — stop sweeping at the first live entry.
+*/
+function pruneExpired(map, now, ttlMs) {
+	for (const [key, entry] of map) {
+		if (now - entry.time <= ttlMs) break;
+		map.delete(key);
+	}
+}
+/**
+* Builds a factory of *stateful, per-connection* codecs for {@link WebSocketTransport} /
+* `ActionServerHandler` — the maximally compact binary wire. Call the returned factory once per live
+* connection (each socket on the client, each accepted connection on the server) so every channel
+* gets its own correlation + identity state.
+*
+* On top of everything {@link createBinaryWsAdapter} drops, a session also drops:
+* - **`cuid`** — replaced by a per-connection integer correlation id. The initiator maps it to its
+*   real cuid; the responder echoes it; each side reconstructs the cuid from its own map. Correlation
+*   only needs to be unique per socket, so a counter suffices.
+* - **`originClient` after the first request** — the first request each side sends carries its
+*   identity; the peer remembers it and injects it into later frames. Replies omit it entirely (a
+*   reply carries the initiator's own origin, which the initiator already knows).
+*
+* Both ends MUST build the factory from the same domains in the same order (positional dictionary).
+* Text frames still return `undefined` from `incoming`, so JSON clients remain interoperable.
+*
+* Hibernation note: after a server connection is evicted its session resets, so a still-connected
+* client (whose session persists) will keep omitting `originClient`. The server must therefore restore
+* the connection→client binding from its own store (see `ActionServerHandler.rehydrateConnection`) and
+* inject `originClient` from there — the session alone can't recover it.
+*/
+function createBinaryWsSessionFactory(domains, options) {
+	const { routeToInt, intToRoute } = buildActionRouteDictionary(domains);
+	const unknownIdentity = RuntimeCoordinate.unknown.toJsonObject();
+	const ttlMs = options?.correlationTtlMs ?? DEFAULT_CORRELATION_TTL_MS;
+	return () => {
+		let outCounter = 0;
+		const corrToCuid = /* @__PURE__ */ new Map();
+		const cuidToCorr = /* @__PURE__ */ new Map();
+		let selfIdentity;
+		let peerIdentity;
+		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-ws] Cannot pack unregistered action route: ${routeKey}`);
+				const now = Date.now();
+				pruneExpired(corrToCuid, now, ttlMs);
+				pruneExpired(cuidToCorr, now, ttlMs);
+				let corr;
+				let wireIdentity;
+				if (json.type === "request") {
+					corr = outCounter++;
+					corrToCuid.set(corr, {
+						value: json.context.cuid,
+						time: now
+					});
+					if (selfIdentity == null && isKnownIdentity(json.context.originClient)) {
+						selfIdentity = json.context.originClient;
+						wireIdentity = json.context.originClient;
+					}
+				} else {
+					corr = cuidToCorr.get(json.context.cuid)?.value ?? -1;
+					if (json.type === "result") cuidToCorr.delete(json.context.cuid);
+				}
+				const envelope = new Array(ENVELOPE_LENGTH);
+				envelope[ENVELOPE.route] = routeInt;
+				envelope[ENVELOPE.type] = PayloadTypeToInt[json.type];
+				envelope[ENVELOPE.corr] = corr;
+				envelope[ENVELOPE.time] = json.time;
+				envelope[ENVELOPE.originClient] = wireIdentity;
+				envelope[ENVELOPE.payload] = extractWirePayload(json);
+				return (0, msgpackr.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 = (0, msgpackr.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 now = Date.now();
+					pruneExpired(corrToCuid, now, ttlMs);
+					pruneExpired(cuidToCorr, now, ttlMs);
+					const corr = envelope[ENVELOPE.corr];
+					const time = envelope[ENVELOPE.time];
+					const wireIdentity = envelope[ENVELOPE.originClient];
+					let cuid;
+					let originClient;
+					if (payloadType === "request") {
+						cuid = (0, nanoid.nanoid)();
+						cuidToCorr.set(cuid, {
+							value: corr,
+							time: now
+						});
+						if (isKnownIdentity(wireIdentity)) peerIdentity = wireIdentity;
+						originClient = peerIdentity ?? unknownIdentity;
+					} else {
+						cuid = corrToCuid.get(corr)?.value ?? (0, nanoid.nanoid)();
+						if (payloadType === "result") corrToCuid.delete(corr);
+						originClient = selfIdentity ?? unknownIdentity;
+					}
+					return assembleWireJson(routeMeta, payloadType, time, {
+						cuid,
+						timeCreated: time,
+						routing: [],
+						originClient
+					}, envelope[ENVELOPE.payload]);
+				} catch (e) {
+					console.error("[binary-ws] Failed to unpack binary action session frame", e);
+					return;
+				}
+			}
+		};
+	};
+}
+//#endregion
+//#region src/utils/decodeActionFrame.ts
+/**
+* Decode a single inbound channel frame (text or binary) into validated action wire JSON, or
+* `undefined` if it isn't a recognisable action payload.
+*
+* Shared by the WebSocket transport's message listener and the server-side `ActionServerHandler` so
+* both decode identically: a binary `decoder.incoming` (e.g. msgpackr) takes precedence, and plain
+* text frames fall back to JSON — keeping binary and JSON clients interoperable on one channel.
+*/
+function decodeActionFrame(frame, decoder) {
+	const decoded = decoder?.incoming?.(frame) ?? (typeof frame === "string" ? parseJsonActionFrame(frame) : void 0);
+	return decoded != null && isActionPayload_Any_JsonObject(decoded) ? decoded : void 0;
+}
+function parseJsonActionFrame(message) {
+	try {
+		const json = JSON.parse(message);
+		return isActionPayload_Any_JsonObject(json) ? json : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/helpers/createUnsetTransportResolvers.ts
+const createUnsetTransportResolvers = (type) => ({ onIncomingActionDataJson: (json) => {
+	console.warn(`Received incoming action JSON [${json.domain}:${json.id}] on Transport [${type}] but no incoming data listener has been set.`);
+} });
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/ws_util.ts
+/**
+* Send a text or binary frame over a socket. A binary formatter may hand back a `Uint8Array` whose
+* backing buffer is typed as `ArrayBufferLike` (msgpackr pools buffers / may be `SharedArrayBuffer`),
+* which `WebSocket.send`'s `BufferSource` parameter rejects — copy it into a fresh `ArrayBuffer`-backed
+* view so the type (and the bytes) are safe to send.
+*/
+function sendFrame(ws, data) {
+	if (typeof data === "string" || data instanceof ArrayBuffer) {
+		ws.send(data);
+		return;
+	}
+	ws.send(new Uint8Array(data));
+}
+/** Normalize any frame form to bytes (for the AES-GCM layer, which works on `Uint8Array`). */
+function toFrameBytes(frame) {
+	if (typeof frame === "string") return new TextEncoder().encode(frame);
+	if (frame instanceof ArrayBuffer) return new Uint8Array(frame);
+	return frame;
+}
+/** Compact a WebSocket URL to `host/pathname` for devtools display, falling back to the raw url. */
+function shortWs(url) {
+	try {
+		const u = new URL(url);
+		return `${u.host}${u.pathname}`;
+	} catch {
+		return url;
+	}
+}
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketConnection.ts
+const HANDSHAKE_TIMEOUT_MS = 15e3;
+var WebSocketConnection = class extends TransportConnection {
+	resolvers;
+	/** URL of the most recently resolved live socket — surfaced to devtools when the definition can't. */
+	_liveSocketUrl;
+	/** Sockets we closed on purpose (via `disconnect`), so their `close` event stays quiet. */
+	_intentionalCloses = /* @__PURE__ */ new WeakSet();
+	constructor(def, resolvers) {
+		super({
+			...def,
+			type: "ws"
+		});
+		this.resolvers = resolvers ?? createUnsetTransportResolvers("ws");
+	}
+	_getCacheKey(_input) {
+		return this.initialized.getTransportCacheKey?.(_input).join("\0") ?? "";
+	}
+	_processTransportStatus(input) {
+		const transportStatusInfo = addTransportStatusMetadata(this.initialized.getTransport(input));
+		if (transportStatusInfo.status !== "initializing" && transportStatusInfo.status !== "ready") return transportStatusInfo;
+		if (transportStatusInfo.status === "ready") {
+			const ws = transportStatusInfo.readyData.ws;
+			if (ws.readyState !== WebSocket.OPEN || this._isSecure(transportStatusInfo.readyData)) {
+				const readyData = transportStatusInfo.readyData;
+				const initialization = async () => {
+					await this._awaitOpen(ws);
+					return {
+						status: "ready",
+						readyData: await this._finalize(readyData)
+					};
+				};
+				return {
+					status: "initializing",
+					timeStarted: Date.now(),
+					initializationPromise: initialization()
+				};
+			}
+		}
+		if (transportStatusInfo.status === "initializing") return {
+			status: "initializing",
+			initializationPromise: transportStatusInfo.initializationPromise.then(async (result) => {
+				if (result.status === "ready") {
+					await this._awaitOpen(result.readyData.ws);
+					return {
+						status: "ready",
+						readyData: await this._finalize(result.readyData)
+					};
+				}
+				return result;
+			}),
+			timeStarted: transportStatusInfo.timeStarted
+		};
+		return {
+			status: "ready",
+			readyData: this._finalizeTransportMethods(transportStatusInfo.readyData)
+		};
+	}
+	getRouteInfo(input) {
+		const base = this.definition?.getRouteInfo(input);
+		if (base?.url != null || this._liveSocketUrl == null) return base;
+		return {
+			type: "ws",
+			...base,
+			url: this._liveSocketUrl,
+			summary: `ws ${shortWs(this._liveSocketUrl)}`
+		};
+	}
+	_isSecure(wsData) {
+		return wsData.secureChannel != null && wsData.secureChannel.securityLevel !== "none";
+	}
+	_awaitOpen(ws) {
+		if (ws.readyState === WebSocket.OPEN) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			ws.addEventListener("open", () => resolve(), { once: true });
+			ws.addEventListener("error", (event) => reject(event), { once: true });
+			ws.addEventListener("close", (event) => reject(/* @__PURE__ */ new Error(`WebSocket closed before open: code=${event.code}`)), { once: true });
+		});
+	}
+	/** Non-secure connections finalize synchronously; secure ones run the handshake first. */
+	_finalize(wsData) {
+		return this._isSecure(wsData) ? this._finalizeSecureMethods(wsData) : this._finalizeTransportMethods(wsData);
+	}
+	_finalizeTransportMethods(wsData) {
+		const ws = wsData.ws;
+		const disconnectListeners = [];
+		const abortSet = /* @__PURE__ */ new Set();
+		this._captureSocketUrl(ws);
+		this._attachLifecycle(ws, disconnectListeners, abortSet);
+		ws.addEventListener("message", async (event) => {
+			const frame = await this._normalizeFrame(event.data);
+			if (frame !== void 0) await this._handleIncomingActionFrame(frame, wsData, void 0);
+		});
+		return this._buildSendMethods(ws, wsData, void 0, disconnectListeners, abortSet);
+	}
+	/**
+	* Secure path: a single message listener feeds the handshake until it completes, then routes action
+	* frames (decrypting for the `encrypted` level). Frames that arrive in the gap between accept and
+	* activation are buffered and flushed, so nothing is lost.
+	*/
+	async _finalizeSecureMethods(wsData) {
+		const ws = wsData.ws;
+		const disconnectListeners = [];
+		const abortSet = /* @__PURE__ */ new Set();
+		this._captureSocketUrl(ws);
+		this._attachLifecycle(ws, disconnectListeners, abortSet);
+		let active = false;
+		let crypto;
+		const handshakeQueue = [];
+		const handshakeWaiters = [];
+		const pendingActionFrames = [];
+		ws.addEventListener("message", async (event) => {
+			const frame = await this._normalizeFrame(event.data);
+			if (frame === void 0) return;
+			if (active) {
+				await this._handleIncomingActionFrame(frame, wsData, crypto);
+				return;
+			}
+			if (typeof frame === "string") {
+				const message = decodeHandshakeMessage(frame);
+				if (message != null) {
+					const waiter = handshakeWaiters.shift();
+					if (waiter != null) waiter(message);
+					else handshakeQueue.push(message);
+					return;
+				}
+			}
+			pendingActionFrames.push(frame);
+		});
+		const nextHandshakeMessage = () => {
+			const queued = handshakeQueue.shift();
+			if (queued != null) return Promise.resolve(queued);
+			return new Promise((resolve, reject) => {
+				const timeout = setTimeout(() => reject(/* @__PURE__ */ new Error("[ws-handshake] timed out waiting for server reply")), HANDSHAKE_TIMEOUT_MS);
+				handshakeWaiters.push((message) => {
+					clearTimeout(timeout);
+					resolve(message);
+				});
+			});
+		};
+		crypto = await this._runClientHandshake(ws, wsData.secureChannel, nextHandshakeMessage);
+		active = true;
+		for (const frame of pendingActionFrames) await this._handleIncomingActionFrame(frame, wsData, crypto);
+		pendingActionFrames.length = 0;
+		return this._buildSendMethods(ws, wsData, crypto, disconnectListeners, abortSet);
+	}
+	async _runClientHandshake(ws, secure, nextHandshakeMessage) {
+		await secure.link.initialize();
+		const handshake = createClientHandshake({
+			link: secure.link,
+			localCoordinate: secure.localCoordinate,
+			dictionaryVersion: secure.dictionaryVersion,
+			securityLevel: secure.securityLevel
+		});
+		sendFrame(ws, encodeHandshakeMessage(await handshake.createHello()));
+		const welcome = await nextHandshakeMessage();
+		if (welcome.t === "reject") throw new Error(`[ws-handshake] rejected by server: ${welcome.reason}`);
+		if (welcome.t !== "welcome") throw new Error(`[ws-handshake] expected welcome, got ${welcome.t}`);
+		sendFrame(ws, encodeHandshakeMessage(await handshake.onWelcome(welcome)));
+		const accept = await nextHandshakeMessage();
+		if (accept.t === "reject") throw new Error(`[ws-handshake] rejected by server: ${accept.reason}`);
+		if (accept.t !== "accept") throw new Error(`[ws-handshake] expected accept, got ${accept.t}`);
+		const result = await handshake.onAccept(accept);
+		return result.securityLevel === "encrypted" ? createActionFrameCrypto({
+			link: secure.link,
+			linkedClientId: result.linkedClientId
+		}) : void 0;
+	}
+	_buildSendMethods(ws, wsData, crypto, disconnectListeners, abortSet) {
+		let sendChain = Promise.resolve();
+		const enqueueSend = (frame) => {
+			if (ws.readyState !== WebSocket.OPEN) return;
+			if (crypto == null) {
+				sendFrame(ws, frame);
+				return;
+			}
+			const bytes = toFrameBytes(frame);
+			sendChain = sendChain.then(() => crypto.encryptFrame(bytes)).then((encrypted) => {
+				if (ws.readyState === WebSocket.OPEN) sendFrame(ws, encrypted);
+			}).catch((err) => console.error("[ws] failed to encrypt/send frame", err));
+		};
+		const sendActionData = (inputs) => {
+			const { action, runningAction, timeout } = inputs;
+			if (ws.readyState !== WebSocket.OPEN) {
+				if (action.type === "request") runningAction._abort(err_nice_transport_ws.fromId("ws_disconnected"));
+				return;
+			}
+			if (action.type === "request") {
+				abortSet.add(runningAction);
+				const timeoutId = setTimeout(() => {
+					runningAction._abort(err_nice_transport.fromId("timeout", { timeout }));
+				}, timeout);
+				runningAction.addUpdateListeners([(update) => {
+					if (update.type === "finished") {
+						clearTimeout(timeoutId);
+						abortSet.delete(runningAction);
+					}
+				}]);
+			}
+			enqueueSend(wsData.formatMessage?.outgoing(inputs) ?? JSON.stringify(inputs.action.toJsonObject()));
+		};
+		return {
+			sendActionData,
+			updateRunConfig: wsData.updateRunConfig,
+			addOnDisconnectListener: (cb) => {
+				disconnectListeners.push(cb);
+			},
+			disconnect: () => {
+				this._intentionalCloses.add(ws);
+				try {
+					ws.close();
+				} catch {}
+			},
+			sendReturnData: (payload, clients) => {
+				enqueueSend((clients != null ? wsData.formatMessage?.outgoing({
+					action: payload,
+					...clients
+				}) : void 0) ?? JSON.stringify(payload.toJsonObject()));
+			}
+		};
+	}
+	/** Decode (and, when encrypted, decrypt) one inbound action frame and hand it to the runtime. */
+	async _handleIncomingActionFrame(frame, wsData, crypto) {
+		let decoded = frame;
+		if (crypto != null) try {
+			decoded = await crypto.decryptFrame(frame);
+		} catch (err) {
+			console.error("[ws] failed to decrypt incoming frame", err);
+			return;
+		}
+		const rawJson = decodeActionFrame(decoded, wsData.formatMessage);
+		if (rawJson != null) this.resolvers.onIncomingActionDataJson(rawJson);
+	}
+	/** Accept text + binary frames (ArrayBuffer / Uint8Array / Blob); Blobs are converted to a buffer. */
+	async _normalizeFrame(data) {
+		if (typeof data === "string" || data instanceof ArrayBuffer || data instanceof Uint8Array) return data;
+		if (typeof Blob !== "undefined" && data instanceof Blob) return await data.arrayBuffer();
+	}
+	_captureSocketUrl(ws) {
+		if (ws.url != null && ws.url !== "") this._liveSocketUrl = ws.url;
+	}
+	_attachLifecycle(ws, disconnectListeners, abortSet) {
+		ws.addEventListener("close", (event) => {
+			if (!this._intentionalCloses.has(ws)) console.error("WebSocket closed:", event);
+			for (const cb of disconnectListeners) cb();
+			this._abortAll(abortSet, err_nice_transport_ws.fromId("ws_disconnected"));
+		});
+		ws.addEventListener("error", (event) => {
+			console.error("WebSocket error:", event);
+			for (const cb of disconnectListeners) cb();
+			this._abortAll(abortSet, err_nice_transport_ws.fromId("ws_error", { originalError: event instanceof Error ? event : void 0 }));
+		});
+	}
+	_abortAll(abortSet, error) {
+		const snapshot = [...abortSet];
+		for (const ra of snapshot) ra._abort(error);
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport.ts
+/**
+* Reusable WebSocket transport definition. Create one with `WebSocketTransport.create({ createWebSocket })`
+* for the common case, or `WebSocketTransport.createAdvanced({ getTransport })` for full control over
+* readiness. The underlying socket is cached (via `getTransportCacheKey`) and reused across actions.
+*/
+var WebSocketTransport = class WebSocketTransport extends Transport {
+	options;
+	type = "ws";
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	static create(options) {
+		return new WebSocketTransport({
+			...options,
+			mode: "socket"
+		});
+	}
+	static createAdvanced(options) {
+		return new WebSocketTransport({
+			...options,
+			mode: "advanced"
+		});
+	}
+	_createConnection(ctx) {
+		const options = this.options;
+		let getTransport;
+		if (options.mode === "advanced") getTransport = options.getTransport;
+		else getTransport = (input) => ({
+			status: "ready",
+			readyData: {
+				ws: options.createWebSocket(input),
+				formatMessage: options.createFormatMessage?.() ?? options.formatMessage,
+				updateRunConfig: options.updateRunConfig,
+				secureChannel: options.security
+			}
+		});
+		return new WebSocketConnection({ initialize: () => ({
+			getTransportCacheKey: options.getTransportCacheKey,
+			getTransport
+		}) }, ctx.resolvers);
+	}
+	getRouteInfo(input) {
+		if (this.options.getRouteInfo != null) return this.options.getRouteInfo(input);
+		return {
+			type: "ws",
+			summary: "ws"
+		};
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel.ts
+/**
+* Derive a stable wire-dictionary version from the ordered route list (FNV-1a over `domain:id,…`), so
+* the version moves automatically whenever the transported domains change — a stale peer is then
+* rejected by the handshake instead of silently misrouting a positionally-packed frame.
+*/
+function deriveDictionaryVersion(domains) {
+	const { intToRoute } = buildActionRouteDictionary(domains);
+	const signature = intToRoute.map((route) => `${route.domain}:${route.id}`).join(",");
+	let hash = 2166136261;
+	for (let i = 0; i < signature.length; i++) {
+		hash ^= signature.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return `auto:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+/**
+* Bundle a secure channel's shared identity from its transported domains. Both ends MUST call this
+* with the same domains in the same order (the binary wire dictionary is positional). The
+* `dictionaryVersion` is derived from those domains unless you pin an explicit one.
+*/
+function defineSecureWsChannel(options) {
+	return {
+		dictionaryVersion: options.dictionaryVersion ?? deriveDictionaryVersion(options.domains),
+		createCodec: createBinaryWsSessionFactory(options.domains, options.sessionOptions)
+	};
+}
+/**
+* Build a {@link WebSocketTransport} for the secure binary channel with the boilerplate folded in: it
+* creates the {@link ClientCryptoKeyLink} from `storageAdapter`, opens an `arraybuffer` socket to
+* `url`, caches it per endpoint, installs the channel's per-connection codec, and assembles the
+* `security` block from the runtime coordinate + channel version. Pass `createWebSocket` /
+* `getTransportCacheKey` to take over those bits when you need to.
+*/
+function createSecureWebSocketTransport(options) {
+	const link = new _nice_code_util.ClientCryptoKeyLink({ storageAdapter: options.storageAdapter });
+	return WebSocketTransport.create({
+		createWebSocket: options.createWebSocket ?? (() => {
+			const ws = new WebSocket(options.url);
+			ws.binaryType = "arraybuffer";
+			return ws;
+		}),
+		getTransportCacheKey: options.getTransportCacheKey ?? (() => [options.url]),
+		createFormatMessage: options.channel.createCodec,
+		updateRunConfig: options.updateRunConfig,
+		getRouteInfo: options.getRouteInfo,
+		security: {
+			securityLevel: options.securityLevel,
+			link,
+			localCoordinate: options.runtime.coordinate.toJsonObject(),
+			dictionaryVersion: options.channel.dictionaryVersion
+		}
+	});
+}
+//#endregion
+//#region src/ActionRuntime/Handler/Server/WsConnectionStateStore.ts
+/**
+* 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);
+* ```
+*/
+var WsConnectionStateStore = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** The validated app state for a connection, or `null` if unset / invalid. */
+	get(connection) {
+		return this._readAttachment(connection).app ?? null;
+	}
+	/** Set the app state, preserving the runtime binding already pinned to the connection. */
+	set(connection, app) {
+		const existing = this._readAttachment(connection);
+		this.options.write(connection, {
+			app,
+			binding: existing.binding
+		});
+	}
+	/** Clear the app state but keep the binding (e.g. a spectator that stopped watching). */
+	clearApp(connection) {
+		const existing = this._readAttachment(connection);
+		this.options.write(connection, { binding: existing.binding });
+	}
+	/** Every live connection paired with its (validated) app state — for rebuilding in-memory state after a wake. */
+	entries() {
+		return this.options.getConnections().map((connection) => [connection, this._readAttachment(connection).app ?? null]);
+	}
+	/** @internal Persist a freshly-bound connection's binding, preserving any app state already stored. */
+	_persistBinding(connection, binding) {
+		const existing = this._readAttachment(connection);
+		this.options.write(connection, {
+			app: existing.app,
+			binding
+		});
+	}
+	/** @internal The persisted binding for a connection, if any (used to replay routing after a wake). */
+	_readBinding(connection) {
+		return this._readAttachment(connection).binding;
+	}
+	_readAttachment(connection) {
+		try {
+			const raw = this.options.read(connection);
+			if (typeof raw !== "object" || raw === null) return {};
+			const attachment = raw;
+			const result = {};
+			if (attachment.binding != null) result.binding = attachment.binding;
+			if (attachment.app !== void 0) {
+				const app = this._validateApp(attachment.app);
+				if (app !== void 0) result.app = app;
+			}
+			return result;
+		} catch {
+			return {};
+		}
+	}
+	_validateApp(value) {
+		const schema = this.options.schema;
+		if (schema == null) return value;
+		const result = schema["~standard"].validate(value);
+		if (result instanceof Promise) return void 0;
+		if (result.issues != null) return void 0;
+		return result.value;
+	}
+};
+//#endregion
+//#region src/ActionRuntime/Handler/Server/ActionServerHandler.ts
+/**
+* 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.
+*/
+var ActionServerHandler = class extends ActionExternalClientHandler {
+	_formatMessage;
+	_createFormatMessage;
+	_send;
+	_runtime;
+	_serverTimeout;
+	_onConnectionBound;
+	/** Incoming-data listeners installed by the runtime (`resolveIncomingActionPayload`). */
+	_incomingListeners = [];
+	_security;
+	/** Normalized accepted levels; whether `none` (plain) is allowed; whether any level needs a handshake. */
+	_allowedLevels;
+	_noneAllowed;
+	_handshakeMode;
+	_connByClient = /* @__PURE__ */ new Map();
+	_clientByConn = /* @__PURE__ */ new Map();
+	_connEncoding = /* @__PURE__ */ new Map();
+	_codecByConn = /* @__PURE__ */ new Map();
+	_handshakeByConn = /* @__PURE__ */ new Map();
+	_cryptoByConn = /* @__PURE__ */ new Map();
+	_authedConns = /* @__PURE__ */ new Set();
+	_plainConns = /* @__PURE__ */ new Set();
+	_inboundChainByConn = /* @__PURE__ */ new Map();
+	_outboundChainByConn = /* @__PURE__ */ new Map();
+	constructor(options) {
+		super({
+			runtimeCoordinate: options.clientEnv,
+			transports: []
+		});
+		this._formatMessage = options.formatMessage;
+		this._createFormatMessage = options.createFormatMessage;
+		this._send = options.send;
+		this._runtime = options.runtime;
+		this._serverTimeout = options.defaultTimeout ?? 1e4;
+		this._onConnectionBound = options.onConnectionBound;
+		this._security = options.security;
+		this._allowedLevels = options.security == null ? [] : Array.isArray(options.security.securityLevel) ? options.security.securityLevel : [options.security.securityLevel];
+		this._noneAllowed = this._allowedLevels.includes("none");
+		this._handshakeMode = this._allowedLevels.some((level) => level !== "none");
+	}
+	/**
+	* The codec for a connection: a per-connection session (cached) when a factory was provided, else
+	* the single shared `formatMessage`.
+	*/
+	_codecFor(connection) {
+		if (this._createFormatMessage != null) {
+			let codec = this._codecByConn.get(connection);
+			if (codec == null) {
+				codec = this._createFormatMessage();
+				this._codecByConn.set(connection, codec);
+			}
+			return codec;
+		}
+		if (this._formatMessage != null) return this._formatMessage;
+		throw err_nice_transport.fromId("not_found", { actionId: "server-handler-codec (provide formatMessage or createFormatMessage)" });
+	}
+	_setIncomingActionDataListener(listener) {
+		this._incomingListeners.push(listener);
+	}
+	/**
+	* 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) {
+		this._onConnectionBound = onConnectionBound;
+	}
+	/**
+	* 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(options) {
+		const store = new WsConnectionStateStore(options);
+		this.setOnConnectionBound((connection, binding) => store._persistBinding(connection, binding));
+		for (const connection of options.getConnections()) {
+			const binding = store._readBinding(connection);
+			if (binding != null) this.rehydrateConnection(connection, binding);
+		}
+		return store;
+	}
+	/**
+	* 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, frame) {
+		if (this._security == null || !this._handshakeMode) {
+			this._receivePlain(connection, frame);
+			return;
+		}
+		const next = (this._inboundChainByConn.get(connection) ?? Promise.resolve()).then(() => this._receiveSecure(connection, frame)).catch((err) => console.error("[ws-server] failed to process inbound frame", err));
+		this._inboundChainByConn.set(connection, next);
+	}
+	_receivePlain(connection, frame) {
+		const wire = decodeActionFrame(frame, this._codecFor(connection));
+		if (wire == null) return;
+		const encoding = typeof frame === "string" ? "json" : "binary";
+		this._connEncoding.set(connection, encoding);
+		if (wire.type === "request") this._resolveRequestIdentity(connection, wire, encoding);
+		for (const listener of this._incomingListeners) listener(wire);
+	}
+	async _receiveSecure(connection, frame) {
+		const security = this._security;
+		if (security == null) return;
+		if (this._plainConns.has(connection)) {
+			this._receivePlain(connection, frame);
+			return;
+		}
+		if (!this._authedConns.has(connection)) {
+			const message = typeof frame === "string" ? decodeHandshakeMessage(frame) : void 0;
+			if (message == null) {
+				if (this._noneAllowed) {
+					this._plainConns.add(connection);
+					this._receivePlain(connection, frame);
+				}
+				return;
+			}
+			await security.link.initialize();
+			let handshake = this._handshakeByConn.get(connection);
+			if (handshake == null) {
+				handshake = createServerHandshake({
+					link: security.link,
+					localCoordinate: security.localCoordinate,
+					dictionaryVersion: security.dictionaryVersion,
+					securityLevel: security.securityLevel,
+					verifyKeyResolver: security.verifyKeyResolver
+				});
+				this._handshakeByConn.set(connection, handshake);
+			}
+			if (message.t === "hello") this._send(connection, encodeHandshakeMessage(await handshake.onHello(message)));
+			else if (message.t === "prove") {
+				const reply = await handshake.onProve(message);
+				this._send(connection, encodeHandshakeMessage(reply));
+				const result = handshake.getResult();
+				if (reply.t === "accept" && result != null) this._completeServerHandshake(connection, result);
+			}
+			return;
+		}
+		let bytes = frame;
+		const cryptoReady = this._cryptoByConn.get(connection);
+		if (cryptoReady != null) try {
+			bytes = await (await cryptoReady).decryptFrame(frame);
+		} catch (err) {
+			console.error("[ws-server] failed to decrypt inbound frame", err);
+			return;
+		}
+		const wire = decodeActionFrame(bytes, this._codecFor(connection));
+		if (wire == null) return;
+		if (wire.type === "request") {
+			const bound = this._clientByConn.get(connection);
+			if (bound != null) wire.context.originClient = bound.toJsonObject();
+		}
+		for (const listener of this._incomingListeners) listener(wire);
+	}
+	_completeServerHandshake(connection, result) {
+		const clientCoord = new RuntimeCoordinate(result.remote);
+		this._bindConnection(connection, clientCoord);
+		this._connEncoding.set(connection, "binary");
+		this._authedConns.add(connection);
+		this._handshakeByConn.delete(connection);
+		if (result.securityLevel === "encrypted" && this._security != null) this._cryptoByConn.set(connection, Promise.resolve(createActionFrameCrypto({
+			link: this._security.link,
+			linkedClientId: result.linkedClientId
+		})));
+		this._onConnectionBound?.(connection, {
+			client: clientCoord.toJsonObject(),
+			encoding: "binary",
+			secure: {
+				securityLevel: result.securityLevel,
+				linkedClientId: result.linkedClientId,
+				keyMaterial: result.encryptionKeyMaterial
+			}
+		});
+	}
+	/**
+	* 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.)
+	*/
+	_resolveRequestIdentity(connection, wire, encoding) {
+		const wireOrigin = wire.context.originClient;
+		if (wireOrigin != null && wireOrigin.envId !== "_unset_") {
+			const clientCoord = new RuntimeCoordinate(wireOrigin);
+			const isNewBinding = this._clientByConn.get(connection)?.stringId !== clientCoord.stringId;
+			this._bindConnection(connection, clientCoord);
+			if (isNewBinding) this._onConnectionBound?.(connection, {
+				client: clientCoord.toJsonObject(),
+				encoding
+			});
+			return;
+		}
+		const bound = this._clientByConn.get(connection);
+		if (bound != null) wire.context.originClient = bound.toJsonObject();
+	}
+	/**
+	* 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, binding) {
+		this._bindConnection(connection, new RuntimeCoordinate(binding.client));
+		this._connEncoding.set(connection, binding.encoding);
+		const secure = binding.secure;
+		if (secure == null) return;
+		this._authedConns.add(connection);
+		if (secure.securityLevel === "encrypted" && secure.keyMaterial != null && this._security != null) {
+			const security = this._security;
+			const { linkedClientId, keyMaterial } = secure;
+			const cryptoReady = security.link.initialize().then(() => security.link.linkClient({
+				linkedClientId,
+				verifyPublicKey: keyMaterial.verifyPublicKey,
+				exchangePublicKey: keyMaterial.exchangePublicKey,
+				saltString: keyMaterial.saltString,
+				infoString: keyMaterial.infoString,
+				bindVerifyKeysIntoDerivation: keyMaterial.bindVerifyKeysIntoDerivation
+			})).then(() => createActionFrameCrypto({
+				link: security.link,
+				linkedClientId
+			}));
+			this._cryptoByConn.set(connection, cryptoReady);
+			const gate = cryptoReady.then(() => {}, (err) => console.error("[ws-server] failed to restore encrypted session", err));
+			this._inboundChainByConn.set(connection, gate);
+			this._outboundChainByConn.set(connection, gate);
+		}
+	}
+	toHandlerRouteItem() {
+		return {
+			type: this.handlerType,
+			client: this.externalClient,
+			transType: "custom",
+			transOrd: 0
+		};
+	}
+	/** Forget a connection (call on socket close) so stale entries don't misroute later results. */
+	dropConnection(connection) {
+		const coord = this._clientByConn.get(connection);
+		if (coord != null && this._connByClient.get(coord.stringId) === connection) this._connByClient.delete(coord.stringId);
+		this._clientByConn.delete(connection);
+		this._connEncoding.delete(connection);
+		this._codecByConn.delete(connection);
+		this._handshakeByConn.delete(connection);
+		this._cryptoByConn.delete(connection);
+		this._authedConns.delete(connection);
+		this._plainConns.delete(connection);
+		this._inboundChainByConn.delete(connection);
+		this._outboundChainByConn.delete(connection);
+	}
+	/** Live connection for a client coordinate, if currently registered. */
+	getConnectionForClient(client) {
+		return this._connByClient.get(client.stringId);
+	}
+	/**
+	* 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(runtime, target, request, options) {
+		const connection = this._resolveConnection(target);
+		return this._dispatch(runtime, connection, request, options?.timeout);
+	}
+	/**
+	* 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(domain, cases) {
+		const handler = new ActionLocalHandler();
+		const executor = cases;
+		const wrapped = {};
+		const wrappedRecord = wrapped;
+		for (const id in cases) {
+			const caseFn = executor[id];
+			if (caseFn == null) continue;
+			wrappedRecord[id] = (request) => caseFn(request, this.getConnectionForClient(request.context.originClient));
+		}
+		return handler.forDomainActionCases(domain, wrapped);
+	}
+	/**
+	* 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(makeRequest, options) {
+		const runtime = options?.runtime ?? this._runtime;
+		if (runtime == null) throw err_nice_transport.fromId("not_found", { actionId: "server-handler-runtime (construct with `runtime` or pass `options.runtime`)" });
+		for (const connection of this._clientByConn.keys()) {
+			if (options?.except != null && connection === options.except) continue;
+			if (options?.where != null && !options.where(connection)) continue;
+			try {
+				this.pushToClient(runtime, connection, makeRequest(), { timeout: options?.timeout });
+			} catch (error) {
+				if (options?.onError != null) options.onError(error, connection);
+				else console.error("[ws-server] broadcast push failed", error);
+			}
+		}
+	}
+	async sendReturnPayload(payload, config) {
+		const connection = this._connByClient.get(payload.context.originClient.stringId);
+		if (connection == null) return false;
+		this._sendPayload(connection, payload, config.targetLocalRuntime.coordinate);
+		return true;
+	}
+	async handleActionRequest(action, config) {
+		const runtime = config?.targetLocalRuntime ?? ActionRuntime.getDefault();
+		const connection = this._resolveSingleConnection();
+		return this._dispatch(runtime, connection, action, config?.timeout);
+	}
+	_dispatch(runtime, connection, action, timeout) {
+		const timeoutMs = timeout ?? this._serverTimeout;
+		action.context._setOriginClient(runtime.coordinate);
+		action.context.addRouteItem({
+			runtime: runtime.coordinate,
+			handler: this.toHandlerRouteItem(),
+			time: Date.now()
+		});
+		const runningAction = new RunningAction({
+			context: action.context,
+			request: action,
+			parentCuid: peekHandlerCuid(),
+			callSite: action._callSite
+		});
+		runtime.registerRunningAction(runningAction);
+		const timeoutId = setTimeout(() => {
+			runningAction._abort(err_nice_transport.fromId("timeout", { timeout: timeoutMs }));
+		}, timeoutMs);
+		runningAction.addUpdateListeners([(update) => {
+			if (update.type === "finished") clearTimeout(timeoutId);
+		}]);
+		try {
+			this._sendPayload(connection, action, runtime.coordinate);
+		} catch (err) {
+			runningAction._abort(err);
+		}
+		return runningAction;
+	}
+	_sendPayload(connection, payload, localClient) {
+		const frame = (this._connEncoding.get(connection) ?? "binary") === "json" ? JSON.stringify(payload.toJsonObject()) : this._codecFor(connection).outgoing({
+			action: payload,
+			localClient,
+			externalClient: this.externalClient
+		});
+		const cryptoReady = this._cryptoByConn.get(connection);
+		if (cryptoReady == null) {
+			this._send(connection, frame);
+			return;
+		}
+		const bytes = toFrameBytes(frame);
+		const next = (this._outboundChainByConn.get(connection) ?? Promise.resolve()).then(() => cryptoReady).then((crypto) => crypto.encryptFrame(bytes)).then((encrypted) => this._send(connection, encrypted)).catch((err) => console.error("[ws-server] failed to encrypt/send frame", err));
+		this._outboundChainByConn.set(connection, next);
+	}
+	_bindConnection(connection, client) {
+		this._connByClient.set(client.stringId, connection);
+		this._clientByConn.set(connection, client);
+	}
+	_resolveConnection(target) {
+		if (target instanceof RuntimeCoordinate) {
+			const connection = this._connByClient.get(target.stringId);
+			if (connection == null) throw err_nice_transport.fromId("not_found", { actionId: target.stringId });
+			return connection;
+		}
+		return target;
+	}
+	_resolveSingleConnection() {
+		if (this._clientByConn.size !== 1) throw err_nice_transport.fromId("not_found", { actionId: "server-handler-target (use pushToClient with an explicit connection or client coordinate)" });
+		return this._clientByConn.keys().next().value;
+	}
+};
+const createServerHandler = (options) => {
+	return new ActionServerHandler(options);
+};
+//#endregion
+//#region src/ActionRuntime/Handler/Server/createActionFetchHandler.ts
+/** Permissive defaults — fine for a public action endpoint; override (or disable) via `cors`. */
+const DEFAULT_CORS_HEADERS = {
+	"Access-Control-Allow-Origin": "*",
+	"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+	"Access-Control-Allow-Headers": "Content-Type",
+	"Access-Control-Max-Age": "86400"
+};
+/**
+* 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); }
+* ```
+*/
+function createActionFetchHandler(runtime, options = {}) {
+	const corsHeaders = options.cors === false ? {} : options.cors ?? DEFAULT_CORS_HEADERS;
+	const isActionPath = options.isActionPath ?? ((url) => url.pathname.endsWith("/action"));
+	const isWebSocketPath = options.isWebSocketPath ?? ((url) => url.pathname.endsWith("/ws"));
+	const withCors = (response) => {
+		if (options.cors === false) return response;
+		const headers = new Headers(response.headers);
+		for (const [key, value] of Object.entries(corsHeaders)) headers.set(key, value);
+		return new Response(response.body, {
+			status: response.status,
+			headers
+		});
+	};
+	return async (request) => {
+		if (request.method === "OPTIONS") return withCors(new Response(null, { status: 204 }));
+		const url = new URL(request.url);
+		if (options.onWebSocketUpgrade != null && request.headers.get("Upgrade") === "websocket" && isWebSocketPath(url)) return options.onWebSocketUpgrade(request, url);
+		if (request.method === "POST" && isActionPath(url)) return withCors((await (await runtime.handleActionPayloadWire(await request.json())).waitForResultPayload()).toHttpResponse({ useErrorStatus: options.useErrorStatus }));
+		return withCors(new Response("Not found", { status: 404 }));
+	};
+}
+//#endregion
+//#region src/ActionRuntime/Handler/Server/createSecureActionServer.ts
+/** Default accepted set: negotiate per connection to whatever the client picks. */
+const DEFAULT_SERVER_SECURITY_LEVELS = [
+	"none",
+	"authenticated",
+	"encrypted"
+];
+/**
+* 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.
+*/
+function createSecureActionServerHandler(options) {
+	const link = new _nice_code_util.ClientCryptoKeyLink({ storageAdapter: options.storageAdapter });
+	return new ActionServerHandler({
+		clientEnv: options.clientEnv,
+		createFormatMessage: options.channel.createCodec,
+		send: options.send,
+		runtime: options.runtime,
+		defaultTimeout: options.defaultTimeout,
+		security: {
+			securityLevel: options.securityLevel ?? DEFAULT_SERVER_SECURITY_LEVELS,
+			link,
+			localCoordinate: options.runtime.coordinate.toJsonObject(),
+			dictionaryVersion: options.channel.dictionaryVersion,
+			verifyKeyResolver: options.verifyKeyResolver ?? createStorageTofuVerifyKeyResolver(options.storageAdapter)
+		}
+	});
+}
+/**
+* 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);
+* ```
+*/
+function createHibernatableWsServerAdapter(options) {
+	const { handler, getWebSockets, getAttachment, setAttachment } = options;
+	handler.setOnConnectionBound(setAttachment);
+	for (const connection of getWebSockets()) {
+		const binding = getAttachment(connection);
+		if (binding != null) handler.rehydrateConnection(connection, binding);
+	}
+	return {
+		receive: (connection, frame) => handler.receive(connection, frame),
+		drop: (connection) => handler.dropConnection(connection)
+	};
+}
+//#endregion
+exports.ActionCore = ActionCore;
+exports.ActionDomain = ActionDomain;
+exports.ActionExternalClientHandler = ActionExternalClientHandler;
+exports.ActionLocalHandler = ActionLocalHandler;
+exports.ActionRootDomain = ActionRootDomain;
+exports.ActionRuntime = ActionRuntime;
+exports.ActionSchema = ActionSchema;
+exports.ActionServerHandler = ActionServerHandler;
+exports.CustomTransport = CustomTransport;
+exports.EActionPayloadType = EActionPayloadType;
+exports.EActionProgressType = EActionProgressType;
+exports.EErrId_NiceAction = EErrId_NiceAction;
+exports.EErrId_NiceTransport = EErrId_NiceTransport;
+exports.EErrId_NiceTransport_WebSocket = EErrId_NiceTransport_WebSocket;
+exports.EHandshakeMessageType = EHandshakeMessageType;
+exports.ERunningActionFinishedType = require_RunningAction_types.ERunningActionFinishedType;
+exports.ERunningActionState = require_RunningAction_types.ERunningActionState;
+exports.ERunningActionUpdateType = require_RunningAction_types.ERunningActionUpdateType;
+exports.ESecurityLevel = ESecurityLevel;
+exports.ETransportStatus = ETransportStatus;
+exports.ETransportType = ETransportType;
+exports.HttpTransport = HttpTransport;
+exports.RunningAction = RunningAction;
+exports.RuntimeCoordinate = RuntimeCoordinate;
+exports.Transport = Transport;
+exports.WebSocketTransport = WebSocketTransport;
+exports.WsConnectionStateStore = WsConnectionStateStore;
+exports.actionSchema = actionSchema;
+exports.createActionFetchHandler = createActionFetchHandler;
+exports.createActionFrameCrypto = createActionFrameCrypto;
+exports.createActionRootDomain = createActionRootDomain;
+exports.createBinaryWsAdapter = createBinaryWsAdapter;
+exports.createBinaryWsSessionFactory = createBinaryWsSessionFactory;
+exports.createClientHandshake = createClientHandshake;
+exports.createExternalClientHandler = createExternalClientHandler;
+exports.createHibernatableWsServerAdapter = createHibernatableWsServerAdapter;
+exports.createInMemoryTofuVerifyKeyResolver = createInMemoryTofuVerifyKeyResolver;
+exports.createLocalHandler = createLocalHandler;
+exports.createSecureActionServerHandler = createSecureActionServerHandler;
+exports.createSecureWebSocketTransport = createSecureWebSocketTransport;
+exports.createServerHandler = createServerHandler;
+exports.createServerHandshake = createServerHandshake;
+exports.createStorageTofuVerifyKeyResolver = createStorageTofuVerifyKeyResolver;
+exports.decodeActionFrame = decodeActionFrame;
+exports.decodeHandshakeMessage = decodeHandshakeMessage;
+exports.defineSecureWsChannel = defineSecureWsChannel;
+exports.encodeHandshakeMessage = encodeHandshakeMessage;
+exports.err_nice_action = err_nice_action;
+exports.err_nice_external_client = err_nice_external_client;
+exports.err_nice_transport = err_nice_transport;
+exports.err_nice_transport_ws = err_nice_transport_ws;
+exports.isActionPayload_Any_JsonObject = isActionPayload_Any_JsonObject;
+exports.isActionPayload_Request_JsonObject = isActionPayload_Request_JsonObject;
+exports.isActionPayload_Result_JsonObject = isActionPayload_Result_JsonObject;
+exports.runtimeLinkId = runtimeLinkId;
+
+//# sourceMappingURL=index.cjs.map