@camstack/addon-matter-broker 0.2.71 → 0.2.73

package/dist/addon.js

@@ -6459,6 +6459,21 @@ var CameraStreamSchema = object({
 	*/
 	autoEligible: boolean().optional(),
 	/**
+	* The profile slot the PUBLISHER says this stream is: `low` for a stream
+	* whose only sensible role is the low-bandwidth one, `high` for a main
+	* stream. Consulted by the broker's automatic ranking
+	* (`rankInitialAssignment`) BEFORE the pixel-count heuristic, and only there:
+	* an operator's manual assignment still wins, and an absent hint is the
+	* pixel-ranked default every camera had before this field existed.
+	*
+	* Why it exists: a camera with ONE stream ranked to `mid` — the slot no
+	* storage class is written for on its own (`recordings` is high|mid,
+	* `recordingsLow` is low) and the one profile scrub does not read. The robot
+	* camera's single 720p relay is a `low` in every respect except the slot the
+	* heuristic put it in.
+	*/
+	profileHint: CamProfileSchema.optional(),
+	/**
 	* Transport-specific opaque metadata. The broker passes it through to
 	* the source reader without inspecting it. Currently used by
 	* `pull-rfc4571` streams to carry the upstream SDP (so the reader can
@@ -7908,7 +7923,22 @@ var RecordingTriggersSchema = object({
 	* il livello: un contatto trovato già aperto al riavvio del runner non fa
 	* registrare.
 	*/
-	sensorDeviceIds: array(number().int().positive()).min(1).max(16).refine(noDuplicates, { message: "sensorDeviceIds must not repeat a device" }).optional()
+	sensorDeviceIds: array(number().int().positive()).min(1).max(16).refine(noDuplicates, { message: "sensorDeviceIds must not repeat a device" }).optional(),
+	/**
+	* La camera registra per tutta la durata del SEGNALE che lei stessa
+	* pubblica — la cap `recording-signal` (`active: true` mentre il device è in
+	* funzione: un robot che pulisce). È un LIVELLO, non un fronte: la finestra
+	* resta aperta finché il segnale è alto e si chiude `postBufferSec` dopo la
+	* caduta, così una pulizia di quaranta minuti è UNA clip.
+	*
+	* Non nomina un device: il segnale è della camera stessa, tenuto fresco dal
+	* suo provider (D224); il recorder lo ascolta su `DeviceStateChanged` e lo
+	* riconcilia leggendo la slice via RPC, con un tetto oltre il quale un
+	* segnale mai abbassato (un evento perso) non può tenere aperta una
+	* registrazione (D11). Vedi `recorder/addon/band-decision.ts`
+	* (`holdTrigger` / `releaseTrigger`).
+	*/
+	deviceSignal: boolean().optional()
 });
 /**
 * Mode of a single recording band — the recorder per-band vocabulary.
@@ -11421,6 +11451,8 @@ method(object({
 	label: string$2().optional(),
 	deviceFeatures: array(string$2()).optional(),
 	autoEligible: boolean().optional(),
+	/** The slot the publisher says this stream IS — see `CameraStreamSchema.profileHint`. */
+	profileHint: CamProfileSchema.optional(),
 	metadata: record(string$2(), unknown()).optional(),
 	/** Required when kind === 'derived' — the source camStreamId the
 	*  derived broker reads its encoded plane from.
@@ -29980,6 +30012,77 @@ method(object({
 	auth: "protected"
 });
 /**
+* A camera's own "record me NOW" LEVEL — a signal the device raises while
+* something it knows about is happening (a robot vacuum cleaning, a machine
+* running, a gate open) and lowers when it stops.
+*
+* It is a level, not an edge. The sensor triggers the recorder already listens
+* to (`SOURCE_CAP_ACTIVE_FIELD`) fire on a rising edge and record for a fixed
+* post-buffer; a cleaning lasts forty minutes, and forty minutes of "this is
+* still happening" cannot be expressed as an edge plus a post-buffer without
+* either re-triggering on a timer (polling — D224 forbids the consumer keeping
+* the fact fresh) or picking a post-buffer long enough to cover every job,
+* which records the dock for that long after every short one. So the recorder
+* reads the LEVEL: it records for as long as `active` is true, plus the band's
+* own post-buffer once it falls.
+*
+* Who owns the fact: the PROVIDER of the device, which already reads the state
+* the signal is derived from (the vacuum's lifecycle state, for Dreame). It
+* writes this slice on every change; consumers subscribe to the kernel's
+* `DeviceStateChanged` for it and read it back through
+* `deviceState.getCapSlice` to reconcile — never a second copy, never a poll
+* against the device (D224, D8/D11).
+*
+* Deliberately NOT a `binary` sensor on the camera: a binary sensor is exported
+* to Home Assistant, HomeKit and the sensor picker as a thing an operator can
+* bind, and "the camera wants to record" is not a room sensor. It is a fact
+* about the camera, on the camera.
+*/
+var RecordingSignalStatusSchema = object({
+	/** True while the device asks to be recorded. */
+	active: boolean(),
+	/**
+	* Why, in the provider's own vocabulary (a vacuum's `cleaning` / `docked`,
+	* …). Free text for the log line and the UI badge; the recorder never
+	* branches on it.
+	*/
+	reason: string$2(),
+	/** Ms epoch of the last `active` transition. 0 if never observed. */
+	lastChangedAt: number()
+});
+/** The runtime-state slice: the status plus the clock every slice carries. */
+var RecordingSignalRuntimeStateSchema = RecordingSignalStatusSchema.extend({ lastFetchedAt: number() });
+var recordingSignalCapability = {
+	name: "recording-signal",
+	scope: "device",
+	deviceNative: true,
+	mode: "singleton",
+	deviceTypes: [DeviceType.Camera],
+	methods: { 
+	/** The current level, straight from the slice the provider keeps fresh. */
+getStatus: method(object({ deviceId: number() }), RecordingSignalStatusSchema) },
+	status: {
+		schema: RecordingSignalStatusSchema,
+		kind: "push",
+		empty: {
+			active: false,
+			reason: "unknown",
+			lastChangedAt: 0
+		}
+	},
+	runtimeState: RecordingSignalRuntimeStateSchema,
+	/**
+	* Runtime-state durability: **session** — a restored `active: true` from
+	* before a restart is exactly the stale level the recorder's reconcile bound
+	* exists to end, and the provider re-derives the true level on activation
+	* anyway. Nothing is lost by forgetting it; a lie is avoided.
+	*
+	* See `RuntimeStateDurability`. Enforced by
+	* `scripts/check-runtime-state-durability.ts`.
+	*/
+	durability: "session"
+};
+/**
 * scene-monitor — device-scoped reference-region state cap. An operator marks
 * a rect ROI on a camera frame and names one or more states; the engine
 * (pipeline-analytics, designated post-processing node) reports which state is
@@ -30477,6 +30580,8 @@ var CamStreamDescriptorSchema = object({
 	deviceFeatures: array(string$2()).optional(),
 	/** Eligible for automatic profile assignment. Absent = `true`. */
 	autoEligible: boolean().optional(),
