@camstack/addon-provider-unifi 0.2.151 → 0.2.153

package/CHANGELOG.md

@@ -7,11 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.153] - 2026-11-01
+
+### Changed
+
+- An integration deleted while its provider was down now has its orphan devices removed after two concordant reads of the integration list
+
+## [0.2.152] - 2026-11-01
+
+### Changed
+
+- Declares the minimum CamStack server it needs; the Addons page shows a held update as requires server >= X
+- Integration reconcile no longer removes devices when the integration list or settings read fails or is empty; devices are removed only on an explicit Deleted/Disabled event
+
 ## [0.2.151] - 2026-11-01
 
 ### Changed
 
 - UniFi is now added as an integration: the controller connection and credentials are the integration's settings, and the controller appears as a Gateway beside its infra devices and clients instead of a Hub.
+- Declares the minimum CamStack server it needs; the Addons page shows a held update as requires server >= X
 
 ## [0.2.150] - 2026-10-28
 

package/dist/addon.js

@@ -5831,7 +5831,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-BHS4ImRX.mjs
+//#region ../types/dist/sleep-CSYuxssh.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -9114,7 +9114,7 @@ var ProfileRtspEntrySchema = object({
 /**
 * The model weight formats a catalog entry can ship. Schema-free on purpose:
 * `types/models.ts` builds Zod schemas from it, but a runner-closure consumer
-* (the model downloader in `@camstack/system`) needs only the list and must
+* (the model downloader in `@camstack/server/system`) needs only the list and must
 * reach it through `@camstack/types/addon` without building the cap schema
 * graph (D28).
 */
@@ -12489,6 +12489,71 @@ var EventOwnerTypeSchema = _enum(EVENT_OWNER_TYPES);
 var MediaPresenceOwnerKindSchema = _enum([...EVENT_OWNER_TYPES, "track"]);
 new Set(EVENT_OWNER_TYPES);
 /**
+* What a published package needs from the rest of the install (D989).
+*
+* One published framework package (`@camstack/server`) carries the kernel, the
+* builtins and the capability contracts, so "which addon runs on which
+* framework" is a question of version, and the answer is DECLARED by the
+* package that knows it:
+*
+*   - an addon says the oldest server it runs on (`requires.server: ">=X"`);
+*   - the server says the oldest addon it works with
+*     (`requires.addons: { "@camstack/addon-x": ">=Y" }`) and the oldest shell
+*     around it (`requires.wrapper: { desktop, image }`);
+*   - a wrapper (the desktop app, the container starter) says which server
+*     range it can host, and reports its own kind and version.
+*
+* The publish workflow STAMPS these after the version bump
+* (`scripts/ci/stamp-requires.mjs`); nobody types a number by hand.
+*
+* A requirement that cannot be checked is NOT met: a shell that reports no
+* version counts as below the minimum, and an unreadable running version is
+* named in the result (a failed read is never a pass).
+*/
+/** `>=MAJOR.MINOR.PATCH[-prerelease]` — the only range shape a requirement uses. */
+var MinVersionSchema = string().regex(/^>=\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, "a minimum is written \">=X.Y.Z\"");
+object({
+	/** The oldest `@camstack/server` this package runs on. */
+	server: MinVersionSchema.optional(),
+	/** The oldest installed version of each named addon package. */
+	addons: record(string(), MinVersionSchema).optional(),
+	/** The oldest shell around the server, per shell kind. */
+	wrapper: object({
+		desktop: MinVersionSchema.optional(),
+		image: MinVersionSchema.optional()
+	}).optional()
+});
+/** One unmet requirement; each names the versions on both sides. */
+var UnmetRequirementSchema = discriminatedUnion("kind", [
+	object({
+		kind: literal("server-too-old"),
+		required: string(),
+		/** `null` — the running server version could not be read. */
+		running: string().nullable()
+	}),
+	object({
+		kind: literal("addon-too-old"),
+		packageName: string(),
+		required: string(),
+		/** `null` — the addon is not installed (or its version is unreadable). */
+		running: string().nullable()
+	}),
+	object({
+		kind: literal("wrapper-too-old"),
+		wrapper: _enum(["desktop", "image"]),
+		required: string(),
+		/** `null` — the wrapper reported no version. */
+		running: string().nullable()
+	})
+]);
+var RequiredAddonUpdateSchema = object({
+	packageName: string(),
+	/** The minimum the target server declares. */
+	required: string(),
+	/** What this node has; `null` when the addon is not installed. */
+	installed: string().nullable()
+});
+/**
 * Which integration instance a settings form is for. An addon that serves several instances
 * (`instanceMode: multiple`) can show a different form per instance — an NVR integration
 * needs its connection, the default integration needs the addon's own sections.
@@ -42904,7 +42969,7 @@ method(object({}), array(TargetKindSchema)), method(object({}), array(TargetSche
 * rebuilds without manual reload.
 *
 * The hub-local builtin `addon-pages-aggregator` (see
-* `@camstack/system/builtins/addon-pages-aggregator`) registers the
+* `@camstack/server/system/builtins/addon-pages-aggregator`) registers the
 * provider. Splitting the public aggregator from the raw collection
 * keeps both ends in codegen — there's no hand-written
 * `addon-pages.router.ts` wrapper anymore.
@@ -43204,7 +43269,7 @@ method(_void(), array(WidgetMetadataSchema).readonly(), { auth: "admin" });
 * manual reload — same scheme used by `addon-pages`.
 *
 * The hub-local builtin `addon-widgets-aggregator` (see
-* `@camstack/system/builtins/addon-widgets-aggregator`) registers the
+* `@camstack/server/system/builtins/addon-widgets-aggregator`) registers the
 * provider. Splitting the public aggregator from the raw collection
 * keeps both ends in codegen — there's no hand-written wrapper.
 */
