@camstack/addon-provider-reolink 1.2.101 → 1.2.103

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/addon.js +892 -759
  2. package/dist/addon.mjs +892 -759
  3. package/package.json +1 -1
package/dist/addon.js CHANGED
@@ -25,7 +25,7 @@ let fs_promises = require("fs/promises");
25
25
  fs_promises = require_chunk.__toESM(fs_promises, 1);
26
26
  let node_os = require("node:os");
27
27
  node_os = require_chunk.__toESM(node_os);
28
- //#region ../types/dist/event-category-zAv7pMUz.mjs
28
+ //#region ../types/dist/event-category-CnLqLOKs.mjs
29
29
  var EventCategory = /* @__PURE__ */ function(EventCategory) {
30
30
  EventCategory["SystemBoot"] = "system.boot";
31
31
  EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -220,6 +220,19 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
220
220
  EventCategory["ProcessCrashed"] = "process.crashed";
221
221
  EventCategory["ProcessRestartScheduled"] = "process.restart_scheduled";
222
222
  EventCategory["ProcessRestarted"] = "process.restarted";
223
+ /**
224
+ * The SET of storage locations changed — one was created, edited, enabled,
225
+ * disabled or deleted through `storage.upsertLocation` / `deleteLocation`.
226
+ *
227
+ * Telemetry, not a transaction (D8/D11): every consumer that re-resolves on
228
+ * it must also converge on its own periodic path, because a dropped event
229
+ * must not leave a node writing to yesterday's disk set forever. It exists
230
+ * because there was NO signal at all — an operator who added a second
231
+ * recordings disk in the admin UI got nothing, and the recorder kept its
232
+ * resolved locations until something else happened to re-resolve them
233
+ * (D387). Payload `StorageLocationsChangedPayload`.
234
+ */
235
+ EventCategory["StorageLocationsChanged"] = "storage.locations-changed";
223
236
  EventCategory["RecordingStarted"] = "recording.started";
224
237
  EventCategory["RecordingStopped"] = "recording.stopped";
225
238
  EventCategory["RecordingError"] = "recording.error";
@@ -7653,362 +7666,6 @@ var CameraSwitchGroupSchema = object({
7653
7666
  fetchedAt: number()
7654
7667
  });
7655
7668
  /**
7656
- * Per-component log CHANNELS — the gate a hot path consults, and the registry
7657
- * an addon declares its channels in.
7658
- *
7659
- * ## Two axes, deliberately separated
7660
- *
7661
- * - **DECLARATION** — which channels exist. Only the addon knows:
7662
- * `stream-broker` knows webrtc/ICE/RTP, `provider-reolink` knows
7663
- * baichuan/handshake. A hand-wired central list rots at the first addition,
7664
- * and rots silently. So a channel is declared where it is consulted, and the
7665
- * `log-channels` capability enumerates the declarations.
7666
- * - **VALUE** — at which level, for which scope, until when. That stays ONE
7667
- * thing: the logging settings document on the `system` cap. Two authorities
7668
- * over the values is the exact defect
7669
- * `docs/design/plans/2026-08-26-logging-per-componente.md` was written to
7670
- * remove; re-introducing it from the cure side would be grotesque.
7671
- *
7672
- * Nothing in this file reads a clock, an env var or a store. The registry is
7673
- * a MIRROR: it is moved only by {@link LogChannelRegistry.apply}, called off
7674
- * the hot path with a value somebody actually read, and by
7675
- * {@link LogChannelRegistry.tick}, called on a timer. A store read that fails
7676
- * never reaches here, so it can neither disarm an armed channel nor arm a
7677
- * disarmed one (D49).
7678
- *
7679
- * ## The canonical call shape
7680
- *
7681
- * ```ts
7682
- * if (CH_RTP.on && CH_RTP.wants(deviceId)) {
7683
- * CH_RTP.log(logger, 'rtp subscriber added', { tags: { deviceId }, meta: { ssrc } })
7684
- * }
7685
- * ```
7686
- *
7687
- * `on` is a plain boolean FIELD — never a getter — and it is the FIRST thing
7688
- * read. Disarmed, a call site costs one load and one branch, and the `extras`
7689
- * object literal is never constructed because it lives inside the branch. It
7690
- * is the same shape already proven in production at `stream-broker.ts:1650`,
7691
- * and the same discipline `LoggingGate.allowsDestination` uses for the
7692
- * destination floor (measured at 1.93 ns/call when off).
7693
- *
7694
- * ## Why a channel emits at `info`
7695
- *
7696
- * `loki-logging.addon.ts` pins the destination default at `info` and
7697
- * `loki-destination.ts` drops everything below it, so a line emitted at
7698
- * `debug` never reaches Loki and the hub's in-memory ring only holds ~35
7699
- * minutes. A diagnostic that cannot be read an hour later is worse than no
7700
- * diagnostic, because it looks done. {@link LogChannelGate.log} therefore
7701
- * emits at the channel's declared level, whose schema floor is `info`.
7702
- */
7703
- /**
7704
- * The level a channel writes at once armed.
7705
- *
7706
- * `debug` is absent ON PURPOSE and not by omission: below `info` the line does
7707
- * not leave the process for Loki, and the whole point of arming a channel is
7708
- * to read it later.
7709
- */
7710
- var LogChannelLevelSchema = _enum([
7711
- "info",
7712
- "warn",
7713
- "error"
7714
- ]);
7715
- /**
7716
- * What an addon declares about one channel. No value, no state — a
7717
- * declaration is inert.
7718
- */
7719
- var LogChannelDescriptorSchema = object({
7720
- /**
7721
- * Dotted `area.thing`, unique across the workspace. `area` is conventionally
7722
- * the addon's short name so an operator reading a channel list can tell who
7723
- * owns it without a second lookup.
7724
- */
7725
- name: string().min(3).regex(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/, "a channel name is dotted lower-kebab, e.g. area.thing"),
7726
- /** One sentence: what the operator will SEE after arming it. */
7727
- description: string().min(1),
7728
- /** The level its lines are emitted at. Never below `info`. */
7729
- defaultLevel: LogChannelLevelSchema,
7730
- /**
7731
- * Whether this channel can be narrowed to a camera.
7732
- *
7733
- * `true` is a PROMISE with two halves, and both must hold: the gate is
7734
- * consulted with the numeric device id, AND every line the channel admits
7735
- * carries `tags: { deviceId }` with that same numeric id. The second half is
7736
- * what makes `| json | deviceId="617"` work in Loki — `loki-payload.ts`
7737
- * keeps `deviceId` out of the stream labels for cardinality, so the tag in
7738
- * the body is the only way to filter.
7739
- *
7740
- * A channel whose lines carry the device only in `meta` (or not at all) is
7741
- * declared `false`. Declaring it `true` anyway would be a lie the UI repeats:
7742
- * the operator narrows to one camera, sees nothing, and concludes the code
7743
- * path was never taken.
7744
- */
7745
- perDevice: boolean()
7746
- });
7747
- /**
7748
- * An armed window over one channel, as the document hands it to a mirror.
7749
- *
7750
- * A window is a DEADLINE, never a flag (ADR-0244): a channel somebody forgot
7751
- * expires by itself, which is the one failure a boolean cannot avoid.
7752
- */
7753
- var LogChannelWindowSchema = object({
7754
- channel: string().min(1),
7755
- /** Epoch ms the window closes at. */
7756
- armedUntilMs: number(),
7757
- /** `null` = every camera. A non-empty list narrows to those numeric ids. */
7758
- deviceIds: array(number().int()).readonly().nullable()
7759
- });
7760
- /**
7761
- * The gate a hot path holds.
7762
- *
7763
- * Obtain it ONCE — at module scope or in a constructor — and keep the
7764
- * reference. Looking a channel up by name per line would put a Map lookup on
7765
- * the path this class exists to keep free.
7766
- */
7767
- var LogChannelGate = class {
7768
- descriptor;
7769
- /**
7770
- * HOT PATH GUARD. A plain data FIELD, and it must stay one.
7771
- *
7772
- * `log-channel.spec.ts` asserts the property descriptor has no getter and
7773
- * booby-traps the device set, so turning this into an accessor — or reading
7774
- * anything before it — fails the spec instead of taxing every line the
7775
- * process emits.
7776
- */
7777
- on = false;
7778
- /** `null` while armed for every camera. Never read while `on` is false. */
7779
- devices = null;
7780
- level;
7781
- closesAtMs = 0;
7782
- constructor(descriptor) {
7783
- this.descriptor = descriptor;
7784
- this.level = descriptor.defaultLevel;
7785
- }
7786
- /** Epoch ms this channel disarms itself at. 0 when disarmed. */
7787
- get armedUntilMs() {
7788
- return this.on ? this.closesAtMs : 0;
7789
- }
7790
- /**
7791
- * Does this channel want a line about `deviceId`?
7792
- *
7793
- * Call it only behind `gate.on &&`. On its own it is still correct — the
7794
- * guard is repeated inside — but the point of the prefix is that a disarmed
7795
- * channel must not pay the call at all.
7796
- */
7797
- wants(deviceId) {
7798
- if (!this.on) return false;
7799
- return this.devices === null || this.devices.has(deviceId);
7800
- }
7801
- /**
7802
- * Emit one line on this channel, at the channel's declared level.
7803
- *
7804
- * The channel name is added as `tags.logChannel` so LogQL can select the
7805
- * channel without matching on the message text, and whatever `tags` the
7806
- * caller passed — `deviceId` above all — is preserved.
7807
- */
7808
- log(logger, message, extras) {
7809
- if (!this.on) return;
7810
- const tags = {
7811
- ...extras.tags,
7812
- logChannel: this.descriptor.name
7813
- };
7814
- const line = {
7815
- ...extras,
7816
- tags
7817
- };
7818
- if (this.level === "error") logger.error(message, line);
7819
- else if (this.level === "warn") logger.warn(message, line);
7820
- else logger.info(message, line);
7821
- }
7822
- /**
7823
- * Arm (or RE-arm, restarting) this channel. Off the hot path only.
7824
- *
7825
- * An empty `deviceIds` list is treated as "every camera" rather than "no
7826
- * camera": a window that matches nothing is indistinguishable from a
7827
- * disarmed one, and the operator who asked for it would wait for lines that
7828
- * can never come.
7829
- */
7830
- arm(window) {
7831
- const ids = window.deviceIds;
7832
- this.devices = ids === null || ids.length === 0 ? null : new Set(ids);
7833
- this.closesAtMs = window.armedUntilMs;
7834
- this.on = true;
7835
- }
7836
- /** Disarm. Off the hot path only. */
7837
- disarm() {
7838
- this.on = false;
7839
- this.devices = null;
7840
- this.closesAtMs = 0;
7841
- }
7842
- };
7843
- /**
7844
- * Every channel this PROCESS declares, and the mirror of what is armed on it.
7845
- *
7846
- * One per process. A forked runner has its own, and it is refreshed through
7847
- * the `log-channels` capability by the hub that owns the document — the
7848
- * registry never reaches for a value itself.
7849
- */
7850
- var LogChannelRegistry = class {
7851
- gates = /* @__PURE__ */ new Map();
7852
- /**
7853
- * Declare a channel and get its gate.
7854
- *
7855
- * A duplicate name throws. Two declarations of one name is a programming
7856
- * error, not a merge: the operator would arm one and the other would stay
7857
- * dark, which is the dead-knob shape (D62) with an extra step.
7858
- */
7859
- declare(descriptor) {
7860
- const parsed = LogChannelDescriptorSchema.parse(descriptor);
7861
- if (this.gates.get(parsed.name) !== void 0) throw new Error(`log channel "${parsed.name}" is already declared in this process — two declarations of one name is a programming error, not a merge`);
7862
- const gate = new LogChannelGate(parsed);
7863
- this.gates.set(parsed.name, gate);
7864
- return gate;
7865
- }
7866
- /** The declarations, sorted by name so a list is stable to read and diff. */
7867
- list() {
7868
- return [...this.gates.values()].map((gate) => gate.descriptor).sort((a, b) => a.name.localeCompare(b.name));
7869
- }
7870
- /** The gate for a declared channel, or `undefined`. */
7871
- gate(name) {
7872
- return this.gates.get(name);
7873
- }
7874
- /**
7875
- * Apply the FULL set of armed windows. Off the hot path.
7876
- *
7877
- * Full, not incremental, and that is the whole design: the document is the
7878
- * authority, so a channel the document does not name is disarmed here. An
7879
- * incremental apply would let a disarm get lost in transit and leave a
7880
- * channel running that nobody can see is running.
7881
- *
7882
- * A window already past its deadline is ignored rather than armed — a
7883
- * restore that re-armed an expired window would make a forgotten diagnostic
7884
- * immortal across restarts.
7885
- *
7886
- * Returns the names it could not place, so the caller can log them: a
7887
- * channel named in the document that this process does not declare is
7888
- * either a typo or an addon that has not booted yet, and both deserve a
7889
- * line rather than silence.
7890
- */
7891
- apply(windows, nowMs) {
7892
- const wanted = /* @__PURE__ */ new Map();
7893
- const unknown = [];
7894
- for (const window of windows) {
7895
- if (window.armedUntilMs <= nowMs) continue;
7896
- if (!this.gates.has(window.channel)) {
7897
- unknown.push(window.channel);
7898
- continue;
7899
- }
7900
- wanted.set(window.channel, window);
7901
- }
7902
- for (const [name, gate] of this.gates) {
7903
- const window = wanted.get(name);
7904
- if (window === void 0) gate.disarm();
7905
- else gate.arm(window);
7906
- }
7907
- return unknown;
7908
- }
7909
- /**
7910
- * Disarm whatever has run out. Called on a timer, NEVER from a log path — a
7911
- * diagnostic that adds a `Date.now()` to the path it is measuring measures
7912
- * itself.
7913
- *
7914
- * Returns the names it closed, so the caller can write the one line that
7915
- * says a window ended and stops "it went quiet" from reading as "the branch
7916
- * was not taken".
7917
- */
7918
- tick(nowMs) {
7919
- const closed = [];
7920
- for (const [name, gate] of this.gates) if (gate.on && gate.armedUntilMs <= nowMs) {
7921
- gate.disarm();
7922
- closed.push(name);
7923
- }
7924
- return closed;
7925
- }
7926
- /** The channels armed right now, as the document would describe them. */
7927
- armed() {
7928
- const out = [];
7929
- for (const [name, gate] of this.gates) if (gate.on) out.push({
7930
- channel: name,
7931
- armedUntilMs: gate.armedUntilMs,
7932
- deviceIds: null
7933
- });
7934
- return out;
7935
- }
7936
- };
7937
- /**
7938
- * Process-wide holder for the {@link LogChannelRegistry}.
7939
- *
7940
- * Three call sites that never meet need the SAME instance: the hot paths that
7941
- * declare a gate at module scope, the `log-channels` provider that enumerates
7942
- * the declarations for the hub, and the same provider applying the windows the
7943
- * document hands down. A registry built inside any one of them would be
7944
- * refreshed and collected — the shape of a knob that never does anything.
7945
- *
7946
- * Same idiom as `logging-gate.singleton.ts` and
7947
- * `http-request-census.singleton.ts`.
7948
- */
7949
- var instance = null;
7950
- /** The process-wide log channel registry. Created empty on first use. */
7951
- function getLogChannelRegistry() {
7952
- instance ??= new LogChannelRegistry();
7953
- return instance;
7954
- }
7955
- /**
7956
- * Declare a channel on the process-wide registry and get its gate.
7957
- *
7958
- * The one call an addon makes. Keep the returned gate in a module-scope
7959
- * `const`: looking a channel up by name per line would put a Map lookup on
7960
- * exactly the path this mechanism exists to keep free.
7961
- *
7962
- * `scripts/check-log-channel-gated.ts` reads these call sites. It pairs the
7963
- * declared name with the binding it is assigned to and refuses to let a
7964
- * channel ship that no `<binding>.on` anywhere consults — a declared channel
7965
- * nobody reads is a knob the operator turns with nothing happening, forever,
7966
- * and without a line. That is D62, and this repo has now shipped it three
7967
- * times (`audioThresholdDbfs`, the HA entities with no source, the second
7968
- * per-camera switch that wrote a store nobody read).
7969
- */
7970
- function declareLogChannel(descriptor) {
7971
- return getLogChannelRegistry().declare(descriptor);
7972
- }
7973
- /**
7974
- * Build the `log-channels` provider for this process.
7975
- *
7976
- * `logger` is used ONLY off the hot path — for the arm/expiry lines — so a
7977
- * channel that is never armed costs this module nothing but a timer.
7978
- */
7979
- function createLogChannelsProvider(logger, options = {}) {
7980
- const registry = getLogChannelRegistry();
7981
- const now = options.now ?? Date.now;
7982
- const tickMs = options.tickMs ?? 5e3;
7983
- const timer = setInterval(() => {
7984
- const closed = registry.tick(now());
7985
- for (const name of closed) logger.info("log channel window closed", {
7986
- tags: { logChannel: name },
7987
- meta: { channel: name }
7988
- });
7989
- }, tickMs);
7990
- timer.unref?.();
7991
- return {
7992
- list: () => registry.list(),
7993
- apply: (input) => {
7994
- const unknown = registry.apply(input.windows, now());
7995
- const armed = registry.armed();
7996
- logger.info("log channels applied", { meta: {
7997
- armed: armed.map((window) => window.channel),
7998
- unknown,
7999
- declared: registry.list().length
8000
- } });
8001
- return {
8002
- armed: armed.length,
8003
- unknown
8004
- };
8005
- },
8006
- stop: () => {
8007
- clearInterval(timer);
8008
- }
8009
- };
8010
- }
8011
- /**
8012
7669
  * Ops-log — the durable, append-only operations audit shared by the
8013
7670
  * recordings and events management surfaces.
8014
7671
  *
@@ -8930,6 +8587,21 @@ var StorageCleanupJobSchema = object({
8930
8587
  });
8931
8588
  var StorageCleanupStatusInputSchema = object({ jobId: string().optional() });
8932
8589
  /**
8590
+ * The one typed state of a storage location. Authoritative Zod schema — the TS
8591
+ * alias below is `z.infer<>` of it, never a second spelling.
8592
+ */
8593
+ var StorageLocationModeSchema = _enum([
8594
+ "active",
8595
+ "readonly",
8596
+ "drain",
8597
+ "disabled"
8598
+ ]);
8599
+ _enum([
8600
+ "normal",
8601
+ "never",
8602
+ "drain"
8603
+ ]);
8604
+ /**
8933
8605
  * `StorageLocationType` — an addon-declared id that identifies the *kind* of
8934
8606
  * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
8935
8607
  * so the persisted record schema and the consumer-facing cap can both consume it
@@ -8954,8 +8626,11 @@ var StorageLocationTypeSchema = string().regex(/^[a-z][a-zA-Z0-9-]*$/);
8954
8626
  * `STORAGE_LOCATION_CARDINALITY` map has been removed.
8955
8627
  *
8956
8628
  * `id` is a stable namespaced string of the form `<type>:<slug>`.
8957
- * The default location for a type uses `id === <type>:default` by
8958
- * convention (the bare type ref like `'backups'` resolves to it).
8629
+ * The seed names its first instance `<type>:default` — a NAME, not a flag.
8630
+ * There is no default location any more (D383): `enabled` is the whole write
8631
+ * model, and a bare type ref resolves to the sole location of the type, or —
8632
+ * transitionally, only while legacy NULL-stamped rows exist — to the row whose
8633
+ * slug is `default`.
8959
8634
  *
8960
8635
  * `isSystem` is a legacy persisted flag. Seed still creates the initial
8961
8636
  * `<type>:default` locations; the flag is no longer a lock, a badge, or a
@@ -8976,23 +8651,37 @@ var StorageLocationSchema = object({
8976
8651
  * flag at upsert time, not here (the schema is provider-agnostic).
8977
8652
  */
8978
8653
  nodeId: string().optional(),
8979
- isDefault: boolean().default(false),
8980
8654
  isSystem: boolean().default(false),
8981
8655
  /**
8982
- * Operator opt-in: whether consumers that BALANCE across several locations
8983
- * of a type may write here. Recordings reads it today; event media and
8984
- * backups are the next consumers, which is why the flag lives on the
8985
- * location rather than in any one addon's store nothing has to be
8986
- * extended to add the next consumer.
8656
+ * THE write switch, and the only one (D383). `enabled: true` means every
8657
+ * consumer that chooses a write target for this type may write here, and all
8658
+ * enabled locations of a type are used TOGETHER; `false` means read-only
8659
+ * still read, still played back, still age-swept, still drained, never
8660
+ * written.
8987
8661
  *
8988
- * OPTIONAL, and ABSENT MEANS ACTIVE. Every location persisted before the
8989
- * flag existed reads back with no flag and keeps working exactly as before;
8990
- * that is the whole compat story, and it is why no migration ships with it.
8991
- * A newly CREATED sibling is stamped `false` by the orchestrator (creating a
8992
- * disk must not silently start writing to it); the default of a type is
8993
- * always stamped `true`.
8662
+ * OPTIONAL only for the wire: an upsert that omits it means "leave what is
8663
+ * stored" on an update and "born inert unless it is the first location of its
8664
+ * type" on a create. On a PERSISTED row absence is legacy and it means
8665
+ * enabled {@link isLocationEnabled} is the one place that says so, and the
8666
+ * orchestrator stamps every flagless row `true` once at hydrate so absence
8667
+ * stops existing rather than being re-derived on every read.
8994
8668
  */
8995
8669
  enabled: boolean().optional(),
8670
+ /**
8671
+ * THE state of this location (D385), and the only authority on what may be
8672
+ * written, read or evicted here. Interpreted in exactly one place —
8673
+ * `storage-location-mode.ts` — which also folds the legacy
8674
+ * `enabled` / `config.readOnly` pair into a mode so an old row is never
8675
+ * ambiguous.
8676
+ *
8677
+ * OPTIONAL only for the wire and for rows written before D385: absence is
8678
+ * resolved by `resolveLocationMode`, and the orchestrator stamps every
8679
+ * unstamped row ONCE at hydrate so absence stops existing rather than being
8680
+ * re-derived on every read. `enabled` survives one release as a DERIVED
8681
+ * mirror (`mode === 'active'`); `withLocationMode` is the only writer of
8682
+ * either, so the two cannot disagree.
8683
+ */
8684
+ mode: StorageLocationModeSchema.optional(),
8996
8685
  /** COMPUTED at read time by the orchestrator (statfs of the backing volume
8997
8686
  * for node-local locations it can reach) — never persisted, absent when the
8998
8687
  * volume is remote/unreachable. The single capacity truth every UI reads. */
@@ -9000,13 +8689,50 @@ var StorageLocationSchema = object({
9000
8689
  totalBytes: number(),
9001
8690
  availableBytes: number()
9002
8691
  }).nullable().optional(),
8692
+ /**
8693
+ * How much of that volume CamStack ITSELF holds on this location (D388) —
8694
+ * COMPUTED at read time from the `storage-occupancy` providers' own figures,
8695
+ * never persisted, never a filesystem walk.
8696
+ *
8697
+ * **ABSENT MEANS UNKNOWN, never zero.** No provider has reported for this
8698
+ * location yet — nobody stores here, the owning addon is down, or the first
8699
+ * refresh has not completed. A UI must omit the segment rather than draw it
8700
+ * at zero, which would claim we occupy nothing (D315). It is an OBJECT and
8701
+ * not a bare number precisely so that a `?? 0` on the consuming side has to
8702
+ * be spelled out loud instead of appearing by accident.
8703
+ *
8704
+ * `measuredAtMs` is the OLDEST contributing measurement, so it is honest
8705
+ * about the whole figure rather than about its freshest part.
8706
+ */
8707
+ owned: object({
8708
+ bytes: number().int().nonnegative(),
8709
+ measuredAtMs: number().int().nonnegative()
8710
+ }).optional(),
9003
8711
  createdAt: number(),
9004
8712
  updatedAt: number()
9005
8713
  });
