camstack 1.2.89 → 1.2.91

package/dist/{chunk-BLJRLA7I.js → chunk-ECD5A36V.js}

@@ -14522,7 +14522,7 @@ function date4(params) {
 // ../../node_modules/zod/v4/classic/external.js
 config(en_default());
 
-// ../types/dist/sleep-B195W080.mjs
+// ../types/dist/sleep-CbBk_3GJ.mjs
 var WELL_KNOWN_TABS = [
   {
     id: "overview",
@@ -26134,6 +26134,21 @@ var TrackFlagFields = {
   markForTrain: external_exports.boolean().optional(),
   /** Operator marked this track for diagnostic attention. */
   debug: external_exports.boolean().optional(),
+  /**
+  * What the operator wants CHECKED on this track, in their own words.
+  *
+  * The flag alone says "look at this" and nothing about what for; a debug set
+  * reviewed hours later is a list of tracks with no question attached. Bound
+  * to `debug` on the WRITE side — the body clears it when `debug` goes off,
+  * and refuses it on a track whose debug is off — so a note can never outlive
+  * the attention it belongs to.
+  *
+  * `''` is a real value ("marked, nothing to add"); the ABSENT key means
+  * "leave whatever is stored alone", which is what lets a surface turn debug
+  * on without a note (a cancelled prompt) and what lets it edit the note
+  * without touching the flag.
+  */
+  debugNote: external_exports.string().max(500).optional(),
   /** Operator favourited this track. Pins it against pruning. */
   favourited: external_exports.boolean().optional()
 };
@@ -26143,6 +26158,12 @@ var TrackFlagsSchema = external_exports.object({
   trackId: external_exports.string(),
   markForTrain: external_exports.boolean(),
   debug: external_exports.boolean(),
+  /** The note as it STANDS after the write — never absent here (a track with no
+  *  note reports `''`), for the same reason the booleans are required: a
+  *  surface that has just written must be able to render the note it now owns
+  *  without a re-fetch, and an absent key would read as "unchanged" on a
+  *  screen that has no previous value to keep. */
+  debugNote: external_exports.string(),
   favourited: external_exports.boolean(),
   /** The lifecycle state the boolean was derived from. Required here (unlike on
   *  a track row) because this shape is only ever produced by the write body,
@@ -27197,11 +27218,20 @@ var pipelineAnalyticsCapability = {
     * staging is a deliberate action of the retrain page, which is also the only
     * thing that produces `trained` in the first place.
     *
-    * Returns the RESOLVED state of both flags (absent → `false`) plus the
-    * `retrainStatus` they were derived from, so a caller can drive its toggle
-    * — and render a `trained` badge — without a re-fetch. Rejects an unknown
-    * track, a new staging mark on a device already holding its full budget, and
-    * any `markForTrain` write against a trained track.
+    * `debugNote` is the operator's sentence about WHAT to check on this track,
+    * and it is bound to `debug`: writing `debug: false` clears it in the same
+    * statement, and a note sent for a track whose debug is off (and is not
+    * being turned on) is DROPPED with a warning rather than stored where
+    * nothing will ever read it. An omitted `debugNote` leaves the stored one
+    * alone — which is what lets a surface turn debug on when the operator
+    * declined to type anything, without that refusal costing them the flag.
+    *
+    * Returns the RESOLVED state of all three flags (absent → `false`) plus the
+    * note (absent → `''`) and the `retrainStatus` they were derived from, so a
+    * caller can drive its toggle — and render a `trained` badge — without a
+    * re-fetch. Rejects an unknown track, a new staging mark on a device already
+    * holding its full budget, and any `markForTrain` write against a trained
+    * track.
     */
     setTrackFlags: method(external_exports.object({
       /** Log/audit scope only — the trackId is globally unique on its own. */

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runDiscover
-} from "./chunk-BLJRLA7I.js";
+} from "./chunk-ECD5A36V.js";
 import "./chunk-LMMQX4CK.js";
 
 // src/cli.ts
@@ -38,7 +38,7 @@ async function runServe(args) {
     ...typeof values.data === "string" ? { data: values.data } : {}
   };
   Object.assign(process.env, buildServeEnv(opts));
-  await import("./launcher-POOJGOAQ.js");
+  await import("./launcher-FFY5TY3C.js");
 }
 
 // src/commands/agent.ts
@@ -83,7 +83,7 @@ async function runAgent(args) {
     ...typeof values.port === "string" ? { port: values.port } : {}
   };
   Object.assign(process.env, buildAgentEnv(opts));
-  await import("./launcher-POOJGOAQ.js");
+  await import("./launcher-FFY5TY3C.js");
 }
 
 // src/commands/setup.ts
@@ -1130,7 +1130,7 @@ function isUnknown(_value) {
   return true;
 }
 async function resolveServerInteractive(presetNamespace) {
-  const { discoverNodes, resolveHubFromDiscovered, filterHubNodes, DEFAULT_HUB_HTTPS_PORT } = await import("./discover-FHE2CTRJ.js");
+  const { discoverNodes, resolveHubFromDiscovered, filterHubNodes, DEFAULT_HUB_HTTPS_PORT } = await import("./discover-QUITQWRC.js");
   if (presetNamespace) {
     const spinner4 = clack.spinner();
     spinner4.start(`Discovering hub on LAN (namespace "${presetNamespace}")`);

package/dist/{discover-FHE2CTRJ.js → discover-QUITQWRC.js}

@@ -5,7 +5,7 @@ import {
   filterHubNodes,
   resolveHubFromDiscovered,
   runDiscover
-} from "./chunk-BLJRLA7I.js";
+} from "./chunk-ECD5A36V.js";
 import "./chunk-LMMQX4CK.js";
 export {
   DEFAULT_HUB_HTTPS_PORT,

package/dist/{launcher-POOJGOAQ.js → launcher-FFY5TY3C.js}

@@ -23633,9 +23633,9 @@ var require_zod = __commonJS({
   }
 });
 
-// ../system/dist/dist-DE3OH-FG.js
-var require_dist_DE3OH_FG = __commonJS({
-  "../system/dist/dist-DE3OH-FG.js"(exports) {
+// ../system/dist/dist-0fjBDzUu.js
+var require_dist_0fjBDzUu = __commonJS({
+  "../system/dist/dist-0fjBDzUu.js"(exports) {
     "use strict";
     var zod = require_zod();
     var EventCategory = /* @__PURE__ */ (function(EventCategory2) {
@@ -36840,6 +36840,21 @@ var require_dist_DE3OH_FG = __commonJS({
       markForTrain: zod.z.boolean().optional(),
       /** Operator marked this track for diagnostic attention. */
       debug: zod.z.boolean().optional(),
+      /**
+      * What the operator wants CHECKED on this track, in their own words.
+      *
+      * The flag alone says "look at this" and nothing about what for; a debug set
+      * reviewed hours later is a list of tracks with no question attached. Bound
+      * to `debug` on the WRITE side — the body clears it when `debug` goes off,
+      * and refuses it on a track whose debug is off — so a note can never outlive
+      * the attention it belongs to.
+      *
+      * `''` is a real value ("marked, nothing to add"); the ABSENT key means
+      * "leave whatever is stored alone", which is what lets a surface turn debug
+      * on without a note (a cancelled prompt) and what lets it edit the note
+      * without touching the flag.
+      */
+      debugNote: zod.z.string().max(500).optional(),
       /** Operator favourited this track. Pins it against pruning. */
       favourited: zod.z.boolean().optional()
     };
@@ -36849,6 +36864,12 @@ var require_dist_DE3OH_FG = __commonJS({
       trackId: zod.z.string(),
       markForTrain: zod.z.boolean(),
       debug: zod.z.boolean(),
+      /** The note as it STANDS after the write — never absent here (a track with no
+      *  note reports `''`), for the same reason the booleans are required: a
+      *  surface that has just written must be able to render the note it now owns
+      *  without a re-fetch, and an absent key would read as "unchanged" on a
+      *  screen that has no previous value to keep. */
+      debugNote: zod.z.string(),
       favourited: zod.z.boolean(),
       /** The lifecycle state the boolean was derived from. Required here (unlike on
       *  a track row) because this shape is only ever produced by the write body,
@@ -37902,11 +37923,20 @@ var require_dist_DE3OH_FG = __commonJS({
         * staging is a deliberate action of the retrain page, which is also the only
         * thing that produces `trained` in the first place.
         *
-        * Returns the RESOLVED state of both flags (absent → `false`) plus the
-        * `retrainStatus` they were derived from, so a caller can drive its toggle
-        * — and render a `trained` badge — without a re-fetch. Rejects an unknown
-        * track, a new staging mark on a device already holding its full budget, and
-        * any `markForTrain` write against a trained track.
+        * `debugNote` is the operator's sentence about WHAT to check on this track,
+        * and it is bound to `debug`: writing `debug: false` clears it in the same
+        * statement, and a note sent for a track whose debug is off (and is not
+        * being turned on) is DROPPED with a warning rather than stored where
+        * nothing will ever read it. An omitted `debugNote` leaves the stored one
+        * alone — which is what lets a surface turn debug on when the operator
+        * declined to type anything, without that refusal costing them the flag.
+        *
+        * Returns the RESOLVED state of all three flags (absent → `false`) plus the
+        * note (absent → `''`) and the `retrainStatus` they were derived from, so a
+        * caller can drive its toggle — and render a `trained` badge — without a
+        * re-fetch. Rejects an unknown track, a new staging mark on a device already
+        * holding its full budget, and any `markForTrain` write against a trained
+        * track.
         */
         setTrackFlags: method(zod.z.object({
           /** Log/audit scope only — the trackId is globally unique on its own. */
@@ -60079,7 +60109,7 @@ var require_alerts_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     function selectExpired(alerts, cutoffMs) {
       return alerts.filter((a) => a.createdAt < cutoffMs).sort((a, b) => a.createdAt - b.createdAt).map((a) => a.id);
     }
@@ -60898,7 +60928,7 @@ var require_console_logging = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var require_formatter = require_formatter_DqAKDlvN();
     var LEVEL_RANK = {
       debug: 0,
@@ -60992,7 +61022,7 @@ var require_core_blocks_addon = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var node_crypto = __require("crypto");
     var node_fs_promises = __require("fs/promises");
     node_fs_promises = require_chunk.__toESM(node_fs_promises);
@@ -61889,11 +61919,11 @@ var require_core_blocks = __commonJS({
   }
 });
 
-// ../system/dist/retired-settings-keys-BgUS9Rr3.js
-var require_retired_settings_keys_BgUS9Rr3 = __commonJS({
-  "../system/dist/retired-settings-keys-BgUS9Rr3.js"(exports) {
+// ../system/dist/retired-settings-keys-pL2Nq6KT.js
+var require_retired_settings_keys_pL2Nq6KT = __commonJS({
+  "../system/dist/retired-settings-keys-pL2Nq6KT.js"(exports) {
     "use strict";
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     function settingsStoreIsAuthoritativeHere(env) {
       const raw = (env["CAMSTACK_ROLE"] ?? "").trim().toLowerCase();
       return raw === "" || raw === "hub";
@@ -64107,8 +64137,8 @@ var require_device_manager_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
-    var require_retired_settings_keys = require_retired_settings_keys_BgUS9Rr3();
+    var require_dist10 = require_dist_0fjBDzUu();
+    var require_retired_settings_keys = require_retired_settings_keys_pL2Nq6KT();
     var node_crypto = __require("crypto");
     var _camstack_types_node = require_node();
     var JOB_HISTORY = 20;
@@ -65799,6 +65829,68 @@ var require_device_manager_addon = __commonJS({
       return linkedIds.filter((id) => picked.has(id));
     }
     var LINK_CANDIDATE_PROJECTION = { projection: "slim" };
+    function findLocationInvisibleContainers(params) {
+      const { selfId, selfLocation, resolvedIds, candidates } = params;
+      if (selfLocation === null || selfLocation.length === 0) return [];
+      const byParent = /* @__PURE__ */ new Map();
+      for (const c of candidates) {
+        if (c.parentDeviceId === null) continue;
+        const bucket = byParent.get(c.parentDeviceId);
+        if (bucket) bucket.push(c);
+        else byParent.set(c.parentDeviceId, [c]);
+      }
+      const out = [];
+      for (const c of candidates) {
+        if (c.type !== require_dist10.DeviceType.Container) continue;
+        if (c.id === selfId) continue;
+        if (c.location !== selfLocation) continue;
+        let anyResolved = false;
+        let anyNullLocation = false;
+        let descendantCount = 0;
+        const visited = /* @__PURE__ */ new Set([c.id]);
+        let frontier = [c.id];
+        while (frontier.length > 0) {
+          const next = [];
+          for (const parentId of frontier) for (const child of byParent.get(parentId) ?? []) {
+            if (visited.has(child.id)) continue;
+            visited.add(child.id);
+            descendantCount += 1;
+            if (resolvedIds.has(child.id)) anyResolved = true;
+            if (child.location === null) anyNullLocation = true;
+            next.push(child.id);
+          }
+          frontier = next;
+        }
+        if (descendantCount > 0 && !anyResolved && anyNullLocation) out.push(c.id);
+      }
+      return out;
+    }
+    var INVISIBLE_CONTAINER_WARN_CAP = 4096;
+    var warnedInvisibleContainers = /* @__PURE__ */ new Set();
+    function warnLocationInvisibleContainers(pctx, cameraId, byId, all, resolved) {
+      if (resolved.mode !== "auto") return;
+      const selfLocation = byId.get(cameraId)?.location ?? null;
+      if (selfLocation === null || selfLocation.length === 0) return;
+      const invisible = findLocationInvisibleContainers({
+        selfId: cameraId,
+        selfLocation,
+        resolvedIds: new Set(resolved.devices.map((d) => d.deviceId)),
+        candidates: all
+      });
+      for (const containerId of invisible) {
+        const key = `${cameraId}:${containerId}`;
+        if (warnedInvisibleContainers.has(key)) continue;
+        if (warnedInvisibleContainers.size >= INVISIBLE_CONTAINER_WARN_CAP) return;
+        warnedInvisibleContainers.add(key);
+        pctx.host.ctx.logger.warn("getLinkedDevices: container matches the camera location but is invisible to auto-link \u2014 its children carry no location; re-save the container location to realign", {
+          tags: { deviceId: containerId },
+          meta: {
+            cameraId,
+            location: selfLocation
+          }
+        });
+      }
+    }
     function resolveFor(deviceId, all, byId, blob) {
       const config = parseLinkedDevicesConfig(blob);
       const ids = resolveLinkedDeviceIds({
@@ -65828,7 +65920,10 @@ var require_device_manager_addon = __commonJS({
     async function getLinkedDevices(pctx, input) {
       const { deviceId } = input;
       const [all, blob] = await Promise.all([listAll(pctx, LINK_CANDIDATE_PROJECTION), pctx.settings.readDeviceStore(deviceId)]);
-      return resolveFor(deviceId, all, new Map(all.map((d) => [d.id, d])), blob);
+      const byId = new Map(all.map((d) => [d.id, d]));
+      const resolved = resolveFor(deviceId, all, byId, blob);
+      warnLocationInvisibleContainers(pctx, deviceId, byId, all, resolved);
+      return resolved;
     }
     async function getLinkedDevicesBatch(pctx, input) {
       const deviceIds = [...new Set(input.deviceIds)];
@@ -65841,10 +65936,14 @@ var require_device_manager_addon = __commonJS({
         return {};
       })))]);
       const byId = new Map(all.map((d) => [d.id, d]));
-      return deviceIds.map((deviceId, index) => ({
-        deviceId,
-        ...resolveFor(deviceId, all, byId, blobs[index] ?? {})
-      }));
+      return deviceIds.map((deviceId, index) => {
+        const resolved = resolveFor(deviceId, all, byId, blobs[index] ?? {});
+        warnLocationInvisibleContainers(pctx, deviceId, byId, all, resolved);
+        return {
+          deviceId,
+          ...resolved
+        };
+      });
     }
     async function buildLinkedDevicesContribution(pctx, deviceId) {
       const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
@@ -66773,6 +66872,121 @@ var require_device_manager_addon = __commonJS({
         roleKeysKeptAtTarget: Object.keys(target.role).toSorted()
       };
     }
+    var LOCATION_BACKFILL_MARKER_KEY = "locationBackfillVersion";
+    function nearestLocatedAncestor(byId, startParentId) {
+      const visited = /* @__PURE__ */ new Set();
+      let cursor = startParentId;
+      while (cursor !== null && !visited.has(cursor)) {
+        visited.add(cursor);
+        const ancestor = byId.get(cursor);
+        if (!ancestor) return null;
+        if (ancestor.location !== null) return ancestor;
+        cursor = ancestor.parentDeviceId;
+      }
+      return null;
+    }
+    function planNullLocationFills(rows) {
+      const byId = new Map(rows.map((r) => [r.id, r]));
+      const plan = [];
+      for (const row of rows) {
+        if (row.location !== null) continue;
+        if (row.parentDeviceId === null) continue;
+        const hit = nearestLocatedAncestor(byId, row.parentDeviceId);
+        if (hit === null) continue;
+        if (hit.type !== require_dist10.DeviceType.Container) continue;
+        if (hit.location === null) continue;
+        plan.push({
+          id: row.id,
+          location: hit.location,
+          ancestorId: hit.id
+        });
+      }
+      return plan;
+    }
+    async function resolveInheritedLocation(rows, parentDeviceId) {
+      const visited = /* @__PURE__ */ new Set();
+      let cursor = parentDeviceId;
+      while (cursor !== null && !visited.has(cursor)) {
+        visited.add(cursor);
+        const ancestor = await rows.get(cursor);
+        if (ancestor === null) return null;
+        if (ancestor.meta.location !== null) return ancestor.meta.type === require_dist10.DeviceType.Container ? ancestor.meta.location : null;
+        cursor = ancestor.meta.parentDeviceId;
+      }
+      return null;
+    }
+    function groupByAncestor(fills) {
+      const grouped = /* @__PURE__ */ new Map();
+      for (const fill of fills) {
+        const bucket = grouped.get(fill.ancestorId);
+        if (bucket) bucket.push(fill);
+        else grouped.set(fill.ancestorId, [fill]);
+      }
+      return grouped;
+    }
+    async function runLocationBackfillAtBoot(pctx, bootRows) {
+      const logger = pctx.host.ctx.logger;
+      const markerRaw = (await pctx.settings.readAddonStore())[LOCATION_BACKFILL_MARKER_KEY];
+      const completedVersion = typeof markerRaw === "number" ? markerRaw : 0;
+      let repaired = false;
+      if (completedVersion < 1) {
+        const patched = [];
+        const failed = [];
+        await pctx.metaStore.withMetaWriteLock(async () => {
+          const plan = planNullLocationFills((await pctx.metaStore.rows.listAll()).map((r) => r.meta));
+          for (const fill of plan) try {
+            const current = await pctx.metaStore.rows.get(fill.id);
+            if (current === null || current.meta.location !== null) continue;
+            await pctx.metaStore.rows.patch(fill.id, { location: fill.location });
+            patched.push(fill);
+          } catch (err) {
+            failed.push({
+              id: fill.id,
+              error: err
+            });
+          }
+        });
+        repaired = true;
+        for (const [ancestorId, fills] of groupByAncestor(patched)) {
+          pctx.host.ctx.eventBus.emit({
+            id: (0, node_crypto.randomUUID)(),
+            timestamp: /* @__PURE__ */ new Date(),
+            source: {
+              type: "device",
+              id: ancestorId
+            },
+            category: require_dist10.EventCategory.DeviceMetaChanged,
+            data: {
+              deviceId: ancestorId,
+              field: "location",
+              value: fills[0]?.location ?? null
+            }
+          });
+          logger.info("location backfill: aligned location-less descendants to their ancestor", {
+            tags: { deviceId: ancestorId },
+            meta: {
+              location: fills[0]?.location,
+              updatedIds: fills.map((f) => f.id)
+            }
+          });
+        }
+        if (failed.length > 0) logger.error("location backfill partially failed \u2014 retrying on the next boot", { meta: {
+          failedIds: failed.map((f) => f.id),
+          errors: failed.map((f) => f.error instanceof Error ? f.error.message : String(f.error))
+        } });
+        else await pctx.metaStore.withAddonStoreWriteLock(async () => {
+          await pctx.settings.writeAddonStore({ [LOCATION_BACKFILL_MARKER_KEY]: 1 });
+        });
+      }
+      const residual = planNullLocationFills((!repaired && bootRows !== void 0 ? bootRows : await pctx.metaStore.rows.listAll()).map((r) => r.meta));
+      for (const [ancestorId, fills] of groupByAncestor(residual)) logger.warn("location cascade misaligned \u2014 location-less descendants under a located ancestor never match location auto-link; re-save the ancestor location to realign", {
+        tags: { deviceId: ancestorId },
+        meta: {
+          location: fills[0]?.location,
+          misalignedDescendantIds: fills.map((f) => f.id)
+        }
+      });
+    }
     async function stampIntegrationId(metaStore, ctx, deviceId, integrationId) {
       await metaStore.withMetaWriteLock(async () => {
         if (!await metaStore.resolvePersistedById(deviceId)) throw new Error(`[device-manager] stampIntegrationId: unknown device id=${deviceId}`);
@@ -66926,7 +67140,7 @@ var require_device_manager_addon = __commonJS({
     async function registerDevice(pctx, input) {
       const { addonId, stableId, id, type, name, parentDeviceId, features, config } = input;
       const featuresArr = Array.isArray(features) ? [...features] : [];
-      const { isFirstRegistration, exportFingerprint, fingerprintChanged } = await pctx.metaStore.withMetaWriteLock(async () => {
+      const { isFirstRegistration, exportFingerprint, fingerprintChanged, inheritedLocation, inheritedDescendantIds, inheritFailed } = await pctx.metaStore.withMetaWriteLock(async () => {
         const existingRow = await pctx.metaStore.rows.get(id);
         const existingMeta = existingRow?.meta;
         const wasRegistered = existingRow?.registered ?? false;
@@ -66938,6 +67152,10 @@ var require_device_manager_addon = __commonJS({
           deviceType: type,
           features: featuresArr
         });
+        const priorLocation = existingMeta?.location ?? null;
+        const resolvedParentId = parentDeviceId ?? null;
+        const parentChanged = existingMeta !== void 0 && (existingMeta.parentDeviceId ?? null) !== resolvedParentId;
+        const inherited = priorLocation === null && resolvedParentId !== null && (isFirst || parentChanged) ? await resolveInheritedLocation(pctx.metaStore.rows, resolvedParentId) : null;
         await pctx.metaStore.rows.upsertRegistration({
           deviceId: id,
           addonId,
@@ -66945,21 +67163,69 @@ var require_device_manager_addon = __commonJS({
           type,
           name: resolvedName,
           userNamed: wasUserNamed,
-          location: existingMeta?.location ?? null,
+          location: priorLocation ?? inherited,
           disabled: existingMeta?.disabled ?? false,
-          parentDeviceId: parentDeviceId ?? null,
+          parentDeviceId: resolvedParentId,
           registered: true,
           features: featuresArr,
           exportFingerprint: fingerprint
         });
+        const descendantsFilled = [];
+        const descendantsFailed = [];
+        if (inherited !== null) for (const descendant of await collectDescendants(pctx.metaStore, id)) {
+          if (descendant.location !== null) continue;
+          try {
+            await pctx.metaStore.rows.patch(descendant.id, { location: inherited });
+            descendantsFilled.push(descendant.id);
+          } catch (err) {
+            descendantsFailed.push({
+              id: descendant.id,
+              error: err
+            });
+          }
+        }
         return {
           isFirstRegistration: isFirst,
           exportFingerprint: fingerprint,
-          fingerprintChanged: existingMeta?.exportFingerprint !== fingerprint
+          fingerprintChanged: existingMeta?.exportFingerprint !== fingerprint,
+          inheritedLocation: inherited,
+          inheritedDescendantIds: descendantsFilled,
+          inheritFailed: descendantsFailed
         };
       });
       if (Object.keys(config).length > 0) await pctx.settings.writeDeviceStore(id, config);
       pctx.metaStore.idToAddonId.set(id, addonId);
+      if (inheritedLocation !== null) {
+        for (const changedId of [id, ...inheritedDescendantIds]) pctx.host.ctx.eventBus.emit({
+          id: (0, node_crypto.randomUUID)(),
+          timestamp: /* @__PURE__ */ new Date(),
+          source: {
+            type: "device",
+            id: changedId
+          },
+          category: require_dist10.EventCategory.DeviceMetaChanged,
+          data: {
+            deviceId: changedId,
+            field: "location",
+            value: inheritedLocation
+          }
+        });
+        pctx.host.ctx.logger.info("registerDevice: inherited located-ancestor location", {
+          tags: { deviceId: id },
+          meta: {
+            location: inheritedLocation,
+            descendantsFilled: inheritedDescendantIds.length
+          }
+        });
+        if (inheritFailed.length > 0) pctx.host.ctx.logger.error("registerDevice: inherited-location fill partially failed \u2014 some descendants NOT aligned", {
+          tags: { deviceId: id },
+          meta: {
+            location: inheritedLocation,
+            failedIds: inheritFailed.map((f) => f.id),
+            errors: inheritFailed.map((f) => f.error instanceof Error ? f.error.message : String(f.error))
+          }
+        });
+      }
       if (isFirstRegistration) pctx.host.ctx.eventBus.emit({
         id: (0, node_crypto.randomUUID)(),
         timestamp: /* @__PURE__ */ new Date(),
@@ -69142,7 +69408,8 @@ var require_device_manager_addon = __commonJS({
         const stateMirror = this.stateMirrorImpl;
         const resolvePersistedById = metaStore.resolvePersistedById;
         const idToAddonId = metaStore.idToAddonId;
-        for (const row of await deviceRows.listAll()) idToAddonId.set(row.meta.id, row.meta.addonId);
+        const bootRows = await deviceRows.listAll();
+        for (const row of bootRows) idToAddonId.set(row.meta.id, row.meta.addonId);
         const stampIntegrationId$1 = (deviceId, integrationId) => stampIntegrationId(metaStore, this.ctx, deviceId, integrationId);
         const pctx = {
           host: this.providerHost,
@@ -69157,6 +69424,11 @@ var require_device_manager_addon = __commonJS({
             return provider;
           }
         };
+        try {
+          await runLocationBackfillAtBoot(pctx, bootRows);
+        } catch (err) {
+          this.ctx.logger.warn("location backfill failed \u2014 fleet boots without it", { meta: { error: require_dist10.errMsg(err) } });
+        }
         const provider = {
           resolveDeviceOwnerSync: (deviceId) => resolveDeviceOwnerSync(pctx, deviceId),
           resolveNativeCapOwnerSync: (capName, deviceId) => resolveNativeCapOwnerSync(pctx, capName, deviceId),
@@ -69392,7 +69664,7 @@ var require_hub_forwarder = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var require_formatter = require_formatter_DqAKDlvN();
     var DEFAULT_OUTBOUND_BUFFER_SIZE = 500;
     var HubForwarderDestination = class {
@@ -69529,7 +69801,7 @@ var require_liveness_monitor_addon = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var NO_DEVICES = "liveness:no-devices";
     var ALL_OFFLINE = "liveness:all-devices-offline";
     var NO_FOOTAGE_PREFIX = "liveness:no-footage:";
@@ -69719,7 +69991,7 @@ var require_local_auth_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var node_crypto = __require("crypto");
     node_crypto = require_chunk.__toESM(node_crypto);
     var crypto$1 = __require("crypto");
@@ -77532,7 +77804,7 @@ var require_loki_logging = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     function sanitizeLabelName(raw) {
       const replaced = raw.replaceAll(/[^a-zA-Z0-9_]/g, "_");
       return /^[a-zA-Z_]/.test(replaced) ? replaced : `_${replaced}`;
@@ -78097,7 +78369,7 @@ var require_native_metrics_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var node_fs_promises = __require("fs/promises");
     var node_child_process = __require("child_process");
     var node_util = __require("util");
@@ -80681,7 +80953,7 @@ var require_filesystem_storage_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var node_crypto = __require("crypto");
     var node_fs_promises = __require("fs/promises");
     var node_path = __require("path");
@@ -81797,8 +82069,8 @@ var require_sqlite_settings_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
-    var require_retired_settings_keys = require_retired_settings_keys_BgUS9Rr3();
+    var require_dist10 = require_dist_0fjBDzUu();
+    var require_retired_settings_keys = require_retired_settings_keys_pL2Nq6KT();
     var node_crypto = __require("crypto");
     var node_fs = __require("fs");
     var node_module = __require("module");
@@ -84288,7 +84560,7 @@ var require_storage_orchestrator_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var require_hub_cap_forward = require_hub_cap_forward_DmHNjbB0();
     var zod = require_zod();
     var node_crypto = __require("crypto");
@@ -87239,7 +87511,7 @@ var require_system_config_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var SECTION_TITLES = {
       server: "Server",
       auth: "Authentication"
@@ -105300,7 +105572,7 @@ var require_winston_logging = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var require_formatter = require_formatter_DqAKDlvN();
     var node_path = __require("path");
     node_path = require_chunk.__toESM(node_path);
@@ -107243,9 +107515,9 @@ var require_event_category_BaEgqJNv = __commonJS({
   }
 });
 
-// ../types/dist/sleep-jdpPltQH.js
-var require_sleep_jdpPltQH = __commonJS({
-  "../types/dist/sleep-jdpPltQH.js"(exports) {
+// ../types/dist/sleep-BtIF8lWc.js
+var require_sleep_BtIF8lWc = __commonJS({
+  "../types/dist/sleep-BtIF8lWc.js"(exports) {
     "use strict";
     var require_event_category = require_event_category_BaEgqJNv();
     var zod = require_zod();
@@ -109236,6 +109508,7 @@ var require_sleep_jdpPltQH = __commonJS({
       DeviceRole2["GenericNotifier"] = "generic-notifier";
       return DeviceRole2;
     })({});
+    var DEVICE_CHILDREN_BATCH_MAX = 256;
     var StaticDirOutputSchema = zod.z.object({ staticDir: zod.z.string() });
     var VersionOutputSchema = zod.z.object({ version: zod.z.string() });
     var viewerUiCapability = {
@@ -110490,6 +110763,12 @@ var require_sleep_jdpPltQH = __commonJS({
         return DEFAULT_RUNTIME_STATE_DURABILITY;
       }
     });
+    Object.defineProperty(exports, "DEVICE_CHILDREN_BATCH_MAX", {
+      enumerable: true,
+      get: function() {
+        return DEVICE_CHILDREN_BATCH_MAX;
+      }
+    });
     Object.defineProperty(exports, "DEVICE_SCOPED_CAPS", {
       enumerable: true,
       get: function() {
@@ -110919,7 +111198,7 @@ var require_addon = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     var require_event_category = require_event_category_BaEgqJNv();
-    var require_sleep = require_sleep_jdpPltQH();
+    var require_sleep = require_sleep_BtIF8lWc();
     var require_err_msg = require_err_msg_COpsHMw2();
     var CAP_INPUT_DEFAULTS = Object.freeze({
       "addons": { "getLogs": { "limit": 100 } },
@@ -111237,6 +111516,7 @@ var require_addon = __commonJS({
     exports.CAP_INPUT_DEFAULTS = CAP_INPUT_DEFAULTS;
     exports.COLLECTION_ARRAY_METHODS = COLLECTION_ARRAY_METHODS;
     exports.DATAPLANE_SECRET_HEADER = require_sleep.DATAPLANE_SECRET_HEADER;
+    exports.DEVICE_CHILDREN_BATCH_MAX = require_sleep.DEVICE_CHILDREN_BATCH_MAX;
     exports.DEVICE_SCOPED_CAPS = require_sleep.DEVICE_SCOPED_CAPS;
     exports.DeviceType = require_sleep.DeviceType;
     exports.DisposerChain = require_sleep.DisposerChain;
@@ -117802,12 +118082,11 @@ var require_dist2 = __commonJS({
   }
 });
 
-// ../system/dist/manifest-system-deps-DMWd5Ygf.js
-var require_manifest_system_deps_DMWd5Ygf = __commonJS({
-  "../system/dist/manifest-system-deps-DMWd5Ygf.js"(exports) {
+// ../system/dist/manifest-system-deps-KBuTXH-y.js
+var require_manifest_system_deps_KBuTXH_y = __commonJS({
+  "../system/dist/manifest-system-deps-KBuTXH-y.js"(exports) {
     "use strict";
     var require_chunk = require_chunk_Cek0wNdY();
-    require_dist_DE3OH_FG();
     require_hub_cap_forward_DmHNjbB0();
     var node_crypto = __require("crypto");
     node_crypto = require_chunk.__toESM(node_crypto);
@@ -119305,7 +119584,7 @@ var require_manifest_system_deps_DMWd5Ygf = __commonJS({
       return lowered.includes("not_found") || lowered.includes("no procedure") || lowered.includes("unknown method") || lowered.includes("no such method") || lowered.includes("not available");
     }
     function createChildrenBatchLoader(opts) {
-      const maxBatch = Math.max(1, opts.maxBatch ?? 256);
+      const maxBatch = Math.max(1, opts.maxBatch ?? _camstack_types_addon.DEVICE_CHILDREN_BATCH_MAX);
       let pending = [];
       let flushScheduled = false;
       let flushing = false;
@@ -129874,7 +130153,7 @@ var require_dist3 = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_DE3OH_FG();
+    var require_dist10 = require_dist_0fjBDzUu();
     var require_builtins_alerts_alerts_addon = require_alerts_addon();
     require_alerts();
     var require_formatter = require_formatter_DqAKDlvN();
@@ -129901,7 +130180,7 @@ var require_dist3 = __commonJS({
     var require_builtins_winston_logging_index = require_winston_logging();
     var require_file_data_plane = require_file_data_plane_DO8KbxCe();
     var require_tls$1 = require_tls_BxQlomxd();
-    var require_manifest_system_deps = require_manifest_system_deps_DMWd5Ygf();
+    var require_manifest_system_deps = require_manifest_system_deps_KBuTXH_y();
     var require_resource_monitor = require_resource_monitor_CdnzxBLP();
     var require_custom_action_registry = require_custom_action_registry_jY0NOZK8();
     var zod = require_zod();
@@ -210991,7 +211270,7 @@ var require_dist4 = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     var require_event_category = require_event_category_BaEgqJNv();
-    var require_sleep = require_sleep_jdpPltQH();
+    var require_sleep = require_sleep_BtIF8lWc();
     var require_canonical_hash = require_canonical_hash_DNV8S5ET();
     var require_enums2 = require_enums();
     var require_err_msg = require_err_msg_COpsHMw2();
@@ -218451,7 +218730,6 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
         })
       }
     };
-    var DEVICE_CHILDREN_BATCH_MAX = 256;
     var ChildLayoutEntrySchema = zod.z.object({
       childKey: zod.z.string(),
       section: zod.z.string(),
@@ -224869,12 +225147,28 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
       "staging",
       "trained"
     ]);
+    var MAX_TRACK_DEBUG_NOTE_LEN = 500;
     var TrackFlagFields = {
       /** Operator marked this track as training material — i.e. `retrainStatus` is
       *  `'staging'`. */
       markForTrain: zod.z.boolean().optional(),
       /** Operator marked this track for diagnostic attention. */
       debug: zod.z.boolean().optional(),
+      /**
+      * What the operator wants CHECKED on this track, in their own words.
+      *
+      * The flag alone says "look at this" and nothing about what for; a debug set
+      * reviewed hours later is a list of tracks with no question attached. Bound
+      * to `debug` on the WRITE side — the body clears it when `debug` goes off,
+      * and refuses it on a track whose debug is off — so a note can never outlive
+      * the attention it belongs to.
+      *
+      * `''` is a real value ("marked, nothing to add"); the ABSENT key means
+      * "leave whatever is stored alone", which is what lets a surface turn debug
+      * on without a note (a cancelled prompt) and what lets it edit the note
+      * without touching the flag.
+      */
+      debugNote: zod.z.string().max(500).optional(),
       /** Operator favourited this track. Pins it against pruning. */
       favourited: zod.z.boolean().optional()
     };
@@ -224884,6 +225178,12 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
       trackId: zod.z.string(),
       markForTrain: zod.z.boolean(),
       debug: zod.z.boolean(),
+      /** The note as it STANDS after the write — never absent here (a track with no
+      *  note reports `''`), for the same reason the booleans are required: a
+      *  surface that has just written must be able to render the note it now owns
+      *  without a re-fetch, and an absent key would read as "unchanged" on a
+      *  screen that has no previous value to keep. */
+      debugNote: zod.z.string(),
       favourited: zod.z.boolean(),
       /** The lifecycle state the boolean was derived from. Required here (unlike on
       *  a track row) because this shape is only ever produced by the write body,
@@ -225939,11 +226239,20 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
         * staging is a deliberate action of the retrain page, which is also the only
         * thing that produces `trained` in the first place.
         *
-        * Returns the RESOLVED state of both flags (absent → `false`) plus the
-        * `retrainStatus` they were derived from, so a caller can drive its toggle
-        * — and render a `trained` badge — without a re-fetch. Rejects an unknown
-        * track, a new staging mark on a device already holding its full budget, and
-        * any `markForTrain` write against a trained track.
+        * `debugNote` is the operator's sentence about WHAT to check on this track,
+        * and it is bound to `debug`: writing `debug: false` clears it in the same
+        * statement, and a note sent for a track whose debug is off (and is not
+        * being turned on) is DROPPED with a warning rather than stored where
+        * nothing will ever read it. An omitted `debugNote` leaves the stored one
+        * alone — which is what lets a surface turn debug on when the operator
+        * declined to type anything, without that refusal costing them the flag.
+        *
+        * Returns the RESOLVED state of all three flags (absent → `false`) plus the
+        * note (absent → `''`) and the `retrainStatus` they were derived from, so a
+        * caller can drive its toggle — and render a `trained` badge — without a
+        * re-fetch. Rejects an unknown track, a new staging mark on a device already
+        * holding its full budget, and any `markForTrain` write against a trained
+        * track.
         */
         setTrackFlags: require_sleep.method(zod.z.object({
           /** Log/audit scope only — the trackId is globally unique on its own. */
@@ -254477,7 +254786,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
     exports.DETECTION_PIPELINE_CAP_NAME = DETECTION_PIPELINE_CAP_NAME;
     exports.DEVICE_BACKEND_TO_FORMAT = DEVICE_BACKEND_TO_FORMAT;
     exports.DEVICE_CAP_NAMES = DEVICE_CAP_NAMES;
-    exports.DEVICE_CHILDREN_BATCH_MAX = DEVICE_CHILDREN_BATCH_MAX;
+    exports.DEVICE_CHILDREN_BATCH_MAX = require_sleep.DEVICE_CHILDREN_BATCH_MAX;
     exports.DEVICE_PROFILES = DEVICE_PROFILES;
     exports.DEVICE_RESTORE_RETRY_CONCURRENCY = DEVICE_RESTORE_RETRY_CONCURRENCY;
     exports.DEVICE_RESTORE_RETRY_DELAYS_MS = DEVICE_RESTORE_RETRY_DELAYS_MS;
@@ -254713,6 +255022,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
     exports.MAX_KEYS = MAX_KEYS;
     exports.MAX_REASONS_PER_KEY = MAX_REASONS_PER_KEY;
     exports.MAX_SENSOR_TRIGGER_DEVICES = MAX_SENSOR_TRIGGER_DEVICES;
+    exports.MAX_TRACK_DEBUG_NOTE_LEN = MAX_TRACK_DEBUG_NOTE_LEN;
     exports.METHOD_ACCESS_MAP = METHOD_ACCESS_MAP;
     exports.METHOD_DEVICE_SELECTORS = METHOD_DEVICE_SELECTORS;
     exports.MODEL_FORMATS = MODEL_FORMATS;
@@ -424248,9 +424558,9 @@ var require_agent_registry_service = __commonJS({
         }
         return nodes.delete(nodeId) === true;
       }
-      /** Typed view of the broker's node catalog — one documented boundary cast. */
+      /** Typed view of the broker's node catalog — reached through the ONE cast. */
       nodeCatalogRegistry() {
-        return this.moleculer.broker.registry;
+        return this.broker.registry;
       }
       /** Typed view of the Moleculer broker — single documented cast. */
       get broker() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camstack",
-  "version": "1.2.89",
+  "version": "1.2.91",
   "description": "CLI tool for managing and running CamStack server",
   "keywords": [
     "camstack",