@camstack/addon-matter-broker 0.2.30 → 0.2.31

package/dist/addon.js

@@ -7540,6 +7540,66 @@ var OpsLogQueryInputSchema = object({
 	/** Max rows returned, newest-first. */
 	limit: number().int().min(1).max(1e3).optional()
 });
+var LabelDefinitionSchema = object({
+	id: string$2(),
+	name: string$2(),
+	category: string$2().optional(),
+	description: string$2().optional(),
+	icon: string$2().optional()
+});
+/** Detection-macro targets a catalog `classMap` may resolve to. */
+var CLASS_MAP_MACRO_TARGETS = [
+	"person",
+	"vehicle",
+	"animal",
+	"package"
+];
+/**
+* Le macro classi di PRIMO LIVELLO: quelle che un object detector emette e che
+* un operatore può selezionare.
+*
+* Sono le tre offerte dallo step `object-detection`
+* (`addon-pipeline/src/detection-pipeline/registry/step-definitions.ts`,
+* `enabledMacroClasses`). `package` sta in {@link CLASS_MAP_MACRO_TARGETS} e in
+* `MACRO_LABELS` — è una macro vera — ma NON qui: appartiene allo step
+* `package-detection`, la cui abilitazione è guidata dalle zone, e offrire la
+* stessa parola due volte ha già fatto accendere a un operatore il proxy COCO
+* (suitcase/backpack/handbag) lasciando spento il detector dedicato.
+*
+* UNA lista. Prima di oggi le stesse tre erano scritte a mano nell'offerta
+* dello step e una seconda volta come union `FirstLevelMacro`
+* (`types/detection.ts`); una terza copia per il trigger di registrazione
+* (`RecordingTriggers.objectClasses`) avrebbe reso invisibile la divergenza
+* successiva.
+*/
+var FIRST_LEVEL_MACRO_CLASSES = [
+	"person",
+	"vehicle",
+	"animal"
+];
+/**
+* Wire schema for a per-model CATALOG classMap override
+* (`ModelCatalogEntry.classMap` / `ModelConvertMetadata.classMap`) —
+* restricted to {@link CLASS_MAP_MACRO_TARGETS}, the only macros the
+* detection pipeline executor actually routes.
+*
+* This is deliberately a DIFFERENT, narrower shape than the general-purpose
+* `ClassMapDefinition` interface above (e.g. `IDetectionAddon.getClassMap()`
+* and the audio `YAMNET_TO_MACRO` catalog both use macro targets outside this
+* enum) — the two used to share the name `ClassMapDefinition`/
+* `ClassMapDefinitionSchema`, which made the schema-type-twin guard
+* (`scripts/check-schema-type-twins.ts`) flag them as a duplicated shape. They
+* are not: it is two different concepts colliding on a name. Keep this type
+* under its own name rather than reusing `ClassMapDefinition` — reusing it
+* would either narrow every `ClassMapDefinition` consumer to the four
+* detection macros (breaking `YAMNET_TO_MACRO`) or drop the validation this
+* schema exists for (see the "rejects a classMap whose target is not a
+* detection macro" test in `model-catalog-schema.test.ts`).
+*/
+var DetectionCatalogClassMapSchema = object({
+	mapping: record(string$2(), _enum(CLASS_MAP_MACRO_TARGETS)),
+	preserveOriginal: boolean()
+});
 /**
 * Numeric day-of-week: 0 = Sunday … 6 = Saturday (matches `Date.getDay`).
 * Named `RecordingWeekday` to avoid collision with the string-union
@@ -7562,10 +7622,55 @@ var RecordingStorageModeSchema = _enum([
 	"events",
 	"continuous"
 ]);
+/**
+* Le macro classi che possono aprire una finestra di registrazione — le stesse
+* tre offerte dallo step `object-detection`, da UNA lista
+* ({@link FIRST_LEVEL_MACRO_CLASSES}).
+*/
+var RecordingObjectTriggerClassSchema = _enum(FIRST_LEVEL_MACRO_CLASSES);
+/**
+* True quando `values` non ripete un elemento.
+*
+* Un duplicato non è innocuo: ogni voce di `objectClasses` / `sensorDeviceIds`
+* diventa una SORGENTE in `bandTriggerSources`, e la stessa sorgente due volte
+* conterebbe due volte le sue finestre in `segmentMissedByMs`.
+*/
+var noDuplicates = (values) => new Set(values).size === values.length;
 /** Which detectors trigger an `events`-mode band. */
 var RecordingTriggersSchema = object({
 	motion: boolean().optional(),
-	audioThresholdDbfs: number().optional()
+	audioThresholdDbfs: number().optional(),
+	/**
+	* Le macro classi la cui detection apre una finestra. ASSENTE = la sorgente
+	* non è ascoltata; un array VUOTO è rifiutato, perché "banda events, trigger
+	* object acceso, nessuna classe" è la stessa forma "abilitata e non registra
+	* nulla, per sempre" contro cui è scritto `eventsBandCanEverDemand`.
+	*
+	* Il segnale letto è GIÀ FILTRATO: solo detection `source: 'pipeline'`, cioè
+	* quelle che hanno attraversato `enabledMacroClasses`, i
+	* `minConfidence<Macro>` e il full-frame guard. L'AI a bordo camera
+	* (`source: 'onboard'`) non attraversa nessuno di quei gate e NON apre
+	* finestre — vedi `recorder/object-trigger.ts`.
+	*/
+	objectClasses: array(RecordingObjectTriggerClassSchema).min(1).refine(noDuplicates, { message: "objectClasses must not repeat a class" }).optional(),
+	/**
+	* I device LINKED il cui FRONTE ALTO apre una finestra. Assente = la sorgente
+	* non è ascoltata; un array vuoto è rifiutato per la stessa ragione di
+	* `objectClasses`.
+	*
+	* Sono id di device SORGENTE, non camere: la banda li nomina, quindi il
+	* percorso caldo (`DeviceStateChanged`, a ritmo di bus su tutta la flotta)
+	* non fa RPC. L'OFFERTA da cui l'operatore li sceglie è un'altra domanda, e
+	* si risolve con `deviceManager.getLinkedDevices` + `getBindingsBatch` per
+	* device (D12) — mai un elenco globale di cap.
+	*
+	* Cosa vuol dire "alto" dipende dal TIPO di device e non è deciso qui:
+	* `SOURCE_CAP_ACTIVE_FIELD` (`catalogs/sensor-active-state.ts`) è LA tabella,
+	* la stessa che il virtual-doorbell usa dal 2026-08-05. Ed è il FRONTE, non
+	* il livello: un contatto trovato già aperto al riavvio del runner non fa
+	* registrare.
+	*/
+	sensorDeviceIds: array(number().int().positive()).min(1).max(16).refine(noDuplicates, { message: "sensorDeviceIds must not repeat a device" }).optional()
 });
 /**
 * Mode of a single recording band — the recorder per-band vocabulary.
@@ -8017,41 +8122,6 @@ var DecoderSessionConfigSchema = object({
 	*/
 	debug: boolean().optional()
 });
