@camstack/addon-matter-broker 0.2.101 → 0.2.103

package/dist/addon.js

@@ -5374,7 +5374,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-DEuj7E3j.mjs
+//#region ../types/dist/sleep-BDR76Ykr.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -11625,6 +11625,21 @@ var streamSignalsCapability = {
 	mode: "singleton",
 	deviceTypes: Object.values(DeviceType),
 	runtimeState: StreamSignalsStatusSchema,
+	/**
+	* Runtime-state durability: **session** — mirrored in RAM, never written.
+	*
+	* The slice holds what the DEVICE says it can emit. That is a probed fact,
+	* not an operator choice: the provider re-declares it on every registration,
+	* so losing it loses nothing and persisting it would freeze an answer the
+	* camera is entitled to change. Measured the same day on the sibling case —
+	* `native-object-detection.supportedClasses` was persisted, and a firmware
+	* class the camera really detected stayed missing for the life of the row
+	* because the fix could not reach it.
+	*
+	* See `RuntimeStateDurability`. Enforced by
+	* `scripts/check-runtime-state-durability.ts`.
+	*/
+	durability: "session",
 	methods: { 
 	/**
 	* What this device can emit. Empty is a valid and common answer — most
@@ -18256,6 +18271,48 @@ var NcAlarmConfigSchema = object({
 	settings: NcAlarmSettingsSchema,
 	coverage: array(NcAlarmModeCoverageSchema)
 });
+/**
+* ONE rule's demand on ONE camera's clip ring.
+*
+* A rule, not a camera: the broker takes the MAX over the asks that reach a
+* camera, so the answer stays a faithful description of the rules and the
+* bounding (the byte budget, the broker's own ceiling) stays where the cost
+* lives. A camera that appears in no ask is being told **nothing** — which is
+* a different thing from never having been told, and only the envelope
+* (`rulesLoaded`) can tell those apart.
+*/
+var NcClipRetentionAskSchema = object({
+	/**
+	* The camera this ask is about. **Absent = every camera**, which is what a
+	* rule with no `conditions.devices` means: it can fire anywhere, so it is
+	* asking everywhere.
+	*/
+	deviceId: number().int().nonnegative().optional(),
+	/** Seconds of history the rule needs held for it. Never zero — a rule that
+	*  needs nothing produces no ask at all. */
+	seconds: number().min(0).max(60),
+	/** The profile the rule cuts from, when it named one. Absent = the cheapest
+	*  assigned, which is what the cut defaults to. */
+	profile: CamProfileSchema.optional(),
+	/** Who is asking — so a retention the operator did not expect names a rule. */
+	ruleId: string$2(),
+	ruleName: string$2(),
+	/** Why this many seconds: the rule's own window, or the occupancy ceiling. */
+	reason: _enum(["window", "occupancy"])
+});
+/**
+* The whole answer, with the one bit that keeps absence from reading as zero.
+*
+* `rulesLoaded` is false until the rule ledger has completed a load at least
+* once. A centre that is up but has not read its rules yet answers with an
+* empty ask list that means nothing at all — applying it would drop every
+* camera's ring to zero for the first events after a restart, which is the
+* footage this mechanism exists to keep.
+*/
+var NcClipRetentionPlanSchema = object({
+	rulesLoaded: boolean(),
+	asks: array(NcClipRetentionAskSchema).readonly()
+});
 method(object({}), object({ rules: array(NcRuleSchema) }), { auth: "admin" }), method(object({ ruleId: string$2() }), object({ rule: NcRuleSchema.nullable() }), { auth: "admin" }), method(object({ rule: NcRuleInputSchema }), object({ rule: NcRuleSchema }), {
 	kind: "mutation",
 	auth: "admin",
@@ -18276,7 +18333,7 @@ method(object({}), object({ rules: array(NcRuleSchema) }), { auth: "admin" }), m
 }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({}), object({ mutedDeviceIds: array(number().int()).readonly() }), { auth: "admin" }), method(object({
+}), method(object({}), NcClipRetentionPlanSchema, { auth: "admin" }), method(object({}), object({ mutedDeviceIds: array(number().int()).readonly() }), { auth: "admin" }), method(object({
 	deviceId: number().int(),
 	muted: boolean()
 }), object({ success: literal(true) }), {
@@ -19461,13 +19518,26 @@ var TrackAudioLabelSchema = object({
 *  - `audio` — an audio event on the camera itself that was anomalous for
 *    THAT camera, loud, and heard while nothing visual was happening (D62).
 *
+*  - `onboard` — the CAMERA's own firmware, paired with a decoded frame in
+*    that frame's pixel space. A real root detector and a SPATIAL one: its
+*    boxes are the same kind of fact `pipeline`'s are, produced by a different
+*    detector.
+*
+* `onboard` was missing here while `DetectionSourceSchema` already had it, so
+* a persisted onboard track failed `safeParse` on read and came back with NO
+* source at all — which `isSpatialTrack` then admitted by accident, through the
+* `undefined` arm rather than by anybody's decision, and which `excludeSources`
+* could not name.
+*
 * The spatial subsystems (tracker association, occupancy count, re-id /
 * embedding, resurrection) MUST skip every synthetic source. Test for that
-* with `isSpatialTrack`, which allow-lists `pipeline` — a `!== 'sensor'`
-* check silently readmits every source added after it was written.
+* with `isSpatialTrack`, which allow-lists the spatial sources explicitly — a
+* `!== 'sensor'` check silently readmits every source added after it was
+* written.
 */
 var TrackSourceSchema = _enum([
 	"pipeline",
+	"onboard",
 	"sensor",
 	"audio"
 ]);
@@ -20850,6 +20920,33 @@ var RunReplayFrameProcessorResultSchema = object({ tracks: array(object({
 	*  solid is this track", cheaper than re-deriving it from a trajectory. */
 	framesMatched: number().int()
 })).readonly() });
+/**
+* The long-term series a camera produces. A closed union so a typo cannot
+* invent one, and the ONE declaration of it — the addon's `AnalyticsLtsSeries`
+* is an alias of this, not a second list.
+*/
+var AnalyticsLtsSeriesSchema = _enum([
+	"motion",
+	"audio-dbfs",
+	"battery",
+	"occupancy"
+]);
+/**
+* One closed 5-minute bucket of a long-term series.
+*
+* `samples` is how many readings the bucket folded — it is the ACTIVITY for a
+* series like `motion`, and the confidence for one like `occupancy`. A bucket
+* that exists at all was measured; a bucket that is absent was not, which is a
+* different claim from zero and the reason this is a sparse series.
+*/
+var LtsBucketSchema = object({
+	scope: string$2(),
+	bucketStart: number().int(),
+	samples: number().int().nonnegative(),
+	sum: number(),
+	min: number(),
+	max: number()
+});
 DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).readonly()), method(object({
 	deviceId: number(),
 	trackId: string$2()
@@ -20896,6 +20993,14 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	kinds: array(string$2()).optional(),
 	limit: number().int().min(1).max(MAX_EVENT_QUERY_LIMIT).default(DEFAULT_EVENT_QUERY_LIMIT)
 }), array(SensorEventSchema).readonly()), method(KeyEventQueryInput, array(KeyEventSchema).readonly()), method(KeyEventBatchQueryInput, array(KeyEventsForDeviceSchema).readonly()), method(object({
+	deviceId: number(),
+	series: AnalyticsLtsSeriesSchema,
+	/** Omit for EVERY scope of this series in the range. */
+	scope: string$2().optional(),
+	from: number(),
+	to: number(),
+	limit: number().int().positive().optional()
+}), array(LtsBucketSchema).readonly()), method(object({
 	deviceId: number(),
 	since: number(),
 	until: number(),
@@ -21514,6 +21619,40 @@ var MotionSourceEnum = _enum([
 */
 var MotionSourcesSchema = array(MotionSourceEnum);
 /**
+* Which root detector a camera runs — EXACTLY ONE.
+*
+* Deliberately the SAME vocabulary post-analysis already tags every detection
+* with (`DetectionSource`) rather than a second spelling of the same two
+* ideas: the value an operator picks here is the value that comes back on the
+* track, the overlay and the debug row.
+*
+* ## Why one, and why it is still an array
+*
+* Two roots on one camera is a capability nobody asked for and the operator has
+* since ruled out. It was never free: both planes feed the SAME per-device
+* stationary registry, both can promote the same parked object, and the two
+* detectors disagree about the same box by construction — which is the
+* disagreement D505 had to arbitrate. Removing the case removes the arbitration.
+*
+* The ARRAY shape survives because the stored settings and the attach payload
+* already speak it on every camera of every fleet, and a cap input that
+* suddenly refuses a stored value makes the camera un-attachable — a fail-closed
+* in the one direction that costs an operator their cameras. So the wire stays
+* tolerant and the TYPE is exact: a longer list is truncated to its first
+* element rather than refused, and `max(1)` is what every consumer can then
+* rely on.
+*
+* AT MOST one, not exactly one. The EMPTY list is a legal, deliberate pick —
+* a camera an operator left with no root detector — and `planDetectionSources`
+* has always said so: inventing a root for them is how a default acts without
+* anybody choosing it. Tightening this to `length(1)` broke that, and the
+* suite caught it.
+*
+* Measured before tightening (2026-09-15, this fleet, 6 h of attaches): 3327
+* `["pipeline"]` and 2 `["onboard"]`. Not one camera had two.
+*/
+var DetectionSourcesSchema = preprocess((value) => Array.isArray(value) && value.length > 1 ? value.slice(0, 1) : value, array(DetectionSourceSchema).max(1));
+/**
 * Input shape for `pipeline-runner.reportMotion` cap method. Exported
 * so cap-side consumers (the orchestrator forward, the runner addon's
 * cap implementation, tests) can reuse the type instead of redeclaring
@@ -21664,6 +21803,35 @@ var RunnerCameraConfigSchema = object({
 	*   events; the orchestrator forwards to `reportMotion`.
 	*/
 	motionSources: MotionSourcesSchema.default(["analyzer"]),
+	/**
+	* WHICH root detector runs for this camera. The detection counterpart of
+	* {@link motionSources}, same shape and same discipline: a per-camera list
+	* of sources the system understands, vendor-agnostic, owned here.
+	*
+	* - `pipeline` — this runner's own root step on decoded pixels (`steps`).
+	* - `onboard` — the CAMERA's own detector, admitted only when it is named
+	*   here. Its boxes reach post-analysis on the same
+	*   `PipelineInferenceResult` payload as the pipeline's, so an onboard-born
+	*   track gets the same tracker, the same overlay and the same detail
+	*   subtree (face / plate / embedding).
+	*
+	* `['onboard']` alone is the REPLACEMENT: this runner's root step does not
+	* run, and that is where a camera with a usable onboard detector buys back
+	* its share of the accelerator. It saves the root inference, not the decode
+	* — the detail subtree still needs pixels to cut crops from.
+	*
+	* A camera whose onboard detections carry no geometry cannot serve as a root
+	* step at all (there is nothing to track), and the cap that knows this says
+	* so on `native-object-detection.getOptions().geometry`. On Reolink that is
+	* every battery camera: the boxes ride a sub-stream a battery camera never
+	* attaches, so such a camera stays on `['pipeline']` and its onboard AI is
+	* worth exactly what it already is — a wake signal with a class.
+	*
+	* Defaults to `['pipeline']`, which is byte-for-byte today's behaviour: a
+	* vendor never turns a detector on for the operator, and neither does a
+	* default.
+	*/
+	detectionSources: DetectionSourcesSchema.default(["pipeline"]),
 	pipelineEnabled: boolean().default(true),
 	/** Ordered tree of video steps. Absent → runner skips video detection. */
 	steps: array(PipelineStepInputSchema).readonly().optional(),
@@ -21845,7 +22013,47 @@ var RunnerLocalMetricsSchema = object({
 	queueDepth: number(),
 	frameLazy: FrameLazyMetricsSchema.optional()
 });
+/**
+* Pipeline Runner capability — runtime detection workhorse.
+*
+* One instance per node. Receives camera assignments from
+* `addon-pipeline-orchestrator`, subscribes to the local stream-broker for
+* decoded frames, drains motion + detection queues, calls the local
+* `motion-detection` and `pipeline-executor` capabilities, and emits typed
+* `pipeline.inference-result` and `detection.motion-analysis` events on
+* the bus.
+*
+* Distinct from `pipeline-orchestrator` (the hub-side load balancer) — the
+* runner has zero knowledge of other agents, no global state, and never
+* makes assignment decisions itself.
+*/
+/**
+* Why a runner declined to look at a camera out of band. Named rather than a
+* bare `false`: a camera asleep on battery (D173), one attached elsewhere, one
+* already mid-session and one already bursting are four different facts, and a
+* caller told only "no" cannot tell a protection from a bug.
+*/
+var OccupancyBurstRefusalSchema = _enum([
+	"not-attached",
+	"battery-asleep",
+	"not-watching",
+	"already-bursting"
+]);
 method(RunnerCameraConfigSchema, object({ success: literal(true) }), { kind: "mutation" }), method(object({ deviceId: number() }), object({ success: literal(true) }), { kind: "mutation" }), method(ReportMotionInputSchema, object({ success: literal(true) }), { kind: "mutation" }), method(_void(), RunnerLocalLoadSchema), method(_void(), RunnerLocalMetricsSchema), method(object({ deviceId: number() }), CameraMetricsSchema.nullable()), method(_void(), array(CameraMetricsWithDeviceIdSchema).readonly()), method(_void(), array(number()).readonly()), method(object({
+	deviceId: number(),
+	/** How many frames to collect. The caller sizes this against what its
+	*  own confirmation needs; the runner clamps it to the field's range. */
+	frames: number().int().positive().optional(),
+	/** Why, for the log. A burst nobody can attribute is a cost nobody can
+	*  defend — the periodic one at least has a timer to point at. */
+	reason: string$2()
+}), object({
+	started: boolean(),
+	refusedBecause: OccupancyBurstRefusalSchema.optional()
+}), {
+	auth: "admin",
+	kind: "mutation"
+}), method(object({
 	handle: FrameHandleSchema,
 	bbox: NativeCropBboxSchema,
 	maxWidth: number().int().positive().optional(),
@@ -28692,11 +28900,46 @@ var NativeObjectDetectionStatusSchema = object({
 	supportedClasses: array(NativeObjectClassEnum).readonly(),
 	/**
 	* Whether forwarding of onboard AI detections is enabled for this device.
-	* Default FALSE (opt-in, cold-start) — onboard AI pushes are noisy/sparse and
-	* churn the tracker, so forwarding stays off until the operator enables it.
+	*
+	* Cold-start OFF on every camera. A vendor does not decide which detector a
+	* camera runs — that is the operator's choice, and it is made where every
+	* other detection choice is made. `geometry` on
+	* {@link NativeObjectDetectionOptionsSchema} is how the form says what the
+	* choice would buy this particular camera.
 	*/
 	enabled: boolean()
 });
+/**
+* WHEN a camera's onboard detections carry geometry.
+*
+* - `boxed` — always. The provider holds a standing channel for the boxes, so
+*   a detection is a trackable subject whenever the camera sees one.
+* - `while-streaming` — only while some stream of this camera is already open.
+*   The boxes ride the video's own side-channel rather than a feed of their
+*   own, so they cost nothing and they exist only when something is pulling.
+*   On Reolink this is every BATTERY camera: a persistent second feed is real
+*   radio drain, but a camera that is awake is awake precisely because
+*   something is in front of it, and its stream is already being pulled.
+* - `flag-only` — never. The firmware ships the class and nothing else; the
+*   pipeline needs geometry to make a subject, so such a push reaches the
+*   tracker as motion and no further.
+*
+* Reported and not inferred, because the operator's question in front of the
+* picker is "what do I get", and these are three different answers (D14: the
+* derived form is only as honest as `getOptions`).
+*/
+var NativeObjectGeometryEnum = _enum([
+	"boxed",
+	"while-streaming",
+	"flag-only"
+]);
+var NativeObjectDetectionOptionsSchema = object({
+	/** Classes this firmware can detect — the same list the status reports. */
+	supportedClasses: array(NativeObjectClassEnum).readonly(),
+	/** What a detection from this camera carries. */
+	geometry: NativeObjectGeometryEnum
+});
+var NativeObjectDetectionSettingsPatchSchema = object({ enabled: boolean().optional() });
 var NativeObjectDetectionRuntimeStateSchema = NativeObjectDetectionStatusSchema.extend({ 
 /** Required by createRuntimeStateBridge — epoch ms of last refresh. */
 lastFetchedAt: number() });
@@ -28706,13 +28949,23 @@ var nativeObjectDetectionCapability = {
 	deviceNative: true,
 	mode: "singleton",
 	deviceTypes: [DeviceType.Camera],
-	methods: { setEnabled: method(object({
-		deviceId: number(),
-		enabled: boolean()
-	}), _void(), {
-		kind: "mutation",
-		auth: "admin"
-	}) },
+	methods: {
+		getOptions: method(object({ deviceId: number() }), NativeObjectDetectionOptionsSchema),
+		setSettings: method(object({
+			deviceId: number(),
+			settings: NativeObjectDetectionSettingsPatchSchema
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		setEnabled: method(object({
+			deviceId: number(),
+			enabled: boolean()
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		})
+	},
 	events: { onDetected: { data: object({
 		deviceId: number(),
 		detection: NativeDetectionSchema
@@ -33560,7 +33813,28 @@ var PerScopeBreakdownSchema = object({
 	/** Total tracked objects in this scope (frame / zone / unzoned). */
 	totalObjects: number().int().nonnegative(),
 	/** Per-class count. Keys are macro class names (e.g. `person`, `car`). */
-	byClass: record(string$2(), number().int().nonnegative())
+	byClass: record(string$2(), number().int().nonnegative()),
+	/**
+	* Of `totalObjects`, how many are STANDING — objects the census holds,
+	* present but not going anywhere (a parked car, a bin, a statue).
+	*
+	* The operator's question about a scene has two halves and they answer
+	* different things: "what is parked here" is stable for hours and must not
+	* flap, while "who is walking through" is the thing an alert is about. One
+	* number could only serve one of them, and `totalObjects` served the first
+	* badly — a passer-by moved it and every occupancy rule saw a change.
+	*
+	* `standing + transient === totalObjects`, always. The total keeps its old
+	* meaning exactly, so no rule written against it changes behaviour.
+	*
+	* ABSENT means UNKNOWN, never zero (D393): a snapshot from a node older than
+	* this field cannot say, and a reader that folds absence in as 0 reports "no
+	* parked objects here" about a camera whose lot is full.
+	*/
+	standingObjects: number().int().nonnegative().optional(),
+	/** Of `totalObjects`, how many are passing through. See `standingObjects` —
+	*  same absence rule. */
+	transientObjects: number().int().nonnegative().optional()
 });
 var ZoneScopeBreakdownSchema = PerScopeBreakdownSchema.extend({
 	zoneId: string$2(),
@@ -33683,6 +33957,23 @@ var HistoryPointSchema = object({
 * triple covers the three spatial scopes (per-zone, frame-wide,
 * outside-any-zone). Crossing them with `className?` gives the full
 * combinatorial coverage the operator UI requested.
+*
+* ## ⚠️ The three history methods are DEPRECATED
+*
+* They are served from a 60-MINUTE in-memory ring. It dies with the process,
+* so after a restart they report nothing about a night that did happen, and any
+* window past an hour is silently clamped — a caller cannot tell a clamp from
+* an empty scene. The presets in the occupancy chart existed to hide that
+* horizon rather than to answer a question.
+*
+* Use `pipelineAnalytics.readLongTermSeries({ series: 'occupancy', scope })`
+* instead. Those rows are already written for every camera, ~60 bytes per
+* (camera, scope, 5-minute bucket), kept for a year, and survive a restart.
+* Spell the scope with `occupancyScope(zoneId?, className?)` — the same
+* function the writer uses, so the two cannot drift.
+*
+* The ring stays until these three go, and it is the only thing left reading
+* it. Do not add a fourth caller.
 */
 var zoneAnalyticsCapability = {
 	name: "zone-analytics",
@@ -38082,12 +38373,24 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"nativeObjectDetection.getOptions": {
+		capName: "native-object-detection",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"nativeObjectDetection.setEnabled": {
 		capName: "native-object-detection",
 		capScope: "device",
 		addonId: null,
 		access: "create"
 	},
+	"nativeObjectDetection.setSettings": {
+		capName: "native-object-detection",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"navigation.getFeatures": {
 		capName: "navigation",
 		capScope: "device",
@@ -38352,6 +38655,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"notificationRules.getClipRetentionAsks": {
+		capName: "notification-rules",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"notificationRules.getConditionCatalog": {
 		capName: "notification-rules",
 		capScope: "system",
@@ -38862,6 +39171,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.readLongTermSeries": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.rebuildObjectEmbeddings": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -39534,6 +39849,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineRunner.requestOccupancyBurst": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineRunner.runDetailSubtree": {
 		capName: "pipeline-runner",
 		capScope: "system",
@@ -42314,11 +42635,21 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"nativeObjectDetection.getOptions": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"nativeObjectDetection.setEnabled": [{
 		name: "deviceId",
 		form: "single",
 		optional: false
 	}],
+	"nativeObjectDetection.setSettings": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"navigation.getFeatures": [{
 		name: "deviceId",
 		form: "single",
@@ -42668,6 +42999,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.readLongTermSeries": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.rebuildObjectEmbeddings": [{
 		name: "deviceId",
 		form: "single",
@@ -42858,6 +43194,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineRunner.requestOccupancyBurst": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineRunner.runDetailSubtree": [{
 		name: "deviceId",
 		form: "single",

package/dist/addon.mjs

@@ -5372,7 +5372,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-DEuj7E3j.mjs
+//#region ../types/dist/sleep-BDR76Ykr.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -11623,6 +11623,21 @@ var streamSignalsCapability = {
 	mode: "singleton",
 	deviceTypes: Object.values(DeviceType),
 	runtimeState: StreamSignalsStatusSchema,
+	/**
+	* Runtime-state durability: **session** — mirrored in RAM, never written.
+	*
+	* The slice holds what the DEVICE says it can emit. That is a probed fact,
+	* not an operator choice: the provider re-declares it on every registration,
+	* so losing it loses nothing and persisting it would freeze an answer the
+	* camera is entitled to change. Measured the same day on the sibling case —
+	* `native-object-detection.supportedClasses` was persisted, and a firmware
+	* class the camera really detected stayed missing for the life of the row
+	* because the fix could not reach it.
+	*
+	* See `RuntimeStateDurability`. Enforced by
+	* `scripts/check-runtime-state-durability.ts`.
+	*/
+	durability: "session",
 	methods: { 
 	/**
 	* What this device can emit. Empty is a valid and common answer — most
@@ -18254,6 +18269,48 @@ var NcAlarmConfigSchema = object({
 	settings: NcAlarmSettingsSchema,
 	coverage: array(NcAlarmModeCoverageSchema)
 });
+/**
+* ONE rule's demand on ONE camera's clip ring.
+*
+* A rule, not a camera: the broker takes the MAX over the asks that reach a
+* camera, so the answer stays a faithful description of the rules and the
+* bounding (the byte budget, the broker's own ceiling) stays where the cost
+* lives. A camera that appears in no ask is being told **nothing** — which is
+* a different thing from never having been told, and only the envelope
+* (`rulesLoaded`) can tell those apart.
+*/
+var NcClipRetentionAskSchema = object({
+	/**
+	* The camera this ask is about. **Absent = every camera**, which is what a
+	* rule with no `conditions.devices` means: it can fire anywhere, so it is
+	* asking everywhere.
+	*/
+	deviceId: number().int().nonnegative().optional(),
+	/** Seconds of history the rule needs held for it. Never zero — a rule that
+	*  needs nothing produces no ask at all. */
+	seconds: number().min(0).max(60),
+	/** The profile the rule cuts from, when it named one. Absent = the cheapest
+	*  assigned, which is what the cut defaults to. */
+	profile: CamProfileSchema.optional(),
+	/** Who is asking — so a retention the operator did not expect names a rule. */
+	ruleId: string$2(),
+	ruleName: string$2(),
+	/** Why this many seconds: the rule's own window, or the occupancy ceiling. */
+	reason: _enum(["window", "occupancy"])
+});
+/**
+* The whole answer, with the one bit that keeps absence from reading as zero.
+*
+* `rulesLoaded` is false until the rule ledger has completed a load at least
+* once. A centre that is up but has not read its rules yet answers with an
+* empty ask list that means nothing at all — applying it would drop every
+* camera's ring to zero for the first events after a restart, which is the
+* footage this mechanism exists to keep.
+*/
+var NcClipRetentionPlanSchema = object({
+	rulesLoaded: boolean(),
+	asks: array(NcClipRetentionAskSchema).readonly()
+});
 method(object({}), object({ rules: array(NcRuleSchema) }), { auth: "admin" }), method(object({ ruleId: string$2() }), object({ rule: NcRuleSchema.nullable() }), { auth: "admin" }), method(object({ rule: NcRuleInputSchema }), object({ rule: NcRuleSchema }), {
 	kind: "mutation",
 	auth: "admin",
@@ -18274,7 +18331,7 @@ method(object({}), object({ rules: array(NcRuleSchema) }), { auth: "admin" }), m
 }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({}), object({ mutedDeviceIds: array(number().int()).readonly() }), { auth: "admin" }), method(object({
+}), method(object({}), NcClipRetentionPlanSchema, { auth: "admin" }), method(object({}), object({ mutedDeviceIds: array(number().int()).readonly() }), { auth: "admin" }), method(object({
 	deviceId: number().int(),
 	muted: boolean()
 }), object({ success: literal(true) }), {
@@ -19459,13 +19516,26 @@ var TrackAudioLabelSchema = object({
 *  - `audio` — an audio event on the camera itself that was anomalous for
 *    THAT camera, loud, and heard while nothing visual was happening (D62).
 *
+*  - `onboard` — the CAMERA's own firmware, paired with a decoded frame in
+*    that frame's pixel space. A real root detector and a SPATIAL one: its
+*    boxes are the same kind of fact `pipeline`'s are, produced by a different
+*    detector.
+*
+* `onboard` was missing here while `DetectionSourceSchema` already had it, so
+* a persisted onboard track failed `safeParse` on read and came back with NO
+* source at all — which `isSpatialTrack` then admitted by accident, through the
+* `undefined` arm rather than by anybody's decision, and which `excludeSources`
+* could not name.
+*
 * The spatial subsystems (tracker association, occupancy count, re-id /
 * embedding, resurrection) MUST skip every synthetic source. Test for that
-* with `isSpatialTrack`, which allow-lists `pipeline` — a `!== 'sensor'`
-* check silently readmits every source added after it was written.
+* with `isSpatialTrack`, which allow-lists the spatial sources explicitly — a
+* `!== 'sensor'` check silently readmits every source added after it was
+* written.
 */
 var TrackSourceSchema = _enum([
 	"pipeline",
+	"onboard",
 	"sensor",
 	"audio"
 ]);
@@ -20848,6 +20918,33 @@ var RunReplayFrameProcessorResultSchema = object({ tracks: array(object({
 	*  solid is this track", cheaper than re-deriving it from a trajectory. */
 	framesMatched: number().int()
 })).readonly() });
+/**
+* The long-term series a camera produces. A closed union so a typo cannot
+* invent one, and the ONE declaration of it — the addon's `AnalyticsLtsSeries`
+* is an alias of this, not a second list.
+*/
+var AnalyticsLtsSeriesSchema = _enum([
+	"motion",
+	"audio-dbfs",
+	"battery",
+	"occupancy"
+]);
+/**
+* One closed 5-minute bucket of a long-term series.
+*
+* `samples` is how many readings the bucket folded — it is the ACTIVITY for a
+* series like `motion`, and the confidence for one like `occupancy`. A bucket
+* that exists at all was measured; a bucket that is absent was not, which is a
+* different claim from zero and the reason this is a sparse series.
+*/
+var LtsBucketSchema = object({
+	scope: string$2(),
+	bucketStart: number().int(),
+	samples: number().int().nonnegative(),
+	sum: number(),
+	min: number(),
+	max: number()
+});
 DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).readonly()), method(object({
 	deviceId: number(),
 	trackId: string$2()
@@ -20894,6 +20991,14 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	kinds: array(string$2()).optional(),
 	limit: number().int().min(1).max(MAX_EVENT_QUERY_LIMIT).default(DEFAULT_EVENT_QUERY_LIMIT)
 }), array(SensorEventSchema).readonly()), method(KeyEventQueryInput, array(KeyEventSchema).readonly()), method(KeyEventBatchQueryInput, array(KeyEventsForDeviceSchema).readonly()), method(object({
+	deviceId: number(),
+	series: AnalyticsLtsSeriesSchema,
+	/** Omit for EVERY scope of this series in the range. */
+	scope: string$2().optional(),
+	from: number(),
+	to: number(),
+	limit: number().int().positive().optional()
+}), array(LtsBucketSchema).readonly()), method(object({
 	deviceId: number(),
 	since: number(),
 	until: number(),
@@ -21512,6 +21617,40 @@ var MotionSourceEnum = _enum([
 */
 var MotionSourcesSchema = array(MotionSourceEnum);
 /**
+* Which root detector a camera runs — EXACTLY ONE.
+*
+* Deliberately the SAME vocabulary post-analysis already tags every detection
+* with (`DetectionSource`) rather than a second spelling of the same two
+* ideas: the value an operator picks here is the value that comes back on the
+* track, the overlay and the debug row.
+*
+* ## Why one, and why it is still an array
+*
+* Two roots on one camera is a capability nobody asked for and the operator has
+* since ruled out. It was never free: both planes feed the SAME per-device
+* stationary registry, both can promote the same parked object, and the two
+* detectors disagree about the same box by construction — which is the
+* disagreement D505 had to arbitrate. Removing the case removes the arbitration.
+*
+* The ARRAY shape survives because the stored settings and the attach payload
+* already speak it on every camera of every fleet, and a cap input that
+* suddenly refuses a stored value makes the camera un-attachable — a fail-closed
+* in the one direction that costs an operator their cameras. So the wire stays
+* tolerant and the TYPE is exact: a longer list is truncated to its first
+* element rather than refused, and `max(1)` is what every consumer can then
+* rely on.
+*
+* AT MOST one, not exactly one. The EMPTY list is a legal, deliberate pick —
+* a camera an operator left with no root detector — and `planDetectionSources`
+* has always said so: inventing a root for them is how a default acts without
+* anybody choosing it. Tightening this to `length(1)` broke that, and the
+* suite caught it.
+*
+* Measured before tightening (2026-09-15, this fleet, 6 h of attaches): 3327
+* `["pipeline"]` and 2 `["onboard"]`. Not one camera had two.
+*/
+var DetectionSourcesSchema = preprocess((value) => Array.isArray(value) && value.length > 1 ? value.slice(0, 1) : value, array(DetectionSourceSchema).max(1));
+/**
 * Input shape for `pipeline-runner.reportMotion` cap method. Exported
 * so cap-side consumers (the orchestrator forward, the runner addon's
 * cap implementation, tests) can reuse the type instead of redeclaring
@@ -21662,6 +21801,35 @@ var RunnerCameraConfigSchema = object({
 	*   events; the orchestrator forwards to `reportMotion`.
 	*/
 	motionSources: MotionSourcesSchema.default(["analyzer"]),
+	/**
+	* WHICH root detector runs for this camera. The detection counterpart of
+	* {@link motionSources}, same shape and same discipline: a per-camera list
+	* of sources the system understands, vendor-agnostic, owned here.
+	*
+	* - `pipeline` — this runner's own root step on decoded pixels (`steps`).
+	* - `onboard` — the CAMERA's own detector, admitted only when it is named
+	*   here. Its boxes reach post-analysis on the same
+	*   `PipelineInferenceResult` payload as the pipeline's, so an onboard-born
+	*   track gets the same tracker, the same overlay and the same detail
+	*   subtree (face / plate / embedding).
+	*
+	* `['onboard']` alone is the REPLACEMENT: this runner's root step does not
+	* run, and that is where a camera with a usable onboard detector buys back
+	* its share of the accelerator. It saves the root inference, not the decode
+	* — the detail subtree still needs pixels to cut crops from.
+	*
+	* A camera whose onboard detections carry no geometry cannot serve as a root
+	* step at all (there is nothing to track), and the cap that knows this says
+	* so on `native-object-detection.getOptions().geometry`. On Reolink that is
+	* every battery camera: the boxes ride a sub-stream a battery camera never
+	* attaches, so such a camera stays on `['pipeline']` and its onboard AI is
+	* worth exactly what it already is — a wake signal with a class.
+	*
+	* Defaults to `['pipeline']`, which is byte-for-byte today's behaviour: a
+	* vendor never turns a detector on for the operator, and neither does a
+	* default.
+	*/
+	detectionSources: DetectionSourcesSchema.default(["pipeline"]),
 	pipelineEnabled: boolean().default(true),
 	/** Ordered tree of video steps. Absent → runner skips video detection. */
 	steps: array(PipelineStepInputSchema).readonly().optional(),
@@ -21843,7 +22011,47 @@ var RunnerLocalMetricsSchema = object({
 	queueDepth: number(),
 	frameLazy: FrameLazyMetricsSchema.optional()
 });
+/**
+* Pipeline Runner capability — runtime detection workhorse.
+*
+* One instance per node. Receives camera assignments from
+* `addon-pipeline-orchestrator`, subscribes to the local stream-broker for
+* decoded frames, drains motion + detection queues, calls the local
+* `motion-detection` and `pipeline-executor` capabilities, and emits typed
+* `pipeline.inference-result` and `detection.motion-analysis` events on
+* the bus.
+*
+* Distinct from `pipeline-orchestrator` (the hub-side load balancer) — the
+* runner has zero knowledge of other agents, no global state, and never
+* makes assignment decisions itself.
+*/
+/**
+* Why a runner declined to look at a camera out of band. Named rather than a
+* bare `false`: a camera asleep on battery (D173), one attached elsewhere, one
+* already mid-session and one already bursting are four different facts, and a
+* caller told only "no" cannot tell a protection from a bug.
+*/
+var OccupancyBurstRefusalSchema = _enum([
+	"not-attached",
+	"battery-asleep",
+	"not-watching",
+	"already-bursting"
+]);
 method(RunnerCameraConfigSchema, object({ success: literal(true) }), { kind: "mutation" }), method(object({ deviceId: number() }), object({ success: literal(true) }), { kind: "mutation" }), method(ReportMotionInputSchema, object({ success: literal(true) }), { kind: "mutation" }), method(_void(), RunnerLocalLoadSchema), method(_void(), RunnerLocalMetricsSchema), method(object({ deviceId: number() }), CameraMetricsSchema.nullable()), method(_void(), array(CameraMetricsWithDeviceIdSchema).readonly()), method(_void(), array(number()).readonly()), method(object({
+	deviceId: number(),
+	/** How many frames to collect. The caller sizes this against what its
+	*  own confirmation needs; the runner clamps it to the field's range. */
+	frames: number().int().positive().optional(),
+	/** Why, for the log. A burst nobody can attribute is a cost nobody can
+	*  defend — the periodic one at least has a timer to point at. */
+	reason: string$2()
+}), object({
+	started: boolean(),
+	refusedBecause: OccupancyBurstRefusalSchema.optional()
+}), {
+	auth: "admin",
+	kind: "mutation"
+}), method(object({
 	handle: FrameHandleSchema,
 	bbox: NativeCropBboxSchema,
 	maxWidth: number().int().positive().optional(),
@@ -28690,11 +28898,46 @@ var NativeObjectDetectionStatusSchema = object({
 	supportedClasses: array(NativeObjectClassEnum).readonly(),
 	/**
 	* Whether forwarding of onboard AI detections is enabled for this device.
-	* Default FALSE (opt-in, cold-start) — onboard AI pushes are noisy/sparse and
-	* churn the tracker, so forwarding stays off until the operator enables it.
+	*
+	* Cold-start OFF on every camera. A vendor does not decide which detector a
+	* camera runs — that is the operator's choice, and it is made where every
+	* other detection choice is made. `geometry` on
+	* {@link NativeObjectDetectionOptionsSchema} is how the form says what the
+	* choice would buy this particular camera.
 	*/
 	enabled: boolean()
 });
+/**
+* WHEN a camera's onboard detections carry geometry.
+*
+* - `boxed` — always. The provider holds a standing channel for the boxes, so
+*   a detection is a trackable subject whenever the camera sees one.
+* - `while-streaming` — only while some stream of this camera is already open.
+*   The boxes ride the video's own side-channel rather than a feed of their
+*   own, so they cost nothing and they exist only when something is pulling.
+*   On Reolink this is every BATTERY camera: a persistent second feed is real
+*   radio drain, but a camera that is awake is awake precisely because
+*   something is in front of it, and its stream is already being pulled.
+* - `flag-only` — never. The firmware ships the class and nothing else; the
+*   pipeline needs geometry to make a subject, so such a push reaches the
+*   tracker as motion and no further.
+*
+* Reported and not inferred, because the operator's question in front of the
+* picker is "what do I get", and these are three different answers (D14: the
+* derived form is only as honest as `getOptions`).
+*/
+var NativeObjectGeometryEnum = _enum([
+	"boxed",
+	"while-streaming",
+	"flag-only"
+]);
+var NativeObjectDetectionOptionsSchema = object({
+	/** Classes this firmware can detect — the same list the status reports. */
+	supportedClasses: array(NativeObjectClassEnum).readonly(),
+	/** What a detection from this camera carries. */
+	geometry: NativeObjectGeometryEnum
+});
+var NativeObjectDetectionSettingsPatchSchema = object({ enabled: boolean().optional() });
 var NativeObjectDetectionRuntimeStateSchema = NativeObjectDetectionStatusSchema.extend({ 
 /** Required by createRuntimeStateBridge — epoch ms of last refresh. */
 lastFetchedAt: number() });
@@ -28704,13 +28947,23 @@ var nativeObjectDetectionCapability = {
 	deviceNative: true,
 	mode: "singleton",
 	deviceTypes: [DeviceType.Camera],
-	methods: { setEnabled: method(object({
-		deviceId: number(),
-		enabled: boolean()
-	}), _void(), {
-		kind: "mutation",
-		auth: "admin"
-	}) },
+	methods: {
+		getOptions: method(object({ deviceId: number() }), NativeObjectDetectionOptionsSchema),
+		setSettings: method(object({
+			deviceId: number(),
+			settings: NativeObjectDetectionSettingsPatchSchema
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		setEnabled: method(object({
+			deviceId: number(),
+			enabled: boolean()
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		})
+	},
 	events: { onDetected: { data: object({
 		deviceId: number(),
 		detection: NativeDetectionSchema
@@ -33558,7 +33811,28 @@ var PerScopeBreakdownSchema = object({
 	/** Total tracked objects in this scope (frame / zone / unzoned). */
 	totalObjects: number().int().nonnegative(),
 	/** Per-class count. Keys are macro class names (e.g. `person`, `car`). */
-	byClass: record(string$2(), number().int().nonnegative())
+	byClass: record(string$2(), number().int().nonnegative()),
+	/**
+	* Of `totalObjects`, how many are STANDING — objects the census holds,
+	* present but not going anywhere (a parked car, a bin, a statue).
+	*
+	* The operator's question about a scene has two halves and they answer
+	* different things: "what is parked here" is stable for hours and must not
+	* flap, while "who is walking through" is the thing an alert is about. One
+	* number could only serve one of them, and `totalObjects` served the first
+	* badly — a passer-by moved it and every occupancy rule saw a change.
+	*
+	* `standing + transient === totalObjects`, always. The total keeps its old
+	* meaning exactly, so no rule written against it changes behaviour.
+	*
+	* ABSENT means UNKNOWN, never zero (D393): a snapshot from a node older than
+	* this field cannot say, and a reader that folds absence in as 0 reports "no
+	* parked objects here" about a camera whose lot is full.
+	*/
+	standingObjects: number().int().nonnegative().optional(),
+	/** Of `totalObjects`, how many are passing through. See `standingObjects` —
+	*  same absence rule. */
+	transientObjects: number().int().nonnegative().optional()
 });
 var ZoneScopeBreakdownSchema = PerScopeBreakdownSchema.extend({
 	zoneId: string$2(),
@@ -33681,6 +33955,23 @@ var HistoryPointSchema = object({
 * triple covers the three spatial scopes (per-zone, frame-wide,
 * outside-any-zone). Crossing them with `className?` gives the full
 * combinatorial coverage the operator UI requested.
+*
+* ## ⚠️ The three history methods are DEPRECATED
+*
+* They are served from a 60-MINUTE in-memory ring. It dies with the process,
+* so after a restart they report nothing about a night that did happen, and any
+* window past an hour is silently clamped — a caller cannot tell a clamp from
+* an empty scene. The presets in the occupancy chart existed to hide that
+* horizon rather than to answer a question.
+*
+* Use `pipelineAnalytics.readLongTermSeries({ series: 'occupancy', scope })`
+* instead. Those rows are already written for every camera, ~60 bytes per
+* (camera, scope, 5-minute bucket), kept for a year, and survive a restart.
+* Spell the scope with `occupancyScope(zoneId?, className?)` — the same
+* function the writer uses, so the two cannot drift.
+*
+* The ring stays until these three go, and it is the only thing left reading
+* it. Do not add a fourth caller.
 */
 var zoneAnalyticsCapability = {
 	name: "zone-analytics",
@@ -38080,12 +38371,24 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"nativeObjectDetection.getOptions": {
+		capName: "native-object-detection",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"nativeObjectDetection.setEnabled": {
 		capName: "native-object-detection",
 		capScope: "device",
 		addonId: null,
 		access: "create"
 	},
+	"nativeObjectDetection.setSettings": {
+		capName: "native-object-detection",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"navigation.getFeatures": {
 		capName: "navigation",
 		capScope: "device",
@@ -38350,6 +38653,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"notificationRules.getClipRetentionAsks": {
+		capName: "notification-rules",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"notificationRules.getConditionCatalog": {
 		capName: "notification-rules",
 		capScope: "system",
@@ -38860,6 +39169,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.readLongTermSeries": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.rebuildObjectEmbeddings": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -39532,6 +39847,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineRunner.requestOccupancyBurst": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineRunner.runDetailSubtree": {
 		capName: "pipeline-runner",
 		capScope: "system",
@@ -42312,11 +42633,21 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"nativeObjectDetection.getOptions": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"nativeObjectDetection.setEnabled": [{
 		name: "deviceId",
 		form: "single",
 		optional: false
 	}],
+	"nativeObjectDetection.setSettings": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"navigation.getFeatures": [{
 		name: "deviceId",
 		form: "single",
@@ -42666,6 +42997,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.readLongTermSeries": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.rebuildObjectEmbeddings": [{
 		name: "deviceId",
 		form: "single",
@@ -42856,6 +43192,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineRunner.requestOccupancyBurst": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineRunner.runDetailSubtree": [{
 		name: "deviceId",
 		form: "single",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-matter-broker",
-  "version": "0.2.101",
+  "version": "0.2.103",
   "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",
@@ -67,7 +67,7 @@
     "dev": "vite build --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "publish": "npm publish --access public"
+    "publish:npm": "npm publish --access public"
   },
   "devDependencies": {
     "@camstack/types": "*",