@@ -61404,7 +61469,18 @@ var ServerUpdateActionResultSchema = object({
 	* store (D877), present when the pre-flight refused the update
 	* (`reason: 'addon-would-refuse'`). Optional for version skew.
 	*/
-	blockers: array(UpdateBlockerSchema).optional()
+	blockers: array(UpdateBlockerSchema).optional(),
+	/**
+	* The minimums the target server declares and this node does not meet
+	* (D989), present when the update was refused with
+	* `reason: 'requirements-unmet'`. Each names the versions on both sides.
+	*/
+	unmet: array(UnmetRequirementSchema).optional(),
+	/**
+	* The addons this node has below the minimum the staged server declares —
+	* the ones to update WITH the server. Present on an accepted update.
+	*/
+	requiredAddonUpdates: array(RequiredAddonUpdateSchema).optional()
 });
 var LaunchOverridesSchema = object({ 
 /** The persisted heap ceiling in MB, or `null` when none is set. */
@@ -63948,7 +64024,9 @@ var PackageUpdateSchema = object({
 	latestVersion: string(),
 	category: _enum(["addon", "core"]),
 	requiresRestart: boolean(),
-	isSystem: boolean()
+	isSystem: boolean(),
+	/** Held: what the newer version needs and this node does not meet (D989). */
+	blockedBy: array(UnmetRequirementSchema).readonly().optional()
 });
 var PackageVersionInfoSchema = object({
 	version: string(),
@@ -69248,7 +69326,7 @@ var lawnMowerControlCapability = {
 * clients — they reverse-connect to the hub. Exposing their interfaces
 * via the same surface would leak internal topology with no upside.
 *
-* Implementation in `@camstack/system/builtins/local-network/`.
+* Implementation in `@camstack/server/system/builtins/local-network/`.
 */
 /** Coarse classification derived from the interface name + IP range. */
 var InterfaceKindEnum = _enum([
@@ -71136,7 +71214,7 @@ onStatusChanged: { data: object({
 * jitter, and observed/peak bandwidth per device + per client.
 *
 * Implementation lives in the server's `NetworkQualityService` (thin
-* wrapper over the shared `NetworkQualityTracker` from `@camstack/system`).
+* wrapper over the shared `NetworkQualityTracker` from `@camstack/server/system`).
 * The provider is registered from `trpc.router.ts` against the existing
 * service instance — no addon owns this state.
 *
@@ -73287,7 +73365,7 @@ var ptzAutotrackCapability = {
 	*  - **Native**: the camera's own firmware autotrack, registered per device by
 	*    the driver when the probe says it exists (Reolink: yes; Hikvision:
 	*    model-dependent).
-	*  - **Wrapper**: the emulated implementation (`@camstack/system`'s `autotrack` builtin),
+	*  - **Wrapper**: the emulated implementation (`@camstack/server/system`'s `autotrack` builtin),
 	*    which follows a subject with `ptz.move` pulses driven by the detection
 	*    pipeline. `defaultActive: false` — the operator binds it per camera in
 	*    the bindings UI.
@@ -94419,6 +94497,88 @@ DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.sceneBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
+/**
+* Closes the gap D49 leaves: an integration deleted while its provider was down never emits an
+* event the provider sees. An integration id absent from an ANSWERED list is only a suspect; its
+* devices go (through the provider's own removeDevices) when a SECOND answered read, at least
+* `minIntervalMs` later, still lacks it. A read that threw changes nothing; reappearing clears.
+*/
+var OrphanIntegrationSweep = class {
+	#logger;
+	#minIntervalMs;
+	#now;
+	#suspects = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#logger = options.logger;
+		this.#minIntervalMs = options.minIntervalMs ?? 6e4;
+		this.#now = options.now ?? Date.now;
+	}
+	get minIntervalMs() {
+		return this.#minIntervalMs;
+	}
+	async sweep(input) {
+		if (input.listedIds === null) return {
+			newSuspects: 0,
+			removed: []
+		};
+		const listed = new Set(input.listedIds);
+		const owners = new Set(input.ownerIds);
+		const now = this.#now();
+		let newSuspects = 0;
+		const removed = [];
+		for (const id of [...this.#suspects.keys()]) if (listed.has(id) || !owners.has(id)) {
+			this.#suspects.delete(id);
+			this.#logger.info("Orphan integration suspect cleared", { meta: {
+				integrationId: id,
+				reason: listed.has(id) ? "listed again" : "owns no devices"
+			} });
+		}
+		for (const id of owners) {
+			if (listed.has(id)) continue;
+			const since = this.#suspects.get(id);
+			if (since === void 0) {
+				this.#suspects.set(id, now);
+				newSuspects += 1;
+				this.#logger.info("Integration owns devices but is absent from the list — suspect", { meta: {
+					integrationId: id,
+					minIntervalMs: this.#minIntervalMs
+				} });
+				continue;
+			}
+			if (now - since < this.#minIntervalMs) continue;
+			try {
+				const count = await input.removeDevices(id);
+				this.#suspects.delete(id);
+				removed.push(id);
+				this.#logger.warn("Orphan integration devices removed — absent from two answered lists", { meta: {
+					integrationId: id,
+					removed: count,
+					firstMissingAt: since
+				} });
+			} catch (err) {
+				this.#logger.warn("Orphan integration device removal failed — kept as suspect", { meta: {
+					integrationId: id,
+					error: errMsg(err)
+				} });
+			}
+		}
+		return {
+			newSuspects,
+			removed
+		};
+	}
+};
+/** The integration ids that own top-level devices of one provider (a config that cannot be read is skipped). */
+async function collectOwnerIntegrationIds(input) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const d of input.reg.getAllForAddon(input.addonId)) {
+		if (d.parentDeviceId !== null) continue;
+		const cfg = await input.devices.loadConfig(d.id).catch(() => ({}));
+		const owner = input.ownerOf(cfg);
+		if (owner !== null) ids.add(owner);
+	}
+	return [...ids];
+}
 String.raw`(?<=^|["'(\s>,\[{])`;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
