@camstack/addon-provider-hikvision 1.2.31 → 1.2.33

package/dist/addon.js

@@ -6,7 +6,7 @@ let node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
 let node_os = require("node:os");
-//#region ../types/dist/event-category-XfKNtfCc.mjs
+//#region ../types/dist/event-category-CIa_iT6b.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -22,6 +22,15 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["SystemRestartCompleted"] = "system.restart-completed";
 	/**
+	* The hub reissued its own TLS certificate at boot (`ensureTlsCert`).
+	* Emitted only when the material on disk actually changed, so an
+	* operator who trusted the old certificate by hand is told rather than
+	* discovering it as a browser error. Payload `TlsCertChangedPayload`.
+	*
+	* Rule: docs/decisions/adr-0227-*.md
+	*/
+	EventCategory["SystemTlsCertChanged"] = "system.tls-cert-changed";
+	/**
 	* A newer addon or server-root package version was found by the
 	* authoritative registry check. Emitted once when any observed
 	* `latestVersion` changes (or a package/node first appears behind);
@@ -19163,6 +19172,12 @@ var CameraStatusSchema = object({
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: number()
 });
+var InferenceDeviceExclusionReasonSchema = _enum([
+	"disabled",
+	"unavailable",
+	"cannot-host-camera-root",
+	"accelerator-preferred"
+]);
 var NodeInferenceDeviceSchema = object({
 	/** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
 	key: string(),
@@ -19193,7 +19208,17 @@ var NodeInferenceDeviceSchema = object({
 	* available per format; this is the stored selection that becomes the
 	* default for EVERY camera landing on this accelerator.
 	*/