8714
+ object({ isDefault: boolean().optional() });
8715
+ /**
8716
+ * How far a `drain` has got (D386) — the read a UI renders, and nothing more.
8717
+ *
8718
+ * `estimatedEmptyAtMs` is derived from the growth the ratchet has actually
8719
+ * OBSERVED and is `null` when it has observed none. Never a fabricated date: a
8720
+ * drain with no observed growth has no honest ETA, and inventing one is how an
8721
+ * operator learns not to believe the screen.
8722
+ */
8723
+ var StorageDrainProgressSchema = object({
8724
+ locationId: string(),
8725
+ startedAtMs: number(),
8726
+ startBytes: number(),
8727
+ bytesRemaining: number(),
8728
+ drained: boolean(),
8729
+ estimatedEmptyAtMs: number().nullable()
8730
+ });
9006
8731
  /**
9007
8732
  * Reference accepted by consumer-facing `api.storage.*` calls.
9008
8733
  * Either:
9009
- * - a `StorageLocationType` (e.g. `'backups'`) → orchestrator resolves to the default of that type
8734
+ * - a `StorageLocationType` (e.g. `'backups'`) → the sole location of that type
8735
+ * (transitionally, the `<type>:default`-slugged row when several exist)
9010
8736
  * - a fully-qualified id (e.g. `'backups:nas-01'`) → addresses a specific instance
9011
8737
  *
9012
8738
  * The orchestrator's `resolveRef(ref)` handles both cases.
@@ -9358,6 +9084,362 @@ function findTimezone(id) {
9358
9084
  return TIMEZONES.find((tz) => tz.id === id);
9359
9085
  }
9360
9086
  /**
9087
+ * Per-component log CHANNELS — the gate a hot path consults, and the registry
9088
+ * an addon declares its channels in.
9089
+ *
9090
+ * ## Two axes, deliberately separated
9091
+ *
9092
+ * - **DECLARATION** — which channels exist. Only the addon knows:
9093
+ * `stream-broker` knows webrtc/ICE/RTP, `provider-reolink` knows
9094
+ * baichuan/handshake. A hand-wired central list rots at the first addition,
9095
+ * and rots silently. So a channel is declared where it is consulted, and the
9096
+ * `log-channels` capability enumerates the declarations.
9097
+ * - **VALUE** — at which level, for which scope, until when. That stays ONE
9098
+ * thing: the logging settings document on the `system` cap. Two authorities
9099
+ * over the values is the exact defect
9100
+ * `docs/design/plans/2026-08-26-logging-per-componente.md` was written to
9101
+ * remove; re-introducing it from the cure side would be grotesque.
9102
+ *
9103
+ * Nothing in this file reads a clock, an env var or a store. The registry is
9104
+ * a MIRROR: it is moved only by {@link LogChannelRegistry.apply}, called off
9105
+ * the hot path with a value somebody actually read, and by
9106
+ * {@link LogChannelRegistry.tick}, called on a timer. A store read that fails
9107
+ * never reaches here, so it can neither disarm an armed channel nor arm a
9108
+ * disarmed one (D49).
9109
+ *
9110
+ * ## The canonical call shape
9111
+ *
9112
+ * ```ts
9113
+ * if (CH_RTP.on && CH_RTP.wants(deviceId)) {
9114
+ * CH_RTP.log(logger, 'rtp subscriber added', { tags: { deviceId }, meta: { ssrc } })
9115
+ * }
9116
+ * ```
9117
+ *
9118
+ * `on` is a plain boolean FIELD — never a getter — and it is the FIRST thing
9119
+ * read. Disarmed, a call site costs one load and one branch, and the `extras`
9120
+ * object literal is never constructed because it lives inside the branch. It
9121
+ * is the same shape already proven in production at `stream-broker.ts:1650`,
9122
+ * and the same discipline `LoggingGate.allowsDestination` uses for the
9123
+ * destination floor (measured at 1.93 ns/call when off).
9124
+ *
9125
+ * ## Why a channel emits at `info`
9126
+ *
9127
+ * `loki-logging.addon.ts` pins the destination default at `info` and
9128
+ * `loki-destination.ts` drops everything below it, so a line emitted at
9129
+ * `debug` never reaches Loki and the hub's in-memory ring only holds ~35
9130
+ * minutes. A diagnostic that cannot be read an hour later is worse than no
9131
+ * diagnostic, because it looks done. {@link LogChannelGate.log} therefore
9132
+ * emits at the channel's declared level, whose schema floor is `info`.
9133
+ */
9134
+ /**
9135
+ * The level a channel writes at once armed.
9136
+ *
9137
+ * `debug` is absent ON PURPOSE and not by omission: below `info` the line does
9138
+ * not leave the process for Loki, and the whole point of arming a channel is
9139
+ * to read it later.
9140
+ */
9141
+ var LogChannelLevelSchema = _enum([
9142
+ "info",
9143
+ "warn",
9144
+ "error"
9145
+ ]);
9146
+ /**
9147
+ * What an addon declares about one channel. No value, no state — a
9148
+ * declaration is inert.
9149
+ */
9150
+ var LogChannelDescriptorSchema = object({
9151
+ /**
9152
+ * Dotted `area.thing`, unique across the workspace. `area` is conventionally
9153
+ * the addon's short name so an operator reading a channel list can tell who
9154
+ * owns it without a second lookup.
9155
+ */
9156
+ name: string().min(3).regex(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/, "a channel name is dotted lower-kebab, e.g. area.thing"),
9157
+ /** One sentence: what the operator will SEE after arming it. */
9158
+ description: string().min(1),
9159
+ /** The level its lines are emitted at. Never below `info`. */
9160
+ defaultLevel: LogChannelLevelSchema,
9161
+ /**
9162
+ * Whether this channel can be narrowed to a camera.
9163
+ *
9164
+ * `true` is a PROMISE with two halves, and both must hold: the gate is
9165
+ * consulted with the numeric device id, AND every line the channel admits
9166
+ * carries `tags: { deviceId }` with that same numeric id. The second half is
9167
+ * what makes `| json | deviceId="617"` work in Loki — `loki-payload.ts`
9168
+ * keeps `deviceId` out of the stream labels for cardinality, so the tag in
9169
+ * the body is the only way to filter.
9170
+ *
9171
+ * A channel whose lines carry the device only in `meta` (or not at all) is
9172
+ * declared `false`. Declaring it `true` anyway would be a lie the UI repeats:
9173
+ * the operator narrows to one camera, sees nothing, and concludes the code
9174
+ * path was never taken.
9175
+ */
9176
+ perDevice: boolean()
9177
+ });
9178
+ /**
9179
+ * An armed window over one channel, as the document hands it to a mirror.
9180
+ *
9181
+ * A window is a DEADLINE, never a flag (ADR-0244): a channel somebody forgot
9182
+ * expires by itself, which is the one failure a boolean cannot avoid.
9183
+ */
9184
+ var LogChannelWindowSchema = object({
9185
+ channel: string().min(1),
9186
+ /** Epoch ms the window closes at. */
9187
+ armedUntilMs: number(),
9188
+ /** `null` = every camera. A non-empty list narrows to those numeric ids. */
9189
+ deviceIds: array(number().int()).readonly().nullable()
9190
+ });
9191
+ /**
9192
+ * The gate a hot path holds.
9193
+ *
9194
+ * Obtain it ONCE — at module scope or in a constructor — and keep the
9195
+ * reference. Looking a channel up by name per line would put a Map lookup on
9196
+ * the path this class exists to keep free.
9197
+ */
9198
+ var LogChannelGate = class {
9199
+ descriptor;
9200
+ /**
9201
+ * HOT PATH GUARD. A plain data FIELD, and it must stay one.
9202
+ *
9203
+ * `log-channel.spec.ts` asserts the property descriptor has no getter and
9204
+ * booby-traps the device set, so turning this into an accessor — or reading
9205
+ * anything before it — fails the spec instead of taxing every line the
9206
+ * process emits.
9207
+ */
9208
+ on = false;
9209
+ /** `null` while armed for every camera. Never read while `on` is false. */
9210
+ devices = null;
9211
+ level;
9212
+ closesAtMs = 0;
9213
+ constructor(descriptor) {
9214
+ this.descriptor = descriptor;
9215
+ this.level = descriptor.defaultLevel;
9216
+ }
9217
+ /** Epoch ms this channel disarms itself at. 0 when disarmed. */
9218
+ get armedUntilMs() {
9219
+ return this.on ? this.closesAtMs : 0;
9220
+ }
9221
+ /**
9222
+ * Does this channel want a line about `deviceId`?
9223
+ *
9224
+ * Call it only behind `gate.on &&`. On its own it is still correct — the
9225
+ * guard is repeated inside — but the point of the prefix is that a disarmed
9226
+ * channel must not pay the call at all.
9227
+ */
9228
+ wants(deviceId) {
9229
+ if (!this.on) return false;
9230
+ return this.devices === null || this.devices.has(deviceId);
9231
+ }
9232
+ /**
9233
+ * Emit one line on this channel, at the channel's declared level.
9234
+ *
9235
+ * The channel name is added as `tags.logChannel` so LogQL can select the
9236
+ * channel without matching on the message text, and whatever `tags` the
9237
+ * caller passed — `deviceId` above all — is preserved.
9238
+ */
9239
+ log(logger, message, extras) {
9240
+ if (!this.on) return;
9241
+ const tags = {
9242
+ ...extras.tags,
9243
+ logChannel: this.descriptor.name
9244
+ };
9245
+ const line = {
9246
+ ...extras,
9247
+ tags
9248
+ };
9249
+ if (this.level === "error") logger.error(message, line);
9250
+ else if (this.level === "warn") logger.warn(message, line);
9251
+ else logger.info(message, line);
9252
+ }
9253
+ /**
9254
+ * Arm (or RE-arm, restarting) this channel. Off the hot path only.
9255
+ *
9256
+ * An empty `deviceIds` list is treated as "every camera" rather than "no
9257
+ * camera": a window that matches nothing is indistinguishable from a
9258
+ * disarmed one, and the operator who asked for it would wait for lines that
9259
+ * can never come.
9260
+ */
9261
+ arm(window) {
9262
+ const ids = window.deviceIds;
9263
+ this.devices = ids === null || ids.length === 0 ? null : new Set(ids);
9264
+ this.closesAtMs = window.armedUntilMs;
9265
+ this.on = true;
9266
+ }
9267
+ /** Disarm. Off the hot path only. */
9268
+ disarm() {
9269
+ this.on = false;
9270
+ this.devices = null;
9271
+ this.closesAtMs = 0;
9272
+ }
9273
+ };
9274
+ /**
9275
+ * Every channel this PROCESS declares, and the mirror of what is armed on it.
9276
+ *
9277
+ * One per process. A forked runner has its own, and it is refreshed through
9278
+ * the `log-channels` capability by the hub that owns the document — the
9279
+ * registry never reaches for a value itself.
9280
+ */
9281
+ var LogChannelRegistry = class {
9282
+ gates = /* @__PURE__ */ new Map();
9283
+ /**
9284
+ * Declare a channel and get its gate.
9285
+ *
9286
+ * A duplicate name throws. Two declarations of one name is a programming
9287
+ * error, not a merge: the operator would arm one and the other would stay
9288
+ * dark, which is the dead-knob shape (D62) with an extra step.
9289
+ */
9290
+ declare(descriptor) {
9291
+ const parsed = LogChannelDescriptorSchema.parse(descriptor);
9292
+ if (this.gates.get(parsed.name) !== void 0) throw new Error(`log channel "${parsed.name}" is already declared in this process — two declarations of one name is a programming error, not a merge`);
9293
+ const gate = new LogChannelGate(parsed);
9294
+ this.gates.set(parsed.name, gate);
9295
+ return gate;
9296
+ }
9297
+ /** The declarations, sorted by name so a list is stable to read and diff. */
9298
+ list() {
9299
+ return [...this.gates.values()].map((gate) => gate.descriptor).sort((a, b) => a.name.localeCompare(b.name));
9300
+ }
9301
+ /** The gate for a declared channel, or `undefined`. */
9302
+ gate(name) {
9303
+ return this.gates.get(name);
9304
+ }
9305
+ /**
9306
+ * Apply the FULL set of armed windows. Off the hot path.
9307
+ *
9308
+ * Full, not incremental, and that is the whole design: the document is the
9309
+ * authority, so a channel the document does not name is disarmed here. An
9310
+ * incremental apply would let a disarm get lost in transit and leave a
9311
+ * channel running that nobody can see is running.
9312
+ *
9313
+ * A window already past its deadline is ignored rather than armed — a
9314
+ * restore that re-armed an expired window would make a forgotten diagnostic
9315
+ * immortal across restarts.
9316
+ *
9317
+ * Returns the names it could not place, so the caller can log them: a
9318
+ * channel named in the document that this process does not declare is
9319
+ * either a typo or an addon that has not booted yet, and both deserve a
9320
+ * line rather than silence.
9321
+ */
9322
+ apply(windows, nowMs) {
9323
+ const wanted = /* @__PURE__ */ new Map();
9324
+ const unknown = [];
9325
+ for (const window of windows) {
9326
+ if (window.armedUntilMs <= nowMs) continue;
9327
+ if (!this.gates.has(window.channel)) {
9328
+ unknown.push(window.channel);
9329
+ continue;
9330
+ }
9331
+ wanted.set(window.channel, window);
9332
+ }
9333
+ for (const [name, gate] of this.gates) {
9334
+ const window = wanted.get(name);
9335
+ if (window === void 0) gate.disarm();
9336
+ else gate.arm(window);
9337
+ }
9338
+ return unknown;
9339
+ }
9340
+ /**
9341
+ * Disarm whatever has run out. Called on a timer, NEVER from a log path — a
9342
+ * diagnostic that adds a `Date.now()` to the path it is measuring measures
9343
+ * itself.
9344
+ *
9345
+ * Returns the names it closed, so the caller can write the one line that
9346
+ * says a window ended and stops "it went quiet" from reading as "the branch
9347
+ * was not taken".
9348
+ */
9349
+ tick(nowMs) {
9350
+ const closed = [];
9351
+ for (const [name, gate] of this.gates) if (gate.on && gate.armedUntilMs <= nowMs) {
9352
+ gate.disarm();
9353
+ closed.push(name);
9354
+ }
9355
+ return closed;
9356
+ }
9357
+ /** The channels armed right now, as the document would describe them. */
9358
+ armed() {
9359
+ const out = [];
9360
+ for (const [name, gate] of this.gates) if (gate.on) out.push({
9361
+ channel: name,
9362
+ armedUntilMs: gate.armedUntilMs,
9363
+ deviceIds: null
9364
+ });
9365
+ return out;
9366
+ }
9367
+ };
9368
+ /**
9369
+ * Process-wide holder for the {@link LogChannelRegistry}.
9370
+ *
9371
+ * Three call sites that never meet need the SAME instance: the hot paths that
9372
+ * declare a gate at module scope, the `log-channels` provider that enumerates
9373
+ * the declarations for the hub, and the same provider applying the windows the
9374
+ * document hands down. A registry built inside any one of them would be
9375
+ * refreshed and collected — the shape of a knob that never does anything.
9376
+ *
9377
+ * Same idiom as `logging-gate.singleton.ts` and
9378
+ * `http-request-census.singleton.ts`.
9379
+ */
9380
+ var instance = null;
9381
+ /** The process-wide log channel registry. Created empty on first use. */
9382
+ function getLogChannelRegistry() {
9383
+ instance ??= new LogChannelRegistry();
9384
+ return instance;
9385
+ }
9386
+ /**
9387
+ * Declare a channel on the process-wide registry and get its gate.
9388
+ *
9389
+ * The one call an addon makes. Keep the returned gate in a module-scope
9390
+ * `const`: looking a channel up by name per line would put a Map lookup on
9391
+ * exactly the path this mechanism exists to keep free.
9392
+ *
9393
+ * `scripts/check-log-channel-gated.ts` reads these call sites. It pairs the
9394
+ * declared name with the binding it is assigned to and refuses to let a
9395
+ * channel ship that no `<binding>.on` anywhere consults — a declared channel
9396
+ * nobody reads is a knob the operator turns with nothing happening, forever,
9397
+ * and without a line. That is D62, and this repo has now shipped it three
9398
+ * times (`audioThresholdDbfs`, the HA entities with no source, the second
9399
+ * per-camera switch that wrote a store nobody read).
9400
+ */
9401
+ function declareLogChannel(descriptor) {
9402
+ return getLogChannelRegistry().declare(descriptor);
9403
+ }
9404
+ /**
9405
+ * Build the `log-channels` provider for this process.
9406
+ *
9407
+ * `logger` is used ONLY off the hot path — for the arm/expiry lines — so a
9408
+ * channel that is never armed costs this module nothing but a timer.
9409
+ */
9410
+ function createLogChannelsProvider(logger, options = {}) {
9411
+ const registry = getLogChannelRegistry();
9412
+ const now = options.now ?? Date.now;
9413
+ const tickMs = options.tickMs ?? 5e3;
9414
+ const timer = setInterval(() => {
9415
+ const closed = registry.tick(now());
9416
+ for (const name of closed) logger.info("log channel window closed", {
9417
+ tags: { logChannel: name },
9418
+ meta: { channel: name }
9419
+ });
9420
+ }, tickMs);
9421
+ timer.unref?.();
9422
+ return {
9423
+ list: () => registry.list(),
9424
+ apply: (input) => {
9425
+ const unknown = registry.apply(input.windows, now());
9426
+ const armed = registry.armed();
9427
+ logger.info("log channels applied", { meta: {
9428
+ armed: armed.map((window) => window.channel),
9429
+ unknown,
9430
+ declared: registry.list().length
9431
+ } });
9432
+ return {
9433
+ armed: armed.length,
9434
+ unknown
9435
+ };
9436
+ },
9437
+ stop: () => {
9438
+ clearInterval(timer);
9439
+ }
9440
+ };
9441
+ }
9442
+ /**
9361
9443
  * Distinct (device, family, variant) counters one instance will hold.
9362
9444
  *
9363
9445
  * A large fleet x the handful of families any single addon reports, with
@@ -22673,7 +22755,7 @@ method(object({
22673
22755
  downloadId: string(),
22674
22756
  offset: number(),
22675
22757
  length: number()
22676
- }), _instanceof(Uint8Array)), method(object({ downloadId: string() }), _void(), { kind: "mutation" }), method(object({ type: StorageLocationTypeSchema.optional() }), array(StorageLocationSchema).readonly()), method(object({ type: StorageLocationTypeSchema }), StorageLocationSchema.nullable()), method(_void(), array(StorageLocationDeclarationSchema).readonly()), method(StorageLocationSchema.omit({
22758
+ }), _instanceof(Uint8Array)), method(object({ downloadId: string() }), _void(), { kind: "mutation" }), method(object({ type: StorageLocationTypeSchema.optional() }), array(StorageLocationSchema).readonly()), method(_void(), array(StorageLocationDeclarationSchema).readonly()), method(StorageLocationSchema.omit({
22677
22759
  createdAt: true,
22678
22760
  updatedAt: true
22679
22761
  }), StorageLocationSchema, {
@@ -22685,7 +22767,7 @@ method(object({
22685
22767
  }), _void(), {
22686
22768
  kind: "mutation",
22687
22769
  auth: "admin"
22688
- }), method(object({ id: string() }), object({
22770
+ }), method(_void(), array(StorageDrainProgressSchema).readonly()), method(object({ id: string() }), object({
22689
22771
  ok: boolean(),
22690
22772
  error: string().optional()
22691
22773
  }), { auth: "admin" }), method(_void(), array(ProviderListEntrySchema).readonly()), method(object({
@@ -22755,6 +22837,51 @@ method(StorageMigrationInputSchema, StorageMigrationPlanSchema, { auth: "admin"
22755
22837
  kind: "mutation",
22756
22838
  auth: "admin"
22757
22839
  }), method(object({}), array(StorageMigrationJobSchema).readonly(), { auth: "admin" });
22840
+ /**
22841
+ * `storage-occupancy` — how many bytes an addon actually HOLDS on a storage
22842
+ * location (D388).
22843
+ *
22844
+ * ## Why this is not `storage-evictable`
22845
+ *
22846
+ * `storage-evictable.getEvictableUsage` looks like the same question and is
22847
+ * not, in two ways that both matter and both bite hardest on the locations an
22848
+ * operator most wants a figure for:
22849
+ *
22850
+ * - it reports the whole eviction DOMAIN, not the location. `recordings:default`
22851
+ * and `recordingsLow:default` deliberately share one root and evict as one
22852
+ * oldest-first pool, so both answer with the SAME combined total. As an
22853
+ * occupancy figure that double-counts the disk.
22854
+ * - it reports ZERO for a location whose eviction policy is `never` (D385) —
22855
+ * a `readonly` or `disabled` disk. Those are exactly the disks an operator
22856
+ * is retiring and staring at.
22857
+ *
22858
+ * So this is its own contract with its own quantity, and the quantity is
22859
+ * OCCUPIED: every byte the addon holds on that location, whether or not it
22860
+ * would ever be willing to delete it. A provider that can only answer
22861
+ * "evictable" must not register here — a number that silently means different
22862
+ * things per class is worse than no number.
22863
+ *
22864
+ * ## Absence is an answer
22865
+ *
22866
+ * A location nobody reports for is UNKNOWN, never zero (D315). The orchestrator
22867
+ * stamps `StorageLocation.owned` only for locations it has a report for, and
22868
+ * the field is an OBJECT rather than a bare number so that a `?? 0` on the
22869
+ * consuming side has to be written out loud instead of appearing by accident.
22870
+ *
22871
+ * `internal: true` — consumed by the orchestrator's `listLocations` stamp, never
22872
+ * a public client surface. Clients read the stamped `StorageLocation.owned`.
22873
+ */
22874
+ /** One provider's occupancy answer for one location. */
22875
+ var StorageOccupancyReportSchema = object({
22876
+ locationId: string(),
22877
+ /** Bytes this provider holds on THAT location — not its eviction domain, and
22878
+ * not net of what it is willing to delete. */
22879
+ ownedBytes: number().int().nonnegative(),
22880
+ /** When the provider last actually measured this. The orchestrator carries it
22881
+ * through so a UI can say how old the figure is instead of implying "now". */
22882
+ measuredAtMs: number().int().nonnegative()
22883
+ });
22884
+ method(object({ locationIds: array(string()).readonly() }), array(StorageOccupancyReportSchema).readonly(), { auth: "admin" });
22758
22885
  var ProviderInfoSchema = discriminatedUnion("shouldSaveDiskSpace", [object({
22759
22886
  providerId: string().min(1),
22760
22887
  displayName: string().min(1),
@@ -24590,108 +24717,6 @@ onStatusChanged: { data: object({
24590
24717
  volatileStateFields: ["lastUpdated"]
24591
24718
  };
24592
24719
  /**
24593
- * Network-link snapshot. Same shape for every provider (a Reolink wifi
24594
- * camera, a Home Assistant device with a signal-strength sensor, a Tapo
24595
- * plug): one slice under `device.runtimeState['network-link']`, one badge,
24596
- * one Home Assistant projection.
24597
- */
24598
- var NetworkLinkStatusSchema = object({
24599
- /** The link the device is on. `'unknown'` = not read yet, not "no link". */
24600
- type: _enum([
24601
- "wifi",
24602
- "ethernet",
24603
- "cellular",
24604
- "unknown"
24605
- ]),
24606
- /**
24607
- * Link quality, 0..100 inclusive, normalised by the provider from whatever
24608
- * the firmware reports (bars, RSSI, a vendor scale). **`null` means NOT
24609
- * KNOWN or NOT APPLICABLE** — a wired link has no signal, and a wireless
24610
- * one whose reading has not landed must not be drawn at 0 %. Consumers
24611
- * SKIP a null rather than coerce it.
24612
- */
24613
- signalPercent: number().min(0).max(100).nullable(),
24614
- /** Raw received signal strength in dBm, when the firmware reports one. */
24615
- rssiDbm: number().optional(),
24616
- /** Network name of a wireless link, when the firmware reports it. */
24617
- ssid: string().optional(),
24618
- /** Ms epoch of the last observation. Lets consumers reason about freshness. */
24619
- lastUpdated: number()
24620
- });
24621
- /** The slice a provider seeds before its first read: nothing is known yet. */
24622
- var NETWORK_LINK_UNKNOWN = {
24623
- type: "unknown",
24624
- signalPercent: null,
24625
- lastUpdated: 0
24626
- };
24627
- /**
24628
- * Normalise a signal the firmware reports as BARS (0..`maxBars`) to 0..100.
24629
- * Out-of-range or non-finite input is not a reading: `null`.
24630
- */
24631
- function signalPercentFromBars(bars, maxBars) {
24632
- if (bars === void 0 || !Number.isFinite(bars) || maxBars <= 0) return null;
24633
- if (bars < 0 || bars > maxBars) return null;
24634
- return Math.round(bars / maxBars * 100);
24635
- }
24636
- /**
24637
- * Normalise an RSSI in dBm to 0..100 on the usual wifi scale: -100 dBm and
24638
- * below is 0 %, -50 dBm and above is 100 %, linear between. Non-finite or
24639
- * positive input is not an RSSI: `null`.
24640
- */
24641
- function signalPercentFromRssi(rssiDbm) {
24642
- if (rssiDbm === void 0 || !Number.isFinite(rssiDbm) || rssiDbm > 0) return null;
24643
- return Math.round((Math.min(-50, Math.max(-100, rssiDbm)) + 100) * 2);
24644
- }
24645
- var networkLinkCapability = {
24646
- name: "network-link",
24647
- scope: "device",
24648
- deviceNative: true,
24649
- mode: "singleton",
24650
- deviceTypes: [
24651
- DeviceType.Camera,
24652
- DeviceType.Sensor,
24653
- DeviceType.Button,
24654
- DeviceType.Switch,
24655
- DeviceType.Light,
24656
- DeviceType.Lock,
24657
- DeviceType.Siren
24658
- ],
24659
- methods: {},
24660
- events: {
24661
- /**
24662
- * Emitted whenever the cached status changes (a link switch, a signal
24663
- * reading that moved). Mirrored on the parent chain by the
24664
- * DeviceEventPropagator like `battery.onStatusChanged`.
24665
- */
24666
- onStatusChanged: { data: object({
24667
- deviceId: number(),
24668
- status: NetworkLinkStatusSchema
24669
- }) } },
24670
- status: {
24671
- schema: NetworkLinkStatusSchema,
24672
- kind: "push",
24673
- empty: NETWORK_LINK_UNKNOWN
24674
- },
24675
- /**
24676
- * Runtime-state slice — every provider stores the same shape under
24677
- * `device.runtimeState['network-link']`, read once by the badge and the
24678
- * Home Assistant projector regardless of the driver.
24679
- */
24680
- runtimeState: NetworkLinkStatusSchema,
24681
- /**
24682
- * Runtime-state durability: **restored** — a link reading is slow to
24683
- * change and a sleeping battery camera may not report for hours; the
24684
- * restored slice is what the badge shows until the next read.
24685
- *
24686
- * See `RuntimeStateDurability`. Enforced by
24687
- * `scripts/check-runtime-state-durability.ts`.
24688
- */
24689
- durability: "restored",
24690
- /** Clock fields: written, but excluded from the compare that decides
24691
- * whether persisting is worth a SQLite commit. */
24692
- volatileStateFields: ["lastUpdated"]
24693
- };
24694
- /**
24695
24720
  * Generic boolean sensor — last-resort fallback when no domain-
24696
24721
  * specific binary cap fits (Home Assistant `binary_sensor` without a
24697
24722
  * known `device_class`, or a domain we haven't typed yet). Pure
@@ -28221,6 +28246,389 @@ var nativeObjectDetectionCapability = {
28221
28246
  volatileStateFields: ["lastFetchedAt"]
28222
28247
  };
28223
28248
  /**
28249
+ * `navigation` — a device-scoped capability that natively expresses the FULL
28250
+ * navigation / action surface of a robot that DRIVES ITSELF and carries an
28251
+ * on-board camera (the Dreame robot-vacuum camera is the first provider).
28252
+ *
28253
+ * Why a NEW cap rather than overloading `ptz`:
28254
+ * - `ptz` moves a *gimbal* on a fixed camera (pan/tilt/zoom of the lens). A
28255
+ * robot vacuum has no gimbal — the whole chassis drives, turns and spins.
28256
+ * The two are different physical models: PTZ is absolute-position + presets,
28257
+ * navigation is momentary drive nudges + discrete robot ACTIONS
28258
+ * (dock / spot-clean / follow-pet / go-to-point / …).
28259
+ * - This cap is the SOURCE OF TRUTH. Two consumers adapt from it rather than
28260
+ * the reverse:
28261
+ * 1. a native CamStack navigation panel (data-driven from `listActions`
28262
+ * / `getOptions`), and
28263
+ * 2. the PTZ surface — a thin adapter mimics `ptz` from `navigation` so a
28264
+ * robot camera shows up in the existing PTZ control path without every
28265
+ * PTZ provider learning about robots. The mapping lives in the adapter,
28266
+ * not here (see the addon design note):
28267
+ * ptz.continuousMove({pan,tilt}) → navigation.move({pan,tilt})
28268
+ * ptz.stop() → navigation.stop()
28269
+ * ptz.goHome() → navigation.runAction('goHome')
28270
+ * ptz.getPresets() → navigation.listActions() (id→preset)
28271
+ * ptz.goToPreset(id) → navigation.runAction(id)
28272
+ *
28273
+ * ## Continuous drive
28274
+ *
28275
+ * `move` is MOMENTARY. Fluid navigation comes from the UI (or the PTZ adapter)
28276
+ * sending `move({pan,tilt})` REPEATEDLY at ~1 Hz while a direction is held, and
28277
+ * one `stop()` on release — exactly like the robot app's remote-drive joystick.
28278
+ * The provider forwards EACH `move` to one drive write; it must NOT debounce or
28279
+ * coalesce them. The UI owns the cadence.
28280
+ *
28281
+ * ## The action dictionary
28282
+ *
28283
+ * The discrete controls (dock / locate / spot-clean / follow / flash / sounds)
28284
+ * are a DATA-DRIVEN dictionary the cap exposes via `listActions()`. Each entry
28285
+ * carries `{ id, kind, label, icon }` (plus `soundId` for sound entries) so the
28286
+ * native panel AND the PTZ mimic render buttons WITHOUT hardcoding a
28287
+ * vendor-specific list. `kind: 'action'` entries are triggered with
28288
+ * `runAction({ actionId })`; `kind: 'sound'` entries with `playSound({ soundId })`
28289
+ * (the entry carries the `soundId` to pass). The general primitives — `move`,
28290
+ * `stop`, `goToPoint` — stay as first-class methods, not dictionary entries.
28291
+ *
28292
+ * NOTE (provider wiring): the first provider (Dreame) drives this with the RAW
28293
+ * `callAction(siid,aiid,in)` / `setProperty({siid,piid,value})` MIoT primitives
28294
+ * that the currently-published `@apocaliss92/nodedreame` already exposes on
28295
+ * every device handle. A future nodedreame publish adds a typed
28296
+ * `DreameCameraController` (drive / playPetSound / spotClean / findPet / …); the
28297
+ * provider can then swap the raw calls for the typed methods with no change to
28298
+ * THIS contract.
28299
+ */
28300
+ /**
28301
+ * A momentary drive nudge. The robot MOVES (no gimbal) for as long as the caller
28302
+ * keeps sending nudges (~1 Hz); an explicit `stop` (or letting the nudges lapse)
28303
+ * halts it.
28304
+ *
28305
+ * - `pan` — turn: negative = left, positive = right, 0 = straight.
28306
+ * - `tilt` — throttle: positive = forward, negative = spin / turn-around.
28307
+ * - `speed` — optional intensity hint [0, 1]; the provider may scale the drive
28308
+ * vector by it (drivers without proportional drive ignore it).
28309
+ *
28310
+ * `pan` / `tilt` are normalized [-1, 1]. Both optional so a caller can nudge one
28311
+ * axis alone; an all-undefined nudge is a no-op.
28312
+ */
28313
+ var NavigationMoveCommandSchema = object({
28314
+ pan: number().min(-1).max(1).optional(),
28315
+ tilt: number().min(-1).max(1).optional(),
28316
+ speed: number().min(0).max(1).optional()
28317
+ });
28318
+ /**
28319
+ * The enumerated discrete actions a navigation-capable robot can perform via
28320
+ * `runAction`. This is the CLOSED vocabulary; a given device advertises the
28321
+ * subset it supports through `listActions`. Sounds are NOT here — they go through
28322
+ * `playSound` (see the `sound` dictionary entries).
28323
+ */
28324
+ var NavigationActionIdSchema = _enum([
28325
+ "goHome",
28326
+ "locate",
28327
+ "spotClean",
28328
+ "findPet",
28329
+ "personFollow",
28330
+ "stop",
28331
+ "startClean",
28332
+ "pauseClean",
28333
+ "dockWash",
28334
+ "autoEmpty",
28335
+ "flashOn",
28336
+ "flashOff"
28337
+ ]);
28338
+ /** Whether a dictionary entry is a `runAction` action or a `playSound` sound. */
28339
+ var NavigationEntryKindSchema = _enum(["action", "sound"]);
28340
+ /**
28341
+ * One entry in the navigation action dictionary — the DATA-DRIVEN unit both the
28342
+ * native panel and the PTZ mimic render as a button.
28343
+ *
28344
+ * - `id` — stable id. For `kind:'action'` it is a {@link NavigationActionId}
28345
+ * (pass to `runAction`); for `kind:'sound'` it is a namespaced id
28346
+ * (`sound:meow`) whose `soundId` is passed to `playSound`.
28347
+ * - `icon` — icon HINT (lucide-style name; the UI maps it to its own set).
28348
+ * - `label` — operator-facing English label.
28349
+ * - `soundId` — wire sound id, present only on `kind:'sound'` entries.
28350
+ * - `enabled` — per-device FEATURE FLAG. `listActions` reports it so the UI /
28351
+ * PTZ render ONLY enabled entries. Data-driven: the provider
28352
+ * flips it from config, never by editing code.
28353
+ */
28354
+ var NavigationActionEntrySchema = object({
28355
+ id: string(),
28356
+ kind: NavigationEntryKindSchema,
28357
+ label: string(),
28358
+ icon: string(),
28359
+ /** Present only on `kind:'sound'` entries — the id to pass to `playSound`. */
28360
+ soundId: number().int().optional(),
28361
+ /** Per-device feature flag — render this entry only when true. */
28362
+ enabled: boolean()
28363
+ });
28364
+ /** Coordinates for `goToPoint` — a point on the robot's live map. */
28365
+ var NavigationPointSchema = object({
28366
+ x: number(),
28367
+ y: number()
28368
+ });
28369
+ /**
28370
+ * Per-device FEATURE-FLAG report for the general (non-dictionary) primitives.
28371
+ * The cap reports which are enabled so the UI / PTZ render only the controls
28372
+ * that are turned on for THIS device. Data-driven: the provider derives these
28373
+ * from config + probe, never hardcoded in the UI. The per-DICTIONARY-entry flags
28374
+ * live on {@link NavigationActionEntrySchema.enabled}; these gate the primitives
28375
+ * that are not dictionary entries.
28376
+ *
28377
+ * - `move` / `stop` — the momentary drive joystick.
28378
+ * - `goToPoint` — send-to-map-coordinate. Ships OFF on Dreame until the
28379
+ * map-coordinate plumbing is wired.
28380
+ * - `runAction` — the discrete action buttons (dictionary `kind:'action'`).
28381
+ * - `playSound` — the sound buttons (dictionary `kind:'sound'`).
28382
+ * - `light` — the on/off fill-light toggle (works anytime).
28383
+ * - `lightMode` — the auto/manual selector + manual level slider (a
28384
+ * camera-service control; needs an active stream).
28385
+ */
28386
+ var NavigationFeaturesSchema = object({
28387
+ move: boolean(),
28388
+ stop: boolean(),
28389
+ goToPoint: boolean(),
28390
+ runAction: boolean(),
28391
+ playSound: boolean(),
28392
+ light: boolean(),
28393
+ lightMode: boolean()
28394
+ });
28395
+ /** Light mode: `auto` lets the camera choose brightness; `manual` uses `level`. */
28396
+ var NavigationLightModeSchema = _enum(["auto", "manual"]);
28397
+ /**
28398
+ * Live navigation state so the UI can reflect what the robot is doing:
28399
+ * - `mode` — coarse activity (idle / cleaning / following / …).
28400
+ * - `following` — person/pet follow is currently armed.
28401
+ * - `flash` — the on-camera fill light is on.
28402
+ * - `lightMode` — auto vs manual fill-light mode.
28403
+ * - `lightLevel` — manual fill-light level (40..100); meaningful when
28404
+ * `lightMode === 'manual'`.
28405
+ */
28406
+ var NavigationStatusSchema = object({
28407
+ mode: _enum([
28408
+ "idle",
28409
+ "cleaning",
28410
+ "spot",
28411
+ "following",
28412
+ "goto",
28413
+ "returning",
28414
+ "paused",
28415
+ "unknown"
28416
+ ]),
28417
+ following: boolean(),
28418
+ flash: boolean(),
28419
+ lightMode: NavigationLightModeSchema,
28420
+ lightLevel: number().min(40).max(100),
28421
+ /** Ms epoch when the slice was last updated. */
28422
+ lastChangedAt: number()
28423
+ });
28424
+ /**
28425
+ * Runtime-state slice owned by this cap (kernel-managed: validated, mirrored,
28426
+ * observable). Adds `lastFetchedAt` on top of the status shape per the
28427
+ * convention.
28428
+ */
28429
+ var NavigationRuntimeStateSchema = NavigationStatusSchema.extend({ lastFetchedAt: number() });
28430
+ var navigationCapability = {
28431
+ name: "navigation",
28432
+ scope: "device",
28433
+ deviceNative: true,
28434
+ mode: "singleton",
28435
+ deviceTypes: [DeviceType.Camera],
28436
+ deviceConfig: { ui: {
28437
+ kind: "widget",
28438
+ widgetId: "host/navigation-panel",
28439
+ tab: "navigation",
28440
+ topTab: true,
28441
+ label: "Navigation",
28442
+ order: 0
28443
+ } },
28444
+ methods: {
28445
+ /**
28446
+ * Momentary drive nudge (the robot moves). `protected` — mirrors
28447
+ * `ptz.continuousMove` so the Viewer navigation panel (and the PTZ-mimic
28448
+ * path) works for any authenticated user, not admin-only. The UI sends
28449
+ * these at ~1 Hz while a control is held; the provider forwards each one to
28450
+ * a single drive write WITHOUT debouncing.
28451
+ */
28452
+ move: method(NavigationMoveCommandSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
28453
+ /** Halt all motion immediately (zero drive vector). */
28454
+ stop: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
28455
+ /** Send the robot to a point on its live map. */
28456
+ goToPoint: method(NavigationPointSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
28457
+ /**
28458
+ * Enumerate the discrete controls THIS device supports (data-driven UI +
28459
+ * PTZ mimic). Camera-probed subset of {@link NAVIGATION_ACTION_CATALOG}.
28460
+ */
28461
+ listActions: method(object({ deviceId: number() }), array(NavigationActionEntrySchema)),
28462
+ /**
28463
+ * Run one discrete action (a `kind:'action'` dictionary entry). Invalid /
28464
+ * unsupported action ids are rejected by the provider.
28465
+ */
28466
+ runAction: method(object({
28467
+ deviceId: number(),
28468
+ actionId: NavigationActionIdSchema
28469
+ }), _void(), { kind: "mutation" }),
28470
+ /** Play a sound by its wire id (the `soundId` of a `kind:'sound'` entry). */
28471
+ playSound: method(object({
28472
+ deviceId: number(),
28473
+ soundId: number().int()
28474
+ }), _void(), { kind: "mutation" }),
28475
+ /**
28476
+ * Turn the on-camera fill light on / off (the `OpenFullLight` control —
28477
+ * works anytime, no active stream required).
28478
+ */
28479
+ setLightOn: method(object({
28480
+ deviceId: number(),
28481
+ on: boolean()
28482
+ }), _void(), { kind: "mutation" }),
28483
+ /**
28484
+ * Set the fill-light mode (auto vs manual). `manual` optionally carries the
28485
+ * initial `level`. The auto/manual + level control is a CAMERA-service
28486
+ * action that generally needs an active camera stream/monitor session — the
28487
+ * UI shows the manual level slider ONLY when `mode === 'manual'`.
28488
+ */
28489
+ setLightMode: method(object({
28490
+ deviceId: number(),
28491
+ mode: NavigationLightModeSchema,
28492
+ level: number().min(40).max(100).optional()
28493
+ }), _void(), { kind: "mutation" }),
28494
+ /** Set the MANUAL fill-light level (40..100). Implies `manual` mode. */
28495
+ setLightLevel: method(object({
28496
+ deviceId: number(),
28497
+ level: number().min(40).max(100)
28498
+ }), _void(), { kind: "mutation" }),
28499
+ /**
28500
+ * Per-device FEATURE-FLAG report for the general primitives — drives which
28501
+ * controls the UI shows (the per-entry flags for the dictionary come back on
28502
+ * `listActions`).
28503
+ */
28504
+ getFeatures: method(object({ deviceId: number() }), NavigationFeaturesSchema)
28505
+ },
28506
+ events: { onStatusChanged: { data: object({
28507
+ deviceId: number(),
28508
+ status: NavigationStatusSchema
28509
+ }) } },
28510
+ status: {
28511
+ schema: NavigationStatusSchema,
28512
+ kind: "push"
28513
+ },
28514
+ /**
28515
+ * Runtime-state slice mirrored by the kernel. The navigation panel watches it
28516
+ * for live mode / follow / flash changes.
28517
+ */
28518
+ runtimeState: NavigationRuntimeStateSchema,
28519
+ /**
28520
+ * Runtime-state durability: **session** — like `vacuum-control`, a restored
28521
+ * `mode: cleaning` / `following: true` is a robot that is not actually doing
28522
+ * that. The live handle re-publishes on connect.
28523
+ *
28524
+ * See `RuntimeStateDurability`. Enforced by
28525
+ * `scripts/check-runtime-state-durability.ts`.
28526
+ */
28527
+ durability: "session"
28528
+ };
28529
+ /**
28530
+ * Network-link snapshot. Same shape for every provider (a Reolink wifi
28531
+ * camera, a Home Assistant device with a signal-strength sensor, a Tapo
28532
+ * plug): one slice under `device.runtimeState['network-link']`, one badge,
28533
+ * one Home Assistant projection.
28534
+ */
28535
+ var NetworkLinkStatusSchema = object({
28536
+ /** The link the device is on. `'unknown'` = not read yet, not "no link". */
28537
+ type: _enum([
28538
+ "wifi",
28539
+ "ethernet",
28540
+ "cellular",
28541
+ "unknown"
28542
+ ]),
28543
+ /**
28544
+ * Link quality, 0..100 inclusive, normalised by the provider from whatever
28545
+ * the firmware reports (bars, RSSI, a vendor scale). **`null` means NOT
28546
+ * KNOWN or NOT APPLICABLE** — a wired link has no signal, and a wireless
28547
+ * one whose reading has not landed must not be drawn at 0 %. Consumers
28548
+ * SKIP a null rather than coerce it.
28549
+ */
28550
+ signalPercent: number().min(0).max(100).nullable(),
28551
+ /** Raw received signal strength in dBm, when the firmware reports one. */
28552
+ rssiDbm: number().optional(),
28553
+ /** Network name of a wireless link, when the firmware reports it. */
28554
+ ssid: string().optional(),
28555
+ /** Ms epoch of the last observation. Lets consumers reason about freshness. */
28556
+ lastUpdated: number()
28557
+ });
28558
+ /** The slice a provider seeds before its first read: nothing is known yet. */
28559
+ var NETWORK_LINK_UNKNOWN = {
28560
+ type: "unknown",
28561
+ signalPercent: null,
28562
+ lastUpdated: 0
28563
+ };
28564
+ /**
28565
+ * Normalise a signal the firmware reports as BARS (0..`maxBars`) to 0..100.
28566
+ * Out-of-range or non-finite input is not a reading: `null`.
28567
+ */
28568
+ function signalPercentFromBars(bars, maxBars) {
28569
+ if (bars === void 0 || !Number.isFinite(bars) || maxBars <= 0) return null;
28570
+ if (bars < 0 || bars > maxBars) return null;
28571
+ return Math.round(bars / maxBars * 100);
28572
+ }
28573
+ /**
28574
+ * Normalise an RSSI in dBm to 0..100 on the usual wifi scale: -100 dBm and
28575
+ * below is 0 %, -50 dBm and above is 100 %, linear between. Non-finite or
28576
+ * positive input is not an RSSI: `null`.
28577
+ */
28578
+ function signalPercentFromRssi(rssiDbm) {
28579
+ if (rssiDbm === void 0 || !Number.isFinite(rssiDbm) || rssiDbm > 0) return null;
28580
+ return Math.round((Math.min(-50, Math.max(-100, rssiDbm)) + 100) * 2);
28581
+ }
28582
+ var networkLinkCapability = {
28583
+ name: "network-link",
28584
+ scope: "device",
28585
+ deviceNative: true,
28586
+ mode: "singleton",
28587
+ deviceTypes: [
28588
+ DeviceType.Camera,
28589
+ DeviceType.Sensor,
28590
+ DeviceType.Button,
28591
+ DeviceType.Switch,
28592
+ DeviceType.Light,
28593
+ DeviceType.Lock,
28594
+ DeviceType.Siren
28595
+ ],
28596
+ methods: {},
28597
+ events: {
28598
+ /**
28599
+ * Emitted whenever the cached status changes (a link switch, a signal
28600
+ * reading that moved). Mirrored on the parent chain by the
28601
+ * DeviceEventPropagator like `battery.onStatusChanged`.
28602
+ */
28603
+ onStatusChanged: { data: object({
28604
+ deviceId: number(),
28605
+ status: NetworkLinkStatusSchema
28606
+ }) } },
28607
+ status: {
28608
+ schema: NetworkLinkStatusSchema,
28609
+ kind: "push",
28610
+ empty: NETWORK_LINK_UNKNOWN
28611
+ },
28612
+ /**
28613
+ * Runtime-state slice — every provider stores the same shape under
28614
+ * `device.runtimeState['network-link']`, read once by the badge and the
28615
+ * Home Assistant projector regardless of the driver.
28616
+ */
28617
+ runtimeState: NetworkLinkStatusSchema,
28618
+ /**
28619
+ * Runtime-state durability: **restored** — a link reading is slow to
28620
+ * change and a sleeping battery camera may not report for hours; the
28621
+ * restored slice is what the badge shows until the next read.
28622
+ *
28623
+ * See `RuntimeStateDurability`. Enforced by
28624
+ * `scripts/check-runtime-state-durability.ts`.
28625
+ */
28626
+ durability: "restored",
28627
+ /** Clock fields: written, but excluded from the compare that decides
28628
+ * whether persisting is worth a SQLite commit. */
28629
+ volatileStateFields: ["lastUpdated"]
28630
+ };
28631
+ /**
28224
28632
  * network-quality — system-scoped singleton capability tracking RTT,
28225
28633
  * jitter, and observed/peak bandwidth per device + per client.
28226
28634
  *
@@ -29864,287 +30272,6 @@ var ptzAutotrackCapability = {
29864
30272
  durability: "session"
29865
30273
  };
29866
30274
  /**
29867
- * `navigation` — a device-scoped capability that natively expresses the FULL
29868
- * navigation / action surface of a robot that DRIVES ITSELF and carries an
29869
- * on-board camera (the Dreame robot-vacuum camera is the first provider).
29870
- *
29871
- * Why a NEW cap rather than overloading `ptz`:
29872
- * - `ptz` moves a *gimbal* on a fixed camera (pan/tilt/zoom of the lens). A
29873
- * robot vacuum has no gimbal — the whole chassis drives, turns and spins.
29874
- * The two are different physical models: PTZ is absolute-position + presets,
29875
- * navigation is momentary drive nudges + discrete robot ACTIONS
29876
- * (dock / spot-clean / follow-pet / go-to-point / …).
29877
- * - This cap is the SOURCE OF TRUTH. Two consumers adapt from it rather than
29878
- * the reverse:
29879
- * 1. a native CamStack navigation panel (data-driven from `listActions`
29880
- * / `getOptions`), and
29881
- * 2. the PTZ surface — a thin adapter mimics `ptz` from `navigation` so a
29882
- * robot camera shows up in the existing PTZ control path without every
29883
- * PTZ provider learning about robots. The mapping lives in the adapter,
29884
- * not here (see the addon design note):
29885
- * ptz.continuousMove({pan,tilt}) → navigation.move({pan,tilt})
29886
- * ptz.stop() → navigation.stop()
29887
- * ptz.goHome() → navigation.runAction('goHome')
29888
- * ptz.getPresets() → navigation.listActions() (id→preset)
29889
- * ptz.goToPreset(id) → navigation.runAction(id)
29890
- *
29891
- * ## Continuous drive
29892
- *
29893
- * `move` is MOMENTARY. Fluid navigation comes from the UI (or the PTZ adapter)
29894
- * sending `move({pan,tilt})` REPEATEDLY at ~1 Hz while a direction is held, and
29895
- * one `stop()` on release — exactly like the robot app's remote-drive joystick.
29896
- * The provider forwards EACH `move` to one drive write; it must NOT debounce or
29897
- * coalesce them. The UI owns the cadence.
29898
- *
29899
- * ## The action dictionary
29900
- *
29901
- * The discrete controls (dock / locate / spot-clean / follow / flash / sounds)
29902
- * are a DATA-DRIVEN dictionary the cap exposes via `listActions()`. Each entry
29903
- * carries `{ id, kind, label, icon }` (plus `soundId` for sound entries) so the
29904
- * native panel AND the PTZ mimic render buttons WITHOUT hardcoding a
29905
- * vendor-specific list. `kind: 'action'` entries are triggered with
29906
- * `runAction({ actionId })`; `kind: 'sound'` entries with `playSound({ soundId })`
29907
- * (the entry carries the `soundId` to pass). The general primitives — `move`,
29908
- * `stop`, `goToPoint` — stay as first-class methods, not dictionary entries.
29909
- *
29910
- * NOTE (provider wiring): the first provider (Dreame) drives this with the RAW
29911
- * `callAction(siid,aiid,in)` / `setProperty({siid,piid,value})` MIoT primitives
29912
- * that the currently-published `@apocaliss92/nodedreame` already exposes on
29913
- * every device handle. A future nodedreame publish adds a typed
29914
- * `DreameCameraController` (drive / playPetSound / spotClean / findPet / …); the
29915
- * provider can then swap the raw calls for the typed methods with no change to
29916
- * THIS contract.
29917
- */
29918
- /**
29919
- * A momentary drive nudge. The robot MOVES (no gimbal) for as long as the caller
29920
- * keeps sending nudges (~1 Hz); an explicit `stop` (or letting the nudges lapse)
29921
- * halts it.
29922
- *
29923
- * - `pan` — turn: negative = left, positive = right, 0 = straight.
29924
- * - `tilt` — throttle: positive = forward, negative = spin / turn-around.
29925
- * - `speed` — optional intensity hint [0, 1]; the provider may scale the drive
29926
- * vector by it (drivers without proportional drive ignore it).
29927
- *
29928
- * `pan` / `tilt` are normalized [-1, 1]. Both optional so a caller can nudge one
29929
- * axis alone; an all-undefined nudge is a no-op.
29930
- */
29931
- var NavigationMoveCommandSchema = object({
29932
- pan: number().min(-1).max(1).optional(),
29933
- tilt: number().min(-1).max(1).optional(),
29934
- speed: number().min(0).max(1).optional()
29935
- });
29936
- /**
29937
- * The enumerated discrete actions a navigation-capable robot can perform via
29938
- * `runAction`. This is the CLOSED vocabulary; a given device advertises the
29939
- * subset it supports through `listActions`. Sounds are NOT here — they go through
29940
- * `playSound` (see the `sound` dictionary entries).
29941
- */
29942
- var NavigationActionIdSchema = _enum([
29943
- "goHome",
29944
- "locate",
29945
- "spotClean",
29946
- "findPet",
29947
- "personFollow",
29948
- "stop",
29949
- "startClean",
29950
- "pauseClean",
29951
- "dockWash",
29952
- "autoEmpty",
29953
- "flashOn",
29954
- "flashOff"
29955
- ]);
29956
- /** Whether a dictionary entry is a `runAction` action or a `playSound` sound. */
29957
- var NavigationEntryKindSchema = _enum(["action", "sound"]);
29958
- /**
29959
- * One entry in the navigation action dictionary — the DATA-DRIVEN unit both the
29960
- * native panel and the PTZ mimic render as a button.
29961
- *
29962
- * - `id` — stable id. For `kind:'action'` it is a {@link NavigationActionId}
29963
- * (pass to `runAction`); for `kind:'sound'` it is a namespaced id
29964
- * (`sound:meow`) whose `soundId` is passed to `playSound`.
29965
- * - `icon` — icon HINT (lucide-style name; the UI maps it to its own set).
29966
- * - `label` — operator-facing English label.
29967
- * - `soundId` — wire sound id, present only on `kind:'sound'` entries.
29968
- * - `enabled` — per-device FEATURE FLAG. `listActions` reports it so the UI /
29969
- * PTZ render ONLY enabled entries. Data-driven: the provider
29970
- * flips it from config, never by editing code.
29971
- */
29972
- var NavigationActionEntrySchema = object({
29973
- id: string(),
29974
- kind: NavigationEntryKindSchema,
29975
- label: string(),
29976
- icon: string(),
29977
- /** Present only on `kind:'sound'` entries — the id to pass to `playSound`. */
29978
- soundId: number().int().optional(),
29979
- /** Per-device feature flag — render this entry only when true. */
29980
- enabled: boolean()
29981
- });
29982
- /** Coordinates for `goToPoint` — a point on the robot's live map. */
29983
- var NavigationPointSchema = object({
29984
- x: number(),
29985
- y: number()
29986
- });
29987
- /**
29988
- * Per-device FEATURE-FLAG report for the general (non-dictionary) primitives.
29989
- * The cap reports which are enabled so the UI / PTZ render only the controls
29990
- * that are turned on for THIS device. Data-driven: the provider derives these
29991
- * from config + probe, never hardcoded in the UI. The per-DICTIONARY-entry flags
29992
- * live on {@link NavigationActionEntrySchema.enabled}; these gate the primitives
29993
- * that are not dictionary entries.
29994
- *
29995
- * - `move` / `stop` — the momentary drive joystick.
29996
- * - `goToPoint` — send-to-map-coordinate. Ships OFF on Dreame until the
29997
- * map-coordinate plumbing is wired.
29998
- * - `runAction` — the discrete action buttons (dictionary `kind:'action'`).
29999
- * - `playSound` — the sound buttons (dictionary `kind:'sound'`).
30000
- * - `light` — the on/off fill-light toggle (works anytime).
30001
- * - `lightMode` — the auto/manual selector + manual level slider (a
30002
- * camera-service control; needs an active stream).
30003
- */
30004
- var NavigationFeaturesSchema = object({
30005
- move: boolean(),
30006
- stop: boolean(),
30007
- goToPoint: boolean(),
30008
- runAction: boolean(),
30009
- playSound: boolean(),
30010
- light: boolean(),
30011
- lightMode: boolean()
30012
- });
30013
- /** Light mode: `auto` lets the camera choose brightness; `manual` uses `level`. */
30014
- var NavigationLightModeSchema = _enum(["auto", "manual"]);
30015
- /**
30016
- * Live navigation state so the UI can reflect what the robot is doing:
30017
- * - `mode` — coarse activity (idle / cleaning / following / …).
30018
- * - `following` — person/pet follow is currently armed.
30019
- * - `flash` — the on-camera fill light is on.
30020
- * - `lightMode` — auto vs manual fill-light mode.
30021
- * - `lightLevel` — manual fill-light level (40..100); meaningful when
30022
- * `lightMode === 'manual'`.
30023
- */
30024
- var NavigationStatusSchema = object({
30025
- mode: _enum([
30026
- "idle",
30027
- "cleaning",
30028
- "spot",
30029
- "following",
30030
- "goto",
30031
- "returning",
30032
- "paused",
30033
- "unknown"
30034
- ]),
30035
- following: boolean(),
30036
- flash: boolean(),
30037
- lightMode: NavigationLightModeSchema,
30038
- lightLevel: number().min(40).max(100),
30039
- /** Ms epoch when the slice was last updated. */
30040
- lastChangedAt: number()
30041
- });
30042
- /**
30043
- * Runtime-state slice owned by this cap (kernel-managed: validated, mirrored,
30044
- * observable). Adds `lastFetchedAt` on top of the status shape per the
30045
- * convention.
30046
- */
30047
- var NavigationRuntimeStateSchema = NavigationStatusSchema.extend({ lastFetchedAt: number() });
30048
- var navigationCapability = {
30049
- name: "navigation",
30050
- scope: "device",
30051
- deviceNative: true,
30052
- mode: "singleton",
30053
- deviceTypes: [DeviceType.Camera],
30054
- deviceConfig: { ui: {
30055
- kind: "widget",
30056
- widgetId: "host/navigation-panel",
30057
- tab: "navigation",
30058
- topTab: true,
30059
- label: "Navigation",
30060
- order: 0
30061
- } },
30062
- methods: {
30063
- /**
30064
- * Momentary drive nudge (the robot moves). `protected` — mirrors
30065
- * `ptz.continuousMove` so the Viewer navigation panel (and the PTZ-mimic
30066
- * path) works for any authenticated user, not admin-only. The UI sends
30067
- * these at ~1 Hz while a control is held; the provider forwards each one to
30068
- * a single drive write WITHOUT debouncing.
30069
- */
30070
- move: method(NavigationMoveCommandSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
30071
- /** Halt all motion immediately (zero drive vector). */
30072
- stop: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
30073
- /** Send the robot to a point on its live map. */
30074
- goToPoint: method(NavigationPointSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
30075
- /**
30076
- * Enumerate the discrete controls THIS device supports (data-driven UI +
30077
- * PTZ mimic). Camera-probed subset of {@link NAVIGATION_ACTION_CATALOG}.
30078
- */
30079
- listActions: method(object({ deviceId: number() }), array(NavigationActionEntrySchema)),
30080
- /**
30081
- * Run one discrete action (a `kind:'action'` dictionary entry). Invalid /
30082
- * unsupported action ids are rejected by the provider.
30083
- */
30084
- runAction: method(object({
30085
- deviceId: number(),
30086
- actionId: NavigationActionIdSchema
30087
- }), _void(), { kind: "mutation" }),
30088
- /** Play a sound by its wire id (the `soundId` of a `kind:'sound'` entry). */
30089
- playSound: method(object({
30090
- deviceId: number(),
30091
- soundId: number().int()
30092
- }), _void(), { kind: "mutation" }),
30093
- /**
30094
- * Turn the on-camera fill light on / off (the `OpenFullLight` control —
30095
- * works anytime, no active stream required).
30096
- */
30097
- setLightOn: method(object({
30098
- deviceId: number(),
30099
- on: boolean()
30100
- }), _void(), { kind: "mutation" }),
30101
- /**
30102
- * Set the fill-light mode (auto vs manual). `manual` optionally carries the
30103
- * initial `level`. The auto/manual + level control is a CAMERA-service
30104
- * action that generally needs an active camera stream/monitor session — the
30105
- * UI shows the manual level slider ONLY when `mode === 'manual'`.
30106
- */
30107
- setLightMode: method(object({
30108
- deviceId: number(),
30109
- mode: NavigationLightModeSchema,
30110
- level: number().min(40).max(100).optional()
30111
- }), _void(), { kind: "mutation" }),
30112
- /** Set the MANUAL fill-light level (40..100). Implies `manual` mode. */
30113
- setLightLevel: method(object({
30114
- deviceId: number(),
30115
- level: number().min(40).max(100)
30116
- }), _void(), { kind: "mutation" }),
30117
- /**
30118
- * Per-device FEATURE-FLAG report for the general primitives — drives which
30119
- * controls the UI shows (the per-entry flags for the dictionary come back on
30120
- * `listActions`).
30121
- */
30122
- getFeatures: method(object({ deviceId: number() }), NavigationFeaturesSchema)
30123
- },
30124
- events: { onStatusChanged: { data: object({
30125
- deviceId: number(),
30126
- status: NavigationStatusSchema
30127
- }) } },
30128
- status: {
30129
- schema: NavigationStatusSchema,
30130
- kind: "push"
30131
- },
30132
- /**
30133
- * Runtime-state slice mirrored by the kernel. The navigation panel watches it
30134
- * for live mode / follow / flash changes.
30135
- */
30136
- runtimeState: NavigationRuntimeStateSchema,
30137
- /**
30138
- * Runtime-state durability: **session** — like `vacuum-control`, a restored
30139
- * `mode: cleaning` / `following: true` is a robot that is not actually doing
30140
- * that. The live handle re-publishes on connect.
30141
- *
30142
- * See `RuntimeStateDurability`. Enforced by
30143
- * `scripts/check-runtime-state-durability.ts`.
30144
- */
30145
- durability: "session"
30146
- };
30147
- /**
30148
30275
  * reboot — device-scoped capability for "soft" device reboots (firmware
30149
30276
  * reboot via vendor protocol; cameras, NVRs, doorbells). Surfaces a
30150
30277
  * single mutation so the UI can offer a confirm-and-reboot button for
@@ -40001,13 +40128,13 @@ Object.freeze({
40001
40128
  addonId: null,
40002
40129
  access: "view"
40003
40130
  },
40004
- "storage.getDefaultLocation": {
40131
+ "storage.list": {
40005
40132
  capName: "storage",
40006
40133
  capScope: "system",
40007
40134
  addonId: null,
40008
40135
  access: "view"
40009
40136
  },
40010
- "storage.list": {
40137
+ "storage.listDrainProgress": {
40011
40138
  capName: "storage",
40012
40139
  capScope: "system",
40013
40140
  addonId: null,
@@ -40157,6 +40284,12 @@ Object.freeze({
40157
40284
  addonId: null,
40158
40285
  access: "view"
40159
40286
  },
40287
+ "storageOccupancy.getOccupancy": {
40288
+ capName: "storage-occupancy",
40289
+ capScope: "system",
40290
+ addonId: null,
40291
+ access: "view"
40292
+ },
40160
40293
  "storageProvider.abortUpload": {
40161
40294
  capName: "storage-provider",
40162
40295
  capScope: "system",