@camstack/addon-provider-bosch 0.1.49 → 0.1.51

package/dist/homecom/addon.js

@@ -1,7 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_bosch_instances = require("../bosch-instances-BHFcR1TK.js");
-const require_account_integration_offline = require("../account-integration-offline-Dcx0sq_v.js");
+const require_bosch_instances = require("../bosch-instances-CYBnIcHg.js");
+const require_account_integration_offline = require("../account-integration-offline-7CH3r5jI.js");
 let node_crypto = require("node:crypto");
+let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_url = require("node:url");
 //#region src/homecom/config.ts
 var HOMECOM_BRANDS = ["bosch", "buderus"];
 var HomeComBrandSchema = require_bosch_instances._enum(HOMECOM_BRANDS);
@@ -178,6 +182,280 @@ function buildHomeComFormSchema() {
 		]
 	}] };
 }
+var EXPLORER_MAX_NODES_CAP = 1500;
+var VALUE_MAX_CHARS = 200;
+/** Roots walked when `/` does not list its children. */
+var EXPLORER_SEED_ROOTS = [
+	"/system",
+	"/heatSources",
+	"/heatingCircuits",
+	"/dhwCircuits",
+	"/gateway",
+	"/notifications",
+	"/recordings",
+	"/devices",
+	"/solarCircuits",
+	"/ventilation"
+];
+/** Under the 60 s UDS request timeout a forked addon's action answers within. */
+var EXPLORER_MAX_DEADLINE_MS = 5e4;
+var DROPPED_SAMPLE_MAX = 20;
+var UNVISITED_SAMPLE_MAX = 100;
+var PATH_SHAPE = /^\/(?:[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*)?$/;
+/**
+* A resource path this walker will request: absolute, plain segments, and no `.` or `..`
+* segment — URL resolution would otherwise lift the request out of the gateway's tree.
+*/
+function isResourcePath(path) {
+	if (!PATH_SHAPE.test(path)) return false;
+	return path.split("/").slice(1).every((segment) => segment !== "." && segment !== "..");
+}
+var explorerOutcomeSchema = require_bosch_instances._enum([
+	"ok",
+	"forbidden",
+	"not-found",
+	"rate-limited",
+	"error"
+]);
+var exploredResourceSchema = require_bosch_instances.object({
+	path: require_bosch_instances.string(),
+	httpStatus: require_bosch_instances.number(),
+	outcome: explorerOutcomeSchema,
+	type: require_bosch_instances.string().optional(),
+	value: require_bosch_instances.union([
+		require_bosch_instances.string(),
+		require_bosch_instances.number(),
+		require_bosch_instances.boolean(),
+		require_bosch_instances._null()
+	]).optional(),
+	unit: require_bosch_instances.string().optional(),
+	writeable: require_bosch_instances.boolean().optional(),
+	recordable: require_bosch_instances.boolean().optional(),
+	allowedValues: require_bosch_instances.array(require_bosch_instances.string()).optional(),
+	minValue: require_bosch_instances.number().optional(),
+	maxValue: require_bosch_instances.number().optional(),
+	childCount: require_bosch_instances.number().optional(),
+	/** References of this container that were not a walkable path. */
+	droppedReferences: require_bosch_instances.number().optional(),
+	error: require_bosch_instances.string().optional()
+});
+var explorerSummarySchema = require_bosch_instances.object({
+	ok: require_bosch_instances.number(),
+	forbidden: require_bosch_instances.number(),
+	"not-found": require_bosch_instances.number(),
+	"rate-limited": require_bosch_instances.number(),
+	error: require_bosch_instances.number()
+});
+var explorerStopReasonSchema = require_bosch_instances._enum([
+	"complete",
+	"max-nodes",
+	"rate-limited",
+	"deadline"
+]);
+function isRecord$3(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finite$1(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function text$1(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function truncate(value) {
+	return value.length > VALUE_MAX_CHARS ? `${value.slice(0, VALUE_MAX_CHARS - 1)}…` : value;
+}
+function shownValue(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "string") return truncate(value);
+	return truncate(JSON.stringify(value));
+}
+function outcomeOf(status) {
+	if (status >= 200 && status < 300) return "ok";
+	if (status === 403) return "forbidden";
+	if (status === 404) return "not-found";
+	if (status === 429) return "rate-limited";
+	return "error";
+}
+/** What a reference names: its `id`, else the part of its `uri` after `/resource`. */
+function referenceText(ref) {
+	if (!isRecord$3(ref)) return null;
+	const id = text$1(ref["id"]);
+	if (id !== void 0 && id.startsWith("/")) return id;
+	const uri = text$1(ref["uri"]);
+	if (uri === void 0) return id ?? null;
+	const at = uri.indexOf("/resource/");
+	if (at < 0) return uri;
+	return uri.slice(at + 9);
+}
+/** The walkable resource path a reference names, or null. */
+function referencePath(ref) {
+	const path = referenceText(ref);
+	return path !== null && isResourcePath(path) ? path : null;
+}
+function referencesOf(body) {
+	if (!isRecord$3(body)) return null;
+	const refs = body["references"];
+	if (!Array.isArray(refs)) return null;
+	const paths = [];
+	const dropped = [];
+	for (const ref of refs) {
+		const path = referencePath(ref);
+		if (path !== null) paths.push(path);
+		else dropped.push(truncate(referenceText(ref) ?? JSON.stringify(ref) ?? "undefined"));
+	}
+	return {
+		total: refs.length,
+		paths,
+		dropped
+	};
+}
+function describeLeaf(path, status, body) {
+	if (!isRecord$3(body)) return {
+		path,
+		httpStatus: status,
+		outcome: "ok"
+	};
+	const allowed = body["allowedValues"];
+	const allowedValues = Array.isArray(allowed) ? allowed.map((v) => truncate(String(v))) : void 0;
+	const type = text$1(body["type"]);
+	const unit = text$1(body["unitOfMeasure"]);
+	const minValue = finite$1(body["minValue"]);
+	const maxValue = finite$1(body["maxValue"]);
+	const writeable = body["writeable"];
+	const recordable = body["recordable"];
+	return {
+		path,
+		httpStatus: status,
+		outcome: "ok",
+		...type !== void 0 ? { type } : {},
+		..."value" in body ? { value: shownValue(body["value"]) } : {},
+		...unit !== void 0 ? { unit } : {},
+		...typeof writeable === "number" || typeof writeable === "boolean" ? { writeable: Boolean(writeable) } : {},
+		...typeof recordable === "number" || typeof recordable === "boolean" ? { recordable: Boolean(recordable) } : {},
+		...allowedValues !== void 0 ? { allowedValues } : {},
+		...minValue !== void 0 ? { minValue } : {},
+		...maxValue !== void 0 ? { maxValue } : {}
+	};
+}
+function emptySummary() {
+	return {
+		ok: 0,
+		forbidden: 0,
+		"not-found": 0,
+		"rate-limited": 0,
+		error: 0
+	};
+}
+function clampDeadline(requested) {
+	return Math.min(Math.max(Math.floor(requested ?? 45e3), 1), EXPLORER_MAX_DEADLINE_MS);
+}
+function clampNodes(requested) {
+	return Math.min(Math.max(Math.floor(requested ?? 400), 1), EXPLORER_MAX_NODES_CAP);
+}
+var defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+async function exploreHomeComResources(input) {
+	const root = input.root ?? "/";
+	if (!isResourcePath(root)) throw new Error(`Not a resource path: ${root}`);
+	const maxNodes = clampNodes(input.maxNodes);
+	const delayMs = Math.max(input.delayMs ?? 150, 150);
+	const sleep = input.sleep ?? defaultSleep;
+	const now = input.now ?? Date.now;
+	const deadlineAt = now() + clampDeadline(input.deadlineMs);
+	const queue = [root];
+	const queued = new Set([root]);
+	const resources = [];
+	const summary = emptySummary();
+	let calls = 0;
+	let stoppedBy = "complete";
+	let droppedReferences = 0;
+	const droppedSamples = [];
+	const enqueue = (paths) => {
+		for (const path of paths) {
+			if (queued.has(path)) continue;
+			queued.add(path);
+			queue.push(path);
+		}
+	};
+	while (queue.length > 0) {
+		if (calls >= maxNodes) {
+			stoppedBy = "max-nodes";
+			break;
+		}
+		if (now() + (calls > 0 ? delayMs : 0) >= deadlineAt) {
+			stoppedBy = "deadline";
+			break;
+		}
+		const path = queue.shift();
+		if (path === void 0) break;
+		if (calls > 0) await sleep(delayMs);
+		calls += 1;
+		let answer;
+		try {
+			answer = await input.read(path);
+		} catch (err) {
+			const error = err instanceof Error ? err.message : String(err);
+			resources.push({
+				path,
+				httpStatus: 0,
+				outcome: "error",
+				error
+			});
+			summary.error += 1;
+			continue;
+		}
+		const outcome = outcomeOf(answer.status);
+		summary[outcome] += 1;
+		if (outcome === "rate-limited") {
+			resources.push({
+				path,
+				httpStatus: answer.status,
+				outcome
+			});
+			stoppedBy = "rate-limited";
+			break;
+		}
+		if (outcome !== "ok") {
+			resources.push({
+				path,
+				httpStatus: answer.status,
+				outcome
+			});
+			if (path === "/" && root === "/") enqueue(EXPLORER_SEED_ROOTS);
+			continue;
+		}
+		const children = referencesOf(answer.body);
+		if (children !== null) {
+			const type = isRecord$3(answer.body) ? text$1(answer.body["type"]) : void 0;
+			resources.push({
+				path,
+				httpStatus: answer.status,
+				outcome,
+				type: type ?? "refEnum",
+				childCount: children.total,
+				...children.dropped.length > 0 ? { droppedReferences: children.dropped.length } : {}
+			});
+			droppedReferences += children.dropped.length;
+			for (const ref of children.dropped) if (droppedSamples.length < DROPPED_SAMPLE_MAX) droppedSamples.push(`${path} -> ${ref}`);
+			enqueue(children.paths);
+			continue;
+		}
+		resources.push(describeLeaf(path, answer.status, answer.body));
+		if (path === "/" && root === "/") enqueue(EXPLORER_SEED_ROOTS);
+	}
+	return {
+		root,
+		resources,
+		summary,
+		stoppedBy,
+		unvisited: queue.length,
+		unvisitedPaths: queue.slice(0, UNVISITED_SAMPLE_MAX),
+		droppedReferences,
+		droppedSamples
+	};
+}
 //#endregion
 //#region src/homecom/custom-actions.ts
 var gatewayChoice = require_bosch_instances.object({
@@ -186,6 +464,27 @@ var gatewayChoice = require_bosch_instances.object({
 	brand: HomeComBrandSchema,
 	region: HomeComRegionSchema
 });
+var exploreResourcesInput = require_bosch_instances.object({
+	/** The HomeCom integration instance; may be omitted when exactly one is connected. */
+	integrationId: require_bosch_instances.string().min(1).optional(),
+	root: require_bosch_instances.string().refine(isResourcePath, "an absolute resource path such as /heatSources, no . or .. segment").optional(),
+	maxNodes: require_bosch_instances.number().int().min(1).max(EXPLORER_MAX_NODES_CAP).optional(),
+	/** Wall-clock budget; the walk returns what it has, with `stoppedBy: 'deadline'`. */
+	deadlineMs: require_bosch_instances.number().int().min(1e3).max(EXPLORER_MAX_DEADLINE_MS).optional()
+});
+var exploreResourcesOutput = require_bosch_instances.object({
+	integrationId: require_bosch_instances.string(),
+	/** Null when the integration has no snapshot yet: unknown, not empty. */
+	gatewayId: require_bosch_instances.string().nullable(),
+	root: require_bosch_instances.string(),
+	stoppedBy: explorerStopReasonSchema,
+	unvisited: require_bosch_instances.number(),
+	unvisitedPaths: require_bosch_instances.array(require_bosch_instances.string()),
+	droppedReferences: require_bosch_instances.number(),
+	droppedSamples: require_bosch_instances.array(require_bosch_instances.string()),
+	summary: explorerSummarySchema,
+	resources: require_bosch_instances.array(exploredResourceSchema)
+});
 var homeComActions = require_bosch_instances.defineCustomActions({
 	beginSignIn: require_bosch_instances.customAction(require_bosch_instances.object({}), require_bosch_instances.object({
 		attemptId: require_bosch_instances.string().min(1),
@@ -219,9 +518,95 @@ var homeComActions = require_bosch_instances.defineCustomActions({
 	}), {
 		kind: "mutation",
 		auth: "admin"
+	}),
+	/** Read-only walk of the gateway's resource tree, for diagnosing what it serves. */
+	exploreResources: require_bosch_instances.customAction(exploreResourcesInput, exploreResourcesOutput, {
+		kind: "query",
+		auth: "admin"
 	})
 });
 //#endregion
+//#region src/homecom/homecom-explore-action.ts
+/** The action refused before it walked anything; `reason` says why. */
+var HomeComExploreRefusedError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "HomeComExploreRefusedError";
+		this.reason = reason;
+	}
+};
+function pickIntegration(input, connected) {
+	if (input.integrationId !== void 0) return input.integrationId;
+	if (connected.length === 1 && connected[0] !== void 0) return connected[0];
+	if (connected.length === 0) throw new HomeComExploreRefusedError("not-connected", "No HomeCom integration is connected.");
+	throw new HomeComExploreRefusedError("ambiguous", `Several HomeCom integrations are connected; name one with integrationId (${connected.join(", ")}).`);
+}
+/**
+* The `exploreResources` action: a read-only walk of one integration's gateway. One walk
+* per integration at a time — a second call while one runs is refused, never queued.
+*/
+function createHomeComExploreAction(deps) {
+	const running = /* @__PURE__ */ new Set();
+	return async (input) => {
+		const integrationId = pickIntegration(input, deps.listConnected());
+		if (running.has(integrationId)) throw new HomeComExploreRefusedError("already-running", `A resource walk is already running for HomeCom integration ${integrationId}.`);
+		const client = deps.getClient(integrationId);
+		if (client === null) throw new HomeComExploreRefusedError("not-connected", `HomeCom integration ${integrationId} is not connected.`);
+		running.add(integrationId);
+		try {
+			return await walk(input, integrationId, client, deps);
+		} finally {
+			running.delete(integrationId);
+		}
+	};
+}
+async function walk(input, integrationId, client, deps) {
+	const result = await exploreHomeComResources({
+		read: (path) => client.readResource(path),
+		...input.root !== void 0 ? { root: input.root } : {},
+		...input.maxNodes !== void 0 ? { maxNodes: input.maxNodes } : {},
+		...input.deadlineMs !== void 0 ? { deadlineMs: input.deadlineMs } : {},
+		...deps.sleep !== void 0 ? { sleep: deps.sleep } : {},
+		...deps.now !== void 0 ? { now: deps.now } : {}
+	});
+	const gatewayId = deps.getGatewayId(integrationId);
+	if (result.droppedReferences > 0) deps.logger.warn("HomeCom resource walk dropped references that are not a walkable path", {
+		tags: { integrationId },
+		meta: {
+			gatewayId,
+			droppedReferences: result.droppedReferences,
+			samples: result.droppedSamples
+		}
+	});
+	deps.logger.info("HomeCom resource tree explored", {
+		tags: { integrationId },
+		meta: {
+			gatewayId,
+			root: result.root,
+			visited: result.resources.length,
+			stoppedBy: result.stoppedBy,
+			unvisited: result.unvisited,
+			droppedReferences: result.droppedReferences,
+			...result.summary
+		}
+	});
+	return {
+		integrationId,
+		gatewayId,
+		...result
+	};
+}
+/** The addon's deps: registered integrations that hold a live client; gateway from the snapshot. */
+function homeComExploreDeps(wiring) {
+	return {
+		listConnected: () => wiring.registry.list().filter((id) => wiring.connections.getClient(id) !== null),
+		getClient: (id) => wiring.connections.getClient(id),
+		getGatewayId: (id) => wiring.connections.getSnapshot(id)?.gateway.gatewayId ?? null,
+		logger: wiring.logger
+	};
+}
+//#endregion
 //#region src/homecom/homecom-device-type.ts
 /**
 * Device types the PointT gateway list reports. The set is the one the MIT
@@ -267,6 +652,210 @@ function unsupportedDeviceTypeMessage(deviceType) {
 	return new HomeComUnknownDeviceTypeError(deviceType ?? "(missing)").message;
 }
 //#endregion
+//#region src/homecom/homecom-bridge.ts
+/**
+* The HomeCom Python bridge: one `python/homecom_worker.py` run per poll or write, built on
+* the MIT `homecom_alt` library (pinned in `python/requirements.txt`).
+*
+* The access token travels ONLY in the JSON written to the child's stdin — never in argv,
+* never in the environment — and the worker never prints it. The OAuth refresh stays in
+* TypeScript: the worker answers `auth` and the caller refreshes and runs it again.
+*/
+var HOMECOM_BRIDGE_DEVICE_TYPES = [
+	"k40",
+	"k30",
+	"icom"
+];
+function isBridgeDeviceType(value) {
+	return HOMECOM_BRIDGE_DEVICE_TYPES.some((type) => type === value);
+}
+var SettingSchema = require_bosch_instances.object({
+	value: require_bosch_instances.union([require_bosch_instances.string(), require_bosch_instances.number()]).nullable(),
+	min: require_bosch_instances.number().nullable(),
+	max: require_bosch_instances.number().nullable(),
+	allowed: require_bosch_instances.array(require_bosch_instances.string()),
+	writeable: require_bosch_instances.boolean().nullable()
+});
+var MaybeSetting = SettingSchema.nullable();
+var HeatingCircuitSchema = require_bosch_instances.object({
+	id: require_bosch_instances.string(),
+	/** The name the gateway gave the circuit in its reference listing, when it gave one. */
+	name: require_bosch_instances.string().nullable().default(null),
+	operationMode: MaybeSetting,
+	heatCoolMode: MaybeSetting,
+	currentSuWiMode: MaybeSetting,
+	suWiSwitchMode: MaybeSetting,
+	roomTemp: require_bosch_instances.number().nullable(),
+	humidity: require_bosch_instances.number().nullable(),
+	currentRoomSetpoint: MaybeSetting,
+	manualRoomSetpoint: MaybeSetting,
+	coolingRoomSetpoint: MaybeSetting,
+	comfortSetpoint: MaybeSetting,
+	ecoSetpoint: MaybeSetting,
+	maxFlowTemp: MaybeSetting
+});
+var DhwCircuitSchema = require_bosch_instances.object({
+	id: require_bosch_instances.string(),
+	operationMode: MaybeSetting,
+	actualTemp: require_bosch_instances.number().nullable(),
+	currentTemperatureLevel: MaybeSetting,
+	charge: MaybeSetting,
+	chargeDuration: MaybeSetting,
+	singleChargeSetpoint: MaybeSetting,
+	currentSetpoint: MaybeSetting,
+	temperatureLevels: require_bosch_instances.record(require_bosch_instances.string(), SettingSchema)
+});
+/**
+* One GET of a heat-pump-only heat-source resource: `refused` (403/500) still proves a heat
+* pump the gateway will not let us read, `absent` (404) is a boiler, `transient` proves nothing.
+*/
+var ProbeOutcomeSchema = require_bosch_instances._enum([
+	"answered",
+	"refused",
+	"absent",
+	"transient"
+]);
+var ReadingSchema = require_bosch_instances.object({
+	heatSource: require_bosch_instances.object({
+		heatPumpType: require_bosch_instances.string().nullable(),
+		supplyTemp: require_bosch_instances.number().nullable(),
+		returnTemp: require_bosch_instances.number().nullable(),
+		modulationPct: require_bosch_instances.number().nullable(),
+		pressureBar: require_bosch_instances.number().nullable(),
+		starts: require_bosch_instances.number().nullable(),
+		outdoorTemp: require_bosch_instances.number().nullable(),
+		thermalKwh: require_bosch_instances.number().nullable(),
+		electricalKwh: require_bosch_instances.number().nullable()
+	}),
+	system: require_bosch_instances.object({
+		away: MaybeSetting,
+		silent: MaybeSetting,
+		additionalHeater: MaybeSetting,
+		holiday: MaybeSetting
+	}),
+	heatingCircuits: require_bosch_instances.array(HeatingCircuitSchema),
+	dhwCircuits: require_bosch_instances.array(DhwCircuitSchema),
+	/** Asked only when the bulk read left the heat-pump type unknown; path → outcome. */
+	heatSourceProbe: require_bosch_instances.record(require_bosch_instances.string(), ProbeOutcomeSchema).default({})
+});
+var FailureKind = require_bosch_instances._enum([
+	"auth",
+	"unreachable",
+	"refused",
+	"api",
+	"protocol",
+	"bad-request"
+]);
+var AnswerSchema = require_bosch_instances.union([
+	require_bosch_instances.object({
+		ok: require_bosch_instances.literal(true),
+		reading: ReadingSchema
+	}),
+	require_bosch_instances.object({
+		ok: require_bosch_instances.literal(true),
+		written: require_bosch_instances.string()
+	}),
+	require_bosch_instances.object({
+		ok: require_bosch_instances.literal(false),
+		kind: FailureKind,
+		error: require_bosch_instances.string()
+	})
+]);
+/** A failed bridge run. The message never carries more than a short stderr tail. */
+var HomeComBridgeError = class extends Error {
+	name = "HomeComBridgeError";
+	kind;
+	constructor(kind, message) {
+		super(message);
+		this.kind = kind;
+	}
+};
+/** A K40 bulk read is several bulk POSTs plus per-circuit GETs, 15 s each at most. */
+var DEFAULT_READ_TIMEOUT_MS = 5e4;
+var DEFAULT_WRITE_TIMEOUT_MS = 3e4;
+var MAX_STDOUT_BYTES = 2 * 1024 * 1024;
+function runWorker(deps, request, timeoutMs) {
+	const spawnFn = deps.spawnFn ?? node_child_process.spawn;
+	return new Promise((resolve, reject) => {
+		const child = spawnFn(deps.pythonPath, [deps.scriptPath], { stdio: "pipe" });
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		const finish = (action) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			action();
+		};
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			finish(() => reject(new HomeComBridgeError("timeout", `the HomeCom bridge did not answer within ${timeoutMs / 1e3}s`)));
+		}, timeoutMs);
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString("utf8");
+			if (stdout.length > MAX_STDOUT_BYTES) {
+				child.kill("SIGKILL");
+				finish(() => reject(new HomeComBridgeError("protocol", "the HomeCom bridge wrote too much output")));
+			}
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr = (stderr + chunk.toString("utf8")).slice(-16384);
+		});
+		child.on("error", (err) => {
+			finish(() => reject(new HomeComBridgeError("protocol", `cannot start the HomeCom bridge: ${err.message}`)));
+		});
+		child.on("close", (code) => {
+			finish(() => {
+				let json;
+				try {
+					json = JSON.parse(stdout.trim());
+				} catch {
+					const tail = stderr.trim().slice(-300) || "no stderr";
+					reject(new HomeComBridgeError("protocol", `the HomeCom bridge produced no JSON (exit ${code ?? "null"}): ${tail}`));
+					return;
+				}
+				const parsed = AnswerSchema.safeParse(json);
+				if (!parsed.success) {
+					reject(new HomeComBridgeError("protocol", "the HomeCom bridge answered an unknown shape"));
+					return;
+				}
+				resolve(parsed.data);
+			});
+		});
+		child.stdin.on("error", () => void 0);
+		child.stdin.end(JSON.stringify(request));
+	});
+}
+function failure(answer) {
+	return answer.ok ? null : new HomeComBridgeError(answer.kind, answer.error);
+}
+function createHomeComBridge(deps) {
+	const readTimeoutMs = deps.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS;
+	const writeTimeoutMs = deps.writeTimeoutMs ?? DEFAULT_WRITE_TIMEOUT_MS;
+	return {
+		async read(target) {
+			const answer = await runWorker(deps, {
+				...target,
+				action: "read"
+			}, readTimeoutMs);
+			const failed = failure(answer);
+			if (failed !== null) throw failed;
+			if (!("reading" in answer)) throw new HomeComBridgeError("protocol", "the HomeCom bridge answered a read with no reading");
+			return answer.reading;
+		},
+		async write(target, write) {
+			const answer = await runWorker(deps, {
+				...target,
+				action: "write",
+				write
+			}, writeTimeoutMs);
+			const failed = failure(answer);
+			if (failed !== null) throw failed;
+			if (!("written" in answer) || answer.written !== write.op) throw new HomeComBridgeError("protocol", "the HomeCom bridge did not confirm the write");
+		}
+	};
+}
+//#endregion
 //#region src/homecom/homecom-domain-mapping.ts
 var MODE_MAP = {
 	Off: "off",
@@ -342,6 +931,280 @@ function waterHeaterSliceFromDhw(dhw, nowMs) {
 		lastChangedAt: nowMs
 	};
 }
