@fased/fased 0.1.62 → 0.1.64

package/dist/gateway/server-methods/models.js

@@ -1,6 +1,5 @@
 import { defaultRuntime } from "../../runtime.js";
 import { resolveAgentDir, resolveDefaultAgentId, resolveSessionAgentId } from "../../agents/agent-scope.js";
-import { listProviderBrandManifests } from "../../providers/registry.js";
 import { DEFAULT_PROVIDER } from "../../agents/defaults.js";
 import { normalizeSecretInput } from "../../utils/normalize-secret-input.js";
 import { normalizeProviderId } from "../../agents/provider-id.js";
@@ -11,6 +10,7 @@ import { loadConfig, writeConfigFile } from "../../config/io.js";
 import "../../config/config.js";
 import { resolveProfileUnusableUntilForDisplay } from "../../agents/auth-profiles/usage.js";
 import "../../agents/auth-profiles.js";
+import { listProviderBrandManifests } from "../../providers/registry.js";
 import { ensureFasedModelsJson } from "../../agents/models-config.js";
 import { deriveModelMetadata } from "../../agents/model-metadata.js";
 import { ErrorCodes, errorShape } from "../protocol/schema/error-codes.js";

package/dist/gateway/server-methods/secrets.js

@@ -0,0 +1,40 @@
+import { logMutatingAdminRpcAudit } from "./mutating-admin-rpc-audit.js";
+import { ErrorCodes, errorShape } from "../protocol/schema/error-codes.js";
+import "../protocol/index.js";
+import { sanitizeGatewaySecretsRuntimeError } from "../server-secrets-runtime.js";
+
+//#region src/gateway/server-methods/secrets.ts
+function createSecretsHandlers(params) {
+	return { "secrets.reload": async ({ respond, client, context }) => {
+		try {
+			const result = await params.reloadSecrets();
+			logMutatingAdminRpcAudit({
+				context,
+				client,
+				method: "secrets.reload",
+				outcome: "succeeded",
+				details: { warningCount: result.warningCount }
+			});
+			respond(true, {
+				ok: true,
+				warningCount: result.warningCount
+			});
+		} catch (err) {
+			const safe = sanitizeGatewaySecretsRuntimeError(err);
+			logMutatingAdminRpcAudit({
+				context,
+				client,
+				method: "secrets.reload",
+				outcome: "failed",
+				details: { code: safe.code }
+			});
+			respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, safe.message, {
+				retryable: true,
+				details: { code: safe.code }
+			}));
+		}
+	} };
+}
+
+//#endregion
+export { createSecretsHandlers };

package/dist/gateway/server-methods.js