+	/** The slot the publisher says this stream IS — see `CameraStreamSchema.profileHint`. */
+	profileHint: CamProfileSchema.optional(),
 	/** Transport-specific opaque metadata (e.g. rfc4571 SDP). */
 	metadata: record(string$2(), unknown()).optional()
 });
@@ -32616,6 +32721,7 @@ var DEVICE_LOCAL_STATE_CAPS = {
 	pressureSensor: pressureSensorCapability,
 	privacyMask: privacyMaskCapability,
 	ptzAutotrack: ptzAutotrackCapability,
+	recordingSignal: recordingSignalCapability,
 	sceneMonitor: sceneMonitorCapability,
 	scriptRunner: scriptRunnerCapability,
 	smoke: smokeCapability,
@@ -33459,6 +33565,53 @@ var BaseDeviceProvider = class extends BaseAddon {
 		const ids = [...this._permanentRestoreFailures.keys()].join(", ");
 		return `${this._permanentRestoreFailures.size} device(s) permanently failed restore (deviceIds: ${ids}) — restart the ${this.providerName} provider to retry`;
 	}
+	/**
+	* A top-level persisted row with NO configuration is a leftover, not a
+	* device — quarantine it instead of dialling it.
+	*
+	* Device 614 was deleted, resurrected as a config-less shell by a write
+	* already in flight (D376), and then dialled at every single boot: eight
+	* `Failed to restore device — bounded retry scheduled` lines in one day,
+	* each one the same Zod refusal on `host` and `password`. The bound was
+	* real, but it is a bound PER PROCESS, and the runner restarts — so nothing
+	* about the row ever stopped costing attempts and log lines.
+	*
+	* No retry can add a configuration that is not there. The row is reported
+	* once, with its `deviceId`, and set aside.
+	*
+	* Top-level only: an accessory child legitimately carries an empty blob (it
+	* lives off its parent), and a hub-adopted child with an emptied blob is
+	* repaired by `healSavedConfig` from its parent instead. Providers that
+	* genuinely create configuration-free top-level devices turn this off.
+	*/
+	quarantineConfiglessTopLevelRestores = true;
+	isUnrestorableShell(saved) {
+		if (!this.quarantineConfiglessTopLevelRestores) return false;
+		if (saved.parentDeviceId !== null) return false;
+		const config = saved.config;
+		if (config === void 0) return false;
+		return Object.keys(config).length === 0;
+	}
+	quarantineShell(saved) {
+		this._permanentRestoreFailures.set(saved.id, {
+			deviceId: saved.id,
+			stableId: saved.stableId,
+			type: saved.type,
+			attempts: 0,
+			lastError: "persisted row has no configuration",
+			failedAt: Date.now()
+		});
+		this.ctx.logger.error("Persisted device row has NO configuration — quarantined: not restored, not retried. Remove it (deviceManager.removeDevice) or re-add the device.", {
+			tags: {
+				deviceId: saved.id,
+				stableId: saved.stableId
+			},
+			meta: {
+				type: saved.type,
+				provider: this.providerName
+			}
+		});
+	}
 	cancelRestoreRetries() {
 		this._restoreRetryScheduler?.cancel();
 		this._restoreRetryScheduler = null;
@@ -33643,6 +33796,10 @@ var BaseDeviceProvider = class extends BaseAddon {
 				});
 				return;
 			}