-var LabelDefinitionSchema = object({
-	id: string$2(),
-	name: string$2(),
-	category: string$2().optional(),
-	description: string$2().optional(),
-	icon: string$2().optional()
-});
-/**
-* Wire schema for a per-model CATALOG classMap override
-* (`ModelCatalogEntry.classMap` / `ModelConvertMetadata.classMap`) —
-* restricted to {@link CLASS_MAP_MACRO_TARGETS}, the only macros the
-* detection pipeline executor actually routes.
-*
-* This is deliberately a DIFFERENT, narrower shape than the general-purpose
-* `ClassMapDefinition` interface above (e.g. `IDetectionAddon.getClassMap()`
-* and the audio `YAMNET_TO_MACRO` catalog both use macro targets outside this
-* enum) — the two used to share the name `ClassMapDefinition`/
-* `ClassMapDefinitionSchema`, which made the schema-type-twin guard
-* (`scripts/check-schema-type-twins.ts`) flag them as a duplicated shape. They
-* are not: it is two different concepts colliding on a name. Keep this type
-* under its own name rather than reusing `ClassMapDefinition` — reusing it
-* would either narrow every `ClassMapDefinition` consumer to the four
-* detection macros (breaking `YAMNET_TO_MACRO`) or drop the validation this
-* schema exists for (see the "rejects a classMap whose target is not a
-* detection macro" test in `model-catalog-schema.test.ts`).
-*/
-var DetectionCatalogClassMapSchema = object({
-	mapping: record(string$2(), _enum([
-		"person",
-		"vehicle",
-		"animal",
-		"package"
-	])),
-	preserveOriginal: boolean()
-});
 var MODEL_FORMATS = [
 	"onnx",
 	"coreml",
@@ -21233,7 +21303,7 @@ var lifecycleJobSchema = object({
 * `useAddonsOnAddonLogs`, etc. flow through the same codegen pipeline
 * as every other cap.
 */
-var LogLevelSchema$1 = _enum([
+var LogLevelSchema$2 = _enum([
 	"debug",
 	"info",
 	"warn",
@@ -21440,7 +21510,7 @@ var CustomActionInputSchema = object({
 method(_void(), array(AddonListItemSchema).readonly()), method(object({
 	addonId: string$2(),
 	limit: number().min(1).max(500).default(100),
-	level: LogLevelSchema$1.optional()
+	level: LogLevelSchema$2.optional()
 }), array(LogQueryEntrySchema)), method(_void(), array(InstalledPackageSchema).readonly()), method(object({
 	packageName: string$2(),
 	version: string$2().optional()
@@ -21538,7 +21608,7 @@ method(_void(), array(AddonListItemSchema).readonly()), method(object({
 	auth: "admin"
 }), method(object({
 	addonId: string$2(),
-	level: LogLevelSchema$1.optional()
+	level: LogLevelSchema$2.optional()
 }), LogStreamEntrySchema, { kind: "subscription" });
 /**
 * Multi-metric air-quality slice. Covers CO₂, total VOCs, particulate
@@ -23279,6 +23349,35 @@ var FaceFilterEnum = _enum([
 	"identified",
 	"all"
 ]);
+/**
+* What a `listRecentFaces` page is ORDERED BY.
+*
+*  - `timestamp` — when the face was seen. The historical (and default) order.
+*  - `suggestionConfidence` — {@link FaceInfo.suggestedMatchScore}, the peak
+*    cosine of the face's SUGGESTED identity. This is the "review by certainty"
+*    order: it puts the suggestions an operator can confirm with one tap at the
+*    top, and it is the reason this enum exists — a client that ranked a capped
+*    page client-side was ranking the newest N, never the most certain N.
+*
+* A row with NO suggestion (`suggestedMatchScore` absent — a legacy row, an
+* auto-assigned face, or a face below the suggestion band) has no certainty to
+* compare. Under `suggestionConfidence` it sorts **LAST, in BOTH directions**
+* — flipping the direction reorders the rows that HAVE a certainty and never
+* floods the page with the ones that do not. `addon-post-analysis`'s
+* `store/face-sort.ts` is the single implementation, tiebreaks newest-first
+* then by faceId, and is what makes this a total order instead of the
+* backend's NULL-collation accident.
+*/
+var FaceSortFieldEnum = _enum(["timestamp", "suggestionConfidence"]);
+var FaceSortDirectionEnum = _enum(["asc", "desc"]);
+/** One suggested group of look-alike UNASSIGNED faces. Ids only — an embedding
+*  never leaves the server. */
+var FaceClusterSchema = object({
+	faceIds: array(string$2()).readonly(),
+	representativeFaceId: string$2(),
+	size: number().int(),
+	cohesion: number()
+});
 var MediaFileLiteSchema$1 = object({
 	key: string$2(),
 	kind: string$2(),
@@ -23325,24 +23424,72 @@ includeCrops: boolean().optional() }).optional(), array(IdentitySchema).readonly
 	kind: "mutation",
 	auth: "admin"
 }), method(object({
-	/** Restrict to one camera. Absent keeps the cluster-wide gallery view. */
+	/**
+	* Restrict to ONE camera. Absent keeps the cluster-wide gallery view.
+	*
+	* The legacy single-camera form, kept verbatim for every caller that
+	* already sends it. A caller that wants a SET sends {@link deviceIds}
+	* instead — never both: `deviceIds` is the authority whenever it is
+	* present, and this field is then ignored rather than unioned, so
+	* there is exactly one answer to "which cameras did I ask for".
+	*/
 	deviceId: number().int().optional(),
+	/**
+	* Restrict to a SET of cameras — the review UI's camera filter, which
+	* until now had to fetch the cluster-wide page and drop rows in the
+	* client (so the `limit` it asked for was spent on cameras it was
+	* about to discard).
+	*
+	* An **empty array reads NOTHING** — `[]` is an empty page, never
+	* "every camera". A request for no devices is a request, not an
+	* omission; same contract as `deviceManager.listFleet` and
+	* `pipelineAnalytics.listRecentTracks`.
+	*
+	* Absent (`undefined`) is the omission, and keeps the cluster-wide view.
+	*/
+	deviceIds: array(number().int()).optional(),
 	limit: number().int().positive().optional(),
 	filter: FaceFilterEnum.optional(),
 	/**
-	* Inline the base64 crop on every row. Default `true` — the existing
-	* behaviour, kept so no caller breaks.
+	* Window lower bound on {@link FaceInfo.timestamp}, INCLUSIVE.
+	* Absent means no lower bound.
+	*/
+	since: number().int().optional(),
+	/**
+	* Window upper bound on {@link FaceInfo.timestamp}, INCLUSIVE.
+	* Absent means no upper bound.
+	*/
+	until: number().int().optional(),
+	/**
+	* Order the page by time or by suggestion certainty. Default
+	* `'timestamp'` — the historical order, unchanged for every caller
+	* that does not ask.
 	*
-	* Set `false` once the caller renders {@link FaceInfo.cropUrl}: that
-	* drops ~2.87 MiB per 500-row page to a few KiB of metadata and lets
-	* the browser cache the images.
+	* See {@link FaceSortFieldEnum} for what a row with no suggestion
+	* does under `'suggestionConfidence'`.
 	*
-	* **This is an INPUT field, so it does not reach the addon until the
-	* next train.** The hub router validates cap inputs against its own
-	* compiled Zod, which strips a key it does not know — verified today
-	* on the OUTPUT side, where an additive field DOES arrive immediately
-	* (`Track.hasFace`). Until the train ships, sending `false` is
-	* harmless and simply keeps the crops inline.
+	* Cost note: `'timestamp'` is served by the `(deviceId, timestamp)`
+	* index and stops reading as soon as `limit` rows have PASSED the
+	* filter. `'suggestionConfidence'` cannot stop early — the most
+	* certain row may be the oldest — so it walks the window. Narrow it
+	* with {@link since} / {@link until}.
+	*/
+	sortBy: FaceSortFieldEnum.optional(),
+	/** Sort direction for {@link sortBy}. Default `'desc'`. */
+	sortDirection: FaceSortDirectionEnum.optional(),
+	/**
+	* Inline the base64 crop on every row.
+	*
+	* Default `false` since the 2026-08-25 inversion — see
+	* `include-crops-default.ts`, which is the ONE place that resolves
+	* this for every gallery, and which records why the inline shape had
+	* to become the one you ASK for (60 457 ms → UDS timeout at 500 rows).
+	* The doc here used to still say `true`; it was wrong, and a leftover
+	* that describes the old design reads as permission to rely on it.
+	*
+	* Nothing loses its image: the row carries {@link FaceInfo.cropUrl},
+	* which the browser fetches off the `event-media` plane in parallel,
+	* cached and ETagged.
 	*/
 	includeCrops: boolean().optional()
 }).optional(), array(FaceInfoSchema).readonly()), method(object({
@@ -23378,13 +23525,39 @@ includeCrops: boolean().optional() }).optional(), array(IdentitySchema).readonly
 }), method(object({
 	threshold: number().min(0).max(1).optional(),
 	minClusterSize: number().int().min(2).optional(),
-	limit: number().int().positive().optional()
-}).optional(), array(object({
-	faceIds: array(string$2()).readonly(),
-	representativeFaceId: string$2(),
-	size: number().int(),
-	cohesion: number()
-})).readonly());
+	/**
+	* Cap on the number of CLUSTERS returned. Renamed from `limit`,
+	* which read as though it bounded the work — it never did.
+	*
+	* Wins over {@link limit} when both are sent.
+	*/
+	maxClusters: number().int().positive().optional(),
+	/**
+	* @deprecated Ambiguous name for {@link maxClusters} — it cuts the
+	* RESULT, not the scan. Kept so existing callers keep working; send
+	* `maxClusters` (and, if you care about cost, {@link maxFacesScanned}).
+	*/
+	limit: number().int().positive().optional(),
+	/**
+	* Cap on the number of unassigned faces READ AND CLUSTERED — the
+	* POOL, not the result.
+	*
+	* This is the knob {@link maxClusters} was mistaken for. Clustering
+	* used to read every unassigned face on the hub no matter what the
+	* caller asked for, because the only bound cut the finished clusters
+	* afterwards; a UI showing a window of 100 paid for a scan of the
+	* whole corpus, on an addon whose disk is under contention.
+	*
+	* The pool is the NEWEST matching faces first — the same order the
+	* gallery shows — so a bound here shortens the horizon, it does not
+	* sample it randomly.
+	*
+	* Default: 1 000 (`FACE_SWEEP_PAGE`, exactly one store page). Chosen
+	* so the live corpus — 372 face rows — is unaffected while the
+	* unbounded scan can never come back as the table grows.
+	*/
+	maxFacesScanned: number().int().positive().optional()
+}).optional(), array(FaceClusterSchema).readonly());
 /**
 * Fan-control cap. Models HA `fan.*` entity-specific surfaces:
 * speed percentage, preset modes, ceiling-fan direction, and
@@ -28326,6 +28499,211 @@ var SetSiteLocationInputSchema = object({
 	latitude: number().min(-90).max(90),
 	longitude: number().min(-180).max(180)
 }).nullable();
+/**
+* One `(procedure, user-agent, ip, principal)` tuple of the HTTP request
+* census. `principal` is the DERIVED identity (`apocaliss92 (admin)`,
+* `scoped:1a2b3c4d (scoped-token)`, `anonymous`) that the tRPC error log
+* already prints - never a token, never an `Authorization` header.
+*/
+var RequestCensusGroupSchema = object({
+	procedure: string$2(),
+	userAgent: string$2(),
+	ip: string$2(),
+	principal: string$2(),
+	calls: number(),
+	perMin: number()
+});
+/**
+* A procedure's TOTAL over the window, across every caller.
+*
+* This block, not the group list, is what answers "did these calls arrive over
+* HTTP at all". A total far BELOW what a store-side census counted over the
+* same window excludes the HTTP plane, which is a result, not a failure.
+*/
+var RequestCensusProcedureSchema = object({
+	procedure: string$2(),
+	calls: number(),
+	perMin: number()
+});
+/**
+* The census as an operator sees it.
+*
+* `persisted` is the honest answer to "will this survive the restart I am
+* about to do": the arm deadline is written to `system-settings` so a window
+* armed now can measure the NEXT boot, and a write that failed must not look
+* like one that succeeded.
+*/
+var RequestCensusStatusSchema = object({
+	armed: boolean(),
+	/** How long the current - or just-closed - window collected, in ms. */
+	elapsedMs: number(),
+	/** The window actually armed, after the server clamped the request. */
+	windowMs: number(),
+	/** Epoch ms the window closes at. 0 when disarmed. */
+	armedUntilMs: number(),
+	httpRequests: number(),
+	batchedRequests: number(),
+	/**
+	* Procedure invocations. Higher than `httpRequests` whenever tRPC batching
+	* is in play (`?batch=1` carries several procedures in one request); this is
+	* the number comparable with a store-side call count.
+	*/
+	procedureCalls: number(),
+	/**
+	* tRPC WebSocket connections opened during the window. NOT calls - the WS
+	* transport resolves one context per connection - but the number that says
+	* whether a plane this census cannot see was busy while HTTP was quiet.
+	*/
+	wsConnections: number(),
+	distinctGroups: number(),
+	/** Calls counted in the totals whose group attribution was shed at the
+	*  cardinality bound. */
+	unattributedCalls: number(),
+	procedures: array(RequestCensusProcedureSchema).readonly(),
+	groups: array(RequestCensusGroupSchema).readonly()
+}).extend({ persisted: boolean() });
+/** Severity vocabulary. Mirrors `LogLevel` in `interfaces/logging.ts`. */
+var LogLevelSchema$1 = _enum([
+	"debug",
+	"info",
+	"warn",
+	"error"
+]);
+/**
+* The diagnostics that can be ARMED for a window. Exactly one today.
+*
+* A diagnostic is anything whose cost is only worth paying while a question is
+* open. It never persists as a boolean: see {@link DiagnosticWindowSchema}.
+*/
+var DiagnosticIdSchema = _enum(["request-census"]);
+/**
+* The layers of the level hierarchy, general → specific. The most specific
+* layer that carries an explicit value wins.
+*
+* `component` is DECLARED and not yet resolvable: the per-component channels
+* are a later slice of the same plan, and a `levelSource` enum that has to
+* grow later would force every consumer of this document to change with it.
+* Nothing returns `component` today.
+*/
+var LoggingScopeKindSchema = _enum([
+	"cluster",
+	"node",
+	"component"
+]);
+/** Where an effective level came from. `default` = nothing is set anywhere. */
+var LoggingLevelSourceSchema = _enum([
+	"default",
+	"cluster",
+	"node",
+	"component"
+]);
+/**
+* One layer of the hierarchy as it actually STANDS.
+*
+* `level: null` is the whole reason this array is returned: it is the
+* difference between "this node is at `info` because I decided it" and
+* "...because it inherits". An operator who clears an override believing they
+* are clearing an inherited value has been handed the same defect as the two
+* contradicting knobs this document exists to remove, moved one floor up.
+*/
+var LoggingLevelLayerSchema = object({
+	scope: LoggingScopeKindSchema,
+	/** The node this layer speaks for; `null` on the cluster layer. */
+	nodeId: string$2().nullable(),
+	/** Explicitly set here, or `null` when this layer inherits. */
+	level: LogLevelSchema$1.nullable()
+});
+/** What a line is judged against, and WHICH layer decided it. */
+var LoggingEffectiveSchema = object({
+	level: LogLevelSchema$1,
+	levelSource: LoggingLevelSourceSchema
+});
+/** Every layer, general → specific. Never collapsed into the effective value. */
+var LoggingExplicitSchema = object({ layers: array(LoggingLevelLayerSchema).readonly() });
+/**
+* An armed diagnostic, with its DEADLINE.
+*
+* The shape of ADR-0244: what is stored is a deadline and never a flag, so a
+* diagnostic somebody forgot expires by itself, and a boot-window measurement
+* survives the restart it exists to measure. `remainingMs` is 0 whenever
+* `armed` is false — a window is never reported as slightly expired.
+*/
+var DiagnosticWindowSchema = object({
+	id: DiagnosticIdSchema,
+	armed: boolean(),
+	/** Epoch ms the window closes at. 0 when disarmed. */
+	armedUntilMs: number(),
+	/** Ms left before it expires on its own. 0 when disarmed. */
+	remainingMs: number(),
+	/** Whether the stored deadline is the one the live diagnostic is running —
+	*  i.e. whether this window would survive a restart. */
+	persisted: boolean()
+});
+/**
+* `armMs: 0` DISARMS. Any positive value arms for that long, clamped by the
+* server — there is no maximum here on purpose: a bound repeated in a schema
+* is a second knob that disagrees with the first the day one of them moves.
+*/
+var DiagnosticWindowPatchSchema = object({
+	id: DiagnosticIdSchema,
+	armMs: number().int().min(0),
+	/** Cadence of the diagnostic's aggregated report line. Clamped by the server. */
+	reportEveryMs: number().int().positive().optional()
+});
+/**
+* A PATCH, and patches MERGE.
+*
+* A field absent from the patch is left exactly as it was — arming a
+* diagnostic never resets a level, and setting a level never disarms a window.
+* The provider must not reconstruct the document as `{ ...snapshot, ...patch }`:
+* `setAll` already merges, and rebuilding the object is how an absent field
+* turns into an erased one.
+*/
+var LoggingSettingsPatchSchema = object({
+	/**
+	* Absent leaves the level untouched. `null` CLEARS the explicit value at the
+	* addressed scope so it inherits again. A value sets it.
+	*/
+	level: LogLevelSchema$1.nullable().optional(),
+	/**
+	* Only the diagnostics NAMED here change. An armed window that is not listed
+	* keeps running — a patch is never a full replacement.
+	*/
+	diagnostics: array(DiagnosticWindowPatchSchema).readonly().optional()
+});
+/**
+* Which LAYER of the hierarchy is addressed. Absent = the cluster layer.
+*
+* Deliberately NOT called `nodeId`: that key is reserved on every cap method
+* input — the generated router strips it and uses it to resolve the PROVIDER
+* on that node (`resolveProvider(cap, nodeId, …)`). A document about
+* `agent-1` addressed as `nodeId` would be forwarded to agent-1 and answered
+* by an agent that holds no cluster document at all. The hub is the single
+* authority over the whole hierarchy and answers for every layer, so the
+* layer selector needs a name the transport does not already own.
+*/
+var GetLoggingSettingsInputSchema = object({ scopeNodeId: string$2().optional() });
+var SetLoggingSettingsInputSchema = object({
+	scopeNodeId: string$2().optional(),
+	patch: LoggingSettingsPatchSchema
+});
+/**
+* The whole document, as read and as returned after every write.
+*
+* `persisted: false` means the settings store could not be read or written.
+* The in-memory mirror still governs behaviour and is unchanged by the
+* failure — a read that fails neither switches a level nor disarms a window
+* (D49) — but the operator is told that what they are looking at would not
+* survive a restart.
+*/
+var LoggingSettingsStateSchema = object({
+	/** The layer this document was read at. `null` = the cluster layer. */
+	scopeNodeId: string$2().nullable(),
+	effective: LoggingEffectiveSchema,
+	explicit: LoggingExplicitSchema,
+	activeWindows: array(DiagnosticWindowSchema).readonly(),
+	persisted: boolean()
+});
 method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), method(_void(), FeatureManifestSchema), method(_void(), array(NetworkAddressSchema).readonly()), method(_void(), unknown().nullable(), { auth: "admin" }), method(record(string$2(), unknown()), _null(), {
 	kind: "mutation",
 	auth: "admin"
@@ -28338,6 +28716,9 @@ method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), met
 }), method(_void(), SiteLocationStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
+}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
+	kind: "mutation",
+	auth: "admin"
 });
 /**
 * Tamper / case-open detection sensor. Drives Home Assistant
@@ -35577,6 +35958,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getLoggingSettings": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"system.getRequestCensus": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getRetentionConfig": {
 		capName: "system",
 		capScope: "system",
@@ -35607,6 +36000,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"system.setLoggingSettings": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"system.setRetentionConfig": {
 		capName: "system",
 		capScope: "system",
@@ -36762,6 +37161,10 @@ Object.freeze({
 		name: "deviceId",
 		form: "single",
 		optional: true
+	}, {
+		name: "deviceIds",
+		form: "array",
+		optional: true
 	}],
 	"fanControl.setDirection": [{
 		name: "deviceId",
@@ -38372,7 +38775,38 @@ object({
 	* fallback — i.e. the pre-2026-08-13 miss profile. Set it there only to
 	* reproduce that.
 	*/
-	tileBudgetMb: number().int().min(0).max(1024)
+	tileBudgetMb: number().int().min(0).max(1024),
+	/**
+	* RAM ceiling per decode worker, in MB, for the SCENE TILES — one
+	* JPEG-encoded copy of the WHOLE native frame, cut in the same instant as the
+	* subject tiles, on frames that detected something.
+	*
+	* It exists because a subject tile cannot answer a FULL-FRAME request:
+	* containment is strict by design, so the native `keyFrame`, the detail
+	* plane's `frameJpeg` rung and the display-crop fallback had no rung at all
+	* below the hold. Measured on the live cluster: 23.3% of key-frame captures
+	* missed, 95.7% of them with `worker-lease-gone` — the raster released one
+	* frame-time after delivery, with the request only p50 367 ms behind it.
+	*
+	* Sizing, and why this is a budget and not a duration: a scene tile is
+	* ~1.5-2.5 MB at 4K (against ~23.75 MB for the raster it was cut from and
+	* ~60-120 KB for a subject tile), and it is cut ~0.4 times a second per busy
+	* camera — only detection-bearing frames get one. 48 MB is therefore ~20-30
+	* frames, i.e. the store's 30 s TTL binds at the steady state and the budget
+	* binds only through a detection burst, where it still covers well past the
+	* measured p90 ask age of 4.3 s. Holding the RASTERS for the same window
+	* would be ~498 MB per camera and ~6 GB at peak concurrency — the OOM this
+	* whole shape exists to avoid.
+	*
+	* A SEPARATE ceiling from `tileBudgetMb` on purpose: a scene tile is ~20× a
+	* subject tile, so one shared budget would let a busy camera's key frames
+	* evict the face/plate tiles the recognisers depend on. Two budgets make that
+	* impossible rather than unlikely. `0` DISABLES scene tiles and restores the
+	* pre-existing behaviour, where a late full-frame request had nothing but the
+	* ≤640 RAM raster — which the `keyFrame` gate rejects, so in practice it had
+	* nothing.
+	*/
+	sceneBudgetMb: number().int().min(0).max(1024)
 });
 /**
 * The values in force when the operator has set nothing.
@@ -38388,12 +38822,14 @@ var DEFAULT_NATIVE_LEASE_SETTINGS = {
 	budgetMb: 1024,
 	activityMs: 15e3,
 	tileBudgetMb: 64,
+	sceneBudgetMb: 48,
 	admission: "inferred"
 };
 DEFAULT_NATIVE_LEASE_SETTINGS.holdFrames;
 DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb;
+DEFAULT_NATIVE_LEASE_SETTINGS.sceneBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;

package/dist/addon.mjs

@@ -7538,6 +7538,66 @@ var OpsLogQueryInputSchema = object({
 	/** Max rows returned, newest-first. */
 	limit: number().int().min(1).max(1e3).optional()
 });