-	steps: record(string(), DeviceStepConfigSchema).optional()
+	steps: record(string(), DeviceStepConfigSchema).optional(),
+	/**
+	* `null` when the device IS a camera-root candidate on this node; otherwise
+	* the reason the dispatcher drops it. Computed by the SAME
+	* `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+	* never disagree with the election — deriving it in the UI from
+	* `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+	* the node's model catalog) and `accelerator-preferred` (needs the node-wide
+	* "an accelerator is serving" predicate).
+	*/
+	exclusion: InferenceDeviceExclusionReasonSchema.nullable()
 });
 var NodeInferenceDevicesSchema = object({
 	nodeId: string(),
@@ -24148,7 +24173,12 @@ var ListResultSchema = object({
 	probedAt: number()
 });
 var PreferredSchema = LocalInterfaceSchema.nullable();
-var GetConnectionEndpointsResultSchema = object({ endpoints: array(object({
+/**
+* Candidate base URL for the SDK to race on connect. Order matters —
+* the SDK should attempt these top-to-bottom with a short per-candidate
+* timeout (e.g. 1500ms) and cache the winner for the session.
+*/
+var ConnectionEndpointSchema = object({
 	/** Operator-facing label (e.g. "LAN — en0", "Public tunnel"). */
 	label: string(),
 	/** Fully-formed base URL with scheme + host + port. */
@@ -24191,7 +24221,42 @@ var GetConnectionEndpointsResultSchema = object({ endpoints: array(object({
 	* ordering between polls.
 	*/
 	priority: number()
-})).readonly() });
+});
+/**
+* Where the advertised local port came from. Ordered most → least
+* authoritative, and the whole point of returning it: a client must be able to
+* tell a FACT about the hub's socket from an echo of its own guess.
+*/
+var LocalPortSourceEnum = _enum([
+	"server-config",
+	"server-env",
+	"caller-hint",
+	"default"
+]);
+/** The port every LAN/loopback `baseUrl` in the same result was built with. */
+var AdvertisedLocalPortSchema = object({
+	port: number().int().min(1).max(65535),
+	source: LocalPortSourceEnum
+});
+var GetConnectionEndpointsResultSchema = object({
+	endpoints: array(ConnectionEndpointSchema).readonly(),
+	/**
+	* The port the hub built the LAN/loopback URLs with, and where that number
+	* came from.
+	*
+	* Returned rather than merely applied, because "the URL is right" and "the
+	* client can KNOW the URL is right" are different properties. A client that
+	* only sees a corrected URL cannot distinguish a hub that fixed the port from
+	* a hub that echoed the port the client sent, so it cannot decide whether to
+	* race the candidate or discard it. With `source` it can: anything but
+	* `caller-hint` is the hub's own socket.
+	*
+	* Absent on hubs predating this field — a client that finds it missing is
+	* talking to an echoing hub and must degrade exactly as it does for
+	* `caller-hint`.
+	*/
+	localPort: AdvertisedLocalPortSchema
+});
 /**
 * The chosen outbound endpoint for notification artifacts. `baseUrl: null` =
 * AUTO (resolved from the candidate ranking at send time); `resolved` reports
@@ -24212,8 +24277,13 @@ var AllowedAddressesSchema = object({
 */
 addresses: array(string()).readonly() });
 method(_void(), ListResultSchema), method(_void(), PreferredSchema), method(object({
-	/** Local hub HTTP port to use in base URLs. */
-	port: number().int().min(1).max(65535),
+	/**
+	* LEGACY HINT — do not send from new code. Kept optional so clients
+	* written against the echoing contract keep working; the hub uses it
+	* only when it cannot read its own port, and says so via
+	* `localPort.source === 'caller-hint'`.
+	*/
+	port: number().int().min(1).max(65535).optional(),
 	/** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
 	*  candidate. Default `true`. */
 	includeLoopback: boolean().optional(),
@@ -30432,11 +30502,63 @@ function startReachabilityPoll(options) {
 	} };
 }
 var LAST_FETCHED_FIELD = "lastFetchedAt";
+/**
+* How long a bridge stops re-attempting a refresh that did not land.
+*
+* Sized against the failure it exists for: a camera whose control plane
+* is unreachable costs the FULL connect give-up (~3s on Linux when the
+* neighbour never answers, up to the client's own timeout otherwise) on
+* every attempt, and a failed refresh never advances `lastFetchedAt`, so
+* without a cooldown the slice is permanently stale and EVERY read pays
+* that price. One attempt per minute is enough to notice the camera
+* coming back; per-read is enough to stall the viewer's first paint.
+*/
+var RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = 6e4;
+/**
+* The freshness window for a cap whose value changes ONLY when WE write it.
+*
+* The usual `staleMs: 10_000` is tuned for a reading that moves on its own — a
+* battery level, a day/night state that flips at dusk. It is the wrong number
+* for a cap like `privacy-mask`, whose two facts (is the video mask on, is the
+* microphone on) change when an operator changes them, through a `setMask` /
+* `setAudioEnabled` that **re-reads the camera and rewrites this very slice**.
+* A write is therefore its own invalidation: the window never delays an
+* operator's own change, however long it is.
+*
+* What the window really bounds is the ONE case we do not write: somebody
+* changing the mask in the vendor app or the camera's web UI. Ten minutes is
+* the trade — that change is visible within ten minutes, and a fleet of 29
+* cameras behind a page that polls every 5s costs about 3 camera round trips a
+* minute instead of 696
+* ([D221](../../../../docs/decisions/adr-0221-a-polled-list-never-dials-a-camera.md)).
+*
+* Use it ONLY with {@link RuntimeStateStaleReadPolicy} `'serve-and-revalidate'`.
+* On the awaiting default a window this long does not remove the stall, it
+* merely makes it rarer and just as long.
+*/
+var OPERATOR_WRITTEN_STALE_MS = 10 * 6e4;
 function createRuntimeStateBridge(params) {
 	const { runtimeState, cap, ownDeviceId, refresh, staleMs, empty, logger } = params;
 	const missCooldownMs = params.refreshMissCooldownMs ?? 6e4;
+	const staleRead = params.staleRead ?? "await-refresh";
 	/** Epoch ms until which a refresh is not re-attempted. 0 = no cooldown. */
 	let missCooldownUntil = 0;
+	/**
+	* The refresh this bridge currently has in the air, if any.
+	*
+	* Providers single-flight their own camera client, so this is not what stops
+	* a second round trip. What it stops is a POLLED reader JOINING one: under
+	* `'serve-and-revalidate'` a read that finds a refresh already outstanding is
+	* answered from the slice at once — even a cold, empty slice, which reports
+	* UNKNOWN, which is the truth about a camera nobody has reached.
+	*
+	* That distinction is the whole cost of an unreachable camera. Measured on
+	* the live hub (device 3629, an offline battery Reolink): its refresh takes
+	* 23.1s to give up, so without this every 5s poll landing inside those 23s
+	* joined the wait and spent the caller's full 1.2s source budget — five
+	* stalled polls per cooldown cycle, for one camera, forever.
+	*/
+	let refreshInFlight = null;
 	const readFetchedAt = () => {
 		const value = runtimeState.getCapState(cap.name)?.[LAST_FETCHED_FIELD];
 		return typeof value === "number" ? value : 0;
@@ -30457,14 +30579,14 @@ function createRuntimeStateBridge(params) {
 			}
 		});
 	};
-	const ensureFresh = async () => {
-		const slice = runtimeState.getCapState(cap.name);
-		const fetchedAt = readFetchedAt();
-		if (slice && Date.now() - fetchedAt <= staleMs) {
-			missCooldownUntil = 0;
-			return;
-		}
-		if (Date.now() < missCooldownUntil) return;
+	/**
+	* One refresh attempt, plus the LANDED check that decides the cooldown.
+	*
+	* @param fetchedAt What `lastFetchedAt` was before the attempt — the only
+	*                  evidence the bridge has that the refresh persisted
+	*                  anything, since providers swallow their own camera errors.
+	*/
+	const runRefresh = async (fetchedAt) => {
 		try {
 			await refresh();
 		} catch (err) {
@@ -30480,6 +30602,41 @@ function createRuntimeStateBridge(params) {
 		}
 		openMissCooldown(void 0);
 	};
+	/**
+	* Start a refresh and remember it, at most one at a time.
+	*
+	* It never rejects: under `'serve-and-revalidate'` the caller is answered
+	* from the slice either way, so a floating rejection would take the process
+	* down for a fault the miss cooldown has already recorded and logged.
+	*/
+	const startRefresh = (fetchedAt) => {
+		const existing = refreshInFlight;
+		if (existing !== null) return existing;
+		const started = runRefresh(fetchedAt).catch(() => void 0).finally(() => {
+			refreshInFlight = null;
+		});
+		refreshInFlight = started;
+		return started;
+	};
+	const ensureFresh = async () => {
+		const slice = runtimeState.getCapState(cap.name);
+		const fetchedAt = readFetchedAt();
+		if (slice && Date.now() - fetchedAt <= staleMs) {
+			missCooldownUntil = 0;
+			return;
+		}
+		if (Date.now() < missCooldownUntil) return;
+		if (staleRead === "serve-and-revalidate") {
+			if (refreshInFlight !== null) return;
+			if (slice && fetchedAt > 0) {
+				startRefresh(fetchedAt);
+				return;
+			}
+			await startRefresh(fetchedAt);
+			return;
+		}
+		await runRefresh(fetchedAt);
+	};
 	const projectStatus = () => {
 		const slice = runtimeState.getCapState(cap.name);
 		if (!slice) return empty();
@@ -42336,6 +42493,29 @@ var HikvisionDeviceCacheSchema = object({
 	* `DeviceFeature.TwoWayAudio` + the `intercom` cap registration.
 	*/
 	hasIntercom: boolean().optional(),
+	/**
+	* The `privacy-mask` cap's per-camera AVAILABILITY facts, as the last
+	* successful read saw them.
+	*
+	* Persisted for the same reason Reolink persists its `capOptionsSnapshot`:
+	* `privacyMask.getOptions` sits on a POLLED path (the admin Cameras badge
+	* asks it per camera every 5s), and these describe what the model can do —
+	* they change on a firmware update, not during operation. Reading them from
+	* here costs no ISAPI round trip, and it survives an addon restart, which
+	* an in-process value does not.
+	*
+	* They come out of the SAME two reads that build the cap's status slice, so
+	* they cannot drift from it.
+	*/
+	privacyMaskOptions: object({
+		/** Zones the firmware advertises. */
+		maxRegions: number().int().nonnegative(),
+		/** True only when a streaming channel reported an audio flag we can
+		*  patch — a switch that writes nothing must never be offered. */
+		supportsAudioMute: boolean(),
+		/** Epoch ms of the read that produced this. */
+		fetchedAt: number()
+	}).optional(),
 	/** ISAPI codec the firmware reports for the talk channel (e.g.
 	*  `G.711ulaw`, `G.711alaw`). Persisted so the intercom session
 	*  doesn't have to re-discover on every open. Optional — discovery
@@ -44338,7 +44518,68 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	registerPrivacyMaskCap(cameraNumber) {
 		const isapi = this.ensureClient();
 		const CAP_NAME = "privacy-mask";
-		const STALE_MS = 1e4;
+		/**
+		* The per-camera AVAILABILITY facts, as the last successful read saw them.
+		*
+		* `getOptions` used to make its own pair of ISAPI calls on every
+		* invocation — and `getCameraStatuses` calls it once per camera per 5s
+		* poll, so on this fleet (20 of 29 cameras are Hikvision) it was the
+		* single largest source of camera traffic on the badge path.
+		*
+		* It is not a second copy of anything: `maxRegions` and the audio-channel
+		* census live nowhere else, and they come out of the SAME two reads that
+		* build the status slice, so they cannot disagree with it. They are kept in
+		* the persisted `deviceCache` rather than only in memory because they must
+		* survive an addon restart — the status slice does (`durability:
+		* 'restored'`), and an options read that did not would be the one caller
+		* still dialling every camera after every deploy.
+		*/
+		const readPersistedOptions = () => {
+			const stored = this.config.get("deviceCache")?.privacyMaskOptions;
+			if (!stored) return null;
+			return {
+				maxRegions: stored.maxRegions,
+				supportedShapes: ["rect", "polygon"],
+				polygonVertices: {
+					min: 4,
+					max: 4
+				},
+				supportsAudioMute: stored.supportsAudioMute
+			};
+		};
+		/**
+		* Epoch ms until which a COLD options probe is not re-attempted.
+		*
+		* Only the cold path below can dial, and only on a camera that has never
+		* produced a descriptor — but "never" and "unreachable" are the same state,
+		* so without this an unreachable camera would be dialled once per poll
+		* forever. Same constant, same reasoning as the bridge's own miss cooldown.
+		*/
+		let optionsProbeCooldownUntil = 0;
+		/** Persist the descriptor, but only when it actually MOVED — this runs on
+		*  every refresh and a per-refresh SQLite commit for an unchanged model
+		*  capability is pure churn. Best-effort: a failed write costs the next
+		*  restart one probe. */
+		const persistOptions = async (next) => {
+			const stored = this.config.get("deviceCache")?.privacyMaskOptions;
+			if (stored && stored.maxRegions === next.maxRegions && stored.supportsAudioMute === next.supportsAudioMute) return;
+			try {
+				const previous = this.config.get("deviceCache") ?? {};
+				await this.config.setAll({ deviceCache: {
+					...previous,
+					privacyMaskOptions: {
+						maxRegions: next.maxRegions,
+						supportsAudioMute: next.supportsAudioMute,
+						fetchedAt: Date.now()
+					}
+				} });
+			} catch (err) {
+				this.ctx.logger.debug("hikvision privacy-mask options persist failed", {
+					tags: { deviceId: this.id },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			}
+		};
 		/** Round-trip the privacy-mask config → cap regions, write slice. */
 		const refreshFromCamera = async () => {
 			if (this.privacyMaskRefreshInFlight) return this.privacyMaskRefreshInFlight;
@@ -44346,6 +44587,15 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				try {
 					const [mask, audio] = await Promise.all([isapi.getPrivacyMask(cameraNumber), this.readStreamAudioChannels(cameraNumber)]);
 					if (!mask) return;
+					await persistOptions({
+						maxRegions: mask.maxRegions > 0 ? mask.maxRegions : 4,
+						supportedShapes: ["rect", "polygon"],
+						polygonVertices: {
+							min: 4,
+							max: 4
+						},
+						supportsAudioMute: audio.length > 0
+					});
 					const regions = mask.regions.map((region, index) => ({
 						id: index,
 						enabled: true,
@@ -44372,22 +44622,25 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				this.privacyMaskRefreshInFlight = null;
 			}
 		};
+		const bridge = createRuntimeStateBridge({
+			runtimeState: this.runtimeState,
+			cap: privacyMaskCapability,
+			ownDeviceId: this.id,
+			refresh: refreshFromCamera,
+			staleMs: OPERATOR_WRITTEN_STALE_MS,
+			staleRead: "serve-and-revalidate",
+			logger: this.ctx.logger,
+			empty: () => ({
+				enabled: false,
+				regions: [],
+				audioEnabled: null,
+				lastFetchedAt: 0
+			})
+		});
 		const provider = {
-			getStatus: createRuntimeStateBridge({
-				runtimeState: this.runtimeState,
-				cap: privacyMaskCapability,
-				ownDeviceId: this.id,
-				refresh: refreshFromCamera,
-				staleMs: STALE_MS,
-				empty: () => ({
-					enabled: false,
-					regions: [],
-					audioEnabled: null,
-					lastFetchedAt: 0
-				})
-			}).getStatus,
+			getStatus: bridge.getStatus,
 			getOptions: async ({ deviceId }) => {
-				const cold = {
+				if (deviceId !== this.id) return {
 					maxRegions: 4,
 					supportedShapes: ["rect", "polygon"],
 					polygonVertices: {
@@ -44396,17 +44649,16 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					},
 					supportsAudioMute: false
 				};
-				if (deviceId !== this.id) return cold;
-				const [mask, audio] = await Promise.all([isapi.getPrivacyMask(cameraNumber), this.readStreamAudioChannels(cameraNumber)]);
-				return {
-					maxRegions: mask && mask.maxRegions > 0 ? mask.maxRegions : 4,
-					supportedShapes: ["rect", "polygon"],
-					polygonVertices: {
-						min: 4,
-						max: 4
-					},
-					supportsAudioMute: audio.length > 0
-				};
+				await bridge.ensureFresh();
+				const warm = readPersistedOptions();
+				if (warm !== null) return warm;
+				if (Date.now() >= optionsProbeCooldownUntil) {
+					optionsProbeCooldownUntil = Date.now() + RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS;
+					await refreshFromCamera();
+					const cold = readPersistedOptions();
+					if (cold !== null) return cold;
+				}
+				throw new Error(`device ${String(this.id)}: privacy-mask options unknown — the camera has not answered`);
 			},
 			setMask: async ({ deviceId, patch }) => {
 				if (deviceId !== this.id) return;

package/dist/addon.mjs

@@ -7,7 +7,7 @@ import { networkInterfaces } from "node:os";
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
-//#region ../types/dist/event-category-XfKNtfCc.mjs
+//#region ../types/dist/event-category-CIa_iT6b.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -23,6 +23,15 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["SystemRestartCompleted"] = "system.restart-completed";
 	/**
+	* The hub reissued its own TLS certificate at boot (`ensureTlsCert`).
+	* Emitted only when the material on disk actually changed, so an
+	* operator who trusted the old certificate by hand is told rather than
+	* discovering it as a browser error. Payload `TlsCertChangedPayload`.
+	*
+	* Rule: docs/decisions/adr-0227-*.md
+	*/
+	EventCategory["SystemTlsCertChanged"] = "system.tls-cert-changed";
+	/**
 	* A newer addon or server-root package version was found by the
 	* authoritative registry check. Emitted once when any observed
 	* `latestVersion` changes (or a package/node first appears behind);
@@ -19164,6 +19173,12 @@ var CameraStatusSchema = object({
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: number()
 });
+var InferenceDeviceExclusionReasonSchema = _enum([
+	"disabled",
+	"unavailable",
+	"cannot-host-camera-root",
+	"accelerator-preferred"
+]);
 var NodeInferenceDeviceSchema = object({
 	/** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
 	key: string(),
@@ -19194,7 +19209,17 @@ var NodeInferenceDeviceSchema = object({
 	* available per format; this is the stored selection that becomes the
 	* default for EVERY camera landing on this accelerator.
 	*/
-	steps: record(string(), DeviceStepConfigSchema).optional()
+	steps: record(string(), DeviceStepConfigSchema).optional(),
+	/**
+	* `null` when the device IS a camera-root candidate on this node; otherwise
+	* the reason the dispatcher drops it. Computed by the SAME
+	* `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+	* never disagree with the election — deriving it in the UI from
+	* `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+	* the node's model catalog) and `accelerator-preferred` (needs the node-wide
+	* "an accelerator is serving" predicate).
+	*/
+	exclusion: InferenceDeviceExclusionReasonSchema.nullable()
 });
 var NodeInferenceDevicesSchema = object({
 	nodeId: string(),
@@ -24149,7 +24174,12 @@ var ListResultSchema = object({
 	probedAt: number()
 });
 var PreferredSchema = LocalInterfaceSchema.nullable();
-var GetConnectionEndpointsResultSchema = object({ endpoints: array(object({
+/**
+* Candidate base URL for the SDK to race on connect. Order matters —
+* the SDK should attempt these top-to-bottom with a short per-candidate
+* timeout (e.g. 1500ms) and cache the winner for the session.
+*/
+var ConnectionEndpointSchema = object({
 	/** Operator-facing label (e.g. "LAN — en0", "Public tunnel"). */
 	label: string(),
 	/** Fully-formed base URL with scheme + host + port. */
@@ -24192,7 +24222,42 @@ var GetConnectionEndpointsResultSchema = object({ endpoints: array(object({
 	* ordering between polls.
 	*/
 	priority: number()
-})).readonly() });
+});
+/**
+* Where the advertised local port came from. Ordered most → least
+* authoritative, and the whole point of returning it: a client must be able to
+* tell a FACT about the hub's socket from an echo of its own guess.
+*/
+var LocalPortSourceEnum = _enum([
+	"server-config",
+	"server-env",
+	"caller-hint",
+	"default"
+]);
+/** The port every LAN/loopback `baseUrl` in the same result was built with. */
+var AdvertisedLocalPortSchema = object({
+	port: number().int().min(1).max(65535),
+	source: LocalPortSourceEnum
+});
+var GetConnectionEndpointsResultSchema = object({
+	endpoints: array(ConnectionEndpointSchema).readonly(),
+	/**
+	* The port the hub built the LAN/loopback URLs with, and where that number
+	* came from.
+	*
+	* Returned rather than merely applied, because "the URL is right" and "the
+	* client can KNOW the URL is right" are different properties. A client that
+	* only sees a corrected URL cannot distinguish a hub that fixed the port from
+	* a hub that echoed the port the client sent, so it cannot decide whether to
+	* race the candidate or discard it. With `source` it can: anything but
+	* `caller-hint` is the hub's own socket.
+	*
+	* Absent on hubs predating this field — a client that finds it missing is
+	* talking to an echoing hub and must degrade exactly as it does for
+	* `caller-hint`.
+	*/
+	localPort: AdvertisedLocalPortSchema
+});
 /**
 * The chosen outbound endpoint for notification artifacts. `baseUrl: null` =
 * AUTO (resolved from the candidate ranking at send time); `resolved` reports
@@ -24213,8 +24278,13 @@ var AllowedAddressesSchema = object({
 */
 addresses: array(string()).readonly() });
 method(_void(), ListResultSchema), method(_void(), PreferredSchema), method(object({
-	/** Local hub HTTP port to use in base URLs. */
-	port: number().int().min(1).max(65535),
+	/**
+	* LEGACY HINT — do not send from new code. Kept optional so clients
+	* written against the echoing contract keep working; the hub uses it
+	* only when it cannot read its own port, and says so via
+	* `localPort.source === 'caller-hint'`.
+	*/
+	port: number().int().min(1).max(65535).optional(),
 	/** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
 	*  candidate. Default `true`. */
 	includeLoopback: boolean().optional(),
@@ -30433,11 +30503,63 @@ function startReachabilityPoll(options) {
 	} };
 }
 var LAST_FETCHED_FIELD = "lastFetchedAt";
+/**
+* How long a bridge stops re-attempting a refresh that did not land.
+*
+* Sized against the failure it exists for: a camera whose control plane
+* is unreachable costs the FULL connect give-up (~3s on Linux when the
+* neighbour never answers, up to the client's own timeout otherwise) on
+* every attempt, and a failed refresh never advances `lastFetchedAt`, so
+* without a cooldown the slice is permanently stale and EVERY read pays
+* that price. One attempt per minute is enough to notice the camera
+* coming back; per-read is enough to stall the viewer's first paint.
+*/
+var RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = 6e4;
+/**
+* The freshness window for a cap whose value changes ONLY when WE write it.
+*
+* The usual `staleMs: 10_000` is tuned for a reading that moves on its own — a
+* battery level, a day/night state that flips at dusk. It is the wrong number
+* for a cap like `privacy-mask`, whose two facts (is the video mask on, is the
+* microphone on) change when an operator changes them, through a `setMask` /
+* `setAudioEnabled` that **re-reads the camera and rewrites this very slice**.
+* A write is therefore its own invalidation: the window never delays an
+* operator's own change, however long it is.
+*
+* What the window really bounds is the ONE case we do not write: somebody
+* changing the mask in the vendor app or the camera's web UI. Ten minutes is
+* the trade — that change is visible within ten minutes, and a fleet of 29
+* cameras behind a page that polls every 5s costs about 3 camera round trips a
+* minute instead of 696
+* ([D221](../../../../docs/decisions/adr-0221-a-polled-list-never-dials-a-camera.md)).
+*
+* Use it ONLY with {@link RuntimeStateStaleReadPolicy} `'serve-and-revalidate'`.
+* On the awaiting default a window this long does not remove the stall, it
+* merely makes it rarer and just as long.
+*/
+var OPERATOR_WRITTEN_STALE_MS = 10 * 6e4;
 function createRuntimeStateBridge(params) {
 	const { runtimeState, cap, ownDeviceId, refresh, staleMs, empty, logger } = params;
 	const missCooldownMs = params.refreshMissCooldownMs ?? 6e4;
+	const staleRead = params.staleRead ?? "await-refresh";
 	/** Epoch ms until which a refresh is not re-attempted. 0 = no cooldown. */
 	let missCooldownUntil = 0;
+	/**
+	* The refresh this bridge currently has in the air, if any.
+	*
+	* Providers single-flight their own camera client, so this is not what stops
+	* a second round trip. What it stops is a POLLED reader JOINING one: under
+	* `'serve-and-revalidate'` a read that finds a refresh already outstanding is
+	* answered from the slice at once — even a cold, empty slice, which reports
+	* UNKNOWN, which is the truth about a camera nobody has reached.
+	*
+	* That distinction is the whole cost of an unreachable camera. Measured on
+	* the live hub (device 3629, an offline battery Reolink): its refresh takes
+	* 23.1s to give up, so without this every 5s poll landing inside those 23s
+	* joined the wait and spent the caller's full 1.2s source budget — five
+	* stalled polls per cooldown cycle, for one camera, forever.
+	*/
+	let refreshInFlight = null;
 	const readFetchedAt = () => {
 		const value = runtimeState.getCapState(cap.name)?.[LAST_FETCHED_FIELD];
 		return typeof value === "number" ? value : 0;
@@ -30458,14 +30580,14 @@ function createRuntimeStateBridge(params) {
 			}
 		});
 	};
-	const ensureFresh = async () => {
-		const slice = runtimeState.getCapState(cap.name);
-		const fetchedAt = readFetchedAt();
-		if (slice && Date.now() - fetchedAt <= staleMs) {
-			missCooldownUntil = 0;
-			return;
-		}
-		if (Date.now() < missCooldownUntil) return;
+	/**
+	* One refresh attempt, plus the LANDED check that decides the cooldown.
+	*
+	* @param fetchedAt What `lastFetchedAt` was before the attempt — the only
+	*                  evidence the bridge has that the refresh persisted
+	*                  anything, since providers swallow their own camera errors.
+	*/
+	const runRefresh = async (fetchedAt) => {
 		try {
 			await refresh();
 		} catch (err) {
@@ -30481,6 +30603,41 @@ function createRuntimeStateBridge(params) {
 		}
 		openMissCooldown(void 0);
 	};
+	/**
+	* Start a refresh and remember it, at most one at a time.
+	*
+	* It never rejects: under `'serve-and-revalidate'` the caller is answered
+	* from the slice either way, so a floating rejection would take the process
+	* down for a fault the miss cooldown has already recorded and logged.
+	*/
+	const startRefresh = (fetchedAt) => {
+		const existing = refreshInFlight;
+		if (existing !== null) return existing;
+		const started = runRefresh(fetchedAt).catch(() => void 0).finally(() => {
+			refreshInFlight = null;
+		});
+		refreshInFlight = started;
+		return started;
+	};
+	const ensureFresh = async () => {
+		const slice = runtimeState.getCapState(cap.name);
+		const fetchedAt = readFetchedAt();
+		if (slice && Date.now() - fetchedAt <= staleMs) {
+			missCooldownUntil = 0;
+			return;
+		}
+		if (Date.now() < missCooldownUntil) return;
+		if (staleRead === "serve-and-revalidate") {
+			if (refreshInFlight !== null) return;
+			if (slice && fetchedAt > 0) {
+				startRefresh(fetchedAt);
+				return;
+			}
+			await startRefresh(fetchedAt);
+			return;
+		}
+		await runRefresh(fetchedAt);
+	};
 	const projectStatus = () => {
 		const slice = runtimeState.getCapState(cap.name);
 		if (!slice) return empty();
@@ -42337,6 +42494,29 @@ var HikvisionDeviceCacheSchema = object({
 	* `DeviceFeature.TwoWayAudio` + the `intercom` cap registration.
 	*/
 	hasIntercom: boolean().optional(),
+	/**
+	* The `privacy-mask` cap's per-camera AVAILABILITY facts, as the last
+	* successful read saw them.
+	*
+	* Persisted for the same reason Reolink persists its `capOptionsSnapshot`:
+	* `privacyMask.getOptions` sits on a POLLED path (the admin Cameras badge
+	* asks it per camera every 5s), and these describe what the model can do —
+	* they change on a firmware update, not during operation. Reading them from
+	* here costs no ISAPI round trip, and it survives an addon restart, which
+	* an in-process value does not.
+	*
+	* They come out of the SAME two reads that build the cap's status slice, so
+	* they cannot drift from it.
+	*/
+	privacyMaskOptions: object({
+		/** Zones the firmware advertises. */
+		maxRegions: number().int().nonnegative(),
+		/** True only when a streaming channel reported an audio flag we can
+		*  patch — a switch that writes nothing must never be offered. */
+		supportsAudioMute: boolean(),
+		/** Epoch ms of the read that produced this. */
+		fetchedAt: number()
+	}).optional(),
 	/** ISAPI codec the firmware reports for the talk channel (e.g.
 	*  `G.711ulaw`, `G.711alaw`). Persisted so the intercom session
 	*  doesn't have to re-discover on every open. Optional — discovery
@@ -44339,7 +44519,68 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	registerPrivacyMaskCap(cameraNumber) {
 		const isapi = this.ensureClient();
 		const CAP_NAME = "privacy-mask";
-		const STALE_MS = 1e4;
+		/**
+		* The per-camera AVAILABILITY facts, as the last successful read saw them.
+		*
+		* `getOptions` used to make its own pair of ISAPI calls on every
+		* invocation — and `getCameraStatuses` calls it once per camera per 5s
+		* poll, so on this fleet (20 of 29 cameras are Hikvision) it was the
+		* single largest source of camera traffic on the badge path.
+		*
+		* It is not a second copy of anything: `maxRegions` and the audio-channel
+		* census live nowhere else, and they come out of the SAME two reads that
+		* build the status slice, so they cannot disagree with it. They are kept in
+		* the persisted `deviceCache` rather than only in memory because they must
+		* survive an addon restart — the status slice does (`durability:
+		* 'restored'`), and an options read that did not would be the one caller
+		* still dialling every camera after every deploy.
+		*/
+		const readPersistedOptions = () => {
+			const stored = this.config.get("deviceCache")?.privacyMaskOptions;
+			if (!stored) return null;
+			return {
+				maxRegions: stored.maxRegions,
+				supportedShapes: ["rect", "polygon"],
+				polygonVertices: {
+					min: 4,
+					max: 4
+				},
+				supportsAudioMute: stored.supportsAudioMute
+			};
+		};
+		/**
+		* Epoch ms until which a COLD options probe is not re-attempted.
+		*
+		* Only the cold path below can dial, and only on a camera that has never
+		* produced a descriptor — but "never" and "unreachable" are the same state,
+		* so without this an unreachable camera would be dialled once per poll
+		* forever. Same constant, same reasoning as the bridge's own miss cooldown.
+		*/
+		let optionsProbeCooldownUntil = 0;
+		/** Persist the descriptor, but only when it actually MOVED — this runs on
+		*  every refresh and a per-refresh SQLite commit for an unchanged model
+		*  capability is pure churn. Best-effort: a failed write costs the next
+		*  restart one probe. */
+		const persistOptions = async (next) => {
+			const stored = this.config.get("deviceCache")?.privacyMaskOptions;
+			if (stored && stored.maxRegions === next.maxRegions && stored.supportsAudioMute === next.supportsAudioMute) return;
+			try {
+				const previous = this.config.get("deviceCache") ?? {};
+				await this.config.setAll({ deviceCache: {
+					...previous,
+					privacyMaskOptions: {
+						maxRegions: next.maxRegions,
+						supportsAudioMute: next.supportsAudioMute,
+						fetchedAt: Date.now()
+					}
+				} });
+			} catch (err) {
+				this.ctx.logger.debug("hikvision privacy-mask options persist failed", {
+					tags: { deviceId: this.id },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			}
+		};
 		/** Round-trip the privacy-mask config → cap regions, write slice. */
 		const refreshFromCamera = async () => {
 			if (this.privacyMaskRefreshInFlight) return this.privacyMaskRefreshInFlight;
@@ -44347,6 +44588,15 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				try {
 					const [mask, audio] = await Promise.all([isapi.getPrivacyMask(cameraNumber), this.readStreamAudioChannels(cameraNumber)]);
 					if (!mask) return;
+					await persistOptions({
+						maxRegions: mask.maxRegions > 0 ? mask.maxRegions : 4,
+						supportedShapes: ["rect", "polygon"],
+						polygonVertices: {
+							min: 4,
+							max: 4
+						},
+						supportsAudioMute: audio.length > 0
+					});
 					const regions = mask.regions.map((region, index) => ({
 						id: index,
 						enabled: true,
@@ -44373,22 +44623,25 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				this.privacyMaskRefreshInFlight = null;
 			}
 		};
+		const bridge = createRuntimeStateBridge({
+			runtimeState: this.runtimeState,
+			cap: privacyMaskCapability,
+			ownDeviceId: this.id,
+			refresh: refreshFromCamera,
+			staleMs: OPERATOR_WRITTEN_STALE_MS,
+			staleRead: "serve-and-revalidate",
+			logger: this.ctx.logger,
+			empty: () => ({
+				enabled: false,
+				regions: [],
+				audioEnabled: null,
+				lastFetchedAt: 0
+			})
+		});
 		const provider = {
-			getStatus: createRuntimeStateBridge({
-				runtimeState: this.runtimeState,
-				cap: privacyMaskCapability,
-				ownDeviceId: this.id,
-				refresh: refreshFromCamera,
-				staleMs: STALE_MS,
-				empty: () => ({
-					enabled: false,
-					regions: [],
-					audioEnabled: null,
-					lastFetchedAt: 0
-				})
-			}).getStatus,
+			getStatus: bridge.getStatus,
 			getOptions: async ({ deviceId }) => {
-				const cold = {
+				if (deviceId !== this.id) return {
 					maxRegions: 4,
 					supportedShapes: ["rect", "polygon"],
 					polygonVertices: {
@@ -44397,17 +44650,16 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					},
 					supportsAudioMute: false
 				};
-				if (deviceId !== this.id) return cold;
-				const [mask, audio] = await Promise.all([isapi.getPrivacyMask(cameraNumber), this.readStreamAudioChannels(cameraNumber)]);
-				return {
-					maxRegions: mask && mask.maxRegions > 0 ? mask.maxRegions : 4,
-					supportedShapes: ["rect", "polygon"],
-					polygonVertices: {
-						min: 4,
-						max: 4
-					},
-					supportsAudioMute: audio.length > 0
-				};
+				await bridge.ensureFresh();
+				const warm = readPersistedOptions();
+				if (warm !== null) return warm;
+				if (Date.now() >= optionsProbeCooldownUntil) {
+					optionsProbeCooldownUntil = Date.now() + RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS;
+					await refreshFromCamera();
+					const cold = readPersistedOptions();
+					if (cold !== null) return cold;
+				}
+				throw new Error(`device ${String(this.id)}: privacy-mask options unknown — the camera has not answered`);
 			},
 			setMask: async ({ deviceId, patch }) => {
 				if (deviceId !== this.id) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-hikvision",
-  "version": "1.2.31",
+  "version": "1.2.33",
   "description": "Hikvision camera device provider addon for CamStack — ISAPI over HTTP(S) with digest auth (snapshot, alarm stream, RTSP discovery)",
   "keywords": [
     "camstack",