+			if (this.isUnrestorableShell(saved)) {
+				this.quarantineShell(saved);
+				return;
+			}
 			try {
 				await attemptRestore(saved);
 			} catch (err) {
@@ -38363,6 +38520,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recordingSignal.getStatus": {
+		capName: "recording-signal",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"sceneMonitor.captureReference": {
 		capName: "scene-monitor",
 		capScope: "device",
@@ -41355,6 +41518,11 @@ Object.freeze({
 		form: "single",
 		optional: true
 	}],
+	"recordingSignal.getStatus": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"sceneMonitor.captureReference": [{
 		name: "deviceId",
 		form: "single",

package/dist/addon.mjs

@@ -6457,6 +6457,21 @@ var CameraStreamSchema = object({
 	*/
 	autoEligible: boolean().optional(),
 	/**
+	* The profile slot the PUBLISHER says this stream is: `low` for a stream
+	* whose only sensible role is the low-bandwidth one, `high` for a main
+	* stream. Consulted by the broker's automatic ranking
+	* (`rankInitialAssignment`) BEFORE the pixel-count heuristic, and only there:
+	* an operator's manual assignment still wins, and an absent hint is the
+	* pixel-ranked default every camera had before this field existed.
+	*
+	* Why it exists: a camera with ONE stream ranked to `mid` — the slot no
+	* storage class is written for on its own (`recordings` is high|mid,
+	* `recordingsLow` is low) and the one profile scrub does not read. The robot
+	* camera's single 720p relay is a `low` in every respect except the slot the
+	* heuristic put it in.
+	*/
+	profileHint: CamProfileSchema.optional(),
+	/**
 	* Transport-specific opaque metadata. The broker passes it through to
 	* the source reader without inspecting it. Currently used by
 	* `pull-rfc4571` streams to carry the upstream SDP (so the reader can
@@ -7906,7 +7921,22 @@ var RecordingTriggersSchema = object({
 	* il livello: un contatto trovato già aperto al riavvio del runner non fa
 	* registrare.
 	*/
-	sensorDeviceIds: array(number().int().positive()).min(1).max(16).refine(noDuplicates, { message: "sensorDeviceIds must not repeat a device" }).optional()
+	sensorDeviceIds: array(number().int().positive()).min(1).max(16).refine(noDuplicates, { message: "sensorDeviceIds must not repeat a device" }).optional(),
+	/**
+	* La camera registra per tutta la durata del SEGNALE che lei stessa
+	* pubblica — la cap `recording-signal` (`active: true` mentre il device è in
+	* funzione: un robot che pulisce). È un LIVELLO, non un fronte: la finestra
+	* resta aperta finché il segnale è alto e si chiude `postBufferSec` dopo la
+	* caduta, così una pulizia di quaranta minuti è UNA clip.
+	*
+	* Non nomina un device: il segnale è della camera stessa, tenuto fresco dal
+	* suo provider (D224); il recorder lo ascolta su `DeviceStateChanged` e lo
+	* riconcilia leggendo la slice via RPC, con un tetto oltre il quale un
+	* segnale mai abbassato (un evento perso) non può tenere aperta una
+	* registrazione (D11). Vedi `recorder/addon/band-decision.ts`
+	* (`holdTrigger` / `releaseTrigger`).
+	*/
+	deviceSignal: boolean().optional()
 });
 /**
 * Mode of a single recording band — the recorder per-band vocabulary.
@@ -11419,6 +11449,8 @@ method(object({
 	label: string$2().optional(),
 	deviceFeatures: array(string$2()).optional(),
 	autoEligible: boolean().optional(),
+	/** The slot the publisher says this stream IS — see `CameraStreamSchema.profileHint`. */
+	profileHint: CamProfileSchema.optional(),
 	metadata: record(string$2(), unknown()).optional(),
 	/** Required when kind === 'derived' — the source camStreamId the
 	*  derived broker reads its encoded plane from.
@@ -29978,6 +30010,77 @@ method(object({
 	auth: "protected"
 });
 /**
+* A camera's own "record me NOW" LEVEL — a signal the device raises while
+* something it knows about is happening (a robot vacuum cleaning, a machine
+* running, a gate open) and lowers when it stops.
+*
+* It is a level, not an edge. The sensor triggers the recorder already listens
+* to (`SOURCE_CAP_ACTIVE_FIELD`) fire on a rising edge and record for a fixed
+* post-buffer; a cleaning lasts forty minutes, and forty minutes of "this is
+* still happening" cannot be expressed as an edge plus a post-buffer without
+* either re-triggering on a timer (polling — D224 forbids the consumer keeping
+* the fact fresh) or picking a post-buffer long enough to cover every job,
+* which records the dock for that long after every short one. So the recorder
+* reads the LEVEL: it records for as long as `active` is true, plus the band's
+* own post-buffer once it falls.
+*
+* Who owns the fact: the PROVIDER of the device, which already reads the state
+* the signal is derived from (the vacuum's lifecycle state, for Dreame). It
+* writes this slice on every change; consumers subscribe to the kernel's
+* `DeviceStateChanged` for it and read it back through
+* `deviceState.getCapSlice` to reconcile — never a second copy, never a poll
+* against the device (D224, D8/D11).
+*
+* Deliberately NOT a `binary` sensor on the camera: a binary sensor is exported
+* to Home Assistant, HomeKit and the sensor picker as a thing an operator can
+* bind, and "the camera wants to record" is not a room sensor. It is a fact
+* about the camera, on the camera.
+*/
+var RecordingSignalStatusSchema = object({
+	/** True while the device asks to be recorded. */
+	active: boolean(),
+	/**
+	* Why, in the provider's own vocabulary (a vacuum's `cleaning` / `docked`,
+	* …). Free text for the log line and the UI badge; the recorder never
+	* branches on it.
+	*/
+	reason: string$2(),
+	/** Ms epoch of the last `active` transition. 0 if never observed. */
+	lastChangedAt: number()
+});
+/** The runtime-state slice: the status plus the clock every slice carries. */
+var RecordingSignalRuntimeStateSchema = RecordingSignalStatusSchema.extend({ lastFetchedAt: number() });
+var recordingSignalCapability = {
+	name: "recording-signal",
+	scope: "device",
+	deviceNative: true,
+	mode: "singleton",
+	deviceTypes: [DeviceType.Camera],
+	methods: { 
+	/** The current level, straight from the slice the provider keeps fresh. */
+getStatus: method(object({ deviceId: number() }), RecordingSignalStatusSchema) },
+	status: {
+		schema: RecordingSignalStatusSchema,
+		kind: "push",
+		empty: {
+			active: false,
+			reason: "unknown",
+			lastChangedAt: 0
+		}
+	},
+	runtimeState: RecordingSignalRuntimeStateSchema,
+	/**
+	* Runtime-state durability: **session** — a restored `active: true` from
+	* before a restart is exactly the stale level the recorder's reconcile bound
+	* exists to end, and the provider re-derives the true level on activation
+	* anyway. Nothing is lost by forgetting it; a lie is avoided.
+	*
+	* See `RuntimeStateDurability`. Enforced by
+	* `scripts/check-runtime-state-durability.ts`.
+	*/
+	durability: "session"
+};
+/**
 * scene-monitor — device-scoped reference-region state cap. An operator marks
 * a rect ROI on a camera frame and names one or more states; the engine
 * (pipeline-analytics, designated post-processing node) reports which state is
@@ -30475,6 +30578,8 @@ var CamStreamDescriptorSchema = object({
 	deviceFeatures: array(string$2()).optional(),
 	/** Eligible for automatic profile assignment. Absent = `true`. */
 	autoEligible: boolean().optional(),
+	/** The slot the publisher says this stream IS — see `CameraStreamSchema.profileHint`. */
+	profileHint: CamProfileSchema.optional(),
 	/** Transport-specific opaque metadata (e.g. rfc4571 SDP). */
 	metadata: record(string$2(), unknown()).optional()
 });
@@ -32614,6 +32719,7 @@ var DEVICE_LOCAL_STATE_CAPS = {
 	pressureSensor: pressureSensorCapability,
 	privacyMask: privacyMaskCapability,
 	ptzAutotrack: ptzAutotrackCapability,
+	recordingSignal: recordingSignalCapability,
 	sceneMonitor: sceneMonitorCapability,
 	scriptRunner: scriptRunnerCapability,
 	smoke: smokeCapability,
@@ -33457,6 +33563,53 @@ var BaseDeviceProvider = class extends BaseAddon {
 		const ids = [...this._permanentRestoreFailures.keys()].join(", ");
 		return `${this._permanentRestoreFailures.size} device(s) permanently failed restore (deviceIds: ${ids}) — restart the ${this.providerName} provider to retry`;
 	}
+	/**
+	* A top-level persisted row with NO configuration is a leftover, not a
+	* device — quarantine it instead of dialling it.
+	*
+	* Device 614 was deleted, resurrected as a config-less shell by a write
+	* already in flight (D376), and then dialled at every single boot: eight
+	* `Failed to restore device — bounded retry scheduled` lines in one day,
+	* each one the same Zod refusal on `host` and `password`. The bound was
+	* real, but it is a bound PER PROCESS, and the runner restarts — so nothing
+	* about the row ever stopped costing attempts and log lines.
+	*
+	* No retry can add a configuration that is not there. The row is reported
+	* once, with its `deviceId`, and set aside.
+	*
+	* Top-level only: an accessory child legitimately carries an empty blob (it
+	* lives off its parent), and a hub-adopted child with an emptied blob is
+	* repaired by `healSavedConfig` from its parent instead. Providers that
+	* genuinely create configuration-free top-level devices turn this off.
+	*/
+	quarantineConfiglessTopLevelRestores = true;
+	isUnrestorableShell(saved) {
+		if (!this.quarantineConfiglessTopLevelRestores) return false;
+		if (saved.parentDeviceId !== null) return false;
+		const config = saved.config;
+		if (config === void 0) return false;
+		return Object.keys(config).length === 0;
+	}
+	quarantineShell(saved) {
+		this._permanentRestoreFailures.set(saved.id, {
+			deviceId: saved.id,
+			stableId: saved.stableId,
+			type: saved.type,
+			attempts: 0,
+			lastError: "persisted row has no configuration",
+			failedAt: Date.now()
+		});
+		this.ctx.logger.error("Persisted device row has NO configuration — quarantined: not restored, not retried. Remove it (deviceManager.removeDevice) or re-add the device.", {
+			tags: {
+				deviceId: saved.id,
+				stableId: saved.stableId
+			},
+			meta: {
+				type: saved.type,
+				provider: this.providerName
+			}
+		});
+	}
 	cancelRestoreRetries() {
 		this._restoreRetryScheduler?.cancel();
 		this._restoreRetryScheduler = null;
@@ -33641,6 +33794,10 @@ var BaseDeviceProvider = class extends BaseAddon {
 				});
 				return;
 			}
+			if (this.isUnrestorableShell(saved)) {
+				this.quarantineShell(saved);
+				return;
+			}
 			try {
 				await attemptRestore(saved);
 			} catch (err) {
@@ -38361,6 +38518,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recordingSignal.getStatus": {
+		capName: "recording-signal",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"sceneMonitor.captureReference": {
 		capName: "scene-monitor",
 		capScope: "device",
@@ -41353,6 +41516,11 @@ Object.freeze({
 		form: "single",
 		optional: true
 	}],
+	"recordingSignal.getStatus": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"sceneMonitor.captureReference": [{
 		name: "deviceId",
 		form: "single",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-matter-broker",
-  "version": "0.2.71",
+  "version": "0.2.73",
   "description": "Matter broker addon for CamStack — owns a Matter fabric (commissioning + the long-lived controller) via the matter.js controller and brokers commissioned Matter nodes into CamStack",
   "keywords": [
     "camstack",