@camstack/addon-provider-homematic 1.2.14 → 1.2.16

package/dist/addon.mjs

@@ -7229,8 +7229,31 @@ var AdoptionJobSchema = object({
 	error: string().nullable()
 });
 /**
-* Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
-* pipeline functions an operator thinks in terms of.
+* Per-camera FUNCTION SWITCHES.
+*
+* ## The aggregate group is being withdrawn — the BADGE is not (D113)
+*
+* This file shipped as "the one coherent on/off surface over the pipeline
+* functions an operator thinks in terms of". The operator's verdict on
+* 2026-08-12 was that the coherent surface bought complexity and no clarity:
+* every function already had a settings page of its own, and a second place to
+* turn it off is a second place to look. Each switch is going back to its own
+* component's original options — detection to the detection-pipeline wrapper
+* binding, audio analysis to its own, recording to `RecordingConfig.enabled`
+* (which was always first-class; the switch was a veneer over
+* `recording.setDeviceConfig`), notifications to a notification-center
+* per-device setting, the two camera planes to their own components.
+*
+* What survives is {@link composeSwitchedOff}: `CameraStatus.switchedOff`, the
+* thing that lets a status surface say DISABLED instead of BROKEN, recomposed
+* straight from the authorities with no group in the middle. That rule was
+* never about a control panel.
+*
+* Everything else here — {@link CAMERA_SWITCH_CATALOG}, {@link CameraSwitch},
+* {@link deriveCameraSwitches}, the `pipelineOrchestrator.getCameraSwitches` /
+* `setCameraSwitch` pair — is a COMPATIBILITY surface for as long as deployed
+* viewers (v1.0.305) and the admin UI still call it. It is deleted when they
+* stop; nothing new may be built on it.
 *
 * ## This file adds no state
 *
@@ -7581,7 +7604,15 @@ var RecordingConfigSchema = object({
 * Each completed/failed run also lands one durable ops-log row on its owning
 * addon surface.
 */