@@ -55,10 +55,9 @@ const CONTROL_PLANE_WRITE_METHODS = new Set([
 ]);
 const SAT_MINING_MUTATION_METHODS = new Set([
 	"sat.openCycle",
-	"sat.bootstrapRegistryReserve",
+	"sat.topUpRegistryReserve",
 	"sat.refillRegistryReserveFromTreasury",
 	"sat.runProtocolMaintenanceOnce",
-	"sat.setProtocolRecipients",
 	"sat.claimProtocolTreasury",
 	"sat.claimProtocolDistributorSat",
 	"sat.initMinerCapital",

package/dist/gateway/server-reload-handlers.js

@@ -19,76 +19,201 @@ function shouldInvalidateGatewayModelCatalog(changedPaths) {
 	return changedPaths.some((path) => path === "models" || path.startsWith("models.") || path === "agents.defaults.model" || path.startsWith("agents.defaults.model.") || path === "agents.defaults.models" || path.startsWith("agents.defaults.models."));
 }
 function createGatewayReloadHandlers(params) {
-	const applyHotReload = async (plan, nextConfig) => {
-		setGatewaySigusr1RestartPolicy({ allowExternal: isRestartEnabled(nextConfig) });
-		const state = params.getState();
-		const nextState = { ...state };
-		if (plan.reloadHooks) {
-			try {
-				nextState.hooksConfig = resolveHooksConfig(nextConfig);
-			} catch (err) {
-				params.logHooks.warn(`hooks config reload failed: ${String(err)}`);
-			}
-		}
-		if (plan.restartHeartbeat) {
-			nextState.heartbeatRunner.updateConfig(nextConfig);
-		}
-		resetDirectoryCache();
-		if (shouldInvalidateGatewayModelCatalog(plan.changedPaths)) {
-			markGatewayModelCatalogStaleForReload();
-		}
-		if (plan.restartCron) {
-			state.cronState.cron.stop();
-			nextState.cronState = buildGatewayCronService({
-				cfg: nextConfig,
-				deps: params.deps,
-				broadcast: params.broadcast
+	const createHotReloadTransaction = (plan) => {
+		const originalState = params.getState();
+		let workingState = { ...originalState };
+		let policyMutated = false;
+		let heartbeatMutated = false;
+		let cronMutated = false;
+		let browserMutated = false;
+		let gmailMutated = false;
+		let concurrencyMutated = false;
+		const channelsMutated = [];
+		let applyStarted = false;
+		let rollbackStarted = false;
+		const publishState = () => {
+			params.setState({ ...workingState });
+		};
+		const startGmailWatcherForReload = async (config, phase) => {
+			let failed = false;
+			await startGmailWatcherWithLogs({
+				cfg: config,
+				log: {
+					info: (message) => params.logHooks.info(message),
+					warn: () => params.logHooks.warn(`gmail watcher ${phase} did not start`),
+					error: () => {
+						failed = true;
+						params.logHooks.error(`gmail watcher ${phase} failed to start`);
+					}
+				},
+				onSkipped: () => params.logHooks.info(`skipping gmail watcher ${phase} (FASED_SKIP_GMAIL_WATCHER=1)`)
 			});
-			void nextState.cronState.cron.start().catch((err) => params.logCron.error(`failed to start: ${String(err)}`));
-		}
-		if (plan.restartBrowserControl) {
-			if (state.browserControl) {
-				await state.browserControl.stop().catch(() => {});
+			if (failed) {
+				throw new Error(`gmail watcher ${phase} failed`);
 			}
-			try {
-				nextState.browserControl = await startBrowserControlServerIfEnabled();
-			} catch (err) {
-				params.logBrowser.error(`server failed to start: ${String(err)}`);
+		};
+		const apply = async (nextConfig) => {
+			if (applyStarted) {
+				throw new Error("hot reload transaction already started");
 			}
-		}
-		if (plan.restartGmailWatcher) {
-			await stopGmailWatcher().catch(() => {});
-			await startGmailWatcherWithLogs({
-				cfg: nextConfig,
-				log: params.logHooks,
-				onSkipped: () => params.logHooks.info("skipping gmail watcher restart (FASED_SKIP_GMAIL_WATCHER=1)")
-			});
-		}
-		if (plan.restartChannels.size > 0) {
-			if (isTruthyEnvValue(process.env.FASED_SKIP_CHANNELS) || isTruthyEnvValue(process.env.FASED_SKIP_PROVIDERS)) {
-				params.logChannels.info("skipping channel reload (FASED_SKIP_CHANNELS=1 or FASED_SKIP_PROVIDERS=1)");
-			} else {
-				const restartChannel = async (name) => {
-					params.logChannels.info(`restarting ${name} channel`);
-					await params.stopChannel(name);
-					await params.startChannel(name);
-				};
-				for (const channel of plan.restartChannels) {
-					await restartChannel(channel);
+			applyStarted = true;
+			policyMutated = true;
+			setGatewaySigusr1RestartPolicy({ allowExternal: isRestartEnabled(nextConfig) });
+			if (plan.reloadHooks) {
+				workingState.hooksConfig = resolveHooksConfig(nextConfig);
+			}
+			if (plan.restartHeartbeat) {
+				heartbeatMutated = true;
+				workingState.heartbeatRunner.updateConfig(nextConfig);
+			}
+			resetDirectoryCache();
+			if (shouldInvalidateGatewayModelCatalog(plan.changedPaths)) {
+				markGatewayModelCatalogStaleForReload();
+			}
+			if (plan.restartCron) {
+				cronMutated = true;
+				workingState.cronState.cron.stop();
+				workingState.cronState = buildGatewayCronService({
+					cfg: nextConfig,
+					deps: params.deps,
+					broadcast: params.broadcast
+				});
+				publishState();
+				await workingState.cronState.cron.start();
+			}
+			if (plan.restartBrowserControl) {
+				browserMutated = true;
+				try {
+					await workingState.browserControl?.stop();
+				} finally {
+					workingState.browserControl = null;
+					publishState();
 				}
+				workingState.browserControl = await startBrowserControlServerIfEnabled();
+				publishState();
 			}
-		}
-		setCommandLaneConcurrency(CommandLane.Cron, nextConfig.cron?.maxConcurrentRuns ?? 1);
-		setCommandLaneConcurrency(CommandLane.Main, resolveAgentMaxConcurrent(nextConfig));
-		setCommandLaneConcurrency(CommandLane.Subagent, resolveSubagentMaxConcurrent(nextConfig));
-		if (plan.hotReasons.length > 0) {
-			params.logReload.info(`config hot reload applied (${plan.hotReasons.join(", ")})`);
-		} else if (plan.noopPaths.length > 0) {
-			params.logReload.info(`config change applied (dynamic reads: ${plan.noopPaths.join(", ")})`);
-		}
-		params.setState(nextState);
+			if (plan.restartGmailWatcher) {
+				gmailMutated = true;
+				await stopGmailWatcher();
+				await startGmailWatcherForReload(nextConfig, "apply");
+			}
+			if (plan.restartChannels.size > 0) {
+				if (isTruthyEnvValue(process.env.FASED_SKIP_CHANNELS) || isTruthyEnvValue(process.env.FASED_SKIP_PROVIDERS)) {
+					params.logChannels.info("skipping channel reload (FASED_SKIP_CHANNELS=1 or FASED_SKIP_PROVIDERS=1)");
+				} else {
+					for (const channel of plan.restartChannels) {
+						channelsMutated.push(channel);
+						params.logChannels.info(`restarting ${channel} channel`);
+						await params.stopChannel(channel);
+						await params.startChannel(channel);
+					}
+				}
+			}
+			concurrencyMutated = true;
+			setCommandLaneConcurrency(CommandLane.Cron, nextConfig.cron?.maxConcurrentRuns ?? 1);
+			setCommandLaneConcurrency(CommandLane.Main, resolveAgentMaxConcurrent(nextConfig));
+			setCommandLaneConcurrency(CommandLane.Subagent, resolveSubagentMaxConcurrent(nextConfig));
+			if (plan.hotReasons.length > 0) {
+				params.logReload.info(`config hot reload applied (${plan.hotReasons.join(", ")})`);
+			} else if (plan.noopPaths.length > 0) {
+				params.logReload.info(`config change applied (dynamic reads: ${plan.noopPaths.join(", ")})`);
+			}
+			publishState();
+		};
+		const rollback = async (previousConfig) => {
+			if (!applyStarted || rollbackStarted) {
+				return;
+			}
+			rollbackStarted = true;
+			const failures = [];
+			const capture = async (operation) => {
+				try {
+					await operation();
+					return true;
+				} catch (error) {
+					failures.push(error);
+					return false;
+				}
+			};
+			if (concurrencyMutated) {
+				await capture(() => {
+					setCommandLaneConcurrency(CommandLane.Cron, previousConfig.cron?.maxConcurrentRuns ?? 1);
+					setCommandLaneConcurrency(CommandLane.Main, resolveAgentMaxConcurrent(previousConfig));
+					setCommandLaneConcurrency(CommandLane.Subagent, resolveSubagentMaxConcurrent(previousConfig));
+				});
+			}
+			for (const channel of channelsMutated.toReversed()) {
+				const stopped = await capture(async () => await params.stopChannel(channel));
+				if (stopped) {
+					await capture(async () => await params.startChannel(channel));
+				}
+			}
+			if (gmailMutated) {
+				const stopped = await capture(async () => await stopGmailWatcher());
+				if (stopped) {
+					await capture(async () => await startGmailWatcherForReload(previousConfig, "rollback"));
+				}
+			}
+			if (browserMutated) {
+				const candidateBrowser = workingState.browserControl;
+				const candidateStopped = await capture(async () => await candidateBrowser?.stop());
+				workingState.browserControl = null;
+				publishState();
+				if (candidateStopped) {
+					let restoredBrowser = null;
+					const restored = await capture(async () => {
+						restoredBrowser = await startBrowserControlServerIfEnabled();
+					});
+					if (restored) {
+						workingState.browserControl = restoredBrowser;
+						publishState();
+					}
+				}
+			}
+			if (cronMutated) {
+				await capture(() => workingState.cronState.cron.stop());
+				workingState.cronState = originalState.cronState;
+				publishState();
+				await capture(async () => await originalState.cronState.cron.start());
+			}
+			if (heartbeatMutated) {
+				const restored = await capture(() => workingState.heartbeatRunner.updateConfig(previousConfig));
+				if (!restored) {
+					await capture(() => workingState.heartbeatRunner.stop());
+				}
+			}
+			workingState.hooksConfig = originalState.hooksConfig;
+			if (policyMutated) {
+				await capture(() => setGatewaySigusr1RestartPolicy({ allowExternal: isRestartEnabled(previousConfig) }));
+			}
+			resetDirectoryCache();
+			if (shouldInvalidateGatewayModelCatalog(plan.changedPaths)) {
+				markGatewayModelCatalogStaleForReload();
+			}
+			publishState();
+			if (failures.length > 0) {
+				throw new Error(`hot reload rollback incomplete (${failures.length} component failure(s))`);
+			}
+		};
+		return {
+			apply,
+			rollback
+		};
+	};
+	const applyHotReload = async (plan, nextConfig) => {
+		await createHotReloadTransaction(plan).apply(nextConfig);
 	};
 	let restartPending = false;
+	let restartDeferral = null;
+	const cancelPendingGatewayRestart = () => {
+		const cancelled = restartDeferral?.cancel() ?? false;
+		restartDeferral = null;
+		restartPending = false;
+		if (cancelled) {
+			params.logReload.info("cancelled deferred config restart before evaluating the latest revision");
+		}
+		return cancelled;
+	};
 	const requestGatewayRestart = (plan, nextConfig) => {
 		setGatewaySigusr1RestartPolicy({ allowExternal: isRestartEnabled(nextConfig) });
 		const reasons = plan.restartReasons.length ? plan.restartReasons.join(", ") : plan.changedPaths.join(", ");
@@ -123,30 +248,33 @@ function createGatewayReloadHandlers(params) {
 		const active = getActiveCounts();
 		if (active.totalActive > 0) {
 			if (restartPending) {
-				params.logReload.info(`config change requires gateway restart (${reasons}) — already waiting for operations to complete`);
-				return;
+				cancelPendingGatewayRestart();
 			}
 			restartPending = true;
 			const initialDetails = formatActiveDetails(active);
 			params.logReload.warn(`config change requires gateway restart (${reasons}) — deferring until ${initialDetails.join(", ")} complete`);
-			deferGatewayRestartUntilIdle({
+			const deferral = deferGatewayRestartUntilIdle({
 				getPendingCount: () => getActiveCounts().totalActive,
 				hooks: {
 					onReady: () => {
 						restartPending = false;
+						restartDeferral = null;
 						params.logReload.info("all operations and replies completed; restarting gateway now");
 					},
 					onTimeout: (_pending, elapsedMs) => {
 						const remaining = formatActiveDetails(getActiveCounts());
 						restartPending = false;
+						restartDeferral = null;
 						params.logReload.warn(`restart timeout after ${elapsedMs}ms with ${remaining.join(", ")} still active; restarting anyway`);
 					},
 					onCheckError: (err) => {
 						restartPending = false;
+						restartDeferral = null;
 						params.logReload.warn(`restart deferral check failed (${String(err)}); restarting gateway now`);
 					}
 				}
 			});
+			restartDeferral = deferral.isPending() ? deferral : null;
 		} else {
 			params.logReload.warn(`config change requires gateway restart (${reasons})`);
 			const emitted = emitGatewayRestart();
@@ -157,6 +285,8 @@ function createGatewayReloadHandlers(params) {
 	};
 	return {
 		applyHotReload,
+		cancelPendingGatewayRestart,
+		createHotReloadTransaction,
 		requestGatewayRestart
 	};
 }

package/dist/gateway/server-runtime-config.js

@@ -1,7 +1,7 @@
 import { isLoopbackHost, isTrustedProxyAddress, isValidIPv4, resolveGatewayBindHost } from "./net.js";
 import { resolveWalletRuntimeConfig } from "../wallet/wallet-runtime-config.js";
-import { resolveWalletApprovalAuthMode } from "../wallet/wallet-approval-auth.js";
 import { normalizeControlUiBasePath } from "./control-ui-shared.js";
+import { resolveWalletApprovalAuthMode } from "../wallet/wallet-approval-auth.js";
 import { resolveHooksConfig } from "./hooks.js";
 import { assertGatewayAuthConfigured, resolveGatewayAuth } from "./auth.js";
 

package/dist/gateway/server-secrets-runtime.js

@@ -0,0 +1,288 @@
+import { resolveMainSessionKeyFromConfig } from "../config/sessions/main-session.js";
+import "../config/sessions.js";
+import { enqueueSystemEvent } from "../infra/system-events.js";
+import { activateSecretsRuntimeSnapshot, clearSecretsRuntimeSnapshot, getActiveSecretsRuntimeSnapshot, prepareSecretsRuntimeSnapshot } from "../secrets/runtime.js";
+import { buildGatewayReloadPlan, diffConfigPaths, resolveGatewayReloadSettings } from "./config-reload.js";
+import { isDeepStrictEqual } from "node:util";
+
+//#region src/gateway/server-secrets-runtime.ts
+var GatewaySecretsRuntimeError = class extends Error {
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "GatewaySecretsRuntimeError";
+		this.code = code;
+	}
+};
+function sanitizeGatewaySecretsRuntimeError(error) {
+	if (error instanceof GatewaySecretsRuntimeError) {
+		return {
+			code: error.code,
+			message: error.message
+		};
+	}
+	return {
+		code: "SECRETS_RELOAD_FAILED",
+		message: "Secret reload failed without changing the active runtime snapshot. Run `fased secrets audit --check` for local diagnostics."
+	};
+}
+function runtimeError(code, message, cause) {
+	return new GatewaySecretsRuntimeError(code, message, cause === undefined ? undefined : { cause });
+}
+function normalizeRuntimeError(error, fallbackCode, fallbackMessage) {
+	return error instanceof GatewaySecretsRuntimeError ? error : runtimeError(fallbackCode, fallbackMessage, error);
+}
+function invalidSnapshotError(snapshot) {
+	const paths = [...new Set(snapshot.issues.map((issue) => issue.path.trim() || "<root>"))].slice(0, 8);
+	const suffix = paths.length > 0 ? ` Invalid paths: ${paths.join(", ")}.` : "";
+	return runtimeError("SECRETS_CONFIG_INVALID", `Secret reload refused an invalid Gateway config.${suffix} Run \`fased doctor\` locally before retrying.`);
+}
+function missingSnapshotError() {
+	return runtimeError("SECRETS_CONFIG_MISSING", "Secret reload refused to replace the active snapshot because the Gateway config file is missing.");
+}
+function staleSourceError() {
+	return runtimeError("SECRETS_SOURCE_STALE", "Secret reload discarded a stale config revision; retry after the current config change finishes.");
+}
+function cloneConfig(config) {
+	return structuredClone(config);
+}
+function sameSourceSnapshot(left, right) {
+	if (left.exists !== right.exists || left.valid !== right.valid) {
+		return false;
+	}
+	if (left.hash && right.hash) {
+		return left.hash === right.hash;
+	}
+	return isDeepStrictEqual(left.config, right.config);
+}
+function planNeedsHotApply(plan) {
+	return plan.hotReasons.length > 0 || plan.reloadHooks || plan.restartGmailWatcher || plan.restartBrowserControl || plan.restartCron || plan.restartHeartbeat || plan.restartChannels.size > 0;
+}
+function assertManualSourceChangeAllowed(params) {
+	const changedPaths = diffConfigPaths(params.previous, params.next);
+	if (changedPaths.length === 0) {
+		return;
+	}
+	const plan = buildGatewayReloadPlan(changedPaths);
+	const settings = resolveGatewayReloadSettings(params.next);
+	if (settings.mode === "restart" || plan.restartGateway) {
+		throw runtimeError("SECRETS_SOURCE_RESTART_REQUIRED", "Secret reload refused config changes that require a Gateway restart. Let the config reloader restart the Gateway, then retry.");
+	}
+	if (planNeedsHotApply(plan)) {
+		throw runtimeError("SECRETS_SOURCE_HOT_RELOAD_REQUIRED", "Secret reload refused config changes that require live component reconfiguration. Let the config reloader apply them, then retry.");
+	}
+}
+function createGatewaySecretsRuntimeController(params) {
+	const prepareSnapshot = params.prepareSnapshot ?? prepareSecretsRuntimeSnapshot;
+	const activateSnapshot = params.activateSnapshot ?? activateSecretsRuntimeSnapshot;
+	const getActiveSnapshot = params.getActiveSnapshot ?? getActiveSecretsRuntimeSnapshot;
+	const clearSnapshot = params.clearSnapshot ?? clearSecretsRuntimeSnapshot;
+	let activeSourceConfig = null;
+	let degraded = false;
+	let closed = false;
+	let latestGeneration = 0;
+	let operationTail = Promise.resolve();
+	let shutdownPromise = null;
+	const runExclusive = (operation) => {
+		const result = operationTail.then(operation, operation);
+		operationTail = result.then(() => undefined, () => undefined);
+		return result;
+	};
+	const runTracked = (operation) => {
+		const generation = ++latestGeneration;
+		return runExclusive(async () => await operation(generation));
+	};
+	const assertCurrent = (generation) => {
+		if (closed) {
+			throw runtimeError("SECRETS_RUNTIME_CLOSED", "Secret reload was cancelled because the Gateway is shutting down.");
+		}
+		if (generation !== latestGeneration) {
+			throw staleSourceError();
+		}
+	};
+	const emitTransition = (code) => {
+		if (params.emitTransition) {
+			params.emitTransition(code);
+			return;
+		}
+		const text = code === "SECRETS_RELOADER_DEGRADED" ? `[${code}] Secret reload failed; the Gateway kept its last-known-good runtime snapshot.` : `[${code}] Secret references recovered and the Gateway activated a new runtime snapshot.`;
+		enqueueSystemEvent(text, {
+			sessionKey: resolveMainSessionKeyFromConfig(),
+			contextKey: "gateway-secrets-runtime",
+			trusted: true
+		});
+	};
+	const recordReloadFailure = (error) => {
+		const safe = sanitizeGatewaySecretsRuntimeError(error);
+		params.log.warn(`[SECRETS_RELOADER_DEGRADED] secret reload failed; keeping last-known-good runtime snapshot (${safe.code}): ${safe.message}`);
+		if (degraded || closed) {
+			return;
+		}
+		degraded = true;
+		emitTransition("SECRETS_RELOADER_DEGRADED");
+	};
+	const recordReloadSuccess = () => {
+		if (!degraded) {
+			return;
+		}
+		degraded = false;
+		params.log.info("[SECRETS_RELOADER_RECOVERED] secret runtime snapshot recovered");
+		emitTransition("SECRETS_RELOADER_RECOVERED");
+	};
+	const logWarnings = (prepared) => {
+		for (const warning of prepared.warnings) {
+			params.log.warn(`[${warning.code}] ${warning.message}`);
+		}
+	};
+	const prepareSafely = async (config) => {
+		try {
+			return await prepareSnapshot({ config });
+		} catch (error) {
+			throw normalizeRuntimeError(error, "SECRETS_RESOLUTION_FAILED", "One or more required secret references could not be resolved. Run `fased secrets audit --check` locally before retrying.");
+		}
+	};
+	const requireReloadableSnapshot = (snapshot) => {
+		if (!snapshot.exists) {
+			throw missingSnapshotError();
+		}
+		if (!snapshot.valid) {
+			throw invalidSnapshotError(snapshot);
+		}
+	};
+	const assertSnapshotStillCurrent = async (expected) => {
+		const current = await params.readConfigSnapshot();
+		requireReloadableSnapshot(current);
+		if (!sameSourceSnapshot(expected, current)) {
+			throw staleSourceError();
+		}
+	};
+	const restoreSnapshot = (previous) => {
+		try {
+			if (previous) {
+				activateSnapshot(previous);
+			} else {
+				clearSnapshot();
+			}
+		} catch {
+			clearSnapshot();
+		}
+	};
+	const activateStartup = (snapshot) => runTracked(async (generation) => {
+		if (!snapshot.valid) {
+			throw invalidSnapshotError(snapshot);
+		}
+		assertCurrent(generation);
+		const prepared = await prepareSafely(snapshot.config);
+		assertCurrent(generation);
+		activateSnapshot(prepared);
+		activeSourceConfig = cloneConfig(snapshot.config);
+		logWarnings(prepared);
+		return prepared;
+	});
+	const activateHotReload = (snapshot, transaction) => runTracked(async (generation) => {
+		try {
+			requireReloadableSnapshot(snapshot);
+			assertCurrent(generation);
+			await assertSnapshotStillCurrent(snapshot);
+			assertCurrent(generation);
+			const prepared = await prepareSafely(snapshot.config);
+			assertCurrent(generation);
+			await assertSnapshotStillCurrent(snapshot);
+			assertCurrent(generation);
+			const previous = getActiveSnapshot();
+			activateSnapshot(prepared);
+			try {
+				await transaction.apply(prepared.config);
+				assertCurrent(generation);
+				await assertSnapshotStillCurrent(snapshot);
+				assertCurrent(generation);
+			} catch (error) {
+				restoreSnapshot(previous);
+				if (previous) {
+					try {
+						await transaction.rollback(previous.config);
+					} catch (rollbackError) {
+						throw runtimeError("SECRETS_HOT_APPLY_FAILED", "Gateway hot reload failed. The last-known-good secret snapshot was restored, but one or more live components could not be restored and remain stopped.", rollbackError);
+					}
+				}
+				throw normalizeRuntimeError(error, "SECRETS_HOT_APPLY_FAILED", "Gateway hot reload failed; the last-known-good secret snapshot and live component state were restored.");
+			}
+			activeSourceConfig = cloneConfig(snapshot.config);
+			logWarnings(prepared);
+			recordReloadSuccess();
+			return prepared;
+		} catch (error) {
+			const safe = normalizeRuntimeError(error, "SECRETS_RELOAD_FAILED", "Secret reload failed without changing the active runtime snapshot.");
+			recordReloadFailure(safe);
+			throw safe;
+		}
+	});
+	const validateRestart = (snapshot) => runTracked(async (generation) => {
+		try {
+			requireReloadableSnapshot(snapshot);
+			assertCurrent(generation);
+			await assertSnapshotStillCurrent(snapshot);
+			assertCurrent(generation);
+			const prepared = await prepareSafely(snapshot.config);
+			assertCurrent(generation);
+			await assertSnapshotStillCurrent(snapshot);
+			assertCurrent(generation);
+			logWarnings(prepared);
+			return { warningCount: prepared.warnings.length };
+		} catch (error) {
+			const safe = normalizeRuntimeError(error, "SECRETS_RELOAD_FAILED", "Secret validation failed; the Gateway restart was not scheduled.");
+			recordReloadFailure(safe);
+			throw safe;
+		}
+	});
+	const reloadFromConfig = () => runTracked(async (generation) => {
+		try {
+			assertCurrent(generation);
+			const snapshot = await params.readConfigSnapshot();
+			requireReloadableSnapshot(snapshot);
+			if (!activeSourceConfig) {
+				throw runtimeError("SECRETS_RELOAD_FAILED", "Secret reload is unavailable before the startup snapshot is active.");
+			}
+			assertManualSourceChangeAllowed({
+				previous: activeSourceConfig,
+				next: snapshot.config
+			});
+			const prepared = await prepareSafely(snapshot.config);
+			assertCurrent(generation);
+			await assertSnapshotStillCurrent(snapshot);
+			assertCurrent(generation);
+			activateSnapshot(prepared);
+			activeSourceConfig = cloneConfig(snapshot.config);
+			logWarnings(prepared);
+			recordReloadSuccess();
+			return { warningCount: prepared.warnings.length };
+		} catch (error) {
+			const safe = normalizeRuntimeError(error, "SECRETS_RELOAD_FAILED", "Secret reload failed without changing the active runtime snapshot.");
+			recordReloadFailure(safe);
+			throw safe;
+		}
+	});
+	const shutdown = () => {
+		if (shutdownPromise) {
+			return shutdownPromise;
+		}
+		closed = true;
+		latestGeneration += 1;
+		shutdownPromise = (async () => {
+			await operationTail;
+			activeSourceConfig = null;
+			degraded = false;
+			clearSnapshot();
+		})();
+		return shutdownPromise;
+	};
+	return {
+		activateStartup,
+		activateHotReload,
+		validateRestart,
+		reloadFromConfig,
+		shutdown
+	};
+}
+
+//#endregion
+export { createGatewaySecretsRuntimeController, sanitizeGatewaySecretsRuntimeError };