+//#endregion
+//#region src/homecom/homecom-heat-pump.ts
+/** A write the gateway would refuse, caught before it is sent. */
+var HomeComHeatPumpRefusalError = class extends Error {
+	name = "HomeComHeatPumpRefusalError";
+};
+var COOLING_VALUES = ["cool", "cooling"];
+/** The current level's own temperature, or the gateway's current setpoint (icom). */
+function dhwTargetSetting(dhw) {
+	const level = dhw.currentTemperatureLevel?.value;
+	if (typeof level === "string" && level !== "off") {
+		const own = dhw.temperatureLevels[level];
+		if (own !== void 0) return own;
+	}
+	return dhw.currentSetpoint;
+}
+/** True when the circuit is cooling now: heat/cool mode or the season says so. */
+function circuitIsCooling(hc) {
+	const mode = hc.heatCoolMode?.value;
+	const season = hc.currentSuWiMode?.value;
+	return typeof mode === "string" && COOLING_VALUES.includes(mode) || typeof season === "string" && COOLING_VALUES.includes(season);
+}
+function numberValue$1(s) {
+	return s !== null && typeof s.value === "number" ? s.value : null;
+}
+function hcReading(hc) {
+	const target = circuitIsCooling(hc) ? numberValue$1(hc.coolingRoomSetpoint) ?? numberValue$1(hc.currentRoomSetpoint) : numberValue$1(hc.currentRoomSetpoint) ?? numberValue$1(hc.manualRoomSetpoint);
+	return {
+		id: hc.id,
+		kind: "hc",
+		currentTemp: hc.roomTemp,
+		targetTemp: target,
+		operationMode: hc.operationMode,
+		heatCoolMode: hc.heatCoolMode,
+		summerWinter: hc.suWiSwitchMode,
+		comfort: hc.comfortSetpoint,
+		eco: hc.ecoSetpoint,
+		maxFlow: hc.maxFlowTemp,
+		level: null,
+		chargeDuration: null,
+		charge: null
+	};
+}
+function dhwReading(dhw) {
+	return {
+		id: dhw.id,
+		kind: "dhw",
+		currentTemp: dhw.actualTemp,
+		targetTemp: numberValue$1(dhwTargetSetting(dhw)),
+		operationMode: dhw.operationMode,
+		heatCoolMode: null,
+		summerWinter: null,
+		comfort: null,
+		eco: null,
+		maxFlow: null,
+		level: dhw.currentTemperatureLevel,
+		chargeDuration: dhw.chargeDuration,
+		charge: dhw.charge
+	};
+}
+function heatPumpReadingFrom(bridge) {
+	const hs = bridge.heatSource;
+	return {
+		circuits: [...bridge.heatingCircuits.map(hcReading), ...bridge.dhwCircuits.map(dhwReading)],
+		heatPumpType: hs.heatPumpType,
+		heatSourceRefused: Object.values(bridge.heatSourceProbe).some((outcome) => outcome === "answered" || outcome === "refused"),
+		silent: bridge.system.silent,
+		away: bridge.system.away,
+		additionalHeater: bridge.system.additionalHeater,
+		holiday: bridge.system.holiday,
+		compressorPct: hs.modulationPct,
+		supply: hs.supplyTemp,
+		return: hs.returnTemp,
+		outdoor: hs.outdoorTemp,
+		thermalKwh: hs.thermalKwh,
+		electricalKwh: hs.electricalKwh,
+		pressureBar: hs.pressureBar,
+		starts: hs.starts
+	};
+}
+/**
+* True when the gateway should be offered as a system device (`hp:0`).
+*
+* Only evidence a gas boiler on the same controller family cannot give counts: a heat-pump
+* type on the heat source, a heat-pump-only heat-source resource the gateway refuses (403/500,
+* never a 404 or a transient failure), the silent mode or the additional heater
+* (heat-pump-only resources), or a heating circuit that can cool. Away, holiday, flow, return, modulation,
+* pressure and starts are answered by a boiler too.
+*/
+function hasSystemDevice(reading) {
+	if (reading.heatPumpType !== null || reading.heatSourceRefused) return true;
+	if (reading.silent !== null || reading.additionalHeater !== null) return true;
+	return reading.circuits.some((c) => c.kind === "hc" && offersCooling(c.heatCoolMode));
+}
+function offersCooling(setting) {
+	if (setting === null) return false;
+	const value = setting.value;
+	if (typeof value === "string" && COOLING_VALUES.includes(value)) return true;
+	return setting.allowed.some((allowed) => COOLING_VALUES.includes(allowed));
+}
+function heatPumpStatusFrom(reading, now) {
+	return {
+		circuits: reading.circuits.map(circuitOf),
+		system: {
+			silent: optionOf(reading.silent),
+			away: optionOf(reading.away),
+			additionalHeater: optionOf(reading.additionalHeater),
+			holiday: optionOf(reading.holiday)
+		},
+		power: {
+			thermalW: null,
+			electricalW: null,
+			compressorPct: reading.compressorPct
+		},
+		temperatures: {
+			supply: reading.supply,
+			return: reading.return,
+			outdoor: reading.outdoor
+		},
+		energy: {
+			thermalKwh: reading.thermalKwh,
+			electricalKwh: reading.electricalKwh
+		},
+		waterPressureBar: reading.pressureBar,
+		starts: reading.starts,
+		lastFetchedAt: now
+	};
+}
+function circuitOf(c) {
+	const kind = kindOf(c);
+	return {
+		id: c.id,
+		kind,
+		label: labelOf(c),
+		icon: kind === "dhw" ? "droplets" : kind === "cooling" ? "snowflake" : "flame",
+		currentTemp: c.currentTemp,
+		targetTemp: c.targetTemp,
+		mode: modeValue(c.operationMode),
+		active: null,
+		operationMode: optionOf(c.operationMode),
+		heatCoolMode: optionOf(c.heatCoolMode),
+		summerWinter: optionOf(c.summerWinter),
+		comfortSetpoint: rangeOf(c.comfort),
+		ecoSetpoint: rangeOf(c.eco),
+		maxFlowTemp: rangeOf(c.maxFlow),
+		temperatureLevel: optionOf(c.level),
+		chargeDuration: rangeOf(c.chargeDuration),
+		extraHotWater: c.charge === null ? null : textOf$1(c.charge) === "start"
+	};
+}
+function kindOf(c) {
+	if (c.kind === "dhw") return "dhw";
+	const mode = textOf$1(c.heatCoolMode);
+	return mode !== null && COOLING_VALUES.includes(mode) ? "cooling" : "heating";
+}
+function labelOf(c) {
+	const n = c.id.replace(/^\D+/, "");
+	if (c.kind === "dhw") return n === "1" || n === "" ? "Hot water" : `Hot water ${n}`;
+	return n === "" ? "Heating circuit" : `Heating circuit ${n}`;
+}
+function textOf$1(s) {
+	return s !== null && typeof s.value === "string" && s.value.length > 0 ? s.value : null;
+}
+/**
+* A mode the gateway answered with an empty value is off (or "none" when the
+* gateway did not list off). A mode it did not answer at all stays null.
+*/
+function modeValue(s) {
+	if (s === null || typeof s.value !== "string") return null;
+	if (s.value.length > 0) return s.value;
+	return s.allowed.includes("off") ? "off" : "none";
+}
+function optionOf(s) {
+	if (s === null) return null;
+	return {
+		value: modeValue(s),
+		allowed: [...s.allowed]
+	};
+}
+function rangeOf(s) {
+	if (s === null) return null;
+	return {
+		value: numberValue$1(s),
+		min: s.min,
+		max: s.max,
+		step: null
+	};
+}
+function requireCircuit(reading, circuitId, want) {
+	const found = reading.circuits.find((c) => c.id === circuitId && c.kind === want);
+	if (found === void 0) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump has no ${want} circuit ${circuitId}`);
+	return found;
+}
+/** The accepted value of an option setting, or a refusal naming why the gateway would refuse. */
+function acceptedOption(s, what, mode) {
+	if (s === null) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is not available`);
+	if (s.writeable === false || s.allowed.length === 0) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is read-only on this gateway`);
+	if (!s.allowed.includes(mode)) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: "${mode}" is not an accepted value of ${what} (${s.allowed.join(", ")})`);
+	return mode;
+}
+/** The value of a range write, within the limits the gateway gave, or a refusal. */
+function acceptedRange(s, what, value) {
+	if (s === null) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is not available`);
+	if (s.writeable === false) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is read-only on this gateway`);
+	if (!Number.isFinite(value)) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} needs a finite number`);
+	if (s.min === null || s.max === null) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} has no limits from the gateway`);
+	if (value < s.min || value > s.max) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${value} is outside ${what} limits ${s.min}..${s.max}`);
+	return value;
+}
+var SYSTEM_OPS = {
+	silent: "silentMode",
+	away: "awayMode",
+	additionalHeater: "additionalHeaterMode",
+	holiday: "holidayMode"
+};
+function systemModeWrite(reading, which, mode) {
+	return {
+		op: SYSTEM_OPS[which],
+		value: acceptedOption(reading[which], `${which} mode`, mode)
+	};
+}
+var CIRCUIT_OPTION_OPS = {
+	operationMode: "hcOperationMode",
+	heatCoolMode: "hcHeatCoolMode",
+	summerWinter: "hcSuWiSwitchMode"
+};
+function circuitOptionWrite(reading, circuitId, which, mode) {
+	const circuit = requireCircuit(reading, circuitId, "hc");
+	return {
+		op: CIRCUIT_OPTION_OPS[which],
+		circuitId,
+		value: acceptedOption(circuit[which], `${circuitId} ${which}`, mode)
+	};
+}
+var DHW_OPTION_OPS = {
+	operationMode: "dhwOperationMode",
+	level: "dhwTemperatureLevel"
+};
+function dhwOptionWrite(reading, circuitId, which, mode) {
+	const circuit = requireCircuit(reading, circuitId, "dhw");
+	return {
+		op: DHW_OPTION_OPS[which],
+		circuitId,
+		value: acceptedOption(circuit[which], `${circuitId} ${which}`, mode)
+	};
+}
+var CIRCUIT_RANGE_OPS = {
+	comfort: "hcComfortSetpoint",
+	eco: "hcEcoSetpoint",
+	maxFlow: "hcMaxFlowTemp"
+};
+function circuitRangeWrite(reading, circuitId, which, value) {
+	const circuit = requireCircuit(reading, circuitId, "hc");
+	return {
+		op: CIRCUIT_RANGE_OPS[which],
+		circuitId,
+		value: acceptedRange(circuit[which], `${circuitId} ${which}`, value)
+	};
+}
+function dhwChargeDurationWrite(reading, circuitId, minutes) {
+	return {
+		op: "dhwChargeDuration",
+		circuitId,
+		value: acceptedRange(requireCircuit(reading, circuitId, "dhw").chargeDuration, `${circuitId} charge duration`, minutes)
+	};
+}
+function extraHotWaterWrite(reading, circuitId) {
+	const charge = requireCircuit(reading, circuitId, "dhw").charge;
+	return {
+		op: "dhwCharge",
+		circuitId,
+		value: acceptedOption(charge, `${circuitId} extra hot water`, "start")
+	};
+}
 var HOMECOM_PROBE_CLOCK = "/gateway/DateTime";
 var HOMECOM_PROBE_FIRMWARE = "/gateway/versionFirmware";
 var HYDRONIC_DROPPED = "heat-source, ventilation, pool and energy resources are not published on a cap";
@@ -659,575 +1522,227 @@ function refName(ref, id) {
 	const raw = ref["name"];
 	if (typeof raw !== "string") return null;
 	const trimmed = raw.trim();
-	if (trimmed.length === 0 || trimmed === id) return null;
-	return trimmed;
-}
-function referenceKeys(body, prefix) {
-	return circuitRefs(body, prefix).map((ref) => ref.id);
-}
-function indexStandard(body) {
-	const map = /* @__PURE__ */ new Map();
-	if (!isRecord$2(body) || !Array.isArray(body["references"])) return map;
-	for (const ref of body["references"]) {
-		if (!isRecord$2(ref) || typeof ref["id"] !== "string") continue;
-		const tail = ref["id"].split("/").filter((part) => part.length > 0).at(-1) ?? ref["id"];
-		const envelope = readEnvelope(ref);
-		if (envelope !== null) map.set(tail, envelope);
-	}
-	return map;
-}
-function numberOf(envelope) {
-	if (envelope === null) return null;
-	return typeof envelope.value === "number" && Number.isFinite(envelope.value) ? envelope.value : null;
-}
-function stringOf(envelope) {
-	if (envelope === null || typeof envelope.value !== "string" || envelope.value.length === 0) return null;
-	return envelope.value;
-}
-function swingOf(envelope) {
-	const value = stringOf(envelope);
-	if (value === null) return null;
-	return value === "swing";
-}
-function safeToken(value) {
-	if (value === null || !TOKEN.test(value)) return null;
-	return value;
-}
-function finite(raw) {
-	return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
-}
-function stringList(raw) {
-	if (!Array.isArray(raw)) return [];
-	const out = [];
-	for (const item of raw) if (typeof item === "string") out.push(item);
-	return out;
-}
-function isRecord$2(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
-//#region src/homecom/homecom-heat-pump.ts
-/**
-* Heat-pump resources of a hydronic gateway (D1026).
-*
-* UNVERIFIED: the paths below come from the layout of the public HomeCom Easy
-* tree as the MIT `homecom_alt` library lists it, and were not checked against a
-* live heat pump. They live in this one table so a wrong path is a one-line
-* fix, and a resource the gateway does not answer reads as `null` (never 0),
-* which the hero then simply does not draw.
-*/
-var HEAT_PUMP_PATHS = {
-	system: {
-		silent: "/heatSources/hs1/silentMode",
-		away: "/system/awayMode",
-		additionalHeater: "/heatSources/hs1/additionalHeaterMode",
-		holiday: "/system/holidayMode"
-	},
-	readings: {
-		thermalW: "/heatSources/hs1/heatPumpPower",
-		electricalW: "/heatSources/hs1/electricalPower",
-		compressorPct: "/heatSources/hs1/compressorModulation",
-		supply: "/heatSources/hs1/supplyTemperature",
-		return: "/heatSources/hs1/returnTemperature",
-		outdoor: "/system/sensors/temperatures/outdoor_t1",
-		thermalKwh: "/recordings/heatSources/total/thermalEnergy",
-		electricalKwh: "/recordings/heatSources/total/electricalEnergy",
-		pressureBar: "/heatSources/hs1/waterPressure",
-		starts: "/heatSources/hs1/numberOfStarts"
-	},
-	/**
-	* Resources only a heat pump's heat source has. A gateway that answers one of them with
-	* anything but 404 (a 403 or a 500 included) has a heat pump it will not let us read.
-	*/
-	identity: {
-		heatPumpType: "/heatSources/hs1/heatPumpType",
-		heatPumpPower: "/heatSources/hs1/heatPumpPower"
-	},
-	circuit: {
-		operationMode: "operationMode",
-		heatCoolMode: "heatCoolMode",
-		summerWinter: "suWiSwitchMode",
-		comfort: "temperatureLevels/comfort2",
-		eco: "temperatureLevels/eco",
-		maxFlow: "maxSupplyTemperature",
-		current: "roomtemperature",
-		target: "currentRoomSetpoint"
-	},
-	dhw: {
-		operationMode: "operationMode",
-		level: "currentTemperatureLevel",
-		chargeDuration: "charge/duration",
-		charge: "charge",
-		current: "actualTemp",
-		target: "currentSetpoint"
-	}
-};
-/** A write the gateway would refuse, caught before it is sent. */
-var HomeComHeatPumpRefusalError = class extends Error {
-	name = "HomeComHeatPumpRefusalError";
-};
-async function readHeatPump(input) {
-	const get = safeGet(input.get, input.onFailure);
-	const circuits = await Promise.all([...input.circuitIds.hc.map((id) => readHc(get, id)), ...input.circuitIds.dhw.map((id) => readDhwCircuit(get, id))]);
-	const r = HEAT_PUMP_PATHS.readings;
-	const s = HEAT_PUMP_PATHS.system;
-	const heatSourceAnswered = await anyAnswers(input.answers, input.onFailure, [HEAT_PUMP_PATHS.identity.heatPumpType, HEAT_PUMP_PATHS.identity.heatPumpPower]);
-	const [silent, away, additionalHeater, holiday] = await Promise.all([
-		setting(get, s.silent),
-		setting(get, s.away),
-		setting(get, s.additionalHeater),
-		setting(get, s.holiday)
-	]);
-	const [thermalW, electricalW, compressorPct, supply, ret, outdoor] = await Promise.all([
-		num(get, r.thermalW),
-		num(get, r.electricalW),
-		num(get, r.compressorPct),
-		num(get, r.supply),
-		num(get, r.return),
-		num(get, r.outdoor)
-	]);
-	const [thermalKwh, electricalKwh, pressureBar, starts] = await Promise.all([
-		num(get, r.thermalKwh),
-		num(get, r.electricalKwh),
-		num(get, r.pressureBar),
-		num(get, r.starts)
-	]);
-	return {
-		circuits,
-		heatSourceAnswered,
-		silent,
-		away,
-		additionalHeater,
-		holiday,
-		thermalW,
-		electricalW,
-		compressorPct,
-		supply,
-		return: ret,
-		outdoor,
-		thermalKwh,
-		electricalKwh,
-		pressureBar,
-		starts
-	};
-}
-async function anyAnswers(answers, onFailure, paths) {
-	if (answers === void 0) return false;
-	return (await Promise.all(paths.map(async (path) => {
-		try {
-			return await answers(path);
-		} catch (error) {
-			onFailure?.(path, error);
-			return false;
-		}
-	}))).some(Boolean);
-}
-/** Any failure of a heat-pump read (HTTP 4xx/5xx, a throw) is "not answered", never an error. */
-function safeGet(get, onFailure) {
-	return async (path) => {
-		try {
-			return await get(path);
-		} catch (error) {
-			onFailure?.(path, error);
-			return null;
-		}
-	};
-}
-var SYSTEM_MODE_KEYS = [
-	"silent",
-	"away",
-	"additionalHeater",
-	"holiday"
-];
-var HEAT_PUMP_ONLY_READINGS = [
-	"thermalW",
-	"electricalW",
-	"compressorPct"
-];
-/**
-* True when the gateway should be offered as a system device (`hp:0`).
-*
-* A system mode counts when the gateway answered it: silent, away, the
-* additional heater, or holiday. An empty string is an answer (holiday often
-* comes back empty); a path that did not answer is not. A heat-pump-only
-* reading counts too (thermal power, electrical power, compressor modulation).
-* So does a circuit whose `heatCoolMode` can be cooling, and a heat source that
-* answers a heat-pump-only resource with any status but 404: some gateways
-* refuse (403) or fail (500) the whole system tree and still serve the
-* circuits. Supply, return, outdoor, pressure, starts and the energy meters do
-* not count: a gas boiler's heat source answers flow, pressure and starts, and
-* that is not a heat pump.
-*/
-function hasSystemDevice(reading) {
-	if (SYSTEM_MODE_KEYS.some((key) => reading[key] !== null)) return true;
-	if (HEAT_PUMP_ONLY_READINGS.some((key) => reading[key] !== null)) return true;
-	if (reading.heatSourceAnswered) return true;
-	return reading.circuits.some((c) => c.kind === "hc" && offersCooling(c.heatCoolMode));
-}
-/**
-* A boiler circuit can carry a `heatCoolMode` that only ever says heating, so the mode alone
-* is no proof. A circuit that can switch to (or already is in) cooling is a heat pump's.
-*/
-function offersCooling(setting) {
-	if (setting === null) return false;
-	return setting.value === "cooling" || setting.allowed.includes("cooling");
-}
-/** Which heat-pump paths this gateway answered. One log per gateway corrects the path table. */
-function heatPumpPathCensus(reading) {
-	const rows = [
-		...systemPathRows(reading),
-		...readingPathRows(reading),
-		...reading.circuits.flatMap(circuitPathRows)
-	];
-	const answered = [];
-	const unanswered = [];
-	for (const row of rows) if (row.present) answered.push(row.path);
-	else unanswered.push(row.path);
-	return {
-		answered,
-		unanswered
-	};
-}
-function systemPathRows(reading) {
-	const s = HEAT_PUMP_PATHS.system;
-	return [
-		{
-			path: s.silent,
-			present: reading.silent !== null
-		},
-		{
-			path: s.away,
-			present: reading.away !== null
-		},
-		{
-			path: s.additionalHeater,
-			present: reading.additionalHeater !== null
-		},
-		{
-			path: s.holiday,
-			present: reading.holiday !== null
-		}
-	];
-}
-function readingPathRows(reading) {
-	const r = HEAT_PUMP_PATHS.readings;
-	return [
-		{
-			path: r.thermalW,
-			present: reading.thermalW !== null
-		},
-		{
-			path: r.electricalW,
-			present: reading.electricalW !== null
-		},
-		{
-			path: r.compressorPct,
-			present: reading.compressorPct !== null
-		},
-		{
-			path: r.supply,
-			present: reading.supply !== null
-		},
-		{
-			path: r.return,
-			present: reading.return !== null
-		},
-		{
-			path: r.outdoor,
-			present: reading.outdoor !== null
-		},
-		{
-			path: r.thermalKwh,
-			present: reading.thermalKwh !== null
-		},
-		{
-			path: r.electricalKwh,
-			present: reading.electricalKwh !== null
-		},
-		{
-			path: r.pressureBar,
-			present: reading.pressureBar !== null
-		},
-		{
-			path: r.starts,
-			present: reading.starts !== null
-		}
-	];
-}
-function circuitPathRows(circuit) {
-	if (circuit.kind === "dhw") return dhwPathRows(circuit);
-	return hcPathRows(circuit);
-}
-function hcPathRows(circuit) {
-	const base = `/heatingCircuits/${circuit.id}`;
-	const p = HEAT_PUMP_PATHS.circuit;
-	return [
-		{
-			path: `${base}/${p.operationMode}`,
-			present: circuit.operationMode !== null
-		},
-		{
-			path: `${base}/${p.heatCoolMode}`,
-			present: circuit.heatCoolMode !== null
-		},
-		{
-			path: `${base}/${p.summerWinter}`,
-			present: circuit.summerWinter !== null
-		},
-		{
-			path: `${base}/${p.comfort}`,
-			present: circuit.comfort !== null
-		},
-		{
-			path: `${base}/${p.eco}`,
-			present: circuit.eco !== null
-		},
-		{
-			path: `${base}/${p.maxFlow}`,
-			present: circuit.maxFlow !== null
-		},
-		{
-			path: `${base}/${p.current}`,
-			present: circuit.currentTemp !== null
-		},
-		{
-			path: `${base}/${p.target}`,
-			present: circuit.targetTemp !== null
-		}
-	];
-}
-function dhwPathRows(circuit) {
-	const base = `/dhwCircuits/${circuit.id}`;
-	const p = HEAT_PUMP_PATHS.dhw;
-	return [
-		{
-			path: `${base}/${p.operationMode}`,
-			present: circuit.operationMode !== null
-		},
-		{
-			path: `${base}/${p.level}`,
-			present: circuit.level !== null
-		},
-		{
-			path: `${base}/${p.chargeDuration}`,
-			present: circuit.chargeDuration !== null
-		},
-		{
-			path: `${base}/${p.charge}`,
-			present: circuit.charge !== null
-		},
-		{
-			path: `${base}/${p.current}`,
-			present: circuit.currentTemp !== null
-		},
-		{
-			path: `${base}/${p.target}`,
-			present: circuit.targetTemp !== null
-		}
-	];
+	if (trimmed.length === 0 || trimmed === id) return null;
+	return trimmed;
 }
-async function readHc(get, id) {
-	const base = `/heatingCircuits/${id}`;
-	const p = HEAT_PUMP_PATHS.circuit;
-	const [operationMode, heatCoolMode, summerWinter, comfort, eco, maxFlow, current, target] = await Promise.all([
-		setting(get, `${base}/${p.operationMode}`),
-		setting(get, `${base}/${p.heatCoolMode}`),
-		setting(get, `${base}/${p.summerWinter}`),
-		setting(get, `${base}/${p.comfort}`),
-		setting(get, `${base}/${p.eco}`),
-		setting(get, `${base}/${p.maxFlow}`),
-		num(get, `${base}/${p.current}`),
-		num(get, `${base}/${p.target}`)
-	]);
-	return {
-		id,
-		kind: "hc",
-		currentTemp: current,
-		targetTemp: target,
-		operationMode,
-		heatCoolMode,
-		summerWinter,
-		comfort,
-		eco,
-		maxFlow,
-		level: null,
-		chargeDuration: null,
-		charge: null
-	};
+function referenceKeys(body, prefix) {
+	return circuitRefs(body, prefix).map((ref) => ref.id);
 }
-async function readDhwCircuit(get, id) {
-	const base = `/dhwCircuits/${id}`;
-	const p = HEAT_PUMP_PATHS.dhw;
-	const [operationMode, level, chargeDuration, charge, current, target] = await Promise.all([
-		setting(get, `${base}/${p.operationMode}`),
-		setting(get, `${base}/${p.level}`),
-		setting(get, `${base}/${p.chargeDuration}`),
-		setting(get, `${base}/${p.charge}`),
-		num(get, `${base}/${p.current}`),
-		num(get, `${base}/${p.target}`)
-	]);
-	return {
-		id,
-		kind: "dhw",
-		currentTemp: current,
-		targetTemp: target,
-		operationMode,
-		heatCoolMode: null,
-		summerWinter: null,
-		comfort: null,
-		eco: null,
-		maxFlow: null,
-		level,
-		chargeDuration,
-		charge
-	};
+function indexStandard(body) {
+	const map = /* @__PURE__ */ new Map();
+	if (!isRecord$2(body) || !Array.isArray(body["references"])) return map;
+	for (const ref of body["references"]) {
+		if (!isRecord$2(ref) || typeof ref["id"] !== "string") continue;
+		const tail = ref["id"].split("/").filter((part) => part.length > 0).at(-1) ?? ref["id"];
+		const envelope = readEnvelope(ref);
+		if (envelope !== null) map.set(tail, envelope);
+	}
+	return map;
 }
-async function setting(get, path) {
-	const envelope = readEnvelope(await get(path));
-	return envelope === null ? null : settingOf(path, envelope);
+function numberOf(envelope) {
+	if (envelope === null) return null;
+	return typeof envelope.value === "number" && Number.isFinite(envelope.value) ? envelope.value : null;
 }
-async function num(get, path) {
-	const envelope = readEnvelope(await get(path));
-	return envelope !== null && typeof envelope.value === "number" && Number.isFinite(envelope.value) ? envelope.value : null;
+function stringOf(envelope) {
+	if (envelope === null || typeof envelope.value !== "string" || envelope.value.length === 0) return null;
+	return envelope.value;
 }
-function settingOf(path, envelope) {
-	return {
-		path,
-		value: envelope.value,
-		min: envelope.min,
-		max: envelope.max,
-		allowed: envelope.allowed
-	};
+function swingOf(envelope) {
+	const value = stringOf(envelope);
+	if (value === null) return null;
+	return value === "swing";
 }
-function heatPumpStatusFrom(reading, now) {
-	return {
-		circuits: reading.circuits.map(circuitOf),
-		system: {
-			silent: optionOf(reading.silent),
-			away: optionOf(reading.away),
-			additionalHeater: optionOf(reading.additionalHeater),
-			holiday: optionOf(reading.holiday)
-		},
-		power: {
-			thermalW: reading.thermalW,
-			electricalW: reading.electricalW,
-			compressorPct: reading.compressorPct
-		},
-		temperatures: {
-			supply: reading.supply,
-			return: reading.return,
-			outdoor: reading.outdoor
-		},
-		energy: {
-			thermalKwh: reading.thermalKwh,
-			electricalKwh: reading.electricalKwh
-		},
-		waterPressureBar: reading.pressureBar,
-		starts: reading.starts,
-		lastFetchedAt: now
-	};
+function safeToken(value) {
+	if (value === null || !TOKEN.test(value)) return null;
+	return value;
 }
-function circuitOf(c) {
-	const kind = kindOf(c);
-	return {
-		id: c.id,
-		kind,
-		label: labelOf(c),
-		icon: kind === "dhw" ? "droplets" : kind === "cooling" ? "snowflake" : "flame",
-		currentTemp: c.currentTemp,
-		targetTemp: c.targetTemp,
-		mode: modeValue(c.operationMode),
-		active: null,
-		operationMode: optionOf(c.operationMode),
-		heatCoolMode: optionOf(c.heatCoolMode),
-		summerWinter: optionOf(c.summerWinter),
-		comfortSetpoint: rangeOf(c.comfort),
-		ecoSetpoint: rangeOf(c.eco),
-		maxFlowTemp: rangeOf(c.maxFlow),
-		temperatureLevel: optionOf(c.level),
-		chargeDuration: rangeOf(c.chargeDuration),
-		extraHotWater: c.charge === null ? null : textOf$1(c.charge) === "start"
-	};
+function finite(raw) {
+	return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
 }
-function kindOf(c) {
-	if (c.kind === "dhw") return "dhw";
-	return textOf$1(c.heatCoolMode) === "cooling" ? "cooling" : "heating";
+function stringList(raw) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) if (typeof item === "string") out.push(item);
+	return out;
 }
-function labelOf(c) {
-	const n = c.id.replace(/^\D+/, "");
-	if (c.kind === "dhw") return n === "1" || n === "" ? "Hot water" : `Hot water ${n}`;
-	return n === "" ? "Heating circuit" : `Heating circuit ${n}`;
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function textOf$1(s) {
+//#endregion
+//#region src/homecom/homecom-bridge-snapshot.ts
+/**
+* The climate and water-heater view of a heat-pump gateway (k40, k30, icom), built from the
+* bridge reading, and the climate writes it accepts. The heat-pump view rides along when
+* the gateway has one (D1026).
+*/
+function numberValue(s) {
+	return s !== null && typeof s.value === "number" ? s.value : null;
+}
+function textValue(s) {
 	return s !== null && typeof s.value === "string" && s.value.length > 0 ? s.value : null;
 }
 /**
-* A mode the gateway answered with an empty value is off (or "none" when the
-* gateway did not list off). A mode it did not answer at all stays null.
+* Cooling writes the cooling setpoint; manual writes the manual room setpoint; auto writes the
+* temperature level (comfort or eco) the circuit runs on now. The library reads no active level
+* for a circuit, so it is the one level whose temperature equals the current room setpoint;
+* none or both matching is unknown, never a guess.
 */
-function modeValue(s) {
-	if (s === null || typeof s.value !== "string") return null;
-	if (s.value.length > 0) return s.value;
-	return s.allowed.includes("off") ? "off" : "none";
+function activeSetpoint(hc) {
+	if (circuitIsCooling(hc)) return {
+		kind: "setting",
+		op: "hcCoolingRoomSetpoint",
+		what: `${hc.id} cooling setpoint`,
+		setting: hc.coolingRoomSetpoint
+	};
+	if (textValue(hc.operationMode) !== "auto") return {
+		kind: "setting",
+		op: "hcManualRoomSetpoint",
+		what: `${hc.id} setpoint`,
+		setting: hc.manualRoomSetpoint
+	};
+	const current = numberValue(hc.currentRoomSetpoint);
+	const comfort = current !== null && numberValue(hc.comfortSetpoint) === current;
+	if (comfort === (current !== null && numberValue(hc.ecoSetpoint) === current)) return {
+		kind: "unknown",
+		reason: `HomeCom ${hc.id}: the active level in auto mode cannot be told from the reading`
+	};
+	return comfort ? {
+		kind: "setting",
+		op: "hcComfortSetpoint",
+		what: `${hc.id} comfort level`,
+		setting: hc.comfortSetpoint
+	} : {
+		kind: "setting",
+		op: "hcEcoSetpoint",
+		what: `${hc.id} eco level`,
+		setting: hc.ecoSetpoint
+	};
 }
-function optionOf(s) {
-	if (s === null) return null;
+function climateCircuit(hc) {
+	const cooling = circuitIsCooling(hc);
+	const active = activeSetpoint(hc);
+	const limits = active.kind === "setting" ? active.setting : null;
+	const modes = hvacModesFromAllowed(hc.operationMode?.allowed ?? []);
 	return {
-		value: modeValue(s),
-		allowed: [...s.allowed]
+		id: hc.id,
+		name: heatingCircuitName(hc.id, hc.name),
+		operationMode: textValue(hc.operationMode) ?? "off",
+		setpoint: cooling ? numberValue(hc.coolingRoomSetpoint) ?? numberValue(hc.currentRoomSetpoint) : numberValue(hc.currentRoomSetpoint) ?? numberValue(hc.manualRoomSetpoint),
+		currentRoomTemp: hc.roomTemp,
+		minTemp: limits?.min ?? null,
+		maxTemp: limits?.max ?? null,
+		currentHumidity: hc.humidity,
+		season: cooling ? "cooling" : textValue(hc.currentSuWiMode),
+		fanMode: "",
+		availableFanModes: [],
+		swingVertical: null,
+		swingHorizontal: null,
+		availableModes: modes.length > 0 ? modes : [...HYDRONIC_MODES]
 	};
 }
-function rangeOf(s) {
-	if (s === null) return null;
+function waterHeater(dhw) {
+	const target = dhwTargetSetting(dhw);
+	const modes = dhw.operationMode?.allowed ?? [];
 	return {
-		value: typeof s.value === "number" && Number.isFinite(s.value) ? s.value : null,
-		min: s.min,
-		max: s.max,
-		step: null
+		currentTemp: dhw.actualTemp,
+		targetTemp: numberValue(target),
+		operationMode: textValue(dhw.operationMode),
+		availableModes: [...modes],
+		minTemp: target?.min ?? null,
+		maxTemp: target?.max ?? null,
+		circuitId: dhw.id
 	};
 }
-function requireCircuit(reading, circuitId, want) {
-	const found = reading.circuits.find((c) => c.id === circuitId && c.kind === want);
-	if (found === void 0) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump has no ${want} circuit ${circuitId}`);
-	return found;
-}
-function optionWrite(s, what, mode) {
-	if (s === null) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is not available`);
-	if (s.allowed.length === 0) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is read-only on this gateway`);
-	if (!s.allowed.includes(mode)) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: "${mode}" is not an accepted value of ${what} (${s.allowed.join(", ")})`);
+function bridgeSnapshot(input) {
+	const { reading } = input;
+	const firstDhw = reading.dhwCircuits[0];
+	if (reading.dhwCircuits.length > 1) {
+		const extra = reading.dhwCircuits.slice(1).map((c) => c.id);
+		input.logDrop(`extra DHW circuits are on the heat pump only: ${extra.join(", ")}`);
+	}
+	for (const [path, outcome] of Object.entries(reading.heatSourceProbe)) if (outcome === "transient") input.logTransientProbe(path);
+	const heatPump = heatPumpReadingFrom(reading);
 	return {
-		path: s.path,
-		value: mode
+		gateway: {
+			gatewayId: input.gatewayId,
+			name: input.gatewayId,
+			model: input.deviceType
+		},
+		circuits: reading.heatingCircuits.map(climateCircuit),
+		dhw: firstDhw === void 0 ? null : waterHeater(firstDhw),
+		deviceType: input.deviceType,
+		family: "hydronic",
+		bridge: reading,
+		...hasSystemDevice(heatPump) ? { heatPump } : {}
 	};
 }
-function rangeWrite(s, what, value) {
-	if (s === null) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} is not available`);
-	if (!Number.isFinite(value)) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} needs a finite number`);
-	if (s.min === null || s.max === null) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${what} has no limits from the gateway`);
-	if (value < s.min || value > s.max) throw new HomeComHeatPumpRefusalError(`HomeCom heat pump: ${value} is outside ${what} limits ${s.min}..${s.max}`);
+function findHc(reading, circuitId) {
+	const found = reading.heatingCircuits.find((c) => c.id === circuitId);
+	if (found === void 0) throw new HomeComHeatPumpRefusalError(`HomeCom has no heating circuit ${circuitId}`);
+	return found;
+}
+function firstDhw(reading) {
+	const found = reading.dhwCircuits[0];
+	if (found === void 0) throw new HomeComHeatPumpRefusalError("HomeCom has no DHW circuit");
+	return found;
+}
+function bridgeSetpointWrite(reading, circuitId, temp) {
+	const active = activeSetpoint(findHc(reading, circuitId));
+	if (active.kind === "unknown") throw new HomeComHeatPumpRefusalError(active.reason);
+	const value = acceptedRange(active.setting, active.what, temp);
 	return {
-		path: s.path,
+		op: active.op,
+		circuitId,
 		value
 	};
 }
