@camstack/addon-osd-manager 0.1.99 → 0.1.100

package/dist/index.js

@@ -5363,7 +5363,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).
@@ -12083,6 +12083,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
@@ -20667,6 +20682,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(),
+	ruleName: string(),
+	/** 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()
+});
 var notificationRulesCapability = {
 	name: "notification-rules",
 	scope: "system",
@@ -20699,6 +20756,23 @@ var notificationRulesCapability = {
 			auth: "admin"
 		}),
 		/**
+		* WHAT THE RULES ACTUALLY ASK the stream broker to retain, per camera.
+		*
+		* The notification centre owns the rules, so it is the only thing that can
+		* say how much history a camera's notifications will ever reach back for.
+		* Before this the broker guessed — a flat minute on every camera — and
+		* learned the PROFILE reactively, after the first clip had already been cut
+		* from the wrong one. This is the same ask stated once, in front.
+		*
+		* A QUERY, pulled by each node's broker, not a push: brokers are per node
+		* (a camera's ring lives wherever its stream is ingested) while this cap is
+		* a singleton, so a push would have to enumerate the cluster. The pull also
+		* makes the failure mode right — a broker that cannot reach the centre
+		* keeps the plan it has, and a plan that has never arrived is UNKNOWN
+		* rather than empty (D49: a read that fails changes nothing).
+		*/
+		getClipRetentionAsks: method(object({}), NcClipRetentionPlanSchema, { auth: "admin" }),
+		/**
 		* PERMANENT per-camera mute — the notifications half of the per-camera
 		* function switch group ([D61](../../../../docs/decisions/adr-0067.md)).
 		*
@@ -23577,6 +23651,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(),
+	bucketStart: number().int(),
+	samples: number().int().nonnegative(),
+	sum: number(),
+	min: number(),
+	max: number()
+});
 var pipelineAnalyticsCapability = {
 	name: "pipeline-analytics",
 	scope: "device",
@@ -23720,6 +23821,30 @@ var pipelineAnalyticsCapability = {
 		getKeyEventsBatch: method(KeyEventBatchQueryInput, array(KeyEventsForDeviceSchema).readonly()),
 		/** Server-side bucketed event counts for the 24-hour timeline.
 		*  Returns one entry per non-empty bucket; empty buckets are omitted. */
+		/**
+		* Read one camera's long-term series — 5-minute buckets, kept for a year.
+		*
+		* This is the history surface for every chart that used to be served from a
+		* RAM ring: the ring dies with the process, cannot answer about last night,
+		* and had a 60-minute horizon, while these rows are ~60 bytes and already
+		* written. `scope` is the series' own dimension — for `occupancy`, spell it
+		* with {@link occupancyScope} rather than by hand, and omit it to get every
+		* scope back at once (the caller then groups with
+		* {@link parseOccupancyScope}).
+		*
+		* Bounds are inclusive on the BUCKET START, so a range that ends mid-bucket
+		* still returns the bucket it lands in — the alternative is a chart whose
+		* last column silently disappears for five minutes out of every five.
+		*/
+		readLongTermSeries: method(object({
+			deviceId: number(),
+			series: AnalyticsLtsSeriesSchema,
+			/** Omit for EVERY scope of this series in the range. */
+			scope: string().optional(),
+			from: number(),
+			to: number(),
+			limit: number().int().positive().optional()
+		}), array(LtsBucketSchema).readonly()),
 		getEventDensity: method(object({
 			deviceId: number(),
 			since: number(),
@@ -24861,6 +24986,14 @@ var MotionSourceEnum = _enum([
 */
 var MotionSourcesSchema = array(MotionSourceEnum);
 /**
+* Which root detectors a camera runs. 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.
+*/
+var DetectionSourcesSchema = array(DetectionSourceSchema);
+/**
 * 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
@@ -25011,6 +25144,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(),
@@ -25206,6 +25368,18 @@ var RunnerLocalMetricsSchema = object({
 * 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"
+]);
 var pipelineRunnerCapability = {
 	name: "pipeline-runner",
 	scope: "system",
@@ -25242,6 +25416,50 @@ var pipelineRunnerCapability = {
 		/** List the deviceIds currently attached to this runner. */
 		getLocalCameras: method(_void(), array(number()).readonly()),
 		/**
+		* Look at a camera NOW, out of band, because something just happened that
+		* only a fresh look can settle.
+		*
+		* The periodic recheck (`occupancyRecheckSec`, 300 s) exists to watch a
+		* still scene. It is the wrong instrument for a QUESTION that has just been
+		* asked: on device 617 a parked car's departure was observed, a departure
+		* strike was armed — and then the motion session ended, the strike decayed
+		* after its 30 s TTL, and the next periodic look arrived up to five minutes
+		* later with nothing left to confirm. Every one of those departures was
+		* settled by the entry ageing out 6 to 10 minutes of observed time later,
+		* and the notification's clip showed an empty space with nothing leaving
+		* it.
+		*
+		* Two numbers make the ask specific, and a caller that ignores them wastes
+		* the burst: a confirmation must land at least
+		* `DEPARTURE_CONFIRM_MIN_GAP_MS` (3 s) after the read that armed the
+		* strike — before that it is the same optical event and is refused — and
+		* `DEPARTURE_ABSENCE_MIN_READS` (5) consecutive unassociated frames are
+		* needed, while `occupancyRecheckFrames` defaults to FOUR. A burst of four
+		* can never confirm an absence; that is why two periodic looks were always
+		* required.
+		*
+		* The runner answers whether it actually started one. A refusal is NAMED,
+		* never a silent `false`: a camera that is asleep on battery (D173 — this
+		* must not become a self-initiated wake), detached, mid-session or already
+		* bursting are four different facts, and a caller told only "no" cannot
+		* tell a protection from a bug.
+		*/
+		requestOccupancyBurst: 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()
+		}), object({
+			started: boolean(),
+			refusedBecause: OccupancyBurstRefusalSchema.optional()
+		}), {
+			auth: "admin",
+			kind: "mutation"
+		}),
+		/**
 		* Best-effort NATIVE-resolution crop of a retention-ring frame. Given the
 		* `FrameHandle` that rode an inference-result event and a normalized `bbox`,
 		* the runner asks the decode worker still holding that frame's NATIVE
@@ -33660,11 +33878,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() });
@@ -33674,13 +33927,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
@@ -39142,7 +39405,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(), number().int().nonnegative())
+	byClass: record(string(), 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(),
@@ -39265,6 +39549,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",
@@ -42429,12 +42730,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",
@@ -42699,6 +43012,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",
@@ -43209,6 +43528,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",
@@ -43881,6 +44206,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",
@@ -46661,11 +46992,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",
@@ -47015,6 +47356,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.readLongTermSeries": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.rebuildObjectEmbeddings": [{
 		name: "deviceId",
 		form: "single",
@@ -47205,6 +47551,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineRunner.requestOccupancyBurst": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineRunner.runDetailSubtree": [{
 		name: "deviceId",
 		form: "single",