@agent-vm/gateway-control-contracts 0.0.112 → 0.0.114

package/dist/index.js

@@ -1,7 +1,788 @@
-import { ControlCorrelationSchema, ControlRpcErrorSchema, ControlRpcResultBaseSchema, ControlSessionStateSchema, KnownControlDomainSchema } from "@agent-vm/control-protocol-contracts";
+import { CONTROL_PROTOCOL_VERSION, ControlCorrelationSchema, ControlRpcErrorSchema, ControlRpcResultBaseSchema, ControlSessionStateSchema, KnownControlDomainSchema } from "@agent-vm/control-protocol-contracts";
 import { z } from "zod/v4";
+//#region src/gateway-control-admission.ts
+const GATEWAY_CONTROL_ADMISSION_LIMITS = {
+	authority: {
+		maxBytes: 1572864,
+		maxMessages: 96
+	},
+	diagnostic: {
+		maxBytes: 1048576,
+		maxMessages: 64
+	},
+	liveness: {
+		maxBytes: 1048576,
+		maxMessages: 64
+	},
+	maxFrameBytes: 65536,
+	perPrincipalAuthority: {
+		maxBytes: 131072,
+		maxMessages: 8
+	},
+	safety: {
+		maxBytes: 524288,
+		maxMessages: 32
+	}
+};
+const GATEWAY_CONTROL_PROCESS_ADMISSION_LIMITS = {
+	maxActiveSessions: 32,
+	maxNonSafetyBytes: 33554432,
+	maxNonSafetyMessages: 2048
+};
+function dequeueFirstCoalescedMessage(messages) {
+	const first = messages.entries().next().value;
+	if (first === void 0) return;
+	messages.delete(first[0]);
+	return first[1];
+}
+const serviceCycle = [
+	"safety",
+	"safety",
+	"safety",
+	"safety",
+	"safety",
+	"safety",
+	"safety",
+	"safety",
+	"authority",
+	"authority",
+	"authority",
+	"authority",
+	"liveness",
+	"liveness",
+	"diagnostic"
+];
+function canReserve(accounting, byteLength, limits) {
+	return accounting.byteCount + byteLength <= limits.maxBytes && accounting.messageCount + 1 <= limits.maxMessages;
+}
+function release(accounting, byteLength) {
+	accounting.byteCount -= byteLength;
+	accounting.messageCount -= 1;
+}
+function requirePositiveLimit(name, value) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer.`);
+}
+function validateMessage(message) {
+	if (message.id.length === 0 || !Number.isSafeInteger(message.byteLength) || message.byteLength <= 0) return {
+		reason: "invalid_message",
+		status: "fence"
+	};
+	if (message.byteLength > GATEWAY_CONTROL_ADMISSION_LIMITS.maxFrameBytes) return {
+		reason: "frame_too_large",
+		status: "fence"
+	};
+	if (message.messageClass === "authority" && (message.stablePrincipal === void 0 || message.stablePrincipal.length === 0)) return {
+		reason: "invalid_message",
+		status: "fence"
+	};
+	if ((message.messageClass === "diagnostic" || message.messageClass === "liveness") && (message.coalesceKey === void 0 || message.coalesceKey.length === 0)) return {
+		reason: "invalid_message",
+		status: "fence"
+	};
+}
+function isGatewayControlProcessAdmissionMessage(message) {
+	return "zoneId" in message && typeof message.zoneId === "string";
+}
+function gatewayControlProcessCoalescingKey(message) {
+	return message.messageClass === "liveness" || message.messageClass === "diagnostic" ? `${message.messageClass}\u0000${message.coalesceKey ?? ""}` : void 0;
+}
+function createGatewayControlAdmissionScheduler() {
+	const safety = [];
+	const safetyAccounting = {
+		byteCount: 0,
+		messageCount: 0
+	};
+	const authorityByPrincipal = /* @__PURE__ */ new Map();
+	const authorityPrincipalOrder = [];
+	const authorityAccounting = {
+		byteCount: 0,
+		messageCount: 0
+	};
+	const livenessByKey = /* @__PURE__ */ new Map();
+	const livenessAccounting = {
+		byteCount: 0,
+		messageCount: 0
+	};
+	const diagnosticByKey = /* @__PURE__ */ new Map();
+	const diagnosticAccounting = {
+		byteCount: 0,
+		messageCount: 0
+	};
+	const inFlightMessages = /* @__PURE__ */ new Map();
+	let serviceCursor = 0;
+	let authorityPrincipalCursor = 0;
+	let coalescedMessages = 0;
+	let droppedMessages = 0;
+	let fencedMessages = 0;
+	let refusedMessages = 0;
+	let shedMessages = 0;
+	const dequeueAuthority = () => {
+		if (authorityPrincipalOrder.length === 0) return;
+		for (let offset = 0; offset < authorityPrincipalOrder.length; offset += 1) {
+			const index = (authorityPrincipalCursor + offset) % authorityPrincipalOrder.length;
+			const principal = authorityPrincipalOrder[index];
+			if (principal === void 0) continue;
+			const queue = authorityByPrincipal.get(principal);
+			const message = queue?.messages.shift();
+			if (queue === void 0 || message === void 0) continue;
+			authorityPrincipalCursor = (index + 1) % authorityPrincipalOrder.length;
+			return message;
+		}
+	};
+	const dequeueClass = (messageClass) => {
+		switch (messageClass) {
+			case "safety": return safety.shift();
+			case "authority": return dequeueAuthority();
+			case "liveness": return dequeueFirstCoalescedMessage(livenessByKey);
+			case "diagnostic": return dequeueFirstCoalescedMessage(diagnosticByKey);
+		}
+		throw new Error("unsupported gateway control admission class");
+	};
+	return {
+		cancelQueued() {
+			const cancelled = [];
+			for (const message of safety.splice(0)) {
+				release(safetyAccounting, message.byteLength);
+				cancelled.push(message);
+			}
+			for (const [principal, queue] of authorityByPrincipal) {
+				for (const message of queue.messages.splice(0)) {
+					release(queue, message.byteLength);
+					release(authorityAccounting, message.byteLength);
+					cancelled.push(message);
+				}
+				if (queue.messageCount === 0) authorityByPrincipal.delete(principal);
+			}
+			for (let index = authorityPrincipalOrder.length - 1; index >= 0; index -= 1) if (!authorityByPrincipal.has(authorityPrincipalOrder[index] ?? "")) authorityPrincipalOrder.splice(index, 1);
+			authorityPrincipalCursor = authorityPrincipalOrder.length === 0 ? 0 : Math.min(authorityPrincipalCursor, authorityPrincipalOrder.length - 1);
+			for (const message of livenessByKey.values()) {
+				release(livenessAccounting, message.byteLength);
+				cancelled.push(message);
+			}
+			livenessByKey.clear();
+			for (const message of diagnosticByKey.values()) {
+				release(diagnosticAccounting, message.byteLength);
+				cancelled.push(message);
+			}
+			diagnosticByKey.clear();
+			return cancelled;
+		},
+		complete(completionToken) {
+			const message = inFlightMessages.get(completionToken);
+			if (message === void 0 || !inFlightMessages.delete(completionToken)) throw new Error("gateway control admission message is not in flight");
+			switch (message.messageClass) {
+				case "safety":
+					release(safetyAccounting, message.byteLength);
+					return;
+				case "authority": {
+					const principal = message.stablePrincipal ?? "";
+					const queue = authorityByPrincipal.get(principal);
+					if (queue === void 0) throw new Error("gateway control authority principal is not admitted");
+					release(queue, message.byteLength);
+					release(authorityAccounting, message.byteLength);
+					if (queue.messageCount === 0) {
+						authorityByPrincipal.delete(principal);
+						const index = authorityPrincipalOrder.indexOf(principal);
+						if (index >= 0) {
+							authorityPrincipalOrder.splice(index, 1);
+							authorityPrincipalCursor = authorityPrincipalOrder.length === 0 ? 0 : Math.min(authorityPrincipalCursor, authorityPrincipalOrder.length - 1);
+						}
+					}
+					return;
+				}
+				case "liveness":
+					release(livenessAccounting, message.byteLength);
+					return;
+				case "diagnostic":
+					release(diagnosticAccounting, message.byteLength);
+					return;
+			}
+		},
+		enqueue(message) {
+			const invalid = validateMessage(message);
+			if (invalid !== void 0) {
+				fencedMessages += 1;
+				return invalid;
+			}
+			switch (message.messageClass) {
+				case "safety":
+					if (!canReserve(safetyAccounting, message.byteLength, GATEWAY_CONTROL_ADMISSION_LIMITS.safety)) {
+						fencedMessages += 1;
+						return {
+							reason: "safety_capacity",
+							status: "fence"
+						};
+					}
+					safety.push(message);
+					safetyAccounting.byteCount += message.byteLength;
+					safetyAccounting.messageCount += 1;
+					return { status: "admitted" };
+				case "authority": {
+					const principal = message.stablePrincipal ?? "";
+					const queue = authorityByPrincipal.get(principal) ?? {
+						byteCount: 0,
+						messageCount: 0,
+						messages: []
+					};
+					if (!canReserve(queue, message.byteLength, GATEWAY_CONTROL_ADMISSION_LIMITS.perPrincipalAuthority)) {
+						refusedMessages += 1;
+						return {
+							reason: "principal_capacity",
+							status: "refused"
+						};
+					}
+					if (!canReserve(authorityAccounting, message.byteLength, GATEWAY_CONTROL_ADMISSION_LIMITS.authority)) {
+						fencedMessages += 1;
+						return {
+							reason: "authority_capacity",
+							status: "fence"
+						};
+					}
+					if (!authorityByPrincipal.has(principal)) {
+						authorityByPrincipal.set(principal, queue);
+						authorityPrincipalOrder.push(principal);
+					}
+					queue.messages.push(message);
+					queue.byteCount += message.byteLength;
+					queue.messageCount += 1;
+					authorityAccounting.byteCount += message.byteLength;
+					authorityAccounting.messageCount += 1;
+					return { status: "admitted" };
+				}
+				case "liveness":
+				case "diagnostic": {
+					const isLiveness = message.messageClass === "liveness";
+					const messages = isLiveness ? livenessByKey : diagnosticByKey;
+					const accounting = isLiveness ? livenessAccounting : diagnosticAccounting;
+					const limits = isLiveness ? GATEWAY_CONTROL_ADMISSION_LIMITS.liveness : GATEWAY_CONTROL_ADMISSION_LIMITS.diagnostic;
+					const key = message.coalesceKey ?? "";
+					const prior = messages.get(key);
+					const nextBytes = accounting.byteCount - (prior?.byteLength ?? 0) + message.byteLength;
+					const nextMessages = accounting.messageCount + (prior === void 0 ? 1 : 0);
+					if (nextBytes > limits.maxBytes || nextMessages > limits.maxMessages) {
+						if (isLiveness) {
+							shedMessages += 1;
+							return {
+								reason: "liveness_capacity",
+								status: "shed"
+							};
+						}
+						droppedMessages += 1;
+						return {
+							reason: "diagnostic_capacity",
+							status: "dropped"
+						};
+					}
+					messages.set(key, message);
+					accounting.byteCount = nextBytes;
+					accounting.messageCount = nextMessages;
+					if (prior !== void 0) coalescedMessages += 1;
+					return prior === void 0 ? { status: "admitted" } : {
+						replacedMessage: prior,
+						status: "replaced"
+					};
+				}
+			}
+			throw new Error("unsupported gateway control admission class");
+		},
+		dequeue(options = {}) {
+			for (let offset = 0; offset < serviceCycle.length; offset += 1) {
+				const index = (serviceCursor + offset) % serviceCycle.length;
+				const messageClass = serviceCycle[index];
+				if (messageClass === void 0) continue;
+				if (options.allowedMessageClasses !== void 0 && !options.allowedMessageClasses.includes(messageClass)) continue;
+				const message = dequeueClass(messageClass);
+				if (message !== void 0) {
+					serviceCursor = (index + 1) % serviceCycle.length;
+					const completionToken = Object.freeze({ completionTokenId: Symbol("gateway-control-admission-completion") });
+					inFlightMessages.set(completionToken, message);
+					return {
+						completionToken,
+						message
+					};
+				}
+			}
+		},
+		diagnostics() {
+			return {
+				authorityBytes: authorityAccounting.byteCount,
+				authorityMessages: authorityAccounting.messageCount,
+				diagnosticBytes: diagnosticAccounting.byteCount,
+				diagnosticMessages: diagnosticAccounting.messageCount,
+				livenessBytes: livenessAccounting.byteCount,
+				livenessMessages: livenessAccounting.messageCount,
+				safetyBytes: safetyAccounting.byteCount,
+				safetyMessages: safetyAccounting.messageCount,
+				coalescedMessages,
+				droppedMessages,
+				fencedMessages,
+				refusedMessages,
+				shedMessages
+			};
+		}
+	};
+}
+function createGatewayControlProcessAdmission(options = {}) {
+	const maxActiveSessions = options.maxActiveSessions ?? GATEWAY_CONTROL_PROCESS_ADMISSION_LIMITS.maxActiveSessions;
+	const maxNonSafetyBytes = options.maxNonSafetyBytes ?? GATEWAY_CONTROL_PROCESS_ADMISSION_LIMITS.maxNonSafetyBytes;
+	const maxNonSafetyMessages = options.maxNonSafetyMessages ?? GATEWAY_CONTROL_PROCESS_ADMISSION_LIMITS.maxNonSafetyMessages;
+	const schedulersByZone = /* @__PURE__ */ new Map();
+	const queuedCoalescibleMessagesByZone = /* @__PURE__ */ new Map();
+	const inFlightMessages = /* @__PURE__ */ new Map();
+	const zoneOrder = [];
+	let zoneCursor = 0;
+	let nonSafetyBytes = 0;
+	let nonSafetyMessages = 0;
+	requirePositiveLimit("maxActiveSessions", maxActiveSessions);
+	requirePositiveLimit("maxNonSafetyBytes", maxNonSafetyBytes);
+	requirePositiveLimit("maxNonSafetyMessages", maxNonSafetyMessages);
+	return {
+		complete(completionToken) {
+			const message = inFlightMessages.get(completionToken);
+			if (message === void 0 || !inFlightMessages.delete(completionToken)) throw new Error("gateway control process admission message is not in flight");
+			const scheduler = schedulersByZone.get(message.zoneId);
+			if (scheduler === void 0) throw new Error("gateway control process admission zone is not registered");
+			scheduler.complete(completionToken);
+			if (message.messageClass !== "safety") {
+				nonSafetyMessages -= 1;
+				nonSafetyBytes -= message.byteLength;
+			}
+		},
+		registerZone(zoneId) {
+			if (zoneId.length === 0) return { status: "capacity_refused" };
+			if (schedulersByZone.has(zoneId)) return { status: "admitted" };
+			if (schedulersByZone.size >= maxActiveSessions) return { status: "capacity_refused" };
+			schedulersByZone.set(zoneId, createGatewayControlAdmissionScheduler());
+			queuedCoalescibleMessagesByZone.set(zoneId, /* @__PURE__ */ new Map());
+			zoneOrder.push(zoneId);
+			return { status: "admitted" };
+		},
+		unregisterZone(zoneId) {
+			const scheduler = schedulersByZone.get(zoneId);
+			if (scheduler === void 0) return;
+			for (;;) {
+				const work = scheduler.dequeue();
+				if (work === void 0) break;
+				const { completionToken, message } = work;
+				if (message.messageClass !== "safety") {
+					nonSafetyBytes -= message.byteLength;
+					nonSafetyMessages -= 1;
+				}
+				scheduler.complete(completionToken);
+			}
+			for (const [completionToken, message] of inFlightMessages) {
+				if (message.zoneId !== zoneId) continue;
+				inFlightMessages.delete(completionToken);
+				scheduler.complete(completionToken);
+				if (message.messageClass !== "safety") {
+					nonSafetyBytes -= message.byteLength;
+					nonSafetyMessages -= 1;
+				}
+			}
+			schedulersByZone.delete(zoneId);
+			queuedCoalescibleMessagesByZone.delete(zoneId);
+			const index = zoneOrder.indexOf(zoneId);
+			if (index >= 0) {
+				zoneOrder.splice(index, 1);
+				zoneCursor = zoneOrder.length === 0 ? 0 : Math.min(zoneCursor, zoneOrder.length - 1);
+			}
+		},
+		enqueue(message) {
+			const scheduler = schedulersByZone.get(message.zoneId);
+			if (scheduler === void 0) return {
+				reason: "global_capacity",
+				status: "refused"
+			};
+			const coalescingKey = gatewayControlProcessCoalescingKey(message);
+			const priorCoalescibleMessage = coalescingKey === void 0 ? void 0 : queuedCoalescibleMessagesByZone.get(message.zoneId)?.get(coalescingKey);
+			const nonSafetyMessageDelta = priorCoalescibleMessage === void 0 ? 1 : 0;
+			const nonSafetyByteDelta = message.byteLength - (priorCoalescibleMessage?.byteLength ?? 0);
+			if (message.messageClass !== "safety" && (nonSafetyMessages + nonSafetyMessageDelta > maxNonSafetyMessages || nonSafetyBytes + nonSafetyByteDelta > maxNonSafetyBytes)) return message.messageClass === "authority" ? {
+				reason: "global_capacity",
+				status: "refused"
+			} : message.messageClass === "liveness" ? {
+				reason: "global_capacity",
+				status: "shed"
+			} : {
+				reason: "global_capacity",
+				status: "dropped"
+			};
+			const before = scheduler.diagnostics();
+			const result = scheduler.enqueue(message);
+			if (message.messageClass !== "safety" && (result.status === "admitted" || result.status === "replaced")) {
+				const after = scheduler.diagnostics();
+				const beforeMessages = before.authorityMessages + before.livenessMessages + before.diagnosticMessages;
+				const afterMessages = after.authorityMessages + after.livenessMessages + after.diagnosticMessages;
+				const beforeBytes = before.authorityBytes + before.livenessBytes + before.diagnosticBytes;
+				const afterBytes = after.authorityBytes + after.livenessBytes + after.diagnosticBytes;
+				nonSafetyMessages += afterMessages - beforeMessages;
+				nonSafetyBytes += afterBytes - beforeBytes;
+				if (coalescingKey !== void 0) queuedCoalescibleMessagesByZone.get(message.zoneId)?.set(coalescingKey, message);
+			}
+			return result;
+		},
+		dequeue() {
+			if (zoneOrder.length === 0) return;
+			for (let offset = 0; offset < zoneOrder.length; offset += 1) {
+				const index = (zoneCursor + offset) % zoneOrder.length;
+				const zoneId = zoneOrder[index];
+				const work = (zoneId === void 0 ? void 0 : schedulersByZone.get(zoneId))?.dequeue();
+				if (zoneId === void 0 || work === void 0) continue;
+				const { completionToken, message } = work;
+				if (!isGatewayControlProcessAdmissionMessage(message) || message.zoneId !== zoneId) throw new Error("gateway control process admission message lost its zone identity");
+				const coalescingKey = gatewayControlProcessCoalescingKey(message);
+				if (coalescingKey !== void 0) {
+					const queuedMessages = queuedCoalescibleMessagesByZone.get(zoneId);
+					if (queuedMessages?.get(coalescingKey) === message) queuedMessages.delete(coalescingKey);
+				}
+				zoneCursor = (index + 1) % zoneOrder.length;
+				inFlightMessages.set(completionToken, message);
+				return {
+					completionToken,
+					message
+				};
+			}
+		},
+		diagnostics() {
+			return {
+				activeSessions: schedulersByZone.size,
+				nonSafetyBytes,
+				nonSafetyMessages
+			};
+		}
+	};
+}
+//#endregion
+//#region src/gateway-control-admission-executor.ts
+const GATEWAY_CONTROL_ADMISSION_EXECUTION_LIMITS = {
+	authority: 4,
+	diagnostic: 1,
+	liveness: 2,
+	safety: 8
+};
+const GATEWAY_CONTROL_ADMISSION_CLASSES = [
+	"authority",
+	"diagnostic",
+	"liveness",
+	"safety"
+];
+function executionMessage(request, work) {
+	return {
+		byteLength: request.byteLength,
+		...request.coalesceKey === void 0 ? {} : { coalesceKey: request.coalesceKey },
+		id: request.id,
+		messageClass: request.messageClass,
+		payload: work,
+		...request.stablePrincipal === void 0 ? {} : { stablePrincipal: request.stablePrincipal }
+	};
+}
+function createGatewayControlAdmissionExecutor(options = {}) {
+	const scheduler = createGatewayControlAdmissionScheduler();
+	const scheduleImmediate = options.scheduleImmediate ?? ((callback) => setImmediate(callback));
+	const executionLimits = {
+		...GATEWAY_CONTROL_ADMISSION_EXECUTION_LIMITS,
+		...options.executionLimits
+	};
+	const activeByClass = {
+		authority: 0,
+		diagnostic: 0,
+		liveness: 0,
+		safety: 0
+	};
+	let pumpScheduled = false;
+	let admissionGeneration = 0;
+	let closedReason;
+	const activeWork = /* @__PURE__ */ new Set();
+	for (const messageClass of GATEWAY_CONTROL_ADMISSION_CLASSES) {
+		const limit = executionLimits[messageClass];
+		if (!Number.isSafeInteger(limit) || limit <= 0) throw new RangeError(`${messageClass} execution limit must be a positive safe integer.`);
+	}
+	const schedulePump = () => {
+		if (pumpScheduled || closedReason !== void 0) return;
+		pumpScheduled = true;
+		scheduleImmediate(() => {
+			pumpScheduled = false;
+			pump();
+		});
+	};
+	const pump = () => {
+		if (closedReason !== void 0) return;
+		for (;;) {
+			const allowedMessageClasses = GATEWAY_CONTROL_ADMISSION_CLASSES.filter((messageClass) => activeByClass[messageClass] < executionLimits[messageClass]);
+			if (allowedMessageClasses.length === 0) return;
+			const admittedWork = scheduler.dequeue({ allowedMessageClasses });
+			if (admittedWork === void 0) return;
+			const { completionToken, message } = admittedWork;
+			const messageClass = message.messageClass;
+			const work = message.payload;
+			activeByClass[messageClass] += 1;
+			activeWork.add(work);
+			(async () => {
+				let executionError;
+				try {
+					await work.execute();
+				} catch (error) {
+					executionError = error;
+				} finally {
+					scheduler.complete(completionToken);
+					activeByClass[messageClass] -= 1;
+					activeWork.delete(work);
+					schedulePump();
+				}
+				if (work.settled || work.admissionGeneration !== admissionGeneration) return;
+				work.settled = true;
+				if (executionError === void 0) {
+					work.resolve({ status: "executed" });
+					return;
+				}
+				work.reject(executionError);
+			})();
+		}
+	};
+	return {
+		close: (reason) => {
+			if (closedReason !== void 0) return;
+			closedReason = reason;
+			admissionGeneration += 1;
+			for (const message of scheduler.cancelQueued()) {
+				const work = message.payload;
+				if (!work.settled) {
+					work.settled = true;
+					work.onCancel?.(reason);
+					work.resolve({
+						reason,
+						status: "closed"
+					});
+				}
+			}
+			for (const work of activeWork) if (!work.settled) {
+				work.settled = true;
+				work.onCancel?.(reason);
+				work.resolve({
+					reason,
+					status: "closed"
+				});
+			}
+		},
+		diagnostics: () => ({
+			activeByClass: { ...activeByClass },
+			scheduler: scheduler.diagnostics()
+		}),
+		submit: (request) => {
+			if (closedReason !== void 0) {
+				const closed = {
+					reason: closedReason,
+					status: "closed"
+				};
+				return {
+					admission: closed,
+					completion: Promise.resolve(closed)
+				};
+			}
+			let resolveCompletion;
+			let rejectCompletion;
+			const completion = new Promise((resolve, reject) => {
+				resolveCompletion = resolve;
+				rejectCompletion = reject;
+			});
+			const work = {
+				admissionGeneration,
+				execute: request.execute,
+				...request.onCancel === void 0 ? {} : { onCancel: request.onCancel },
+				payload: request.payload,
+				reject: rejectCompletion,
+				resolve: resolveCompletion,
+				settled: false
+			};
+			const result = scheduler.enqueue(executionMessage(request, work));
+			switch (result.status) {
+				case "admitted":
+					schedulePump();
+					return {
+						admission: { status: "admitted" },
+						completion
+					};
+				case "replaced":
+					if (!result.replacedMessage.payload.settled) {
+						result.replacedMessage.payload.settled = true;
+						result.replacedMessage.payload.onCancel?.("replaced");
+						result.replacedMessage.payload.resolve({ status: "replaced" });
+					}
+					schedulePump();
+					return {
+						admission: { status: "replaced" },
+						completion
+					};
+				case "dropped":
+				case "fence":
+				case "refused":
+				case "shed":
+					resolveCompletion(result);
+					return {
+						admission: result,
+						completion
+					};
+			}
+			throw new Error("unsupported gateway control admission result");
+		}
+	};
+}
+//#endregion
+//#region src/gateway-control-admission-classification.ts
+function authorityClassification(stablePrincipal) {
+	return stablePrincipal === void 0 || stablePrincipal.length === 0 ? {
+		reason: "stable_principal_required",
+		status: "refused"
+	} : {
+		authoritySchedulingKey: stablePrincipal,
+		messageClass: "authority",
+		stablePrincipal,
+		status: "classified"
+	};
+}
+function diagnosticCoalesceKey(payload) {
+	return JSON.stringify([
+		payload.eventKind,
+		"leaseId" in payload ? payload.leaseId : void 0,
+		"transitionId" in payload ? payload.transitionId : void 0,
+		"operation" in payload ? payload.operation : void 0,
+		"channelProviderId" in payload ? payload.channelProviderId : void 0
+	]);
+}
+function classifyGatewayControlAdmission(options) {
+	const message = options.message;
+	if (message.kind === "command_result") return options.matchedPendingResult === true ? {
+		messageClass: "safety",
+		status: "classified"
+	} : {
+		reason: "forged_command_result",
+		status: "fence"
+	};
+	if (message.kind === "heartbeat") return {
+		coalesceKey: `${options.direction}:control-heartbeat`,
+		messageClass: "liveness",
+		status: "classified"
+	};
+	if (message.kind === "event") {
+		if (options.direction !== "gateway_to_controller") return {
+			reason: "direction_violation",
+			status: "fence"
+		};
+		switch (message.operation) {
+			case "runtime_status": return {
+				coalesceKey: `runtime-status:${message.payload.statusKind}`,
+				messageClass: "liveness",
+				status: "classified"
+			};
+			case "health_event": return {
+				coalesceKey: diagnosticCoalesceKey(message.payload),
+				messageClass: "diagnostic",
+				status: "classified"
+			};
+		}
+	}
+	if (message.operation === "control_ping") return {
+		coalesceKey: `${options.direction}:control-ping`,
+		messageClass: "liveness",
+		status: "classified"
+	};
+	if (options.direction === "controller_to_gateway") switch (message.operation) {
+		case "operation_cancel": return options.controllerSafetyOperation === true && message.payload.initiatedBy === "controller" ? {
+			messageClass: "safety",
+			status: "classified"
+		} : {
+			reason: "direction_violation",
+			status: "fence"
+		};
+		case "recovery_command": return options.controllerSafetyOperation === true ? {
+			messageClass: "safety",
+			status: "classified"
+		} : {
+			reason: "direction_violation",
+			status: "fence"
+		};
+		case "caller_context_register":
+		case "lease_create":
+		case "lease_get":
+		case "lease_peek":
+		case "lease_reacquire":
+		case "lease_release":
+		case "lease_renew":
+		case "lease_use_start":
+		case "lease_use_heartbeat":
+		case "lease_use_end":
+		case "tool_portal_controller_host_action": return {
+			reason: "direction_violation",
+			status: "fence"
+		};
+	}
+	switch (message.operation) {
+		case "caller_context_register": return authorityClassification(options.stablePrincipal);
+		case "lease_renew": return options.stablePrincipal === void 0 ? {
+			reason: "stable_principal_required",
+			status: "refused"
+		} : {
+			coalesceKey: `${options.stablePrincipal}:lease:${message.payload.leaseId}`,
+			messageClass: "liveness",
+			status: "classified"
+		};
+		case "lease_use_heartbeat": return options.stablePrincipal === void 0 ? {
+			reason: "stable_principal_required",
+			status: "refused"
+		} : {
+			coalesceKey: `${options.stablePrincipal}:lease:${message.payload.leaseId}:use:${message.payload.useId}`,
+			messageClass: "liveness",
+			status: "classified"
+		};
+		case "operation_cancel": return message.payload.initiatedBy === "gateway" ? {
+			reason: "unproven_gateway_cancel",
+			status: "refused"
+		} : {
+			reason: "direction_violation",
+			status: "fence"
+		};
+		case "recovery_command": return {
+			reason: "direction_violation",
+			status: "fence"
+		};
+		case "lease_create":
+		case "lease_get":
+		case "lease_peek":
+		case "lease_reacquire":
+		case "lease_release":
+		case "lease_use_start":
+		case "lease_use_end":
+		case "tool_portal_controller_host_action": return authorityClassification(options.stablePrincipal);
+	}
+	return {
+		reason: "direction_violation",
+		status: "fence"
+	};
+}
+//#endregion
 //#region src/index.ts
 const GatewayControlDomainSchema = z.literal("gateway_control");
+const GatewayControlHelloSchema = z.object({
+	attachmentGeneration: z.number().int().positive(),
+	controllerEpoch: z.string().min(1),
+	domain: GatewayControlDomainSchema,
+	gatewayEpoch: z.string().min(1),
+	peerId: z.string().min(1),
+	processEpoch: z.string().min(1),
+	protocolVersion: z.literal(CONTROL_PROTOCOL_VERSION)
+}).strict();
+const GatewayControlHelloResponseSchema = z.object({
+	attachmentGeneration: z.number().int().positive(),
+	connectionId: z.string().uuid(),
+	controllerEpoch: z.string().min(1),
+	outcome: z.enum([
+		"accepted",
+		"rejected",
+		"generation_mismatch",
+		"stale_attachment"
+	]),
+	sessionId: z.string().uuid()
+}).strict();
 const GatewayControlRpcOperationSchema = z.enum([
 	"control_ping",
 	"caller_context_register",
@@ -52,6 +833,7 @@ const GatewayControlCapabilityRefSchema = z.object({
 }).strict();
 const GatewayControlToolCallCorrelationSchema = ControlCorrelationSchema.extend({ capability: GatewayControlCapabilityRefSchema.optional() }).strict();
 const GatewayControlTrustedCallerContextIdSchema = z.string().uuid();
+const GatewayControlAdmissionPrincipalSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 const GatewayControlTrustedLeaseContextSchema = z.object({
 	agentId: z.string().min(1),
 	agentWorkspaceDir: z.string().min(1),
@@ -65,6 +847,7 @@ const GatewayControlTrustedLeaseContextSchema = z.object({
 	zoneId: z.string().min(1)
 }).strict();
 const GatewayControlCallerContextRefSchema = z.object({ callerContextId: GatewayControlTrustedCallerContextIdSchema }).strict();
+const GatewayControlRegisteredCallerContextRefSchema = GatewayControlCallerContextRefSchema.extend({ admissionPrincipal: GatewayControlAdmissionPrincipalSchema }).strict();
 const GatewayControlCallerContextProofAlgorithmSchema = z.literal("hmac-sha256");
 const GatewayControlCallerContextProofSchema = z.object({
 	algorithm: GatewayControlCallerContextProofAlgorithmSchema,
@@ -406,7 +1189,7 @@ const GatewayControlSessionStateSchema = ControlSessionStateSchema;
 const GatewayControlToolVmSshAccessSchema = z.object({
 	host: z.string().min(1),
 	identityPem: z.string().min(1).optional(),
-	knownHostsLine: z.string().optional(),
+	knownHostsLine: z.string().min(1).optional(),
 	port: z.number().int().positive(),
 	user: z.string().min(1)
 }).strict();
@@ -475,7 +1258,7 @@ const GatewayControlRpcBareResponsePayloadSchema = z.discriminatedUnion("result"
 }).strict()]);
 const GatewayControlRpcCallerContextResponsePayloadSchema = z.discriminatedUnion("result", [GatewayControlRpcResponseCorrelationSchema.extend({
 	...GatewayControlRpcForbiddenResponseFieldsSchema,
-	callerContext: GatewayControlCallerContextRefSchema,
+	callerContext: GatewayControlRegisteredCallerContextRefSchema,
 	result: z.literal("ok")
 }).strict(), GatewayControlRpcResponseCorrelationSchema.extend({
 	...GatewayControlRpcForbiddenResponseFieldsSchema,
@@ -768,6 +1551,14 @@ function buildGatewayControlJsonSchemas() {
 			io: "input",
 			unrepresentable: "any"
 		}),
+		hello: z.toJSONSchema(GatewayControlHelloSchema, {
+			io: "input",
+			unrepresentable: "any"
+		}),
+		helloResponse: z.toJSONSchema(GatewayControlHelloResponseSchema, {
+			io: "input",
+			unrepresentable: "any"
+		}),
 		message: z.toJSONSchema(GatewayControlRpcMessageSchema, {
 			io: "input",
 			unrepresentable: "any"
@@ -782,6 +1573,6 @@ function assertGatewayControlDomainRegistered() {
 	return KnownControlDomainSchema.extract(["gateway_control"]).parse("gateway_control");
 }
 //#endregion
-export { ControllerInitiatedGatewayOperationCancelPayloadSchema, GatewayControlActiveOperationIdSchema, GatewayControlCallerContextAgentAuthoritySchema, GatewayControlCallerContextProofAlgorithmSchema, GatewayControlCallerContextProofSchema, GatewayControlCallerContextRefSchema, GatewayControlCallerContextRegisterPayloadSchema, GatewayControlCapabilityRefSchema, GatewayControlControllerHostProbeActionResultSchema, GatewayControlControllerHostProbePayloadSchema, GatewayControlControllerHostProbeResultSchema, GatewayControlControllerRequestHealthOperationSchema, GatewayControlDomainSchema, GatewayControlEventOnlyOperationSchema, GatewayControlForbiddenPayloadFieldSchema, GatewayControlHealthEventPayloadSchema, GatewayControlHealthEventResultSchema, GatewayControlHeartbeatPayloadSchema, GatewayControlLeaseCreateIntentPayloadSchema, GatewayControlLeaseIdPayloadSchema, GatewayControlLeaseReacquireIntentPayloadSchema, GatewayControlLeaseRejectionReasonSchema, GatewayControlLeaseSnapshotSchema, GatewayControlLeaseStaleEvidenceSchema, GatewayControlLeaseUseEndPayloadSchema, GatewayControlLeaseUseHeartbeatPayloadSchema, GatewayControlLeaseUseSnapshotSchema, GatewayControlLeaseUseStartPayloadSchema, GatewayControlOperationCancelPayloadSchema, GatewayControlPingPayloadSchema, GatewayControlProviderRuntimeHealthSchema, GatewayControlRecoveryCommandPayloadSchema, GatewayControlRpcBareResponsePayloadSchema, GatewayControlRpcCallerContextResponsePayloadSchema, GatewayControlRpcCommandMessageSchema, GatewayControlRpcCommandResultMessageSchema, GatewayControlRpcCommandResultOperationSchema, GatewayControlRpcControllerHostActionResponsePayloadSchema, GatewayControlRpcDomainCorrelationSchema, GatewayControlRpcErrorSchema, GatewayControlRpcEventMessageSchema, GatewayControlRpcLeaseResponsePayloadSchema, GatewayControlRpcLeaseUseResponsePayloadSchema, GatewayControlRpcMessageSchema, GatewayControlRpcOperationCancelResponsePayloadSchema, GatewayControlRpcOperationSchema, GatewayControlRpcResponseBasePayloadSchema, GatewayControlRpcResponsePayloadSchema, GatewayControlRpcResultSchema, GatewayControlRuntimeFindingSchema, GatewayControlRuntimeStatusPayloadSchema, GatewayControlSessionHealthOperationSchema, GatewayControlSessionStateSchema, GatewayControlToolCallCorrelationSchema, GatewayControlToolPortalControllerHostActionPayloadSchema, GatewayControlToolPortalControllerHostActionResultSchema, GatewayControlToolVmLeaseCallerContextStateSchema, GatewayControlToolVmLeaseLifecycleEventRoleSchema, GatewayControlToolVmLeaseLifecycleTransitionSchema, GatewayControlToolVmSshAccessSchema, GatewayControlToolVmSshHealthOperationSchema, GatewayControlTrustedCallerContextIdSchema, GatewayControlTrustedLeaseContextSchema, GatewayControlZoneGitCommitSummarySchema, GatewayControlZoneGitPushControllerHostActionPayloadSchema, GatewayControlZoneGitPushControllerHostActionResultSchema, GatewayControlZoneGitPushResultSchema, GatewayInitiatedOperationCancelPayloadSchema, assertGatewayControlDomainRegistered, assertGatewayControlEnvelopeDeliveryPolicy, buildGatewayControlCallerContextAgentAuthorityPayload, buildGatewayControlCallerContextProofPayload, buildGatewayControlJsonSchemas, deriveGatewayControlDeliveryPolicy, gatewayControlCommandExecutionTimeoutMsByOperation, gatewayControlDeliveryPolicyByKind, gatewayControlDeliveryPolicyByOperation };
+export { ControllerInitiatedGatewayOperationCancelPayloadSchema, GATEWAY_CONTROL_ADMISSION_EXECUTION_LIMITS, GATEWAY_CONTROL_ADMISSION_LIMITS, GATEWAY_CONTROL_PROCESS_ADMISSION_LIMITS, GatewayControlActiveOperationIdSchema, GatewayControlAdmissionPrincipalSchema, GatewayControlCallerContextAgentAuthoritySchema, GatewayControlCallerContextProofAlgorithmSchema, GatewayControlCallerContextProofSchema, GatewayControlCallerContextRefSchema, GatewayControlCallerContextRegisterPayloadSchema, GatewayControlCapabilityRefSchema, GatewayControlControllerHostProbeActionResultSchema, GatewayControlControllerHostProbePayloadSchema, GatewayControlControllerHostProbeResultSchema, GatewayControlControllerRequestHealthOperationSchema, GatewayControlDomainSchema, GatewayControlEventOnlyOperationSchema, GatewayControlForbiddenPayloadFieldSchema, GatewayControlHealthEventPayloadSchema, GatewayControlHealthEventResultSchema, GatewayControlHeartbeatPayloadSchema, GatewayControlHelloResponseSchema, GatewayControlHelloSchema, GatewayControlLeaseCreateIntentPayloadSchema, GatewayControlLeaseIdPayloadSchema, GatewayControlLeaseReacquireIntentPayloadSchema, GatewayControlLeaseRejectionReasonSchema, GatewayControlLeaseSnapshotSchema, GatewayControlLeaseStaleEvidenceSchema, GatewayControlLeaseUseEndPayloadSchema, GatewayControlLeaseUseHeartbeatPayloadSchema, GatewayControlLeaseUseSnapshotSchema, GatewayControlLeaseUseStartPayloadSchema, GatewayControlOperationCancelPayloadSchema, GatewayControlPingPayloadSchema, GatewayControlProviderRuntimeHealthSchema, GatewayControlRecoveryCommandPayloadSchema, GatewayControlRegisteredCallerContextRefSchema, GatewayControlRpcBareResponsePayloadSchema, GatewayControlRpcCallerContextResponsePayloadSchema, GatewayControlRpcCommandMessageSchema, GatewayControlRpcCommandResultMessageSchema, GatewayControlRpcCommandResultOperationSchema, GatewayControlRpcControllerHostActionResponsePayloadSchema, GatewayControlRpcDomainCorrelationSchema, GatewayControlRpcErrorSchema, GatewayControlRpcEventMessageSchema, GatewayControlRpcLeaseResponsePayloadSchema, GatewayControlRpcLeaseUseResponsePayloadSchema, GatewayControlRpcMessageSchema, GatewayControlRpcOperationCancelResponsePayloadSchema, GatewayControlRpcOperationSchema, GatewayControlRpcResponseBasePayloadSchema, GatewayControlRpcResponsePayloadSchema, GatewayControlRpcResultSchema, GatewayControlRuntimeFindingSchema, GatewayControlRuntimeStatusPayloadSchema, GatewayControlSessionHealthOperationSchema, GatewayControlSessionStateSchema, GatewayControlToolCallCorrelationSchema, GatewayControlToolPortalControllerHostActionPayloadSchema, GatewayControlToolPortalControllerHostActionResultSchema, GatewayControlToolVmLeaseCallerContextStateSchema, GatewayControlToolVmLeaseLifecycleEventRoleSchema, GatewayControlToolVmLeaseLifecycleTransitionSchema, GatewayControlToolVmSshAccessSchema, GatewayControlToolVmSshHealthOperationSchema, GatewayControlTrustedCallerContextIdSchema, GatewayControlTrustedLeaseContextSchema, GatewayControlZoneGitCommitSummarySchema, GatewayControlZoneGitPushControllerHostActionPayloadSchema, GatewayControlZoneGitPushControllerHostActionResultSchema, GatewayControlZoneGitPushResultSchema, GatewayInitiatedOperationCancelPayloadSchema, assertGatewayControlDomainRegistered, assertGatewayControlEnvelopeDeliveryPolicy, buildGatewayControlCallerContextAgentAuthorityPayload, buildGatewayControlCallerContextProofPayload, buildGatewayControlJsonSchemas, classifyGatewayControlAdmission, createGatewayControlAdmissionExecutor, createGatewayControlAdmissionScheduler, createGatewayControlProcessAdmission, deriveGatewayControlDeliveryPolicy, gatewayControlCommandExecutionTimeoutMsByOperation, gatewayControlDeliveryPolicyByKind, gatewayControlDeliveryPolicyByOperation };
 
 //# sourceMappingURL=index.js.map