@@ -95915,6 +96075,97 @@ async function reconcileInfraFeatures(input) {
 	return changed;
 }
 //#endregion
+//#region src/unifi-reconciler.ts
+/**
+* Keeps one live client per enabled integration. Devices are removed ONLY on an explicit
+* lifecycle event naming the integration (D49): a list that failed, an empty list or an
+* unreadable connection changes nothing about devices and is logged, never read as "gone".
+*/
+var UnifiReconciler = class {
+	#deps;
+	#sweep;
+	#rerun = null;
+	constructor(deps) {
+		this.#deps = deps;
+		this.#sweep = new OrphanIntegrationSweep({
+			logger: deps.logger,
+			...deps.sweepOptions
+		});
+	}
+	/** Upsert a client per usable enabled integration; drop the CLIENT (never devices) of one the list answered is gone. */
+	async reconcile() {
+		const { logger, clients } = this.#deps;
+		let all;
+		try {
+			all = await this.#deps.listIntegrations();
+		} catch (err) {
+			logger.warn("Unifi integration reconcile skipped — the integration list did not answer", { meta: { error: errMsg(err) } });
+			return;
+		}
+		const enabled = all.filter((i) => i.addonId === this.#deps.addonId && i.enabled);
+		for (const integration of enabled) try {
+			if (!await this.#deps.applySettings(integration)) logger.warn("Unifi integration has no usable connection — left as it is", { meta: { integrationId: integration.id } });
+		} catch (err) {
+			logger.warn("Unifi reconcile failed for integration — left as it is", { meta: {
+				integrationId: integration.id,
+				error: errMsg(err)
+			} });
+		}
+		const enabledIds = new Set(enabled.map((i) => i.id));
+		for (const id of clients.list()) if (!enabledIds.has(id)) await clients.remove(id);
+		await this.#sweepOrphans(all.map((i) => i.id));
+	}
+	/** Stop the scheduled second read (addon stop). */
+	dispose() {
+		if (this.#rerun !== null) clearTimeout(this.#rerun);
+		this.#rerun = null;
+	}
+	/**
+	* An integration deleted while this addon was down emits nothing it sees: its id owns devices
+	* yet is absent from the ANSWERED list. Removal needs a second answered read later, so one
+	* re-run is scheduled when a suspect appears (bounded: one timer, no retry loop).
+	*/
+	async #sweepOrphans(listedIds) {
+		const { ownerIntegrationIds, removeDevices, logger } = this.#deps;
+		if (ownerIntegrationIds === void 0) return;
+		try {
+			const ownerIds = await ownerIntegrationIds();
+			if ((await this.#sweep.sweep({
+				ownerIds,
+				listedIds,
+				removeDevices
+			})).newSuspects > 0 && this.#rerun === null) {
+				this.#rerun = setTimeout(() => {
+					this.#rerun = null;
+					this.reconcile();
+				}, this.#sweep.minIntervalMs + 1e3);
+				this.#rerun.unref();
+			}
+		} catch (err) {
+			logger.warn("Orphan integration sweep failed — devices left as they are", { meta: { error: errMsg(err) } });
+		}
+	}
+	/** An explicit lifecycle event: only `deleted` / `disabled` of a named integration remove devices. */
+	async onLifecycle(kind, integrationId) {
+		await this.reconcile();
+		if (kind === "enabled" || integrationId === null) return;
+		try {
+			const removed = await this.#deps.removeDevices(integrationId);
+			this.#deps.logger.info("Unifi integration devices removed", { meta: {
+				integrationId,
+				kind,
+				removed
+			} });
+		} catch (err) {
+			this.#deps.logger.warn("Unifi integration device removal failed", { meta: {
+				integrationId,
+				kind,
+				error: errMsg(err)
+			} });
+		}
+	}
+};
+//#endregion
 //#region src/unifi-integration-device-cascade.ts
 /**
 * Remove every top-level device (Gateway, infra Container, client Presence) of an integration that
@@ -95992,6 +96243,7 @@ var UnifiProviderAddon = class extends BaseDeviceProvider {
 		[DeviceType.Sensor]: UnifiFeatureDevice,
 		[DeviceType.Presence]: UnifiFeatureDevice
 	};
+	integrationReconciler = null;
 	clients = null;
 	constructor() {
 		super({});
@@ -96017,6 +96269,8 @@ var UnifiProviderAddon = class extends BaseDeviceProvider {
 			this.ctx.logger.warn("UniFi shutdown error", { meta: { error: errMsg(err) } });
 		}
 		this.clients = null;
+		this.integrationReconciler?.dispose();
+		this.integrationReconciler = null;
 		unifiControllers.clear();
 		await super.onShutdown();
 	}
@@ -96033,51 +96287,63 @@ var UnifiProviderAddon = class extends BaseDeviceProvider {
 		return unifiStableId(integrationId, childNativeId);
 	}
 	/**
-	* Rebuild the clients from the live integration list: upsert one per enabled integration
-	* with a host, drop the ones that vanished and cascade-remove their devices. Idempotent;
-	* runs at boot and on every integration lifecycle event.
+	* Upsert one client per enabled integration and drop the client of one the list ANSWERED is
+	* gone. Never removes a device (D49): that follows only an explicit lifecycle event.
+	* Idempotent; runs at boot and on every integration lifecycle event.
 	*/