+var LabelDefinitionSchema = object({
+	id: string$2(),
+	name: string$2(),
+	category: string$2().optional(),
+	description: string$2().optional(),
+	icon: string$2().optional()
+});
+/** Detection-macro targets a catalog `classMap` may resolve to. */
+var CLASS_MAP_MACRO_TARGETS = [
+	"person",
+	"vehicle",
+	"animal",
+	"package"
+];
+/**
+* Le macro classi di PRIMO LIVELLO: quelle che un object detector emette e che
+* un operatore può selezionare.
+*
+* Sono le tre offerte dallo step `object-detection`
+* (`addon-pipeline/src/detection-pipeline/registry/step-definitions.ts`,
+* `enabledMacroClasses`). `package` sta in {@link CLASS_MAP_MACRO_TARGETS} e in
+* `MACRO_LABELS` — è una macro vera — ma NON qui: appartiene allo step
+* `package-detection`, la cui abilitazione è guidata dalle zone, e offrire la
+* stessa parola due volte ha già fatto accendere a un operatore il proxy COCO
+* (suitcase/backpack/handbag) lasciando spento il detector dedicato.
+*
+* UNA lista. Prima di oggi le stesse tre erano scritte a mano nell'offerta
+* dello step e una seconda volta come union `FirstLevelMacro`
+* (`types/detection.ts`); una terza copia per il trigger di registrazione
+* (`RecordingTriggers.objectClasses`) avrebbe reso invisibile la divergenza
+* successiva.
+*/
+var FIRST_LEVEL_MACRO_CLASSES = [
+	"person",
+	"vehicle",
+	"animal"
+];
+/**
+* Wire schema for a per-model CATALOG classMap override
+* (`ModelCatalogEntry.classMap` / `ModelConvertMetadata.classMap`) —
+* restricted to {@link CLASS_MAP_MACRO_TARGETS}, the only macros the
+* detection pipeline executor actually routes.
+*
+* This is deliberately a DIFFERENT, narrower shape than the general-purpose
+* `ClassMapDefinition` interface above (e.g. `IDetectionAddon.getClassMap()`
+* and the audio `YAMNET_TO_MACRO` catalog both use macro targets outside this
+* enum) — the two used to share the name `ClassMapDefinition`/
+* `ClassMapDefinitionSchema`, which made the schema-type-twin guard
+* (`scripts/check-schema-type-twins.ts`) flag them as a duplicated shape. They
+* are not: it is two different concepts colliding on a name. Keep this type
+* under its own name rather than reusing `ClassMapDefinition` — reusing it
+* would either narrow every `ClassMapDefinition` consumer to the four
+* detection macros (breaking `YAMNET_TO_MACRO`) or drop the validation this
+* schema exists for (see the "rejects a classMap whose target is not a
+* detection macro" test in `model-catalog-schema.test.ts`).
+*/
+var DetectionCatalogClassMapSchema = object({
+	mapping: record(string$2(), _enum(CLASS_MAP_MACRO_TARGETS)),
+	preserveOriginal: boolean()
+});
 /**
 * Numeric day-of-week: 0 = Sunday … 6 = Saturday (matches `Date.getDay`).
 * Named `RecordingWeekday` to avoid collision with the string-union
@@ -7560,10 +7620,55 @@ var RecordingStorageModeSchema = _enum([
 	"events",
 	"continuous"
 ]);
+/**
+* Le macro classi che possono aprire una finestra di registrazione — le stesse
+* tre offerte dallo step `object-detection`, da UNA lista
+* ({@link FIRST_LEVEL_MACRO_CLASSES}).
+*/
+var RecordingObjectTriggerClassSchema = _enum(FIRST_LEVEL_MACRO_CLASSES);
+/**
+* True quando `values` non ripete un elemento.
+*
+* Un duplicato non è innocuo: ogni voce di `objectClasses` / `sensorDeviceIds`
+* diventa una SORGENTE in `bandTriggerSources`, e la stessa sorgente due volte
+* conterebbe due volte le sue finestre in `segmentMissedByMs`.
+*/
+var noDuplicates = (values) => new Set(values).size === values.length;
 /** Which detectors trigger an `events`-mode band. */
 var RecordingTriggersSchema = object({
 	motion: boolean().optional(),
-	audioThresholdDbfs: number().optional()
+	audioThresholdDbfs: number().optional(),
+	/**
+	* Le macro classi la cui detection apre una finestra. ASSENTE = la sorgente
+	* non è ascoltata; un array VUOTO è rifiutato, perché "banda events, trigger
+	* object acceso, nessuna classe" è la stessa forma "abilitata e non registra
+	* nulla, per sempre" contro cui è scritto `eventsBandCanEverDemand`.
+	*
+	* Il segnale letto è GIÀ FILTRATO: solo detection `source: 'pipeline'`, cioè
+	* quelle che hanno attraversato `enabledMacroClasses`, i
+	* `minConfidence<Macro>` e il full-frame guard. L'AI a bordo camera
+	* (`source: 'onboard'`) non attraversa nessuno di quei gate e NON apre
+	* finestre — vedi `recorder/object-trigger.ts`.
+	*/
+	objectClasses: array(RecordingObjectTriggerClassSchema).min(1).refine(noDuplicates, { message: "objectClasses must not repeat a class" }).optional(),
+	/**
+	* I device LINKED il cui FRONTE ALTO apre una finestra. Assente = la sorgente
+	* non è ascoltata; un array vuoto è rifiutato per la stessa ragione di
+	* `objectClasses`.
+	*
+	* Sono id di device SORGENTE, non camere: la banda li nomina, quindi il
+	* percorso caldo (`DeviceStateChanged`, a ritmo di bus su tutta la flotta)
+	* non fa RPC. L'OFFERTA da cui l'operatore li sceglie è un'altra domanda, e
+	* si risolve con `deviceManager.getLinkedDevices` + `getBindingsBatch` per
+	* device (D12) — mai un elenco globale di cap.
+	*
+	* Cosa vuol dire "alto" dipende dal TIPO di device e non è deciso qui:
+	* `SOURCE_CAP_ACTIVE_FIELD` (`catalogs/sensor-active-state.ts`) è LA tabella,
+	* la stessa che il virtual-doorbell usa dal 2026-08-05. Ed è il FRONTE, non
+	* il livello: un contatto trovato già aperto al riavvio del runner non fa
+	* registrare.
+	*/
+	sensorDeviceIds: array(number().int().positive()).min(1).max(16).refine(noDuplicates, { message: "sensorDeviceIds must not repeat a device" }).optional()
 });
 /**
 * Mode of a single recording band — the recorder per-band vocabulary.
@@ -8015,41 +8120,6 @@ var DecoderSessionConfigSchema = object({
 	*/
 	debug: boolean().optional()
 });