-function systemModeWrite(reading, which, mode) {
-	return optionWrite(reading[which], `${which} mode`, mode);
-}
-function circuitOptionWrite(reading, circuitId, which, mode) {
-	return optionWrite(requireCircuit(reading, circuitId, "hc")[which], `${circuitId} ${which}`, mode);
-}
-function dhwOptionWrite(reading, circuitId, which, mode) {
-	return optionWrite(requireCircuit(reading, circuitId, "dhw")[which], `${circuitId} ${which}`, mode);
+/** The gateway's token for an HVAC mode: heat is `manual`; cool is a heat/cool mode. */
+function operationToken(mode) {
+	switch (mode) {
+		case "Heat":
+		case "heat": return "manual";
+		case "Auto": return "auto";
+		case "Off": return "off";
+		default: return mode;
+	}
 }
-function circuitRangeWrite(reading, circuitId, which, value) {
-	return rangeWrite(requireCircuit(reading, circuitId, "hc")[which], `${circuitId} ${which}`, value);
+function bridgeModeWrite(reading, circuitId, mode) {
+	const hc = findHc(reading, circuitId);
+	if (mode === "cool" || mode === "Cool") {
+		const token = (hc.heatCoolMode?.allowed ?? []).includes("cool") ? "cool" : "cooling";
+		return {
+			op: "hcHeatCoolMode",
+			circuitId,
+			value: acceptedOption(hc.heatCoolMode, `${circuitId} heat/cool mode`, token)
+		};
+	}
+	return {
+		op: "hcOperationMode",
+		circuitId,
+		value: acceptedOption(hc.operationMode, `${circuitId} mode`, operationToken(mode))
+	};
 }
-function dhwChargeDurationWrite(reading, circuitId, minutes) {
-	return rangeWrite(requireCircuit(reading, circuitId, "dhw").chargeDuration, `${circuitId} charge duration`, minutes);
+/** The hot-water target is the temperature of the level the tank runs on now. */
+function bridgeDhwTargetWrite(reading, temp) {
+	const dhw = firstDhw(reading);
+	const level = textValue(dhw.currentTemperatureLevel);
+	if (level === null || level === "off" || dhw.temperatureLevels[level] === void 0) throw new HomeComHeatPumpRefusalError("HomeCom DHW: setpoint not supported");
+	const value = acceptedRange(dhw.temperatureLevels[level] ?? null, `${dhw.id} ${level}`, temp);
+	return {
+		op: "dhwLevelTemp",
+		circuitId: dhw.id,
+		level,
+		value
+	};
 }
-function extraHotWaterWrite(reading, circuitId) {
-	const charge = requireCircuit(reading, circuitId, "dhw").charge;
-	return optionWrite(charge, `${circuitId} extra hot water`, "start");
+function bridgeDhwModeWrite(reading, mode) {
+	const dhw = firstDhw(reading);
+	const value = acceptedOption(dhw.operationMode, `${dhw.id} mode`, mode);
+	return {
+		op: "dhwOperationMode",
+		circuitId: dhw.id,
+		value
+	};
 }
 //#endregion
 //#region src/homecom/homecom-oauth.ts
@@ -1340,7 +1855,8 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 	let last = null;
 	let refreshTail = Promise.resolve();
 	const dropped = /* @__PURE__ */ new Set();
-	let heatPumpPathsLogged = false;
+	const bridgeFailuresLogged = /* @__PURE__ */ new Set();
+	const bridge = deps.bridge;
 	const base = homeComApiBase(config.region);
 	function authHeaders() {
 		return {
@@ -1409,17 +1925,6 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 		if (!res.ok) throw new Error(`HomeCom API ${path} failed: HTTP ${res.status}`);
 		return res.body;
 	}
-	/**
-	* Evidence that the resource exists: a 2xx, or the 403 the gateway gives a resource it
-	* serves but will not show. 404 is "absent". Anything else (429, 5xx) is a transient
-	* failure, so it is NOT evidence either way: it is logged and counts as unknown.
-	*/
-	async function resourceAnswers(path) {
-		const res = await authed(homeComResourceUrl(gatewayId, path), { method: "GET" });
-		if (res.ok || res.status === 403) return true;
-		if (res.status !== 404) logHeatPumpFailure(path, /* @__PURE__ */ new Error(`HTTP ${res.status}`));
-		return false;
-	}
 	async function putWrite(write) {
 		const res = await authed(homeComResourceUrl(gatewayId, write.path), {
 			method: "PUT",
@@ -1485,58 +1990,95 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 	}
 	async function fetchSystem() {
 		const resolved = await resolveDeviceType();
-		const withHeatPump = await attachHeatPump(await readPointtSnapshot({
-			deviceType: resolved.deviceType,
-			family: resolved.family,
+		const snapshot = await readSnapshot(resolved.deviceType, resolved.family);
+		last = snapshot;
+		return snapshot;
+	}
+	async function readSnapshot(type, family) {
+		if (isBridgeDeviceType(type)) if (bridge !== void 0) {
+			const reading = await readThroughBridge(bridge, type);
+			if (reading !== null) return bridgeSnapshot({
+				gatewayId,
+				deviceType: type,
+				reading,
+				logDrop,
+				logTransientProbe
+			});
+		} else logDrop("the HomeCom bridge is not available (no Python): the heat pump is not read");
+		return readPointtSnapshot({
+			deviceType: type,
+			family,
 			gatewayId,
 			get: getResource,
 			logDrop
-		}));
-		last = withHeatPump;
-		return withHeatPump;
-	}
-	async function attachHeatPump(snapshot) {
-		if (snapshot.family !== "hydronic" || snapshot.deviceType === "rrc2") return snapshot;
-		const dhwId = snapshot.dhw?.circuitId;
-		const heatPump = await readHeatPump({
-			get: getResource,
-			onFailure: logHeatPumpFailure,
-			answers: resourceAnswers,
-			circuitIds: {
-				hc: snapshot.circuits.map((circuit) => circuit.id),
-				dhw: dhwId === void 0 ? [] : [dhwId]
-			}
 		});
-		logHeatPumpPaths(heatPump);
-		return hasSystemDevice(heatPump) ? {
-			...snapshot,
-			heatPump
-		} : snapshot;
-	}
-	function logHeatPumpPaths(reading) {
-		if (heatPumpPathsLogged) return;
-		heatPumpPathsLogged = true;
-		const census = heatPumpPathCensus(reading);
-		logger?.info("HomeCom heat-pump paths", {
-			tags: { gatewayId },
-			meta: {
-				answered: census.answered,
-				unanswered: census.unanswered
+	}
+	/**
+	* A failed bridge read must not take the climate and water-heater devices down, nor change
+	* the heat pump's shape: anything but an authentication failure keeps the last bridge
+	* reading (so an adopted heat pump keeps its values and discovery its devices), or — before
+	* any bridge read has succeeded — falls back to the plain climate resources. Named once per
+	* failure kind until a read succeeds again.
+	*/
+	async function readThroughBridge(from, type) {
+		try {
+			const reading = await bridgeCall((t) => from.read(bridgeTarget(t, type)));
+			bridgeFailuresLogged.clear();
+			return reading;
+		} catch (error) {
+			if (!(error instanceof HomeComBridgeError)) throw error;
+			const kept = last?.bridge ?? null;
+			if (!bridgeFailuresLogged.has(error.kind)) {
+				bridgeFailuresLogged.add(error.kind);
+				logger?.warn(kept === null ? "HomeCom bridge read failed; the climate resources are read until it answers" : "HomeCom bridge read failed; the last bridge reading is kept until it answers", {
+					tags: { gatewayId },
+					meta: {
+						kind: error.kind,
+						error: error.message
+					}
+				});
 			}
-		});
+			return kept;
+		}
 	}
-	function logHeatPumpFailure(path, error) {
-		const key = `heat-pump-read:${path}`;
+	function logTransientProbe(path) {
+		const key = `probe:${path}`;
 		if (dropped.has(key)) return;
 		dropped.add(key);
-		logger?.warn("HomeCom heat-pump resource could not be read; it is skipped", {
+		logger?.warn("HomeCom heat-source probe failed transiently; it does not count as evidence", {
 			tags: { gatewayId },
-			meta: {
-				path,
-				error: error instanceof Error ? error.message : String(error)
-			}
+			meta: { path }
 		});
 	}
+	function bridgeTarget(t, type) {
+		return {
+			token: t,
+			gatewayId,
+			deviceType: type
+		};
+	}
+	/** One bridge run; an `auth` answer refreshes the token once and runs it again. */
+	async function bridgeCall(run) {
+		const used = token;
+		try {
+			return await run(used);
+		} catch (error) {
+			if (!(error instanceof HomeComBridgeError) || error.kind !== "auth") throw error;
+			if (!refreshOnUnauthorized) throw new HomeComAuthError("token expired");
+		}
+		await refreshIfStale(used);
+		try {
+			return await run(token);
+		} catch (error) {
+			if (error instanceof HomeComBridgeError && error.kind === "auth") throw new HomeComAuthError("token expired after refresh");
+			throw error;
+		}
+	}
+	async function bridgeWrite(snapshot, write) {
+		const type = snapshot.deviceType;
+		if (bridge === void 0 || !isBridgeDeviceType(type)) throw new Error("HomeCom heat-pump writes need the HomeCom bridge (embedded Python).");
+		await bridgeCall((t) => bridge.write(bridgeTarget(t, type), write));
+	}
 	async function probePath(path) {
 		const res = await authed(homeComResourceUrl(gatewayId, path), {
 			method: "GET",
@@ -1564,16 +2106,36 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 			throw new Error(`HomeCom gateway ${gatewayId} did not answer /gateway/DateTime or /gateway/versionFirmware.`);
 		},
 		async setCircuitSetpoint(circuitId, temp) {
-			await putWrite(circuitSetpointWrite(await requireSnapshot(), circuitId, temp));
+			const snapshot = await requireSnapshot();
+			if (snapshot.bridge !== void 0) {
+				await bridgeWrite(snapshot, bridgeSetpointWrite(snapshot.bridge, circuitId, temp));
+				return;
+			}
+			await putWrite(circuitSetpointWrite(snapshot, circuitId, temp));
 		},
 		async setCircuitMode(circuitId, mode) {
-			for (const write of circuitModeWrites(await requireSnapshot(), circuitId, mode)) await putWrite(write);
+			const snapshot = await requireSnapshot();
+			if (snapshot.bridge !== void 0) {
+				await bridgeWrite(snapshot, bridgeModeWrite(snapshot.bridge, circuitId, mode));
+				return;
+			}
+			for (const write of circuitModeWrites(snapshot, circuitId, mode)) await putWrite(write);
 		},
 		async setDhwTarget(temp) {
-			await putWrite(dhwTargetWrite(await requireSnapshot(), temp));
+			const snapshot = await requireSnapshot();
+			if (snapshot.bridge !== void 0) {
+				await bridgeWrite(snapshot, bridgeDhwTargetWrite(snapshot.bridge, temp));
+				return;
+			}
+			await putWrite(dhwTargetWrite(snapshot, temp));
 		},
 		async setDhwMode(mode) {
-			await putWrite(dhwModeWrite(await requireSnapshot(), mode));
+			const snapshot = await requireSnapshot();
+			if (snapshot.bridge !== void 0) {
+				await bridgeWrite(snapshot, bridgeDhwModeWrite(snapshot.bridge, mode));
+				return;
+			}
+			await putWrite(dhwModeWrite(snapshot, mode));
 		},
 		async setFanMode(_circuitId, fanMode) {
 			const snapshot = await requireSnapshot();
@@ -1591,7 +2153,15 @@ function createHomeComApiClient(config, gatewayId, deps = {}) {
 			await putWrite(swingWrite(snapshot, "horizontal", on));
 		},
 		async writeHeatPump(writes) {
-			for (const write of writes) await putWrite(write);
+			const snapshot = await requireSnapshot();
+			for (const write of writes) await bridgeWrite(snapshot, write);
+		},
+		async readResource(path) {
+			const res = await authed(homeComResourceUrl(gatewayId, path), { method: "GET" });
+			return {
+				status: res.status,
+				body: res.body
+			};
 		}
 	};
 }
@@ -2244,6 +2814,7 @@ var HomeComIntegrationManager = class {
 		this.#onDisconnected = options.onDisconnected;
 		this.#surfaceSink = options.surfaceSink;
 		const fetchFn = options.fetchFn;
+		const bridge = options.bridge;
 		this.#onGatewayChosen = options.onGatewayChosen ?? (() => void 0);
 		const onTokensRotated = async (tokens) => {
 			this.#connection = {
@@ -2264,6 +2835,7 @@ var HomeComIntegrationManager = class {
 			fetchFn,
 			onTokensRotated,
 			logger: this.#logger,
+			...bridge !== void 0 ? { bridge } : {},
 			deviceType: this.#gateways.find((gateway) => gateway.gatewayId === gatewayId)?.deviceType
 		}));
 		this.#pollIntervalMs = options.pollIntervalMs ?? 6e4;
@@ -2387,6 +2959,7 @@ var HomeComClientRegistry = class {
 		this.#onGatewayChosen = deps.onGatewayChosen ?? (() => void 0);
 		const fetchFn = deps.fetchFn;
 		const makeClient = deps.makeClient;
+		const bridge = deps.bridge;
 		this.#makeManager = deps.makeManager ?? ((opts) => new HomeComIntegrationManager({
 			id: opts.integrationId,
 			name: opts.name,
@@ -2399,6 +2972,7 @@ var HomeComClientRegistry = class {
 			surfaceSink: homeComConnections,
 			fetchFn,
 			makeClient,
+			...bridge !== void 0 ? { bridge } : {},
 			pollIntervalMs: 6e4
 		}));
 	}
@@ -2491,6 +3065,27 @@ var HomeComClientRegistry = class {
 	}
 };
 //#endregion
+//#region src/homecom/homecom-python-paths.ts
+var WORKER = "homecom_worker.py";
+/**
+* Absolute path of the bundled `python/homecom_worker.py`: next to `dist/` in a deployed
+* package (one level up from a `dist/` chunk, two from `dist/homecom/`), two levels up from
+* `src/homecom/` in the workspace.
+*/
+function resolveHomeComWorker(fromModuleUrl = require("url").pathToFileURL(__filename).href) {
+	const here = (0, node_path.dirname)((0, node_url.fileURLToPath)(fromModuleUrl));
+	const candidates = [
+		(0, node_path.join)(here, "../python"),
+		(0, node_path.join)(here, "../../python"),
+		(0, node_path.join)(here, "python")
+	];
+	for (const dir of candidates) {
+		const file = (0, node_path.join)(dir, WORKER);
+		if ((0, node_fs.existsSync)(file)) return file;
+	}
+	throw new Error(`provider-bosch: ${WORKER} not found. Searched:\n${candidates.join("\n")}`);
+}
+//#endregion
 //#region src/homecom/homecom-connection-test.ts
 var NO_GATEWAY = "This Bosch account has no HomeCom gateway.";
 function signInIncomplete(paths) {
@@ -3003,7 +3598,7 @@ var HomeComHeatPumpDevice = class extends require_bosch_instances.BaseDevice {
 		await client.writeHeatPump([write]);
 		this.ctx.logger.info("HomeCom heat pump: value written", {
 			tags: { deviceId: this.ctx.id },
-			meta: { path: write.path }
+			meta: { op: write.op }
 		});
 		try {
 			const snapshot = await client.fetchSystem();
@@ -3012,7 +3607,7 @@ var HomeComHeatPumpDevice = class extends require_bosch_instances.BaseDevice {
 			this.ctx.logger.warn("HomeCom heat pump: value written, the refresh failed", {
 				tags: { deviceId: this.ctx.id },
 				meta: {
-					path: write.path,
+					op: write.op,
 					error: error instanceof Error ? error.message : String(error)
 				}
 			});
@@ -3083,7 +3678,9 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 		};
 		const persistTokens = buildHomeComTokenPersister(persistDeps);
 		const persistGateway = buildHomeComGatewayPersister(persistDeps);
+		const bridge = await this.createBridge();
 		this.clients = new HomeComClientRegistry(this.ctx.logger, {
+			...bridge !== null ? { bridge } : {},
 			onTokensRotated: (integrationId, tokens) => persistTokens(integrationId, tokens),
 			onGatewayChosen: (integrationId, gatewayId) => void persistGateway(integrationId, gatewayId)
 		});
@@ -3095,6 +3692,11 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 		});
 		await this.reconcileIntegrations();
 		this.subscribeIntegrationLifecycle();
+		const explore = createHomeComExploreAction(homeComExploreDeps({
+			registry: this.clients,
+			connections: homeComConnections,
+			logger: this.ctx.logger
+		}));
 		return {
 			providers: [
 				...regs,
@@ -3121,7 +3723,8 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 				signOut: async () => ({
 					signedOut: true,
 					summary: "Signed out."
-				})
+				}),
+				exploreResources: explore
 			}
 		};
 	}
@@ -3135,6 +3738,23 @@ var BoschHomeComProviderAddon = class extends require_bosch_instances.BaseDevice
 		this.instances = null;
 		await super.onShutdown();
 	}
+	/** The `homecom_alt` bridge on the embedded Python; null leaves k40/k30/icom on plain reads. */
+	async createBridge() {
+		try {
+			const pythonPath = await this.ctx.deps.ensurePython();
+			if (pythonPath === null) {
+				this.ctx.logger.warn("HomeCom: embedded Python is unavailable, the heat pump is not read");
+				return null;
+			}
+			return createHomeComBridge({
+				pythonPath,
+				scriptPath: resolveHomeComWorker()
+			});
+		} catch (err) {
+			this.ctx.logger.warn("HomeCom: the Python bridge could not be prepared", { meta: { error: require_bosch_instances.errMsg(err) } });
+			return null;
+		}
+	}
 	requireClients() {
 		if (!this.clients) throw new Error("HomeCom provider not initialised");
 		return this.clients;