-	async reconcileIntegrations() {
-		const reg = this.requireClients();
-		try {
-			const mine = (await this.ctx.api.integrations.list.query()).filter((i) => i.addonId === this.ctx.id && i.enabled);
-			const surviving = /* @__PURE__ */ new Set();
-			for (const integration of mine) try {
+	reconciler() {
+		this.integrationReconciler ??= new UnifiReconciler({
+			addonId: this.ctx.id,
+			logger: this.ctx.logger,
+			clients: this.requireClients(),
+			listIntegrations: () => this.ctx.api.integrations.list.query(),
+			applySettings: async (integration) => {
+				const reg = this.requireClients();
 				const read = connectionFromSettings(await this.ctx.api.integrations.getSettings.query({ id: integration.id }));
-				if (read === null) {
-					this.ctx.logger.warn("UniFi integration has no controller host — skipping", { meta: { integrationId: integration.id } });
-					continue;
-				}
+				if (read === null) return false;
 				await reg.upsert(integration.id, integration.name, read.connection, read.credentialsLocked);
-				surviving.add(integration.id);
-			} catch (err) {
-				this.ctx.logger.warn("UniFi reconcile failed for integration", { meta: {
-					integrationId: integration.id,
-					error: errMsg(err)
-				} });
-			}
-			const vanished = reg.list().filter((id) => !surviving.has(id));
-			await reg.retain(surviving);
-			for (const integrationId of vanished) await this.cascadeRemoveDevicesForIntegration(integrationId);
-		} catch (err) {
-			this.ctx.logger.warn("UniFi integration reconcile failed", { meta: { error: errMsg(err) } });
-		}
+				return true;
+			},
+			removeDevices: (integrationId) => this.cascadeRemoveDevicesForIntegration(integrationId),
+			ownerIntegrationIds: () => this.ownerIntegrationIds()
+		});
+		return this.integrationReconciler;
 	}
+	async reconcileIntegrations() {
+		await this.reconciler().reconcile();
+	}
+	/** Lifecycle events: only an explicit Deleted/Disabled naming an integration removes devices. */
 	subscribeIntegrationLifecycle() {
-		const handler = (event) => {
+		const on = (kind) => (event) => {
 			const addonId = event.data["addonId"];
 			if (typeof addonId === "string" && addonId !== this.ctx.id) return;
-			this.reconcileIntegrations();
+			const integrationId = event.data["integrationId"];
+			this.reconciler().onLifecycle(kind, typeof integrationId === "string" ? integrationId : null);
 		};
-		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationEnabled }, handler);
-		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDisabled }, handler);
-		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDeleted }, handler);
+		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationEnabled }, on("enabled"));
+		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDisabled }, on("disabled"));
+		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDeleted }, on("deleted"));
+	}
+	/** The integrations that own devices here, for the orphan sweep. */
+	async ownerIntegrationIds() {
+		const reg = this.ctx.kernel.deviceRegistry;
+		const devices = this.ctx.kernel.devices;
+		if (!reg || !devices) return [];
+		return await collectOwnerIntegrationIds({
+			reg,
+			devices,
+			addonId: this.addonId,
+			ownerOf: (cfg) => {
+				const owner = cfg["integrationId"];
+				return cfg["system"] === "unifi" && typeof owner === "string" ? owner : null;
+			}
+		});
 	}
 	async cascadeRemoveDevicesForIntegration(integrationId) {
 		const reg = this.ctx.kernel.deviceRegistry;
 		const devices = this.ctx.kernel.devices;
-		if (!reg || !devices) return;
-		await cascadeRemoveDevicesForIntegration({
+		if (!reg || !devices) return 0;
+		return await cascadeRemoveDevicesForIntegration({
 			reg,
 			devices,
 			addonId: this.addonId,

package/dist/addon.mjs

@@ -5830,7 +5830,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-BHS4ImRX.mjs
+//#region ../types/dist/sleep-CSYuxssh.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -9113,7 +9113,7 @@ var ProfileRtspEntrySchema = object({
 /**
 * The model weight formats a catalog entry can ship. Schema-free on purpose:
 * `types/models.ts` builds Zod schemas from it, but a runner-closure consumer
-* (the model downloader in `@camstack/system`) needs only the list and must
+* (the model downloader in `@camstack/server/system`) needs only the list and must
 * reach it through `@camstack/types/addon` without building the cap schema
 * graph (D28).
 */
@@ -12488,6 +12488,71 @@ var EventOwnerTypeSchema = _enum(EVENT_OWNER_TYPES);
 var MediaPresenceOwnerKindSchema = _enum([...EVENT_OWNER_TYPES, "track"]);
 new Set(EVENT_OWNER_TYPES);
 /**
+* What a published package needs from the rest of the install (D989).
+*
+* One published framework package (`@camstack/server`) carries the kernel, the
+* builtins and the capability contracts, so "which addon runs on which
+* framework" is a question of version, and the answer is DECLARED by the
+* package that knows it:
+*
+*   - an addon says the oldest server it runs on (`requires.server: ">=X"`);
+*   - the server says the oldest addon it works with
+*     (`requires.addons: { "@camstack/addon-x": ">=Y" }`) and the oldest shell
+*     around it (`requires.wrapper: { desktop, image }`);
+*   - a wrapper (the desktop app, the container starter) says which server
+*     range it can host, and reports its own kind and version.
+*
+* The publish workflow STAMPS these after the version bump
+* (`scripts/ci/stamp-requires.mjs`); nobody types a number by hand.
+*
+* A requirement that cannot be checked is NOT met: a shell that reports no
+* version counts as below the minimum, and an unreadable running version is
+* named in the result (a failed read is never a pass).
+*/
+/** `>=MAJOR.MINOR.PATCH[-prerelease]` — the only range shape a requirement uses. */
+var MinVersionSchema = string().regex(/^>=\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, "a minimum is written \">=X.Y.Z\"");
+object({
+	/** The oldest `@camstack/server` this package runs on. */
+	server: MinVersionSchema.optional(),
+	/** The oldest installed version of each named addon package. */
+	addons: record(string(), MinVersionSchema).optional(),
+	/** The oldest shell around the server, per shell kind. */
+	wrapper: object({
+		desktop: MinVersionSchema.optional(),
+		image: MinVersionSchema.optional()
+	}).optional()
+});
+/** One unmet requirement; each names the versions on both sides. */
+var UnmetRequirementSchema = discriminatedUnion("kind", [
+	object({
+		kind: literal("server-too-old"),
+		required: string(),
+		/** `null` — the running server version could not be read. */
+		running: string().nullable()
+	}),
+	object({
+		kind: literal("addon-too-old"),
+		packageName: string(),
+		required: string(),
+		/** `null` — the addon is not installed (or its version is unreadable). */
+		running: string().nullable()
+	}),
+	object({
+		kind: literal("wrapper-too-old"),
+		wrapper: _enum(["desktop", "image"]),
+		required: string(),
+		/** `null` — the wrapper reported no version. */
+		running: string().nullable()
+	})
+]);
+var RequiredAddonUpdateSchema = object({
+	packageName: string(),
+	/** The minimum the target server declares. */
+	required: string(),
+	/** What this node has; `null` when the addon is not installed. */
+	installed: string().nullable()
+});
+/**
 * Which integration instance a settings form is for. An addon that serves several instances
 * (`instanceMode: multiple`) can show a different form per instance — an NVR integration
 * needs its connection, the default integration needs the addon's own sections.
@@ -42903,7 +42968,7 @@ method(object({}), array(TargetKindSchema)), method(object({}), array(TargetSche
 * rebuilds without manual reload.
 *
 * The hub-local builtin `addon-pages-aggregator` (see
-* `@camstack/system/builtins/addon-pages-aggregator`) registers the
+* `@camstack/server/system/builtins/addon-pages-aggregator`) registers the
 * provider. Splitting the public aggregator from the raw collection
 * keeps both ends in codegen — there's no hand-written
 * `addon-pages.router.ts` wrapper anymore.
@@ -43203,7 +43268,7 @@ method(_void(), array(WidgetMetadataSchema).readonly(), { auth: "admin" });
 * manual reload — same scheme used by `addon-pages`.
 *
 * The hub-local builtin `addon-widgets-aggregator` (see
-* `@camstack/system/builtins/addon-widgets-aggregator`) registers the
+* `@camstack/server/system/builtins/addon-widgets-aggregator`) registers the
 * provider. Splitting the public aggregator from the raw collection
 * keeps both ends in codegen — there's no hand-written wrapper.
 */
@@ -61403,7 +61468,18 @@ var ServerUpdateActionResultSchema = object({
 	* store (D877), present when the pre-flight refused the update
 	* (`reason: 'addon-would-refuse'`). Optional for version skew.
 	*/
-	blockers: array(UpdateBlockerSchema).optional()
+	blockers: array(UpdateBlockerSchema).optional(),
+	/**
+	* The minimums the target server declares and this node does not meet
+	* (D989), present when the update was refused with
+	* `reason: 'requirements-unmet'`. Each names the versions on both sides.
+	*/
+	unmet: array(UnmetRequirementSchema).optional(),
+	/**
+	* The addons this node has below the minimum the staged server declares —
+	* the ones to update WITH the server. Present on an accepted update.
+	*/
+	requiredAddonUpdates: array(RequiredAddonUpdateSchema).optional()
 });
 var LaunchOverridesSchema = object({ 
 /** The persisted heap ceiling in MB, or `null` when none is set. */
@@ -63947,7 +64023,9 @@ var PackageUpdateSchema = object({
 	latestVersion: string(),
 	category: _enum(["addon", "core"]),
 	requiresRestart: boolean(),
-	isSystem: boolean()
+	isSystem: boolean(),
+	/** Held: what the newer version needs and this node does not meet (D989). */
+	blockedBy: array(UnmetRequirementSchema).readonly().optional()
 });
 var PackageVersionInfoSchema = object({
 	version: string(),
@@ -69247,7 +69325,7 @@ var lawnMowerControlCapability = {
 * clients — they reverse-connect to the hub. Exposing their interfaces
 * via the same surface would leak internal topology with no upside.
 *
-* Implementation in `@camstack/system/builtins/local-network/`.
+* Implementation in `@camstack/server/system/builtins/local-network/`.
 */
 /** Coarse classification derived from the interface name + IP range. */
 var InterfaceKindEnum = _enum([
@@ -71135,7 +71213,7 @@ onStatusChanged: { data: object({
 * jitter, and observed/peak bandwidth per device + per client.
 *
 * Implementation lives in the server's `NetworkQualityService` (thin
-* wrapper over the shared `NetworkQualityTracker` from `@camstack/system`).
+* wrapper over the shared `NetworkQualityTracker` from `@camstack/server/system`).
 * The provider is registered from `trpc.router.ts` against the existing
 * service instance — no addon owns this state.
 *
@@ -73286,7 +73364,7 @@ var ptzAutotrackCapability = {
 	*  - **Native**: the camera's own firmware autotrack, registered per device by
 	*    the driver when the probe says it exists (Reolink: yes; Hikvision:
 	*    model-dependent).
-	*  - **Wrapper**: the emulated implementation (`@camstack/system`'s `autotrack` builtin),
+	*  - **Wrapper**: the emulated implementation (`@camstack/server/system`'s `autotrack` builtin),
 	*    which follows a subject with `ptz.move` pulses driven by the detection
 	*    pipeline. `defaultActive: false` — the operator binds it per camera in
 	*    the bindings UI.
@@ -94418,6 +94496,88 @@ DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.sceneBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
+/**
+* Closes the gap D49 leaves: an integration deleted while its provider was down never emits an
+* event the provider sees. An integration id absent from an ANSWERED list is only a suspect; its
+* devices go (through the provider's own removeDevices) when a SECOND answered read, at least
+* `minIntervalMs` later, still lacks it. A read that threw changes nothing; reappearing clears.
+*/
+var OrphanIntegrationSweep = class {
+	#logger;
+	#minIntervalMs;
+	#now;
+	#suspects = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#logger = options.logger;
+		this.#minIntervalMs = options.minIntervalMs ?? 6e4;
+		this.#now = options.now ?? Date.now;
+	}
+	get minIntervalMs() {
+		return this.#minIntervalMs;
+	}
+	async sweep(input) {
+		if (input.listedIds === null) return {
+			newSuspects: 0,
+			removed: []
+		};
+		const listed = new Set(input.listedIds);
+		const owners = new Set(input.ownerIds);
+		const now = this.#now();
+		let newSuspects = 0;
+		const removed = [];
+		for (const id of [...this.#suspects.keys()]) if (listed.has(id) || !owners.has(id)) {
+			this.#suspects.delete(id);
+			this.#logger.info("Orphan integration suspect cleared", { meta: {
+				integrationId: id,
+				reason: listed.has(id) ? "listed again" : "owns no devices"
+			} });
+		}
+		for (const id of owners) {
+			if (listed.has(id)) continue;
+			const since = this.#suspects.get(id);
+			if (since === void 0) {
+				this.#suspects.set(id, now);
+				newSuspects += 1;
+				this.#logger.info("Integration owns devices but is absent from the list — suspect", { meta: {
+					integrationId: id,
+					minIntervalMs: this.#minIntervalMs
+				} });
+				continue;
+			}
+			if (now - since < this.#minIntervalMs) continue;
+			try {
+				const count = await input.removeDevices(id);
+				this.#suspects.delete(id);
+				removed.push(id);
+				this.#logger.warn("Orphan integration devices removed — absent from two answered lists", { meta: {
+					integrationId: id,
+					removed: count,
+					firstMissingAt: since
+				} });
+			} catch (err) {
+				this.#logger.warn("Orphan integration device removal failed — kept as suspect", { meta: {
+					integrationId: id,
+					error: errMsg(err)
+				} });
+			}
+		}
+		return {
+			newSuspects,
+			removed
+		};
+	}
+};
+/** The integration ids that own top-level devices of one provider (a config that cannot be read is skipped). */
+async function collectOwnerIntegrationIds(input) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const d of input.reg.getAllForAddon(input.addonId)) {
+		if (d.parentDeviceId !== null) continue;
+		const cfg = await input.devices.loadConfig(d.id).catch(() => ({}));
+		const owner = input.ownerOf(cfg);
+		if (owner !== null) ids.add(owner);
+	}
+	return [...ids];
+}
 String.raw`(?<=^|["'(\s>,\[{])`;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
@@ -95914,6 +96074,97 @@ async function reconcileInfraFeatures(input) {
 	return changed;
 }
 //#endregion
+//#region src/unifi-reconciler.ts
+/**
+* Keeps one live client per enabled integration. Devices are removed ONLY on an explicit
+* lifecycle event naming the integration (D49): a list that failed, an empty list or an
+* unreadable connection changes nothing about devices and is logged, never read as "gone".
+*/
+var UnifiReconciler = class {
+	#deps;
+	#sweep;
+	#rerun = null;
+	constructor(deps) {
+		this.#deps = deps;
+		this.#sweep = new OrphanIntegrationSweep({
+			logger: deps.logger,
+			...deps.sweepOptions
+		});
+	}
+	/** Upsert a client per usable enabled integration; drop the CLIENT (never devices) of one the list answered is gone. */
+	async reconcile() {
+		const { logger, clients } = this.#deps;
+		let all;
+		try {
+			all = await this.#deps.listIntegrations();
+		} catch (err) {
+			logger.warn("Unifi integration reconcile skipped — the integration list did not answer", { meta: { error: errMsg(err) } });
+			return;
+		}
+		const enabled = all.filter((i) => i.addonId === this.#deps.addonId && i.enabled);
+		for (const integration of enabled) try {
+			if (!await this.#deps.applySettings(integration)) logger.warn("Unifi integration has no usable connection — left as it is", { meta: { integrationId: integration.id } });
+		} catch (err) {
+			logger.warn("Unifi reconcile failed for integration — left as it is", { meta: {
+				integrationId: integration.id,
+				error: errMsg(err)
+			} });
+		}
+		const enabledIds = new Set(enabled.map((i) => i.id));
+		for (const id of clients.list()) if (!enabledIds.has(id)) await clients.remove(id);
+		await this.#sweepOrphans(all.map((i) => i.id));
+	}
+	/** Stop the scheduled second read (addon stop). */
+	dispose() {
+		if (this.#rerun !== null) clearTimeout(this.#rerun);
+		this.#rerun = null;
+	}
+	/**
+	* An integration deleted while this addon was down emits nothing it sees: its id owns devices
+	* yet is absent from the ANSWERED list. Removal needs a second answered read later, so one
+	* re-run is scheduled when a suspect appears (bounded: one timer, no retry loop).
+	*/
+	async #sweepOrphans(listedIds) {
+		const { ownerIntegrationIds, removeDevices, logger } = this.#deps;
+		if (ownerIntegrationIds === void 0) return;
+		try {
+			const ownerIds = await ownerIntegrationIds();
+			if ((await this.#sweep.sweep({
+				ownerIds,
+				listedIds,
+				removeDevices
+			})).newSuspects > 0 && this.#rerun === null) {
+				this.#rerun = setTimeout(() => {
+					this.#rerun = null;
+					this.reconcile();
+				}, this.#sweep.minIntervalMs + 1e3);
+				this.#rerun.unref();
+			}
+		} catch (err) {
+			logger.warn("Orphan integration sweep failed — devices left as they are", { meta: { error: errMsg(err) } });
+		}
+	}
+	/** An explicit lifecycle event: only `deleted` / `disabled` of a named integration remove devices. */
+	async onLifecycle(kind, integrationId) {
+		await this.reconcile();
+		if (kind === "enabled" || integrationId === null) return;
+		try {
+			const removed = await this.#deps.removeDevices(integrationId);
+			this.#deps.logger.info("Unifi integration devices removed", { meta: {
+				integrationId,
+				kind,
+				removed
+			} });
+		} catch (err) {
+			this.#deps.logger.warn("Unifi integration device removal failed", { meta: {
+				integrationId,
+				kind,
+				error: errMsg(err)
+			} });
+		}
+	}
+};
+//#endregion
 //#region src/unifi-integration-device-cascade.ts
 /**
 * Remove every top-level device (Gateway, infra Container, client Presence) of an integration that
@@ -95991,6 +96242,7 @@ var UnifiProviderAddon = class extends BaseDeviceProvider {
 		[DeviceType.Sensor]: UnifiFeatureDevice,
 		[DeviceType.Presence]: UnifiFeatureDevice
 	};
+	integrationReconciler = null;
 	clients = null;
 	constructor() {
 		super({});
@@ -96016,6 +96268,8 @@ var UnifiProviderAddon = class extends BaseDeviceProvider {
 			this.ctx.logger.warn("UniFi shutdown error", { meta: { error: errMsg(err) } });
 		}
 		this.clients = null;
+		this.integrationReconciler?.dispose();
+		this.integrationReconciler = null;
 		unifiControllers.clear();
 		await super.onShutdown();
 	}
@@ -96032,51 +96286,63 @@ var UnifiProviderAddon = class extends BaseDeviceProvider {
 		return unifiStableId(integrationId, childNativeId);
 	}
 	/**
-	* Rebuild the clients from the live integration list: upsert one per enabled integration
-	* with a host, drop the ones that vanished and cascade-remove their devices. Idempotent;
-	* runs at boot and on every integration lifecycle event.
+	* Upsert one client per enabled integration and drop the client of one the list ANSWERED is
+	* gone. Never removes a device (D49): that follows only an explicit lifecycle event.
+	* Idempotent; runs at boot and on every integration lifecycle event.
 	*/