+/**
+* `queued` exists because the recorder mover is SINGLE-FLIGHT and an operator
+* rebalance enqueues one job per (camera, profile). Refusing the second job —
+* what the engine did before — turned a fifteen-camera rebalance into fifteen
+* manual retries. Queued jobs run FIFO; a queued job that is cancelled never
+* runs at all.
+*/
 var RelocateJobStateSchema = _enum([
+	"queued",
 	"running",
 	"done",
 	"failed",
@@ -7616,6 +7647,15 @@ var RelocateFootageInputSchema = object({
 	/** Limits relocation to the logical profile class. Omit only for the
 	* pre-orchestration compatibility path. */
 	footageClass: RelocateFootageClassSchema.optional(),
+	/** Scope the move to ONE camera. Absent = every camera on the source, which
+	*  is what a whole-disk drain means. The rebalance path always sets it: its
+	*  unit is a (camera, profile) pile, not a disk. */
+	deviceId: number().int().optional(),
+	/** Scope the move to specific segment profiles (`high` / `mid` / `low`).
+	*  Finer than `footageClass`, which cannot separate high from mid — and the
+	*  placement plan assigns those two independently, so a rebalance that could
+	*  only say "recordings" would move footage the plan never asked to move. */
+	profiles: array(string()).optional(),
 	/** Copy throttle in MB/s (default 40) — the drain is a background chore,
 	*  never allowed to starve live writers. */
 	throttleMbps: number().min(1).max(1e3).optional()
@@ -7751,6 +7791,21 @@ var StorageLocationSchema = object({
 	nodeId: string().optional(),
 	isDefault: boolean().default(false),
 	isSystem: boolean().default(false),
+	/**
+	* Operator opt-in: whether consumers that BALANCE across several locations
+	* of a type may write here. Recordings reads it today; event media and
+	* backups are the next consumers, which is why the flag lives on the
+	* location rather than in any one addon's store — nothing has to be
+	* extended to add the next consumer.
+	*
+	* OPTIONAL, and ABSENT MEANS ACTIVE. Every location persisted before the
+	* flag existed reads back with no flag and keeps working exactly as before;
+	* that is the whole compat story, and it is why no migration ships with it.
+	* A newly CREATED sibling is stamped `false` by the orchestrator (creating a
+	* disk must not silently start writing to it); the default of a type is
+	* always stamped `true`.
+	*/
+	enabled: boolean().optional(),
 	/** COMPUTED at read time by the orchestrator (statfs of the backing volume
 	*  for node-local locations it can reach) — never persisted, absent when the
 	*  volume is remote/unreachable. The single capacity truth every UI reads. */
@@ -12369,7 +12424,8 @@ method(object({
 }), EmbeddingResultSchema), method(object({ text: string() }), EmbeddingResultSchema), method(_void(), EmbeddingInfoSchema);
 /**
 * filesystem-browse — per-node capability for browsing the node's local
-* filesystem, sandboxed to operator-configured allowed roots. Used by the
+* filesystem. Reads are unconfined (whole filesystem, from `/` down); WRITES
+* are sandboxed to operator-configured allowed roots (D115). Used by the
 * admin "Add filesystem location" flow to pick a node + path. `mode:'per-node'`
 * (one provider per node); the hub calls it with `{nodeId}` so the codegen
 * routes to that exact node (default `nodeIdMode:'routing'`).
@@ -14210,6 +14266,13 @@ var MaskGridDimsSchema = object({
 * `package-event` are pure trigger kinds (no urgency dimension). Extending
 * this one field keeps the schema additive — a rule still declares exactly
 * one trigger.
+*
+* AUDIO rules add no member here, for the reason occupancy added none: the
+* enum is mirrored by hand in the viewer (`scripts/check-viewer-condition-
+* mirror.ts` fails the build on a member the app cannot render) and every
+* member costs a release train. A sustained-sound rule is therefore an
+* `immediate` rule carrying {@link NcConditions.audio} — the condition is the
+* trigger discriminator, exactly as `occupancy` is on `device-event`.
 */
 var NcDeliverySchema = _enum([
 	"immediate",
@@ -14224,15 +14287,32 @@ var NcDeliverySchema = _enum([
 * depend on a provider's raw event name or payload shape.
 */
 var NcSystemEventKindSchema = _enum([
-	"camera-online",
-	"camera-offline",
+	"device-online",
+	"device-offline",
+	"device-disabled",
+	"device-enabled",
 	"stream-online",
 	"stream-offline",
 	"node-online",
 	"node-offline",
 	"addon-update-available",
-	"server-update-available"
+	"server-update-available",
+	"alarm-triggered",
+	"alarm-armed",
+	"alarm-disarmed",
+	"camera-online",
+	"camera-offline",
+	"camera-disabled",
+	"camera-enabled"
 ]);
+/** The legacy tail of {@link NcSystemEventKindSchema} — see its docblock. */
+var NC_LEGACY_SYSTEM_EVENT_KINDS = new Set([
+	"camera-online",
+	"camera-offline",
+	"camera-disabled",
+	"camera-enabled"
+]);
+NcSystemEventKindSchema.options.filter((kind) => !NC_LEGACY_SYSTEM_EVENT_KINDS.has(kind));
 /**
 * One coherent system-event condition. `kinds` is the required opt-in safety
 * gate; the remaining lists are optional narrowing filters relevant to the
@@ -14241,6 +14321,18 @@ var NcSystemEventKindSchema = _enum([
 var NcSystemEventConditionSchema = object({
 	kinds: array(NcSystemEventKindSchema).min(1),
 	deviceIds: array(number().int()).min(1).optional(),
+	/**
+	* Narrow a `device-*` kind to these device TYPES (`DeviceType` values —
+	* `camera`, `switch`, `sensor`, `container`, …). Absent = every type, which
+	* is what a liveness rule means when nobody said otherwise.
+	*
+	* This is where "only my cameras" is expressed, and it lives on the rule for
+	* one reason: the intake cannot know which devices this household cares
+	* about, and a producer-side filter is one no operator can change. Fails
+	* CLOSED — a subject whose device type is unknown (an id the device mirror
+	* does not carry) matches no `deviceTypes` list.
+	*/
+	deviceTypes: array(string().min(1)).min(1).optional(),
 	nodeIds: array(string().min(1)).min(1).optional(),
 	packageNames: array(string().min(1)).min(1).optional()
 });
@@ -14291,6 +14383,47 @@ var NcOccupancyConditionSchema = object({
 	sustainSeconds: number().int().min(0).max(3600).default(15)
 });
 /**
+* Audio condition (IMMEDIATE trigger) — a rule on SOUND, not on a picture.
+*
+* Operator-approved vocabulary (2026-08-12, option A — the same one the
+* reference notifier uses, so an operator moving between them re-uses what
+* they already know): a rule matches when, over a sampling window of
+* `samplingSeconds`, at least `hitPercent`% of the audio samples in that
+* window are HITS. A sample is a hit when it satisfies BOTH present filters:
+*
+*  - `dbThreshold` — its level is at or above this many dBFS (see
+*    {@link NC_AUDIO_DBFS_FLOOR}: negative-going, `0` = full scale);
+*  - `labels` — the classifier put at least one of these labels on it.
+*
+* Both are OPTIONAL and independent, which is the point of the shape: a
+* loudness rule ("something loud at 3am") needs no model to be right, and a
+* label rule ("a dog barked") needs no threshold. **Fail-closed when NEITHER
+* is given** — a window in which every sample is trivially a hit would fire on
+* silence, so the engine refuses such a condition rather than notifying on
+* nothing (the schema cannot express "at least one of" without becoming a
+* ZodEffects the cap path would have to special-case).
+*
+* `hitPercent` is over the samples the window actually HOLDS, and the window
+* must be FULL before it can match — a window that has been open for two
+* seconds of its ten is 100% of nothing, and firing on it would make
+* `samplingSeconds` decorative.
+*
+* Labels are the audio macro classes (`AUDIO_MACRO_LABELS` / the NC taxonomy's
+* `audio-*` ids). Both spellings are accepted — the matcher normalizes the
+* `audio-` prefix away on both sides, so a picker that offers taxonomy ids and
+* an operator who typed `dog` mean the same thing.
+*/
+var NcAudioConditionSchema = object({
+	/** Audio macro labels; absent = any sound (level-only rule). */
+	labels: array(string().min(1)).min(1).optional(),
+	/** Level floor in dBFS (negative-going, `0` = full scale); absent = any level. */
+	dbThreshold: number().min(-96).max(0).optional(),
+	/** Percentage of the window's samples that must be hits (1–100). */
+	hitPercent: number().int().min(1).max(100).default(60),
+	/** Length of the sampling window in seconds. */
+	samplingSeconds: number().int().min(1).max(300).default(10)
+});
+/**
 * Which zone-crossing DIRECTION a rule accepts (`ObjectEvent.zoneCrossing`).
 *
 * The values are not symmetric, and deliberately so — the absent value has to
@@ -14563,7 +14696,33 @@ var NcConditionsSchema = object({
 	* threshold and holds for `sustainSeconds`. Fail-closed on missing
 	* substrate (no snapshot / missing zone). See {@link NcOccupancyCondition}.
 	*/
-	occupancy: NcOccupancyConditionSchema.optional()
+	occupancy: NcOccupancyConditionSchema.optional(),
+	/**
+	* IMMEDIATE only. Sustained-sound matcher — `hitPercent` of the samples in a
+	* `samplingSeconds` window clear the optional `dbThreshold` and carry one of
+	* the optional `labels`. Fail-closed on missing substrate (no audio samples,
+	* a window that is not full yet, neither filter given). See
+	* {@link NcAudioCondition}.
+	*
+	* Presence of this key is what makes a rule an AUDIO rule: the engine fires
+	* it ONLY on a confirmed audio window, and a rule carrying it never fires on
+	* a detection, a track or a device event (the same fail-closed pairing
+	* `occupancy` has with the `device-event` trigger). That is how audio labels
+	* leave `classes`: an audio rule names its sounds HERE, and the legacy path
+	* (an `immediate` rule naming an `audio-*` class, one notification per
+	* classified sample) stays exactly as it was for rules that already use it.
+	*
+	* NOT in {@link NC_CONDITION_CATALOG} yet, and that is the sequencing rule
+	* rather than an oversight: the viewer mirrors the descriptor enums BY HAND
+	* (`camstack/src/data/notification-center.ts`, guarded by
+	* `scripts/check-viewer-condition-mirror.ts`) and its rule editor STRIPS the
+	* condition fields it does not know when a rule is saved from the phone.
+	* Publishing an editor for a condition the app cannot round-trip is how an
+	* operator loses a rule's conditions by opening it — so the descriptor, the
+	* admin widget and the viewer mirror land together (P2 + P3), and only then
+	* does an audio rule become authorable.
+	*/
+	audio: NcAudioConditionSchema.optional()
 });
 /** One delivery target: a `notification-output` Target ref + passthrough params. */
 var NcRuleTargetSchema = object({
@@ -14677,6 +14836,73 @@ var NcThrottleSchema = object({
 	*/
 	granularity: NcThrottleGranularitySchema.optional()
 });
+/**
+* How long the confirm gate may hold ONE notification, and how big the picture
+* it judges may be.
+*
+* The clamp is the product decision, not a coincidence of the model: p50 was
+* 4.9 s warm and 15.3 s cold against qwen3-vl-8b, and a notification that
+* arrives after the visitor has gone is not a notification. 448 px was enough
+* to score 16/16 on the operator's parking scenario — bigger costs latency and
+* tokens for pixels the model pools away.
+*/
+var NC_CONFIRM_MIN_TIMEOUT_MS = 1e3;
+var NC_CONFIRM_MAX_TIMEOUT_MS = 2e4;
+var NC_CONFIRM_DEFAULT_TIMEOUT_MS = 8e3;
+/** Comparison the model's COUNT must satisfy for the notification to fire. */
+var NcConfirmExpectSchema = object({
+	op: _enum([
+		">=",
+		">",
+		"<=",
+		"<",
+		"=="
+	]),
+	count: number().int().min(0).max(1e3)
+});
+/**
+* AI CONFIRM — a vision model looks at the picture this notification is about
+* to ship and says whether it agrees with the rule.
+*
+* It runs AFTER the attachments resolve, deliberately: the crop JUDGED is the
+* crop SHIPPED (D52). A verdict about a different pixel rectangle than the one
+* on the operator's phone is not a verdict about this notification.
+*
+* FAIL-OPEN is the only safe default. A gate that cannot reach its model, or
+* whose model is cold, must not silence a camera — so `onTimeout: 'fire'` is
+* the default and every fail-open is COUNTED, because a gate that always fails
+* open looks in the log exactly like a gate that works.
+*
+* Every field is `.optional()` rather than relied on as a Zod default at the
+* runtime seam: a Zod default does NOT run on the addon→addon cap path (three
+* production failures in one day), so the gate reads absent as the constant
+* above rather than trusting a parse it may never have seen.
+*/
+var NcConfirmSchema = object({
+	/** Off unless asked for. An absent `confirm` and `enabled:false` are the
+	*  same thing, and both mean "deliver exactly as before". */
+	enabled: boolean().default(false),
+	/** Explicit vision profile; absent = the `purpose:'vision'` cluster default. */
+	profileId: string().optional(),
+	/**
+	* The operator's question, in his own words. Absent = a question derived
+	* from the rule (its class and its expectation).
+	*
+	* NEVER composed with text READ OUT OF THE FRAME. The model reads OSD
+	* banners, signage and plates as instructions if you let them reach the
+	* prompt — proven live — so the authoritative contract stays in the system
+	* turn and only rule-authored words land here.
+	*/
+	prompt: string().max(1e3).optional(),
+	/** Fire only when the model's count satisfies this. Absent = the model's
+	*  own boolean verdict decides. */
+	expect: NcConfirmExpectSchema.optional(),
+	timeoutMs: number().int().min(NC_CONFIRM_MIN_TIMEOUT_MS).max(NC_CONFIRM_MAX_TIMEOUT_MS).default(NC_CONFIRM_DEFAULT_TIMEOUT_MS),
+	/** What a timeout / unreachable model MEANS. `fire` (default) = fail-open. */
+	onTimeout: _enum(["fire", "suppress"]).default("fire"),
+	/** Longest edge the judged image is downscaled to before it is sent. */
+	maxImagePx: number().int().min(64).max(2048).default(448)
+});
 /** Client-supplied rule fields (server stamps id/createdBy/createdAt/updatedAt). */
 var NcRuleInputSchema = object({
 	name: string().min(1).max(200),
@@ -14737,7 +14963,13 @@ var NcRuleInputSchema = object({
 	* `{ cap: 'alarm-panel', method: 'arm', args: { mode: 'away' } }`, the same
 	* shape as every other actuation.
 	*/
-	actions: NcRuleActionsSchema.optional()
+	actions: NcRuleActionsSchema.optional(),
+	/**
+	* AI CONFIRM — see {@link NcConfirmSchema}. `.optional()`, never defaulted:
+	* a rule that predates the gate must keep delivering byte-for-byte as it
+	* did, and absent is the only way to say that without a migration.
+	*/
+	confirm: NcConfirmSchema.optional()
 });
 /**
 * Partial patch for `updateRule` — any subset of the input fields, plus the
@@ -14748,7 +14980,37 @@ var NcRuleInputSchema = object({
 * still flow through `nc.setRuleTargetEnabled` (owner-checked), never a raw
 * `updateRule` patch.
 */
-var NcRulePatchSchema = NcRuleInputSchema.partial().extend({ disabledTargetIds: array(string()).optional() });
+var NcRulePatchSchema = NcRuleInputSchema.partial().extend({
+	disabledTargetIds: array(string()).optional(),
+	/**
+	* `.partial()` DOES NOT REMOVE A FIELD'S `.default()`.
+	*
+	* It makes the key optional to SUPPLY; the parse still materialises the
+	* default when the key is absent. And `NcRuleStore.update` merges with
+	* `{ ...existing, ...patch }`, so a materialised key OVERWRITES the stored
+	* one — which made every partial edit destructive:
+	*
+	*   nc.updateRule({ throttle })         → conditions reset to `{}`
+	*   nc.setRuleTargetEnabled(...)        → conditions reset to `{}`
+	*   setEnabled(ruleId, false)           → conditions reset to `{}`
+	*
+	* A rule scoped to one camera and one zone silently became a rule that
+	* matches EVERY event on EVERY camera, and lost its `media` policy
+	* (zoneCrop / gif / clip / frame) and its `priority` at the same time. Seen
+	* live on 2026-08-12: a rule scoped to device 617 fired on 590 and 615
+	* within a minute of a two-field patch.
+	*
+	* So every defaulted field is re-declared here WITHOUT its default. The
+	* inner defaults still apply when the caller DOES send the key — `{}` for
+	* conditions remains a real instruction ("clear them") — and only the
+	* absent key is now genuinely absent.
+	*/
+	enabled: boolean().optional(),
+	conditions: NcConditionsSchema.optional(),
+	media: NcMediaPolicySchema.optional(),
+	throttle: NcThrottleSchema.optional(),
+	priority: number().int().min(1).max(5).optional()
+});
 /** A persisted rule. */
 var NcRuleSchema = NcRuleInputSchema.extend({
 	id: string(),
@@ -15049,6 +15311,25 @@ var NcAlarmSettingsPatchSchema = NcAlarmSettingsSchema.partial();
 * Never authored, never stored — see `alarm-mode-coverage.ts` for why a stored
 * copy would lie the first time a rule is disabled.
 */
+/**
+* Why a device a mode NAMES is nonetheless not armed by it.
+*
+* Each value is an existing authority, never a new flag (D62): `muted` is the
+* per-camera notification switch the Notification Center already owns,
+* `detection-off` is the device's own detection binding being inactive, and
+* `offline` is the device manager's liveness. A fourth reason would mean a
+* fourth authority, and inventing one here is how a panel starts disagreeing
+* with the switches the operator actually used.
+*/
+var NcAlarmSkipReasonSchema = _enum([
+	"muted",
+	"detection-off",
+	"offline"
+]);
+var NcAlarmSkippedDeviceSchema = object({
+	deviceId: number().int(),
+	reason: NcAlarmSkipReasonSchema
+});
 var NcAlarmModeCoverageSchema = object({
 	mode: AlarmArmModeSchema,
 	/** Enabled rules gated on `armed_<mode>`. Zero means the mode does nothing. */
@@ -15056,7 +15337,18 @@ var NcAlarmModeCoverageSchema = object({
 	/** At least one covering rule has no device scope, so the mode covers all. */
 	allDevices: boolean(),
 	/** Ids named by the covering rules. A SUBSET when `allDevices` is true. */
-	deviceIds: array(number().int())
+	deviceIds: array(number().int()),
+	/**
+	* Devices this mode NAMES but cannot actually arm, each with the switch that
+	* excludes it.
+	*
+	* "Away armed — 12 cameras" is a promise, and a muted camera among those
+	* twelve makes it false in exactly the way nobody notices until an incident.
+	* Defaulted to `[]` so a coverage answer computed before this field existed
+	* still parses as "nothing known to be skipped" rather than failing the whole
+	* alarm tab.
+	*/
+	skippedDevices: array(NcAlarmSkippedDeviceSchema).default([])
 });
 var NcAlarmConfigSchema = object({
 	/**
@@ -17888,9 +18180,16 @@ var CameraStatusSchema = object({
 	audio: CameraAudioStatusSchema.nullable(),
 	recording: CameraRecordingStatusSchema.nullable(),
 	/**
-	* Per-camera function switches an OPERATOR has turned off
+	* Per-camera functions an OPERATOR has turned off
 	* ([D61](../../../../docs/decisions/adr-0067.md)).
 	*
+	* Composed from the AUTHORITIES themselves — the wrapper bindings,
+	* `RecordingConfig.enabled`, the notification mute, the broker's audio
+	* policy, the camera's own microphone — via `composeSwitchedOff`, not from
+	* the deprecated `getCameraSwitches` group ([D113](../../../../docs/decisions/adr-0113.md)).
+	* The badge outlives the control panel: the panel was a convenience, this is
+	* the difference between a camera being off and a camera being dead.
+	*
 	* This is the difference between DISABLED and BROKEN. A camera whose
 	* `detection` block reports zero fps and whose `switchedOff` contains
 	* `'object-detection'` was switched off by a person; the same camera with an
@@ -24632,7 +24931,19 @@ var RecordingManifestSchema = object({
 *  profiles/subtrees/locations on this node). */
 var RecordingDeviceUsageSchema = object({
 	deviceId: number(),
-	usedBytes: number()
+	usedBytes: number(),
+	/**
+	* Start of this camera's OLDEST indexed segment, across every profile and
+	* location — the "Oldest footage" column in Recordings → Storage, and the
+	* only honest answer to "is retention actually holding?" per camera.
+	*
+	* `null` = the camera has no footage. OPTIONAL because a recorder that
+	* predates this field omits it entirely, and a hub whose types carry the
+	* field must keep validating that older provider's payload: the framework
+	* (types) and the addon ship on different trains, and the addon is usually
+	* the later of the two.
+	*/
+	oldestMs: number().nullable().optional()
 });
 /** Recording storage usage + capacity for one storage location. */
 var RecordingLocationUsageSchema = object({
@@ -24660,6 +24971,57 @@ var RecordingStorageUsageSchema = object({
 	locations: array(RecordingLocationUsageSchema)
 });
 /**
+* The OPERATOR-ARMED half of multi-location recordings (D116).
+*
+* The placement plan decides where NEW writes go and moves nothing. A rebalance
+* is the operator asking for the EXISTING archive to be brought into line with
+* that plan: one relocate job per (camera, profile) pile that sits on the wrong
+* location, run FIFO behind the single-flight mover.
+*
+* `plan…` and `start…` return the SAME shape deliberately — what the operator
+* confirms is exactly what gets enqueued, and `jobIds` is the only difference
+* (empty on the plan).
+*/
+var RecordingRebalanceMoveSchema = object({
+	deviceId: number(),
+	profile: string(),
+	fromLocationId: string(),
+	toLocationId: string(),
+	bytes: number(),
+	files: number().int()
+});
+/** Why a pile that is out of place is staying there. Every refusal is
+*  reported: a rebalance that silently drops a camera reads exactly like one
+*  that had nothing to do. */
+var RecordingRebalanceSkipReasonSchema = _enum([
+	"unassigned",
+	"target-not-writable",
+	"below-threshold",
+	"no-headroom"
+]);
+var RecordingRebalanceSkipSchema = object({
+	deviceId: number(),
+	profile: string(),
+	fromLocationId: string(),
+	/** The location the plan wants; null when the camera has no assignment. */
+	toLocationId: string().nullable(),
+	bytes: number(),
+	reason: RecordingRebalanceSkipReasonSchema
+});
+var RecordingRebalancePlanSchema = object({
+	moves: array(RecordingRebalanceMoveSchema),
+	skipped: array(RecordingRebalanceSkipSchema),
+	bytesToMove: number(),
+	/** Relocate job ids enqueued. Always empty for the plan (dry-run) call. */
+	jobIds: array(string())
+});
+var RecordingRebalanceInputSchema = object({
+	/** Copy throttle in MB/s (default 40) — a rebalance is a background chore. */
+	throttleMbps: number().min(1).max(1e3).optional(),
+	/** Ignore piles smaller than this (default 1 GB). */
+	minMoveGb: number().min(0).optional()
+});
+/**
 * Result of locating footage at a wall-clock instant for one device/profile.
 * `segment` carries the covering segment's window; `gap` reports the forward
 * nearest covered edge (`null` past the end of footage / when none exists)
@@ -24822,9 +25184,24 @@ method(object({
 }), method(object({ jobId: string() }), RelocateJobSchema.nullable(), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(RelocateFootageInputSchema, object({ jobId: string() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({}), array(RelocateJobSchema).readonly(), {
+	kind: "query",
+	auth: "admin"
+}), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(RecordingRebalanceInputSchema, RecordingRebalancePlanSchema, {
+	kind: "query",
+	auth: "admin"
+}), method(RecordingRebalanceInputSchema, RecordingRebalancePlanSchema, {
+	kind: "mutation",
+	auth: "admin"
 });
 /**
-* `recordingExport` cap — render a footage time range into a single downloadable
+* `recording-export` cap — render a footage time range into a single downloadable
 * MP4 (regular / accelerated / decelerated / timelapse, ± audio), kept for a
 * bounded lifetime with a durable history, auto-expiry, and optional
 * delete-after-download.
@@ -24839,10 +25216,53 @@ method(object({
 */
 /** Playback-speed multiplier for the render (1 = realtime). */
 var ExportSpeedSchema = number().min(.25).max(32);
+/**
+* One dense interval, in WALL-CLOCK SECONDS FROM THE EXPORT'S OWN `fromMs`.
+*
+* **Wall clock, not ffmpeg's `t`** — and the recorder translates. A caller
+* derives these bounds from things that happened at a TIME (a track's
+* `firstSeen`), while `t` runs over the source playlist: the concatenation of
+* every segment present for the range, with each recording GAP removed. The
+* two agree only on a window that recorded without one interruption, and only
+* the render side knows the segments, so the translation lives there
+* (`export-dense-map.ts`, addon-pipeline).
+*
+* It was not always so. These seconds were fed to `between(t,…)` verbatim, and
+* on a 10 h window holding 29,393 s of footage every range landed late by the
+* gap accumulated before it — up to 6,607 s, well past EOF. Nothing matched,
+* the video was a uniform timelapse, and the log line reported the five ranges
+* that had been ASKED for (2026-08-13, export `57d14363`, camera 615).
+*
+* Relative and not absolute epoch, because an absolute epoch would make every
+* call site responsible for the same subtraction.
+*/
+var ExportDenseRangeSchema = object({
+	fromSec: number().nonnegative(),
+	toSec: number().nonnegative()
+}).refine((r) => r.toSec > r.fromSec, { message: "dense range must have toSec > fromSec" });
+/**
+* Dense-interval overlay for a timelapse: sample at `dense.everyMs` INSIDE the
+* listed ranges and at the base `everyMs` everywhere else.
+*
+* `everyMs` must be strictly smaller than the base cadence — a dense rate that
+* is not denser renders a uniform timelapse the operator believes is two-rate.
+*/
+var ExportDenseSchema = object({
+	everyMs: number().int().positive(),
+	ranges: array(ExportDenseRangeSchema).min(1).max(200)
+});
 /** Timelapse cadence — sample one source frame per `everyMs`, output at `outputFps`. */
 var ExportTimelapseSchema = object({
 	everyMs: number().int().positive(),
-	outputFps: number().int().min(1).max(60).optional()
+	outputFps: number().int().min(1).max(60).optional(),
+	/** Optional second, FASTER rate over the intervals that matter. */
+	dense: ExportDenseSchema.optional()
+}).superRefine((v, ctx) => {
+	if (v.dense !== void 0 && v.dense.everyMs >= v.everyMs) ctx.addIssue({
+		code: ZodIssueCode.custom,
+		message: "dense.everyMs must be strictly smaller than the base everyMs",
+		path: ["dense", "everyMs"]
+	});
 });
 /**
 * Render options. `speed` and `timelapse` are mutually exclusive. `includeAudio`
@@ -24900,6 +25320,19 @@ var ExportDownloadSchema = object({
 	url: string(),
 	endpoints: array(string())
 });
+/**
+* A finished export's bytes, inline.
+*
+* `bytes` is the DECODED length — the number the caller bounds and logs
+* against, so nobody has to infer it from the base64 length.
+*/
+var ExportBytesSchema = object({
+	base64: string(),
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	bytes: number().int().nonnegative()
+});
 method(object({
 	deviceId: number(),
 	profile: string(),
@@ -24924,6 +25357,9 @@ method(object({
 }), method(object({ exportId: string() }), ExportDownloadSchema, {
 	kind: "query",
 	auth: "protected"
+}), method(object({ exportId: string() }), ExportBytesSchema, {
+	kind: "query",
+	auth: "protected"
 });
 /**
 * scene-monitor — device-scoped reference-region state cap. An operator marks
@@ -31601,6 +32037,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"recording.cancelRelocateJob": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"recording.cancelStorageMigrationMove": {
 		capName: "recording",
 		capScope: "system",
@@ -31655,6 +32097,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recording.listRelocateJobs": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"recording.locateSegment": {
 		capName: "recording",
 		capScope: "system",
@@ -31667,6 +32115,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"recording.planStorageRebalance": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"recording.pruneFootage": {
 		capName: "recording",
 		capScope: "system",
@@ -31691,6 +32145,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"recording.relocateFootage": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"recording.renderClip": {
 		capName: "recording",
 		capScope: "system",
@@ -31727,38 +32187,50 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"recording.startStorageRebalance": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"recordingExport.cancelExport": {
-		capName: "recordingExport",
+		capName: "recording-export",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
 	"recordingExport.createExport": {
-		capName: "recordingExport",
+		capName: "recording-export",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
 	"recordingExport.deleteExport": {
-		capName: "recordingExport",
+		capName: "recording-export",
 		capScope: "system",
 		addonId: null,
 		access: "delete"
 	},
 	"recordingExport.getDownloadUrl": {
-		capName: "recordingExport",
+		capName: "recording-export",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
 	"recordingExport.getExport": {
-		capName: "recordingExport",
+		capName: "recording-export",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
 	"recordingExport.listExports": {
-		capName: "recordingExport",
+		capName: "recording-export",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"recordingExport.readExportBytes": {
+		capName: "recording-export",
 		capScope: "system",
 		addonId: null,
 		access: "view"
@@ -33135,6 +33607,104 @@ var FramerateField = number().int().min(1).max(60);
 var TargetsField = array(NcRuleTargetSchema).min(1);
 var PriorityField = number().int().min(1).max(5);
 /**
+* Explicit override of the DENSE sampling cadence, seconds.
+*
+* Absent ⇒ derived as `max(1s, cadenceSec / 30)` — a 30 s base samples every
+* 1 s inside a detection range. (It was `base / 10` until 2026-08-12, which
+* made that same base 3 s and rendered a person pass as two frames.)
+*
+* THE ARITHMETIC. A detection range of `rangeSec` seconds sampled every
+* `denseCadenceSec` and played at `framerate` occupies
+*
+*     outputSeconds = (rangeSec / denseCadenceSec) / framerate
+*
+* so a 7 s pass at 1 s / 12 fps is 0.58 s of video, and at 0.5 s it is 1.17 s.
+* Halving this field doubles the frames INSIDE ranges only — the base cadence,
+* and therefore the length of a quiet night, does not move.
+*
+* Floored at {@link TIMELAPSE_DENSE_FLOOR_SEC}: asking for frames faster than
+* the recording has them returns the same frames, requested twice. Must be
+* STRICTLY smaller than `cadenceSec` — a dense rate that is not denser renders
+* a uniform video the operator believes is two-rate — and upsert refuses it
+* rather than letting the export cap reject the render hours after the window.
+*/
+var DenseCadenceSecField = number().min(.1).max(3600);
+/**
+* Minimum seconds of OUTPUT video each detection range must occupy.
+*
+* The operator-facing form of the arithmetic above: instead of solving for a
+* cadence, state the dwell and let the renderer solve. `minDwellSec: 1` on a
+* 30 s base at 12 fps turns a 7 s pass into a full second of video by sampling
+* that range every ~583 ms.
+*
+* ONE CADENCE SERVES EVERY RANGE. `ExportDenseSchema.everyMs` is global — the
+* ranges are terms of a single ffmpeg `select` expression that cannot vary rate
+* per term — so the MOST DEMANDING (shortest) range sets the rate and longer
+* ranges are sampled denser than they need. Per-range cadences require a cap
+* schema change and are the tracked follow-up.
+*
+* A range too short to reach the dwell even at {@link TIMELAPSE_DENSE_FLOOR_SEC}
+* is rendered with every frame that EXISTS and no more: the guarantee is capped
+* by real footage, never met by duplicating frames into motion that never
+* happened.
+*/
+var MinDwellSecField = number().min(0).max(60);
+/**
+* Caption burned into the notification's preview frame.
+*
+* Same `{{var}}` vocabulary as {@link TimelapseTemplateSchema} (`camera`,
+* `rule`, `from`, `to`) and rendered by the SAME renderer — a second
+* templating dialect for one field would be a second thing to explain.
+*
+* Absent ⇒ {@link DEFAULT_TIMELAPSE_PREVIEW_TEXT}. An EMPTY STRING is the
+* operator saying "the frame, no caption" — a distinct, reachable answer, and
+* the reason this is not `.min(1)`.
+*/
+var PreviewTextField = string().max(200);
+/**
+* Whether the notification's preview is a STILL or a short animation.
+*
+* The operator's ask, verbatim: *"inviato come gif o video (come per le altre
+* rule)"* — his Scrypted advanced-notifier has a `gifRule`, and a ten-hour
+* night reads better as three seconds of motion than as one frame of it. Both
+* modes get the SAME treatment (blurred frame, large centred title); `'gif'`
+* simply applies it to a dozen frames sampled across the render and assembles
+* them.
+*
+* `'image'` is the default and stays the default: a GIF costs a dozen ffmpeg
+* seeks and a palette pass, and no rule that never asked for one should start
+* paying that on the deploy that shipped it.
+*
+* A GIF that cannot be assembled DEGRADES to the still — never to nothing.
+*/
+var PreviewModeField = _enum(["image", "gif"]);
+/**
+* Which detection classes the notification reports counts for.
+*
+* The counts come from the tracks the render ALREADY fetched for its dense-range
+* plan — no second query — aggregated per class. Absent or empty means "every
+* class the window actually contained", which is what an operator who never
+* opened the field wants; a list narrows it (`['person']` on a driveway that
+* counts cars all night).
+*
+* Class names are the tracker's own (`person`, `vehicle`, `animal`, `package`,
+* …). An unknown name simply never matches and reports nothing — it is not an
+* error, because a rule may legitimately name a class this camera's model does
+* not emit.
+*
+* The counts are exposed to {@link TimelapseTemplateSchema} as:
+*  - `{{detections}}` — total over the reported classes
+*  - `{{detectionSummary}}` — `2 persone, 1 veicolo`
+*  - `{{count_person}}` / `{{count_vehicle}}` / `{{count_animal}}` / … —
+*    one per class, `count_` + the class name
+*
+* With NO custom body template the summary is appended to the derived body, and
+* only when the total is non-zero: a nightly `0 rilevamenti` is a line nobody
+* reads. With a custom template the operator owns every word — nothing is
+* appended, so `{{detectionSummary}}` is how he asks for it.
+*/
+var ReportClassesField = array(string().min(1).max(40)).max(20);
+/**
 * Client-supplied timelapse-rule fields. The server stamps id / createdBy /
 * createdAt / updatedAt / ownerUserId / lastGeneratedAt — none of them appear
 * here (see the ownership note above).
@@ -33154,9 +33724,30 @@ var TimelapseRuleInputSchema = object({
 	cadenceSec: CadenceSecField.default(15),
 	/** Output frames per second of the assembled mp4 (predecessor parity). */
 	framerate: FramerateField.default(10),
+	/**
+	* Explicit dense cadence — see {@link DenseCadenceSecField}. Absent ⇒ derived
+	* as `max(1s, cadenceSec / 30)`, which is what every rule written before this
+	* field gets.
+	*/
+	denseCadenceSec: DenseCadenceSecField.optional(),
+	/** Output-seconds guarantee per detection range — see {@link MinDwellSecField}. */
+	minDwellSec: MinDwellSecField.optional(),
 	/** `notification-output` targets the finished video/thumbnail is sent to. */
 	targets: TargetsField,
 	template: TimelapseTemplateSchema.optional(),
+	/**
+	* Caption on the notification's PREVIEW FRAME — see {@link PreviewTextField}
+	* and {@link DEFAULT_TIMELAPSE_PREVIEW_TEXT}.
+	*
+	* Deliberately NOT part of {@link TimelapseTemplateSchema}: that object is
+	* the notification's title/body, and clearing it (`template: null`) must not
+	* silently clear the caption too.
+	*/
+	previewText: PreviewTextField.optional(),
+	/** Still or animation — see {@link PreviewModeField}. */
+	previewMode: PreviewModeField.default("image"),
+	/** Classes the notification counts — see {@link ReportClassesField}. */
+	reportClasses: ReportClassesField.optional(),
 	/** Canonical notification priority ordinal (1..5); per-target overridable. */
 	priority: PriorityField.default(3)
 });
@@ -33167,8 +33758,13 @@ object({
 	schedule: NcScheduleSchema.optional(),
 	cadenceSec: CadenceSecField.optional(),
 	framerate: FramerateField.optional(),
+	denseCadenceSec: DenseCadenceSecField.optional(),
+	minDwellSec: MinDwellSecField.optional(),
 	targets: TargetsField.optional(),
 	template: TimelapseTemplateSchema.nullable().optional(),
+	previewText: PreviewTextField.optional(),
+	previewMode: PreviewModeField.optional(),
+	reportClasses: ReportClassesField.optional(),
 	priority: PriorityField.optional()
 });
 TimelapseRuleInputSchema.extend({
@@ -33180,10 +33776,28 @@ TimelapseRuleInputSchema.extend({
 	*/
 	ownerUserId: string().optional(),
 	/**
-	* Epoch-ms of the last successful generation — the 1-hour re-generation
-	* guard's durable state (predecessor parity). Absent = never generated.
+	* Epoch-ms of the NEWEST successful generation across every camera of this
+	* rule. What a UI shows, and the compatibility floor for
+	* {@link readTimelapseGeneratedAt}. Absent = never generated.
 	*/
 	lastGeneratedAt: number().optional(),
+	/**
+	* PER-CAMERA generation state, keyed by `String(deviceId)` — the
+	* re-generation guard's real durable state.
+	*
+	* One rule covers several cameras and each renders its own video, so a rule
+	* -wide stamp is wrong in the direction that DESTROYS work: camera A
+	* succeeding at 06:05 tells camera B, whose render failed, that it is
+	* already done — and B's night is gone for good, because the window will not
+	* come back.
+	*
+	* ADDITIVE, so the migration is free: a row written before this field simply
+	* has no map, and {@link readTimelapseGeneratedAt} falls back to
+	* {@link TimelapseRuleSchema.shape.lastGeneratedAt}. Reading an old row as
+	* "never generated" would re-render and re-notify every camera of every rule
+	* once, on the deploy that shipped the map.
+	*/
+	generatedByDevice: record(string(), number()).optional(),
 	/** userId of the caller who created the rule (server-stamped). */
 	createdBy: string(),
 	createdAt: number(),
@@ -33234,25 +33848,32 @@ object({
 var NativeLeaseAdmissionSchema = _enum(["all", "inferred"]);
 object({
 	/**
-	* How long a retained native frame is served before it counts as a miss.
+	* How many delivered frames the worker HOLDS at once, waiting for each one's
+	* detection result.
 	*
-	* Must cover the FULL late-crop horizon: detection inference + the
-	* cross-process inference-result hop to hub post-analysis + tracking + the
-	* tRPC crop round-trip back. Below ~500 ms the busiest cameras' subject crops
-	* outrun it and fall back to the ≤640 detection frame; above ~3 s the resident
-	* RAM per busy camera grows linearly with no measured hit-rate gain.
+	* This replaced a TTL on 2026-08-13, and the replacement is the whole point:
+	* a time window was never related to the event the pixels were waiting for.
+	* A held frame now lives from delivery until the runner has its `FrameResult`
+	* — at which moment the runner cuts the subject tiles it actually wanted and
+	* releases the frame. The bound exists only so a runner that stops answering
+	* cannot pin RAM: above it the OLDEST held frame is dropped and counted.
+	*
+	* Sizing: the steady state is `inferenceLatency × deliveredFps`, measured at
+	* 40-160 ms × ≤25 fps = 1-4 frames. The default leaves headroom for a hiccup
+	* without ever approaching the old resident set (43 frames × 24.9 MB at 4K).
+	* Raising it does not buy hit rate — it buys tolerance for a slow runner, and
+	* `holdOverflow` on the metrics line is what says you need it.
 	*/
-	ttlMs: number().int().min(250).max(1e4),
+	holdFrames: number().int().min(1).max(64),
 	/**
 	* Hard per-decode-worker RAM ceiling for retained native frames, in MB.
 	*
-	* Intended as a SAFETY ceiling with the TTL as the effective cap — but check
-	* which one is actually binding before reasoning from that. At the shipped
-	* 1024 MB and a 2 800 ms TTL, a 4K camera hits the CEILING first (~43 frames
-	* at ~24 MB each) and the TTL never gets to expire anything; `leaseMb` /
-	* `leaseFrames` on the metrics line say which. When the ceiling binds, a
-	* change that admits fewer frames buys retention WINDOW at constant RAM
-	* rather than giving RAM back — lower this knob if RAM is what you wanted.
+	* Since 2026-08-13 this is a SAFETY ceiling and nothing else: `holdFrames`
+	* is what decides how much is held, and the ceiling is the number above which
+	* something is wrong. Before that it was the effective cap — at 1024 MB with
+	* a 2 800 ms TTL a 4K camera sat pinned at `leaseMb:1020, leaseFrames:43`
+	* with the TTL expiring nothing, which is exactly the confusion the hold
+	* removes. `leaseMb` / `leaseFrames` still say what is resident.
 	* `0` DISABLES the lease entirely and falls the worker back to the tiny
 	* leak-prone GPU surface ring (~85% crop miss; that is what the lease exists
 	* to replace).
@@ -33278,22 +33899,45 @@ object({
 	* there is the signal that some caller names frames outside the inference set
 	* and that this must go back to `all`.
 	*/
-	admission: NativeLeaseAdmissionSchema
+	admission: NativeLeaseAdmissionSchema,
+	/**
+	* RAM ceiling per decode worker, in MB, for the SUBJECT TILES — the
+	* compressed native crops the worker cuts at the moment a frame's detection
+	* result arrives, and keeps long after the frame itself is freed.
+	*
+	* This is the knob that replaced the old retention window, and it buys about
+	* three orders of magnitude more of it: a tile is one subject at native
+	* resolution, JPEG-encoded (~60-120 KB on a 4K person), against ~24.9 MB for
+	* the frame it was cut from. A frame on which nothing was detected costs
+	* nothing at all, which is the real change — the old lease paid per FRAME and
+	* was interrogated per SUBJECT.
+	*
+	* `0` DISABLES tiles, leaving only the hold window and the ≤640 RAM
+	* fallback — i.e. the pre-2026-08-13 miss profile. Set it there only to
+	* reproduce that.
+	*/
+	tileBudgetMb: number().int().min(0).max(1024)
 });
 /**
-* The values in force when the operator has set nothing — byte-for-byte the
-* constants the decode worker shipped with as env-var defaults, so making these
-* settings changed no behaviour on the day it landed.
+* The values in force when the operator has set nothing.
+*
+* `budgetMb` stays at 1024 on the day the hold landed, deliberately: it stopped
+* being the retention window and became the OOM ceiling, and lowering a ceiling
+* in the same change that redefines it would make a regression and a retune
+* indistinguishable. Cut it once `tileHits` / `holdOverflow` have been read on
+* live traffic.
 */
 var DEFAULT_NATIVE_LEASE_SETTINGS = {
-	ttlMs: 1200,
+	holdFrames: 8,
 	budgetMb: 1024,
 	activityMs: 15e3,
+	tileBudgetMb: 64,
 	admission: "inferred"
 };
-DEFAULT_NATIVE_LEASE_SETTINGS.ttlMs;
+DEFAULT_NATIVE_LEASE_SETTINGS.holdFrames;
 DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
+DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 /**
 * Pure fuzzy matcher for adoption location import. Normalized