-var LabelDefinitionSchema = object({
-	id: string$2(),
-	name: string$2(),
-	category: string$2().optional(),
-	description: string$2().optional(),
-	icon: string$2().optional()
-});
-/**
-* Wire schema for a per-model CATALOG classMap override
-* (`ModelCatalogEntry.classMap` / `ModelConvertMetadata.classMap`) —
-* restricted to {@link CLASS_MAP_MACRO_TARGETS}, the only macros the
-* detection pipeline executor actually routes.
-*
-* This is deliberately a DIFFERENT, narrower shape than the general-purpose
-* `ClassMapDefinition` interface above (e.g. `IDetectionAddon.getClassMap()`
-* and the audio `YAMNET_TO_MACRO` catalog both use macro targets outside this
-* enum) — the two used to share the name `ClassMapDefinition`/
-* `ClassMapDefinitionSchema`, which made the schema-type-twin guard
-* (`scripts/check-schema-type-twins.ts`) flag them as a duplicated shape. They
-* are not: it is two different concepts colliding on a name. Keep this type
-* under its own name rather than reusing `ClassMapDefinition` — reusing it
-* would either narrow every `ClassMapDefinition` consumer to the four
-* detection macros (breaking `YAMNET_TO_MACRO`) or drop the validation this
-* schema exists for (see the "rejects a classMap whose target is not a
-* detection macro" test in `model-catalog-schema.test.ts`).
-*/
-var DetectionCatalogClassMapSchema = object({
-	mapping: record(string$2(), _enum([
-		"person",
-		"vehicle",
-		"animal",
-		"package"
-	])),
-	preserveOriginal: boolean()
-});
 var MODEL_FORMATS = [
 	"onnx",
 	"coreml",
@@ -21231,7 +21301,7 @@ var lifecycleJobSchema = object({
 * `useAddonsOnAddonLogs`, etc. flow through the same codegen pipeline
 * as every other cap.
 */
-var LogLevelSchema$1 = _enum([
+var LogLevelSchema$2 = _enum([
 	"debug",
 	"info",
 	"warn",
@@ -21438,7 +21508,7 @@ var CustomActionInputSchema = object({
 method(_void(), array(AddonListItemSchema).readonly()), method(object({
 	addonId: string$2(),
 	limit: number().min(1).max(500).default(100),
-	level: LogLevelSchema$1.optional()
+	level: LogLevelSchema$2.optional()
 }), array(LogQueryEntrySchema)), method(_void(), array(InstalledPackageSchema).readonly()), method(object({
 	packageName: string$2(),
 	version: string$2().optional()
@@ -21536,7 +21606,7 @@ method(_void(), array(AddonListItemSchema).readonly()), method(object({
 	auth: "admin"
 }), method(object({
 	addonId: string$2(),
-	level: LogLevelSchema$1.optional()
+	level: LogLevelSchema$2.optional()
 }), LogStreamEntrySchema, { kind: "subscription" });
 /**
 * Multi-metric air-quality slice. Covers CO₂, total VOCs, particulate
@@ -23277,6 +23347,35 @@ var FaceFilterEnum = _enum([
 	"identified",
 	"all"
 ]);
+/**
+* What a `listRecentFaces` page is ORDERED BY.
+*
+*  - `timestamp` — when the face was seen. The historical (and default) order.
+*  - `suggestionConfidence` — {@link FaceInfo.suggestedMatchScore}, the peak
+*    cosine of the face's SUGGESTED identity. This is the "review by certainty"
+*    order: it puts the suggestions an operator can confirm with one tap at the
+*    top, and it is the reason this enum exists — a client that ranked a capped
+*    page client-side was ranking the newest N, never the most certain N.
+*
+* A row with NO suggestion (`suggestedMatchScore` absent — a legacy row, an
+* auto-assigned face, or a face below the suggestion band) has no certainty to
+* compare. Under `suggestionConfidence` it sorts **LAST, in BOTH directions**
+* — flipping the direction reorders the rows that HAVE a certainty and never
+* floods the page with the ones that do not. `addon-post-analysis`'s
+* `store/face-sort.ts` is the single implementation, tiebreaks newest-first
+* then by faceId, and is what makes this a total order instead of the
+* backend's NULL-collation accident.
+*/
+var FaceSortFieldEnum = _enum(["timestamp", "suggestionConfidence"]);
+var FaceSortDirectionEnum = _enum(["asc", "desc"]);
+/** One suggested group of look-alike UNASSIGNED faces. Ids only — an embedding
+*  never leaves the server. */
+var FaceClusterSchema = object({
+	faceIds: array(string$2()).readonly(),
+	representativeFaceId: string$2(),
+	size: number().int(),
+	cohesion: number()
+});
 var MediaFileLiteSchema$1 = object({
 	key: string$2(),
 	kind: string$2(),
@@ -23323,24 +23422,72 @@ includeCrops: boolean().optional() }).optional(), array(IdentitySchema).readonly
 	kind: "mutation",
 	auth: "admin"
 }), method(object({
-	/** Restrict to one camera. Absent keeps the cluster-wide gallery view. */
+	/**
+	* Restrict to ONE camera. Absent keeps the cluster-wide gallery view.
+	*
+	* The legacy single-camera form, kept verbatim for every caller that
+	* already sends it. A caller that wants a SET sends {@link deviceIds}
+	* instead — never both: `deviceIds` is the authority whenever it is
+	* present, and this field is then ignored rather than unioned, so
+	* there is exactly one answer to "which cameras did I ask for".
+	*/
 	deviceId: number().int().optional(),
+	/**
+	* Restrict to a SET of cameras — the review UI's camera filter, which
+	* until now had to fetch the cluster-wide page and drop rows in the
+	* client (so the `limit` it asked for was spent on cameras it was
+	* about to discard).
+	*
+	* An **empty array reads NOTHING** — `[]` is an empty page, never
+	* "every camera". A request for no devices is a request, not an
+	* omission; same contract as `deviceManager.listFleet` and
+	* `pipelineAnalytics.listRecentTracks`.
+	*
+	* Absent (`undefined`) is the omission, and keeps the cluster-wide view.
+	*/
+	deviceIds: array(number().int()).optional(),
 	limit: number().int().positive().optional(),
 	filter: FaceFilterEnum.optional(),
 	/**
-	* Inline the base64 crop on every row. Default `true` — the existing
-	* behaviour, kept so no caller breaks.
+	* Window lower bound on {@link FaceInfo.timestamp}, INCLUSIVE.
+	* Absent means no lower bound.
+	*/
+	since: number().int().optional(),
+	/**
+	* Window upper bound on {@link FaceInfo.timestamp}, INCLUSIVE.
+	* Absent means no upper bound.
+	*/
+	until: number().int().optional(),
+	/**
+	* Order the page by time or by suggestion certainty. Default
+	* `'timestamp'` — the historical order, unchanged for every caller
+	* that does not ask.
 	*
-	* Set `false` once the caller renders {@link FaceInfo.cropUrl}: that
-	* drops ~2.87 MiB per 500-row page to a few KiB of metadata and lets
-	* the browser cache the images.
+	* See {@link FaceSortFieldEnum} for what a row with no suggestion
+	* does under `'suggestionConfidence'`.
 	*
-	* **This is an INPUT field, so it does not reach the addon until the
-	* next train.** The hub router validates cap inputs against its own
-	* compiled Zod, which strips a key it does not know — verified today
-	* on the OUTPUT side, where an additive field DOES arrive immediately
-	* (`Track.hasFace`). Until the train ships, sending `false` is
-	* harmless and simply keeps the crops inline.
+	* Cost note: `'timestamp'` is served by the `(deviceId, timestamp)`
+	* index and stops reading as soon as `limit` rows have PASSED the
+	* filter. `'suggestionConfidence'` cannot stop early — the most
+	* certain row may be the oldest — so it walks the window. Narrow it
+	* with {@link since} / {@link until}.
+	*/
+	sortBy: FaceSortFieldEnum.optional(),
+	/** Sort direction for {@link sortBy}. Default `'desc'`. */
+	sortDirection: FaceSortDirectionEnum.optional(),
+	/**
+	* Inline the base64 crop on every row.
+	*
+	* Default `false` since the 2026-08-25 inversion — see
+	* `include-crops-default.ts`, which is the ONE place that resolves
+	* this for every gallery, and which records why the inline shape had
+	* to become the one you ASK for (60 457 ms → UDS timeout at 500 rows).
+	* The doc here used to still say `true`; it was wrong, and a leftover
+	* that describes the old design reads as permission to rely on it.
+	*
+	* Nothing loses its image: the row carries {@link FaceInfo.cropUrl},
+	* which the browser fetches off the `event-media` plane in parallel,
+	* cached and ETagged.
 	*/
 	includeCrops: boolean().optional()
 }).optional(), array(FaceInfoSchema).readonly()), method(object({
@@ -23376,13 +23523,39 @@ includeCrops: boolean().optional() }).optional(), array(IdentitySchema).readonly
 }), method(object({
 	threshold: number().min(0).max(1).optional(),
 	minClusterSize: number().int().min(2).optional(),
-	limit: number().int().positive().optional()
-}).optional(), array(object({
-	faceIds: array(string$2()).readonly(),
-	representativeFaceId: string$2(),
-	size: number().int(),
-	cohesion: number()
-})).readonly());
+	/**
+	* Cap on the number of CLUSTERS returned. Renamed from `limit`,
+	* which read as though it bounded the work — it never did.
+	*
+	* Wins over {@link limit} when both are sent.
+	*/
+	maxClusters: number().int().positive().optional(),
+	/**
+	* @deprecated Ambiguous name for {@link maxClusters} — it cuts the
+	* RESULT, not the scan. Kept so existing callers keep working; send
+	* `maxClusters` (and, if you care about cost, {@link maxFacesScanned}).
+	*/
+	limit: number().int().positive().optional(),
+	/**
+	* Cap on the number of unassigned faces READ AND CLUSTERED — the
+	* POOL, not the result.
+	*
+	* This is the knob {@link maxClusters} was mistaken for. Clustering
+	* used to read every unassigned face on the hub no matter what the
+	* caller asked for, because the only bound cut the finished clusters
+	* afterwards; a UI showing a window of 100 paid for a scan of the
+	* whole corpus, on an addon whose disk is under contention.
+	*
+	* The pool is the NEWEST matching faces first — the same order the
+	* gallery shows — so a bound here shortens the horizon, it does not
+	* sample it randomly.
+	*
+	* Default: 1 000 (`FACE_SWEEP_PAGE`, exactly one store page). Chosen
+	* so the live corpus — 372 face rows — is unaffected while the
+	* unbounded scan can never come back as the table grows.
+	*/
+	maxFacesScanned: number().int().positive().optional()
+}).optional(), array(FaceClusterSchema).readonly());
 /**
 * Fan-control cap. Models HA `fan.*` entity-specific surfaces:
 * speed percentage, preset modes, ceiling-fan direction, and
@@ -28324,6 +28497,211 @@ var SetSiteLocationInputSchema = object({
 	latitude: number().min(-90).max(90),
 	longitude: number().min(-180).max(180)
 }).nullable();
+/**
+* One `(procedure, user-agent, ip, principal)` tuple of the HTTP request
+* census. `principal` is the DERIVED identity (`apocaliss92 (admin)`,
+* `scoped:1a2b3c4d (scoped-token)`, `anonymous`) that the tRPC error log
+* already prints - never a token, never an `Authorization` header.
+*/
+var RequestCensusGroupSchema = object({
+	procedure: string$2(),
+	userAgent: string$2(),
+	ip: string$2(),
+	principal: string$2(),
+	calls: number(),
+	perMin: number()
+});
+/**
+* A procedure's TOTAL over the window, across every caller.
+*
+* This block, not the group list, is what answers "did these calls arrive over
+* HTTP at all". A total far BELOW what a store-side census counted over the
+* same window excludes the HTTP plane, which is a result, not a failure.
+*/
+var RequestCensusProcedureSchema = object({
+	procedure: string$2(),
+	calls: number(),
+	perMin: number()
+});
+/**
+* The census as an operator sees it.
+*
+* `persisted` is the honest answer to "will this survive the restart I am
+* about to do": the arm deadline is written to `system-settings` so a window
+* armed now can measure the NEXT boot, and a write that failed must not look
+* like one that succeeded.
+*/
+var RequestCensusStatusSchema = object({
+	armed: boolean(),
+	/** How long the current - or just-closed - window collected, in ms. */
+	elapsedMs: number(),
+	/** The window actually armed, after the server clamped the request. */
+	windowMs: number(),
+	/** Epoch ms the window closes at. 0 when disarmed. */
+	armedUntilMs: number(),
+	httpRequests: number(),
+	batchedRequests: number(),
+	/**
+	* Procedure invocations. Higher than `httpRequests` whenever tRPC batching
+	* is in play (`?batch=1` carries several procedures in one request); this is
+	* the number comparable with a store-side call count.
+	*/
+	procedureCalls: number(),
+	/**
+	* tRPC WebSocket connections opened during the window. NOT calls - the WS
+	* transport resolves one context per connection - but the number that says
+	* whether a plane this census cannot see was busy while HTTP was quiet.
+	*/
+	wsConnections: number(),
+	distinctGroups: number(),
+	/** Calls counted in the totals whose group attribution was shed at the
+	*  cardinality bound. */
+	unattributedCalls: number(),
+	procedures: array(RequestCensusProcedureSchema).readonly(),
+	groups: array(RequestCensusGroupSchema).readonly()
+}).extend({ persisted: boolean() });
+/** Severity vocabulary. Mirrors `LogLevel` in `interfaces/logging.ts`. */
+var LogLevelSchema$1 = _enum([
+	"debug",
+	"info",
+	"warn",
+	"error"
+]);
+/**
+* The diagnostics that can be ARMED for a window. Exactly one today.
+*
+* A diagnostic is anything whose cost is only worth paying while a question is
+* open. It never persists as a boolean: see {@link DiagnosticWindowSchema}.
+*/
+var DiagnosticIdSchema = _enum(["request-census"]);
+/**
+* The layers of the level hierarchy, general → specific. The most specific
+* layer that carries an explicit value wins.
+*
+* `component` is DECLARED and not yet resolvable: the per-component channels
+* are a later slice of the same plan, and a `levelSource` enum that has to
+* grow later would force every consumer of this document to change with it.
+* Nothing returns `component` today.
+*/
+var LoggingScopeKindSchema = _enum([
+	"cluster",
+	"node",
+	"component"
+]);
+/** Where an effective level came from. `default` = nothing is set anywhere. */
+var LoggingLevelSourceSchema = _enum([
+	"default",
+	"cluster",
+	"node",
+	"component"
+]);
+/**
+* One layer of the hierarchy as it actually STANDS.
+*
+* `level: null` is the whole reason this array is returned: it is the
+* difference between "this node is at `info` because I decided it" and
+* "...because it inherits". An operator who clears an override believing they
+* are clearing an inherited value has been handed the same defect as the two
+* contradicting knobs this document exists to remove, moved one floor up.
+*/
+var LoggingLevelLayerSchema = object({
+	scope: LoggingScopeKindSchema,
+	/** The node this layer speaks for; `null` on the cluster layer. */
+	nodeId: string$2().nullable(),
+	/** Explicitly set here, or `null` when this layer inherits. */
+	level: LogLevelSchema$1.nullable()
+});
+/** What a line is judged against, and WHICH layer decided it. */
+var LoggingEffectiveSchema = object({
+	level: LogLevelSchema$1,
+	levelSource: LoggingLevelSourceSchema
+});
+/** Every layer, general → specific. Never collapsed into the effective value. */
+var LoggingExplicitSchema = object({ layers: array(LoggingLevelLayerSchema).readonly() });
+/**
+* An armed diagnostic, with its DEADLINE.
+*
+* The shape of ADR-0244: what is stored is a deadline and never a flag, so a
+* diagnostic somebody forgot expires by itself, and a boot-window measurement
+* survives the restart it exists to measure. `remainingMs` is 0 whenever
+* `armed` is false — a window is never reported as slightly expired.
+*/
+var DiagnosticWindowSchema = object({
+	id: DiagnosticIdSchema,
+	armed: boolean(),
+	/** Epoch ms the window closes at. 0 when disarmed. */
+	armedUntilMs: number(),
+	/** Ms left before it expires on its own. 0 when disarmed. */
+	remainingMs: number(),
+	/** Whether the stored deadline is the one the live diagnostic is running —
+	*  i.e. whether this window would survive a restart. */
+	persisted: boolean()
+});
+/**
+* `armMs: 0` DISARMS. Any positive value arms for that long, clamped by the
+* server — there is no maximum here on purpose: a bound repeated in a schema
+* is a second knob that disagrees with the first the day one of them moves.
+*/
+var DiagnosticWindowPatchSchema = object({
+	id: DiagnosticIdSchema,
+	armMs: number().int().min(0),
+	/** Cadence of the diagnostic's aggregated report line. Clamped by the server. */
+	reportEveryMs: number().int().positive().optional()
+});
+/**
+* A PATCH, and patches MERGE.
+*
+* A field absent from the patch is left exactly as it was — arming a
+* diagnostic never resets a level, and setting a level never disarms a window.
+* The provider must not reconstruct the document as `{ ...snapshot, ...patch }`:
+* `setAll` already merges, and rebuilding the object is how an absent field
+* turns into an erased one.
+*/
+var LoggingSettingsPatchSchema = object({
+	/**
+	* Absent leaves the level untouched. `null` CLEARS the explicit value at the
+	* addressed scope so it inherits again. A value sets it.
+	*/
+	level: LogLevelSchema$1.nullable().optional(),
+	/**
+	* Only the diagnostics NAMED here change. An armed window that is not listed
+	* keeps running — a patch is never a full replacement.
+	*/
+	diagnostics: array(DiagnosticWindowPatchSchema).readonly().optional()
+});
+/**
+* Which LAYER of the hierarchy is addressed. Absent = the cluster layer.
+*
+* Deliberately NOT called `nodeId`: that key is reserved on every cap method
+* input — the generated router strips it and uses it to resolve the PROVIDER
+* on that node (`resolveProvider(cap, nodeId, …)`). A document about
+* `agent-1` addressed as `nodeId` would be forwarded to agent-1 and answered
+* by an agent that holds no cluster document at all. The hub is the single
+* authority over the whole hierarchy and answers for every layer, so the
+* layer selector needs a name the transport does not already own.
+*/
+var GetLoggingSettingsInputSchema = object({ scopeNodeId: string$2().optional() });
+var SetLoggingSettingsInputSchema = object({
+	scopeNodeId: string$2().optional(),
+	patch: LoggingSettingsPatchSchema
+});
+/**
+* The whole document, as read and as returned after every write.
+*
+* `persisted: false` means the settings store could not be read or written.
+* The in-memory mirror still governs behaviour and is unchanged by the
+* failure — a read that fails neither switches a level nor disarms a window
+* (D49) — but the operator is told that what they are looking at would not
+* survive a restart.
+*/
+var LoggingSettingsStateSchema = object({
+	/** The layer this document was read at. `null` = the cluster layer. */
+	scopeNodeId: string$2().nullable(),
+	effective: LoggingEffectiveSchema,
+	explicit: LoggingExplicitSchema,
+	activeWindows: array(DiagnosticWindowSchema).readonly(),
+	persisted: boolean()
+});
 method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), method(_void(), FeatureManifestSchema), method(_void(), array(NetworkAddressSchema).readonly()), method(_void(), unknown().nullable(), { auth: "admin" }), method(record(string$2(), unknown()), _null(), {
 	kind: "mutation",
 	auth: "admin"
@@ -28336,6 +28714,9 @@ method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), met
 }), method(_void(), SiteLocationStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
+}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
+	kind: "mutation",
+	auth: "admin"
 });
 /**
 * Tamper / case-open detection sensor. Drives Home Assistant
@@ -35575,6 +35956,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getLoggingSettings": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"system.getRequestCensus": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getRetentionConfig": {
 		capName: "system",
 		capScope: "system",
@@ -35605,6 +35998,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"system.setLoggingSettings": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"system.setRetentionConfig": {
 		capName: "system",
 		capScope: "system",
@@ -36760,6 +37159,10 @@ Object.freeze({
 		name: "deviceId",
 		form: "single",
 		optional: true
+	}, {
+		name: "deviceIds",
+		form: "array",
+		optional: true
 	}],
 	"fanControl.setDirection": [{
 		name: "deviceId",
@@ -38370,7 +38773,38 @@ object({
 	* fallback — i.e. the pre-2026-08-13 miss profile. Set it there only to
 	* reproduce that.
 	*/
-	tileBudgetMb: number().int().min(0).max(1024)
+	tileBudgetMb: number().int().min(0).max(1024),
+	/**
+	* RAM ceiling per decode worker, in MB, for the SCENE TILES — one
+	* JPEG-encoded copy of the WHOLE native frame, cut in the same instant as the
+	* subject tiles, on frames that detected something.
+	*
+	* It exists because a subject tile cannot answer a FULL-FRAME request:
+	* containment is strict by design, so the native `keyFrame`, the detail
+	* plane's `frameJpeg` rung and the display-crop fallback had no rung at all
+	* below the hold. Measured on the live cluster: 23.3% of key-frame captures
+	* missed, 95.7% of them with `worker-lease-gone` — the raster released one
+	* frame-time after delivery, with the request only p50 367 ms behind it.
+	*
+	* Sizing, and why this is a budget and not a duration: a scene tile is
+	* ~1.5-2.5 MB at 4K (against ~23.75 MB for the raster it was cut from and
+	* ~60-120 KB for a subject tile), and it is cut ~0.4 times a second per busy
+	* camera — only detection-bearing frames get one. 48 MB is therefore ~20-30
+	* frames, i.e. the store's 30 s TTL binds at the steady state and the budget
+	* binds only through a detection burst, where it still covers well past the
+	* measured p90 ask age of 4.3 s. Holding the RASTERS for the same window
+	* would be ~498 MB per camera and ~6 GB at peak concurrency — the OOM this
+	* whole shape exists to avoid.
+	*
+	* A SEPARATE ceiling from `tileBudgetMb` on purpose: a scene tile is ~20× a
+	* subject tile, so one shared budget would let a busy camera's key frames
+	* evict the face/plate tiles the recognisers depend on. Two budgets make that
+	* impossible rather than unlikely. `0` DISABLES scene tiles and restores the
+	* pre-existing behaviour, where a late full-frame request had nothing but the
+	* ≤640 RAM raster — which the `keyFrame` gate rejects, so in practice it had
+	* nothing.
+	*/
+	sceneBudgetMb: number().int().min(0).max(1024)
 });
 /**
 * The values in force when the operator has set nothing.
@@ -38386,12 +38820,14 @@ var DEFAULT_NATIVE_LEASE_SETTINGS = {
 	budgetMb: 1024,
 	activityMs: 15e3,
 	tileBudgetMb: 64,
+	sceneBudgetMb: 48,
 	admission: "inferred"
 };
 DEFAULT_NATIVE_LEASE_SETTINGS.holdFrames;
 DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb;
+DEFAULT_NATIVE_LEASE_SETTINGS.sceneBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-matter-broker",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "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",