-	async reconcileIntegrations() {
-		const reg = this.requireClients();
-		try {
-			const mine = (await this.ctx.api.integrations.list.query()).filter((i) => i.addonId === this.ctx.id && i.enabled);
-			const surviving = /* @__PURE__ */ new Set();
-			for (const integration of mine) try {
+	reconciler() {
+		this.integrationReconciler ??= new UnifiReconciler({
+			addonId: this.ctx.id,
+			logger: this.ctx.logger,
+			clients: this.requireClients(),
+			listIntegrations: () => this.ctx.api.integrations.list.query(),
+			applySettings: async (integration) => {
+				const reg = this.requireClients();
 				const read = connectionFromSettings(await this.ctx.api.integrations.getSettings.query({ id: integration.id }));
-				if (read === null) {
-					this.ctx.logger.warn("UniFi integration has no controller host — skipping", { meta: { integrationId: integration.id } });
-					continue;
-				}
+				if (read === null) return false;
 				await reg.upsert(integration.id, integration.name, read.connection, read.credentialsLocked);
-				surviving.add(integration.id);
-			} catch (err) {
-				this.ctx.logger.warn("UniFi reconcile failed for integration", { meta: {
-					integrationId: integration.id,
-					error: errMsg(err)
-				} });
-			}
-			const vanished = reg.list().filter((id) => !surviving.has(id));
-			await reg.retain(surviving);
-			for (const integrationId of vanished) await this.cascadeRemoveDevicesForIntegration(integrationId);
-		} catch (err) {
-			this.ctx.logger.warn("UniFi integration reconcile failed", { meta: { error: errMsg(err) } });
-		}
+				return true;
+			},
+			removeDevices: (integrationId) => this.cascadeRemoveDevicesForIntegration(integrationId),
+			ownerIntegrationIds: () => this.ownerIntegrationIds()
+		});
+		return this.integrationReconciler;
 	}
+	async reconcileIntegrations() {
+		await this.reconciler().reconcile();
+	}
+	/** Lifecycle events: only an explicit Deleted/Disabled naming an integration removes devices. */
 	subscribeIntegrationLifecycle() {
-		const handler = (event) => {
+		const on = (kind) => (event) => {
 			const addonId = event.data["addonId"];
 			if (typeof addonId === "string" && addonId !== this.ctx.id) return;
-			this.reconcileIntegrations();
+			const integrationId = event.data["integrationId"];
+			this.reconciler().onLifecycle(kind, typeof integrationId === "string" ? integrationId : null);
 		};
-		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationEnabled }, handler);
-		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDisabled }, handler);
-		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDeleted }, handler);
+		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationEnabled }, on("enabled"));
+		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDisabled }, on("disabled"));
+		this.ctx.eventBus.subscribe({ category: EventCategory.IntegrationDeleted }, on("deleted"));
+	}
+	/** The integrations that own devices here, for the orphan sweep. */
+	async ownerIntegrationIds() {
+		const reg = this.ctx.kernel.deviceRegistry;
+		const devices = this.ctx.kernel.devices;
+		if (!reg || !devices) return [];
+		return await collectOwnerIntegrationIds({
+			reg,
+			devices,
+			addonId: this.addonId,
+			ownerOf: (cfg) => {
+				const owner = cfg["integrationId"];
+				return cfg["system"] === "unifi" && typeof owner === "string" ? owner : null;
+			}
+		});
 	}
 	async cascadeRemoveDevicesForIntegration(integrationId) {
 		const reg = this.ctx.kernel.deviceRegistry;
 		const devices = this.ctx.kernel.devices;
-		if (!reg || !devices) return;
-		await cascadeRemoveDevicesForIntegration({
+		if (!reg || !devices) return 0;
+		return await cascadeRemoveDevicesForIntegration({
 			reg,
 			devices,
 			addonId: this.addonId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-unifi",
-  "version": "0.2.151",
+  "version": "0.2.153",
   "description": "UniFi Network controller device-provider addon for CamStack — local-controller infra switches/APs (as containers) + network-client presence. No cameras.",
   "keywords": [
     "camstack",
@@ -57,7 +57,10 @@
           }
         ]
       }
-    ]
+    ],
+    "requires": {
+      "server": ">=1.2.722"
+    }
   },
   "files": [
     "dist",