@camstack/server 1.2.353 → 1.2.355

package/dist/api/capabilities.router.js

@@ -205,25 +205,15 @@ function createCapabilitiesRouter(addonRegistry, configService, loggingService)
             const overrides = registry.getDeviceOverrides(input.deviceId);
             return Object.fromEntries(overrides);
         }),
-        setDeviceCollectionFilter: trpc_middleware_1.adminProcedure
-            .input(zod_1.z.object({ deviceId: zod_1.z.string(), capability: zod_1.z.string(), addonIds: zod_1.z.array(zod_1.z.string()) }))
-            .mutation(({ input }) => {
-            const registry = addonRegistry.getCapabilityRegistry();
-            registry.setDeviceCollectionFilter(input.deviceId, input.capability, input.addonIds);
-            logger.info('Device collection filter set', {
-                tags: { deviceId: Number(input.deviceId) },
-                meta: { capability: input.capability, addonIds: input.addonIds },
-            });
-        }),
-        clearDeviceCollectionFilter: trpc_middleware_1.adminProcedure
-            .input(zod_1.z.object({ deviceId: zod_1.z.string(), capability: zod_1.z.string() }))
-            .mutation(({ input }) => {
-            const registry = addonRegistry.getCapabilityRegistry();
-            registry.clearDeviceCollectionFilter(input.deviceId, input.capability);
-            logger.info('Device collection filter cleared', {
-                tags: { deviceId: Number(input.deviceId) },
-                meta: { capability: input.capability },
-            });
-        }),
+        /*
+         * `setDeviceCollectionFilter` / `clearDeviceCollectionFilter` were REMOVED
+         * here (D556). They wrote an in-memory per-device allow list that nothing
+         * persisted, so an operator's pick survived until the next hub restart and
+         * then silently reverted — a control that looks like it works, which is the
+         * defect D62 exists for. Which sources a camera has is now asked of the ONE
+         * authority that already owned a per-camera function switch:
+         * `deviceManager.setWrapperActive`. The registry keeps only its projection,
+         * written by `device-source-activation.ts` and by nothing else.
+         */
     });
 }

package/dist/api/core/capabilities.router.js

@@ -114,25 +114,15 @@ function createCapabilitiesRouter(registry, config) {
             }
             return result;
         }),
-        setDeviceCollectionFilter: trpc_middleware_js_1.adminProcedure
-            .input(zod_1.z.object({
-            deviceId: zod_1.z.string(),
-            capability: zod_1.z.string(),
-            addonIds: zod_1.z.array(zod_1.z.string()),
-        }))
-            .output(zod_1.z.void())
-            .mutation(({ input }) => {
-            if (!registry)
-                throw new Error('Capability registry unavailable');
-            registry.setDeviceCollectionFilter(input.deviceId, input.capability, input.addonIds);
-        }),
-        clearDeviceCollectionFilter: trpc_middleware_js_1.adminProcedure
-            .input(zod_1.z.object({ deviceId: zod_1.z.string(), capability: zod_1.z.string() }))
-            .output(zod_1.z.void())
-            .mutation(({ input }) => {
-            if (!registry)
-                throw new Error('Capability registry unavailable');
-            registry.clearDeviceCollectionFilter(input.deviceId, input.capability);
-        }),
+        /*
+         * `setDeviceCollectionFilter` / `clearDeviceCollectionFilter` were REMOVED
+         * here (D556). They wrote an in-memory per-device allow list that nothing
+         * persisted, so an operator's pick survived until the next hub restart and
+         * then silently reverted — a control that looks like it works, which is the
+         * defect D62 exists for. Which sources a camera has is now asked of the ONE
+         * authority that already owned a per-camera function switch:
+         * `deviceManager.setWrapperActive`. The registry keeps only its projection,
+         * written by `device-source-activation.ts` and by nothing else.
+         */
     });
 }

package/dist/api/trpc/cap-router-runtime.js

@@ -28,8 +28,10 @@ exports.createCapRouterPrimitives = createCapRouterPrimitives;
 exports.createCapRouterServices = createCapRouterServices;
 exports.buildRuntimeCapRouters = buildRuntimeCapRouters;
 const system_1 = require("@camstack/system");
+const types_1 = require("@camstack/types");
 const server_1 = require("@trpc/server");
 const cap_mount_helpers_js_1 = require("./cap-mount-helpers.js");
+const device_collection_dispatch_js_1 = require("./device-collection-dispatch.js");
 const trpc_middleware_js_1 = require("./trpc.middleware.js");
 /**
  * Pre-computed set of capName → array-output method names for collection
@@ -41,7 +43,10 @@ exports.COLLECTION_ARRAY_METHODS = computeArrayMethods();
 function computeArrayMethods() {
     const out = new Map();
     for (const def of system_1.ALL_CAPABILITY_DEFINITIONS) {
-        if (def.mode !== 'collection')
+        // The effective MOUNT, never `mode`: a device-scoped wrapper collection
+        // (`videoclips`, D554) fans over ONE DEVICE's sources through the
+        // per-device dispatcher, and must never be fanned globally here.
+        if ((0, types_1.resolveCapMount)(def).kind !== 'collection')
             continue;
         const names = [];
         for (const [name, schema] of Object.entries(def.methods)) {
@@ -56,6 +61,22 @@ function computeArrayMethods() {
     }
     return out;
 }
+/**
+ * Is this cap served by the GLOBAL collection mount — every registered
+ * provider, for every caller?
+ *
+ * `mode: 'collection'` alone does not answer it any more: a device-scoped
+ * wrapper collection keeps the per-device mount (D554,
+ * `device-collection-dispatch.ts`), and fanning it globally here would answer
+ * one camera with another camera's sources on the `ctx.api` path while the
+ * tRPC path resolved per device — two authorities disagreeing about the same
+ * call, which is exactly what {@link aggregateCollectionCall} exists to
+ * prevent.
+ */
+function isGlobalCollection(reg, capName) {
+    const def = reg.getDefinition(capName);
+    return def !== undefined && (0, types_1.resolveCapMount)(def).kind === 'collection';
+}
 /**
  * Resolve a collection cap's provider exactly as the codegen-emitted
  * mount did:
@@ -108,7 +129,7 @@ function resolveCollectionProvider(reg, capName, addonId) {
 async function aggregateCollectionCall(reg, capName, method, args) {
     if (!reg)
         return null;
-    if (reg.getDefinition(capName)?.mode !== 'collection')
+    if (!isGlobalCollection(reg, capName))
         return null;
     if (!exports.COLLECTION_ARRAY_METHODS.get(capName)?.includes(method))
         return null;
@@ -141,7 +162,7 @@ async function aggregateCollectionCall(reg, capName, method, args) {
 function addonPinOf(reg, capName, method, args) {
     if (!reg)
         return null;
-    if (reg.getDefinition(capName)?.mode !== 'collection')
+    if (!isGlobalCollection(reg, capName))
         return null;
     if (exports.COLLECTION_ARRAY_METHODS.get(capName)?.includes(method) === true)
         return null;
@@ -258,8 +279,26 @@ function createCapRouterServices(deps) {
                 const factory = deps.serverProviders[capName];
                 return factory ? factory(ctx) : null;
             }
+            // Both per-device mounts go through the SAME dispatcher. It resolves
+            // `getNativeProvider` first (the provider IS the device) and falls
+            // through to the D13 resolver `getProviderForDevice` — which is what a
+            // `device-scoped` WRAPPER needs: the per-device binding
+            // (`setWrapperActive` → `setDeviceOverride`) when there is one, the
+            // global active provider when there is not. No second resolver.
             case 'device-native':
+            case 'device-scoped': {
+                // A device-scoped cap whose mode is `collection` has SEVERAL providers
+                // per device — sources listed beside each other (D549 decision 2,
+                // D554). `requireDeviceScoped` resolves exactly one of them, and on a
+                // collection cap `getProviderForDevice` answers with whichever addon
+                // registered FIRST: every camera served by one source, silently. The
+                // collection twin fans the array methods over the device's sources and
+                // routes the scalar ones by the source inside the id.
+                if (reg?.getMode(capName) === 'collection') {
+                    return (0, device_collection_dispatch_js_1.requireDeviceCollection)(reg, capName, deps.logger);
+                }
                 return (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, capName);
+            }
             case 'collection':
                 return resolveCollectionProvider(reg, capName, addonId);
             // singleton / per-node / hub-only resolve the active singleton.

package/dist/api/trpc/device-collection-dispatch.js

@@ -0,0 +1,484 @@
+"use strict";
+/**
+ * The per-device COLLECTION dispatcher — a capability whose providers are
+ * SOURCES of one device, listed beside each other.
+ *
+ * `requireDeviceScoped` (`cap-mount-helpers.ts`) resolves ONE provider for a
+ * device: the native, else the D13 `getProviderForDevice`. That is right for a
+ * cap where a device has one answer. `videoclips` is not that cap any more
+ * (D549 decision 2, D554): a camera's clips live in several places at once —
+ * the analytics visit log, the camera's own SD card, a hub's storage, HomeKit
+ * — and the operator asked for all of them, side by side, never one hidden
+ * behind another. `getProviderForDevice` on a collection cap returns the FIRST
+ * registered provider, so leaving `videoclips` on it would have answered every
+ * camera from whichever addon booted first: the same silent single-answer
+ * defect D552 closed, wearing a different hat.
+ *
+ * The three rules this module implements, and nothing else:
+ *
+ *  1. **Fan out, per device.** An ARRAY-returning method is called on every
+ *     source the DEVICE has (`CapabilityRegistry.resolveCollectionForDevice` —
+ *     the enabled providers, minus the ones the operator switched off for this
+ *     camera through `deviceManager.setWrapperActive`, D556), and the results
+ *     are concatenated. No dedup, no best-source
+ *     pick: a clip held in two storages appears twice, once per source, and
+ *     each row says which (D549 decision 11 — stated there as a consequence
+ *     precisely so it is not "fixed" later).
+ *  2. **One failing source never empties the others.** Every source is called
+ *     independently and a rejection removes only its own rows — and says so,
+ *     per source, with `tags: { deviceId }`. A fan-out where one throwing
+ *     provider empties the list is worse than no fan-out. For the SOURCE
+ *     listing itself the failure becomes a row (`unreachable` + the reason):
+ *     an empty list from a camera nobody could reach reads as "this camera has
+ *     no recordings", which is the defect this whole line of work is about.
+ *  3. **A scalar method routes by the SOURCE inside the id it carries.** Clip
+ *     ids are self-contained and source-prefixed (`analytics:…`,
+ *     `native:reolink:onboard:…`, `hksv:…`), so the dispatcher asks each
+ *     source which ids it owns ({@link SOURCE_LISTING_METHOD}) and hands the
+ *     call to the one that claims the longest matching prefix. An id nobody
+ *     claims is REFUSED by name — never handed to the first provider, which is
+ *     how a fabricated `addonId` once came back with another addon's answer
+ *     (D552 consequences, `rejectUnresolvedAddonPin`).
+ *
+ * A device with exactly ONE source skips 1's merge and 3's probe entirely: its
+ * rows are returned verbatim in the provider's own order and its scalar calls
+ * go straight through. That is not an optimisation — it is the promise that a
+ * camera with one provider behaves exactly as it did before this mount
+ * existed, and it is pinned by spec.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOURCE_LISTING_METHOD = void 0;
+exports.requireDeviceCollection = requireDeviceCollection;
+const system_1 = require("@camstack/system");
+const types_1 = require("@camstack/types");
+const server_1 = require("@trpc/server");
+/**
+ * The device-collection CONVENTION: a cap whose providers are sources declares
+ * this method, taking `{ deviceId }` and returning one row per source with a
+ * `source` id and an `availability` block. It is what makes rule 3 possible
+ * without a second registry of id prefixes — the provider that mints the ids
+ * is the one that names them.
+ */
+exports.SOURCE_LISTING_METHOD = 'listSources';
+/** The field on a source row that carries its id / clip-id namespace. */
+const SOURCE_ID_FIELD = 'source';
+/** The field on a source row that names the addon serving it (D555/D557). */
+const SOURCE_ADDON_FIELD = 'addonId';
+/** The field a source row carries the operator's off switch on (D556 amended). */
+const SOURCE_SWITCHED_OFF_FIELD = 'switchedOff';
+/** The availability field a switched-off row must not carry a value in. */
+const CATALOG_AGE_FIELD = 'catalogAsOf';
+/**
+ * EVERY source a DEVICE has, in registration order with the device's native
+ * provider first when it has one — each one marked with whether the operator
+ * switched it off.
+ *
+ * `resolveCollectionForDevice` decides which of the registered providers this
+ * device may use: it drops disabled ones and ones inactive for the system. The
+ * ones the operator switched OFF for this camera are NOT dropped here — they
+ * are marked, because a switched-off source must still produce a ROW to be
+ * switched back on from, and only its own provider can name it (D554 decision
+ * 4; D556 as amended). What that mark costs the source is everything else:
+ * {@link requireDeviceCollection} calls it for the source listing and for
+ * nothing else. The deny set is the registry's PROJECTION of the persisted
+ * wrapper activation — the operator's verb is `deviceManager.setWrapperActive`
+ * and the authority is its store, never a second one here (D556).
+ *
+ * `resolveCollectionForDevice` returns provider objects only, so the addon ids
+ * — needed to NAME a source that failed, to stamp the rows, and to apply the
+ * addon-grained half of the deny set — come from `getCollectionEntries` by
+ * object identity: both come from the same registry map in the same call, so
+ * the reference IS the key.
+ */
+function sourcesForDevice(registry, capName, deviceId) {
+    const admitted = new Set(registry.resolveCollectionForDevice(capName, String(deviceId), {
+        includeSwitchedOff: true,
+    }));
+    const sources = [];
+    const seen = new Set();
+    const native = registry.getNativeProvider(capName, deviceId);
+    if (native !== null) {
+        // The native is NOT in `state.providers`, so `resolveCollectionForDevice`
+        // never sees it — it is asked about separately, against the same authority
+        // (D556 decision 5). Without this the picker would carry one row the
+        // operator cannot switch off, and it is the camera's OWN recordings:
+        // exactly the source the external-videoclips line is about.
+        const nativeAddonId = registry.getNativeAddonId(capName, deviceId) ?? 'native';
+        sources.push({
+            addonId: nativeAddonId,
+            provider: native,
+            switchedOff: registry.isDeviceSourceDisabled(String(deviceId), capName, nativeAddonId),
+        });
+        seen.add(native);
+    }
+    for (const [addonId, provider] of registry.getCollectionEntries(capName)) {
+        if (!admitted.has(provider) || seen.has(provider))
+            continue;
+        seen.add(provider);
+        sources.push({
+            addonId,
+            provider,
+            switchedOff: registry.isDeviceSourceDisabled(String(deviceId), capName, addonId),
+        });
+    }
+    return sources;
+}
+/** Is `method` one of the cap's array-returning (fan-out) methods? */
+function isFanOutMethod(registry, capName, method) {
+    const def = registry.getDefinition(capName);
+    if (def === undefined)
+        return false;
+    const schema = (0, types_1.expandCapMethods)(def)[method];
+    if (schema === undefined || schema.kind === 'subscription')
+        return false;
+    return (0, types_1.isArrayOutputSchema)(schema.output);
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Call one source, naming the cap, the source and the method on any refusal. */
+async function callSource(source, method, input, capName, deviceId) {
+    const fn = source.provider[method];
+    if (typeof fn !== 'function') {
+        throw new server_1.TRPCError({
+            code: 'NOT_IMPLEMENTED',
+            message: `Capability "${capName}" source "${source.addonId}" for device ${deviceId} does not implement "${method}"`,
+        });
+    }
+    return await fn.call(source.provider, input);
+}
+/**
+ * The `startMs` a row is ordered by, or null when the row does not declare a
+ * time range. A merge across sources is newest-first (D549 decision 2's
+ * `(startMs, endMs, id)`); rows that carry no window — a source listing, say —
+ * keep the order their providers produced them in.
+ */
+function startMsOf(row) {
+    if (row === null || typeof row !== 'object')
+        return null;
+    const range = Reflect.get(row, 'timeRange');
+    if (range === null || typeof range !== 'object')
+        return null;
+    const startMs = Reflect.get(range, 'startMs');
+    return typeof startMs === 'number' ? startMs : null;
+}
+function endMsOf(row) {
+    if (row === null || typeof row !== 'object')
+        return 0;
+    const range = Reflect.get(row, 'timeRange');
+    if (range === null || typeof range !== 'object')
+        return 0;
+    const endMs = Reflect.get(range, 'endMs');
+    return typeof endMs === 'number' ? endMs : 0;
+}
+function idOf(row) {
+    if (row === null || typeof row !== 'object')
+        return '';
+    const id = Reflect.get(row, 'id');
+    return typeof id === 'string' ? id : '';
+}
+/** Newest-first by `(startMs, endMs, id)`; applied only when EVERY row has a window. */
+function mergeRows(rows) {
+    if (rows.some((row) => startMsOf(row) === null))
+        return rows;
+    return [...rows].sort((a, b) => {
+        const byStart = (startMsOf(b) ?? 0) - (startMsOf(a) ?? 0);
+        if (byStart !== 0)
+            return byStart;
+        const byEnd = endMsOf(b) - endMsOf(a);
+        if (byEnd !== 0)
+            return byEnd;
+        return idOf(a).localeCompare(idOf(b));
+    });
+}
+/**
+ * The row a source listing gets when the source could not be reached AT ALL.
+ *
+ * The source id is the addon's, because a provider that threw could not name
+ * its own sources — saying "this provider, as a whole, did not answer" is the
+ * honest version, and the reason carries the refusal verbatim. Never composed
+ * with a provider's output: this row replaces rows that do not exist.
+ */
+function unreachableSourceRow(addonId, reason) {
+    return {
+        [SOURCE_ID_FIELD]: addonId,
+        label: addonId,
+        availability: { state: 'unreachable', reason },
+    };
+}
+async function fanOut(registry, sources, method, input, capName, deviceId, logger) {
+    const isSourceListing = method === exports.SOURCE_LISTING_METHOD;
+    const settled = await Promise.allSettled(sources.map(async (source) => await callSource(source, method, input, capName, deviceId)));
+    const rows = [];
+    for (const [index, result] of settled.entries()) {
+        const source = sources[index];
+        if (source === undefined)
+            continue;
+        if (result.status === 'rejected') {
+            const reason = errMessage(result.reason);
+            // A branch that drops work says so — a fan-out that silently loses a
+            // source is indistinguishable from a camera that has none.
+            logger?.warn(`${capName}.${method}: source failed — its rows are missing from this answer`, {
+                tags: { deviceId, addonId: source.addonId },
+                meta: { capability: capName, method, reason },
+            });
+            if (isSourceListing)
+                rows.push(unreachableSourceRow(source.addonId, reason));
+            continue;
+        }
+        if (!Array.isArray(result.value)) {
+            logger?.warn(`${capName}.${method}: source answered a non-array — contributing nothing`, {
+                tags: { deviceId, addonId: source.addonId },
+                meta: { capability: capName, method },
+            });
+            continue;
+        }
+        rows.push(...finishRows(registry, capName, deviceId, source, result.value, isSourceListing));
+    }
+    return mergeRows(rows);
+}
+/**
+ * The availability block without its catalog age.
+ *
+ * `catalogAsOf` means "when this source's catalog was last CONFIRMED". A source
+ * the operator switched off is never asked for a catalog, so it has no
+ * confirmation to report and will never get a fresher one — and an age that can
+ * only grow draws a STALLING source rather than an off switch (D62: disabled
+ * must never look like broken). The rest of the block is left exactly as the
+ * provider said it: what the source CAN do is a different question from whether
+ * it may.
+ */
+function withoutCatalogAge(availability) {
+    if (availability === null || typeof availability !== 'object')
+        return availability;
+    return Object.fromEntries(Object.entries(availability).filter(([key]) => key !== CATALOG_AGE_FIELD));
+}
+/**
+ * Stamp each row with the addon that really served it, mark a source listing
+ * row the operator switched off, and drop the CLIP rows of such a source.
+ *
+ * The two halves are deliberately asymmetric, and that asymmetry is the whole
+ * of D556's amendment: a switched-off source contributes no clips (the point of
+ * the switch) and keeps its row (the control the switch is undone from). A
+ * `listSources` that dropped the row left an unticked source with nothing to
+ * un-tick — on a Reolink camera, which has exactly one source since D555's
+ * collapse, that is the entire picker.
+ *
+ * **The stamp** is authoritative: a surface cannot otherwise resolve a source
+ * row to who answers it, and the alternative — a `native:reolink:* →
+ * provider-reolink` prefix table inside the widget — is a second authority on
+ * provider identity living in the one package with no business knowing it
+ * (D557). The registry's id is a fact; a provider's own value is a claim, so
+ * the fact wins.
+ *
+ * **The drop** happens here rather than in `sourcesForDevice` because one
+ * addon serves SEVERAL of a device's sources (`addon-provider-reolink` answers
+ * a hub child with `onboard` AND `hub`), so dropping the PROVIDER would turn
+ * off every source it has while the operator ticked one. Rows are where
+ * sources are actually named, so this is the grain the per-source authority
+ * applies at — same registry projection, same migration rule, one step finer.
+ *
+ * A camera with NO deny entry is untouched: the rows come back verbatim, in
+ * the provider's own order, which is D554 decision 6's guarantee and today's
+ * behaviour for every camera on the fleet.
+ */
+function finishRows(registry, capName, deviceId, source, rows, isSourceListing) {
+    const denied = registry.getDeviceDisabledSources(String(deviceId), capName);
+    const out = [];
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object') {
+            out.push(row);
+            continue;
+        }
+        const rowSourceId = Reflect.get(row, SOURCE_ID_FIELD);
+        // ONE predicate for the whole deny set, migration rule included: an entry
+        // is a source id, or (pre-re-key, D555) the id of the addon that serves it.
+        const off = denied.length > 0 &&
+            (0, system_1.isSourceDenied)(denied, {
+                addonId: source.addonId,
+                ...(typeof rowSourceId === 'string' ? { sourceId: rowSourceId } : {}),
+            });
+        if (isSourceListing) {
+            const stamped = {
+                ...row,
+                [SOURCE_ADDON_FIELD]: source.addonId,
+            };
+            out.push(off
+                ? {
+                    ...stamped,
+                    availability: withoutCatalogAge(Reflect.get(row, 'availability')),
+                    [SOURCE_SWITCHED_OFF_FIELD]: true,
+                }
+                : stamped);
+            continue;
+        }
+        if (off)
+            continue;
+        out.push(row);
+    }
+    return out;
+}
+async function claimsOf(sources, capName, deviceId, logger) {
+    const claimed = new Map();
+    const unknownClaims = [];
+    const settled = await Promise.allSettled(sources.map(async (source) => await callSource(source, exports.SOURCE_LISTING_METHOD, { deviceId }, capName, deviceId)));
+    for (const [index, result] of settled.entries()) {
+        const source = sources[index];
+        if (source === undefined)
+            continue;
+        if (result.status === 'rejected' || !Array.isArray(result.value)) {
+            // It could not name its sources, so it cannot be excluded on that basis
+            // either — a read that FAILS must not destroy work (D49).
+            logger?.warn(`${capName}.${exports.SOURCE_LISTING_METHOD}: source could not name its ids — routing falls back to it only if it is the only such source`, {
+                tags: { deviceId, addonId: source.addonId },
+                meta: {
+                    capability: capName,
+                    reason: result.status === 'rejected' ? errMessage(result.reason) : 'non-array answer',
+                },
+            });
+            unknownClaims.push(source);
+            continue;
+        }
+        for (const row of result.value) {
+            if (row === null || typeof row !== 'object')
+                continue;
+            const id = Reflect.get(row, SOURCE_ID_FIELD);
+            if (typeof id === 'string' && id.length > 0 && !claimed.has(id))
+                claimed.set(id, source);
+        }
+    }
+    return { claimed, unknownClaims };
+}
+/** Every top-level string value of an object input — the candidate routing keys. */
+function stringFieldsOf(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return [];
+    const out = [];
+    for (const value of Object.values(input)) {
+        if (typeof value === 'string' && value.length > 0)
+            out.push(value);
+    }
+    return out;
+}
+/**
+ * The source that owns a source-prefixed id: `<sourceId>` itself, or anything
+ * under `<sourceId>:`. The LONGEST matching source wins, so
+ * `native:reolink:onboard` beats a hypothetical `native:reolink`.
+ */
+function ownerOf(claims, input) {
+    let best = null;
+    for (const value of stringFieldsOf(input)) {
+        for (const [sourceId, source] of claims.claimed) {
+            if (value !== sourceId && !value.startsWith(`${sourceId}:`))
+                continue;
+            if (best === null || sourceId.length > best.sourceId.length)
+                best = { source, sourceId };
+        }
+    }
+    return best;
+}
+async function dispatchScalar(sources, method, input, capName, deviceId, logger) {
+    const claims = await claimsOf(sources, capName, deviceId, logger);
+    const owner = ownerOf(claims, input);
+    if (owner !== null)
+        return await callSource(owner.source, method, input, capName, deviceId);
+    const fallback = claims.unknownClaims.length === 1 ? claims.unknownClaims[0] : undefined;
+    if (fallback !== undefined) {
+        logger?.warn(`${capName}.${method}: no source claimed this id — using the one source that could not name its ids`, {
+            tags: { deviceId, addonId: fallback.addonId },
+            meta: { capability: capName, method },
+        });
+        return await callSource(fallback, method, input, capName, deviceId);
+    }
+    const known = [...claims.claimed.keys()];
+    logger?.warn(`${capName}.${method}: refused — no source of this device claims the id`, {
+        tags: { deviceId },
+        meta: { capability: capName, method, knownSources: known, input },
+    });
+    throw new server_1.TRPCError({
+        code: 'BAD_REQUEST',
+        message: `Capability "${capName}.${method}": no source of device ${deviceId} claims ` +
+            `${JSON.stringify(input)}. Sources: ${known.length > 0 ? known.join(', ') : '(none named)'}. ` +
+            `An unclaimed id is refused rather than answered by another source.`,
+    });
+}
+/**
+ * Build the per-device COLLECTION dispatcher for `capName` — the collection
+ * twin of `requireDeviceScoped`, and the provider object the cap router's
+ * `device-scoped` mount resolves when the cap's mode is `collection`.
+ *
+ * Returns null without a registry (the router then surfaces
+ * PRECONDITION_FAILED), exactly as the singleton dispatcher does.
+ */
+function requireDeviceCollection(registry, capName, logger) {
+    if (!registry)
+        return null;
+    const dispatcher = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            return async (input) => {
+                const deviceId = input !== null && typeof input === 'object' ? Reflect.get(input, 'deviceId') : undefined;
+                if (typeof deviceId !== 'number') {
+                    throw new server_1.TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: `${capName}.${prop}: input must carry numeric "deviceId"`,
+                    });
+                }
+                const all = sourcesForDevice(registry, capName, deviceId);
+                if (all.length === 0) {
+                    throw new server_1.TRPCError({
+                        code: 'PRECONDITION_FAILED',
+                        message: `Capability "${capName}" not registered for device ${deviceId}`,
+                    });
+                }
+                // The LISTING sees every source the device has, switched off or not
+                // — that row is the only control the operator has to switch one back
+                // on. Everything else sees the SERVING set.
+                const listing = prop === exports.SOURCE_LISTING_METHOD;
+                const sources = listing ? all : all.filter((source) => !source.switchedOff);
+                if (sources.length === 0) {
+                    // Every source is switched off. That is an operator's decision and
+                    // not a missing provider, so it must not wear PRECONDITION_FAILED's
+                    // "not registered" — the rows say which it is, and the answer to
+                    // "what clips does it have" is honestly none (D556 left this open).
+                    logger?.info(`${capName}.${prop}: every source of this device is switched off`, {
+                        tags: { deviceId },
+                        meta: { capability: capName, method: prop, sources: all.map((s) => s.addonId) },
+                    });
+                    if (isFanOutMethod(registry, capName, prop))
+                        return [];
+                    throw new server_1.TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: `Capability "${capName}.${prop}": every source of device ${deviceId} is ` +
+                            `switched off for this camera. Switch one back on to serve it.`,
+                    });
+                }
+                const first = sources[0];
+                if (isFanOutMethod(registry, capName, prop)) {
+                    // One source is not a merge: its rows travel verbatim, in its own
+                    // order, so a camera with one provider answers exactly as it did
+                    // before this dispatcher existed.
+                    if (sources.length === 1 && first !== undefined) {
+                        // One PROVIDER is not a merge — but it may still serve several
+                        // SOURCES, and the operator may have switched one of them off.
+                        // So the rows are finished (stamped, and filtered by source)
+                        // even here; with no deny entry that is the identity function,
+                        // so an untouched camera answers exactly as it did before
+                        // (D554 decision 6).
+                        const answered = await callSource(first, prop, input, capName, deviceId);
+                        if (!Array.isArray(answered))
+                            return answered;
+                        return finishRows(registry, capName, deviceId, first, answered, prop === exports.SOURCE_LISTING_METHOD);
+                    }
+                    return await fanOut(registry, sources, prop, input, capName, deviceId, logger);
+                }
+                if (sources.length === 1 && first !== undefined) {
+                    return await callSource(first, prop, input, capName, deviceId);
+                }
+                return await dispatchScalar(sources, prop, input, capName, deviceId, logger);
+            };
+        },
+    });
+    return dispatcher;
+}

package/dist/api/trpc/generated-cap-mounts.js

@@ -78,7 +78,7 @@ function mountAllCaps(services) {
         alarmPanel: (0, generated_cap_routers_js_1.createCapRouter_alarmPanel)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'alarm-panel'), remoteCapProxy),
         alerts: (0, generated_cap_routers_js_1.createCapRouter_alerts)((_ctx) => reg?.getSingleton('alerts') ?? null, remoteCapProxy),
         ambientLightSensor: (0, generated_cap_routers_js_1.createCapRouter_ambientLightSensor)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'ambient-light-sensor'), remoteCapProxy),
-        audioAnalysis: (0, generated_cap_routers_js_1.createCapRouter_audioAnalysis)((_ctx) => reg?.getSingleton('audio-analysis') ?? null, remoteCapProxy),
+        audioAnalysis: (0, generated_cap_routers_js_1.createCapRouter_audioAnalysis)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'audio-analysis'), remoteCapProxy),
         audioAnalyzer: (0, generated_cap_routers_js_1.createCapRouter_audioAnalyzer)((_ctx) => reg?.getSingleton('audio-analyzer') ?? null, remoteCapProxy),
         audioCodec: (0, generated_cap_routers_js_1.createCapRouter_audioCodec)((_ctx) => reg?.getSingleton('audio-codec') ?? null, remoteCapProxy),
         audioMetrics: (0, generated_cap_routers_js_1.createCapRouter_audioMetrics)((_ctx) => reg?.getSingleton('audio-metrics') ?? null, remoteCapProxy),
@@ -107,8 +107,8 @@ function mountAllCaps(services) {
         button: (0, generated_cap_routers_js_1.createCapRouter_button)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'button'), remoteCapProxy),
         cameraCredentials: (0, generated_cap_routers_js_1.createCapRouter_cameraCredentials)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'camera-credentials'), remoteCapProxy),
         cameraGridLayout: (0, generated_cap_routers_js_1.createCapRouter_cameraGridLayout)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'camera-grid-layout'), remoteCapProxy),
-        cameraPipelineConfig: (0, generated_cap_routers_js_1.createCapRouter_cameraPipelineConfig)((_ctx) => reg?.getSingleton('camera-pipeline-config') ?? null, remoteCapProxy),
-        cameraStreams: (0, generated_cap_routers_js_1.createCapRouter_cameraStreams)((_ctx) => reg?.getSingleton('camera-streams') ?? null, remoteCapProxy),
+        cameraPipelineConfig: (0, generated_cap_routers_js_1.createCapRouter_cameraPipelineConfig)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'camera-pipeline-config'), remoteCapProxy),
+        cameraStreams: (0, generated_cap_routers_js_1.createCapRouter_cameraStreams)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'camera-streams'), remoteCapProxy),
         carbonMonoxide: (0, generated_cap_routers_js_1.createCapRouter_carbonMonoxide)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'carbon-monoxide'), remoteCapProxy),
         climateControl: (0, generated_cap_routers_js_1.createCapRouter_climateControl)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'climate-control'), remoteCapProxy),
         color: (0, generated_cap_routers_js_1.createCapRouter_color)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'color'), remoteCapProxy),
@@ -162,7 +162,7 @@ function mountAllCaps(services) {
         }, remoteCapProxy),
         dayNight: (0, generated_cap_routers_js_1.createCapRouter_dayNight)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'day-night'), remoteCapProxy),
         decoder: (0, generated_cap_routers_js_1.createCapRouter_decoder)((_ctx) => reg?.getSingleton('decoder') ?? null, remoteCapProxy),
-        detectionPipeline: (0, generated_cap_routers_js_1.createCapRouter_detectionPipeline)((_ctx) => reg?.getSingleton('detection-pipeline') ?? null, remoteCapProxy),
+        detectionPipeline: (0, generated_cap_routers_js_1.createCapRouter_detectionPipeline)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'detection-pipeline'), remoteCapProxy),
         deviceAdoption: (0, generated_cap_routers_js_1.createCapRouter_deviceAdoption)((_ctx) => reg?.getSingleton('device-adoption') ??
             null, remoteCapProxy),
         deviceDiscovery: (0, generated_cap_routers_js_1.createCapRouter_deviceDiscovery)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'device-discovery'), remoteCapProxy),
@@ -337,8 +337,7 @@ function mountAllCaps(services) {
         modelDistributor: (0, generated_cap_routers_js_1.createCapRouter_modelDistributor)((_ctx) => reg?.getSingleton('model-distributor') ??
             null, remoteCapProxy),
         motion: (0, generated_cap_routers_js_1.createCapRouter_motion)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'motion'), remoteCapProxy),
-        motionDetection: (0, generated_cap_routers_js_1.createCapRouter_motionDetection)((_ctx) => reg?.getSingleton('motion-detection') ??
-            null, remoteCapProxy),
+        motionDetection: (0, generated_cap_routers_js_1.createCapRouter_motionDetection)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'motion-detection'), remoteCapProxy),
         motionTrigger: (0, generated_cap_routers_js_1.createCapRouter_motionTrigger)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'motion-trigger'), remoteCapProxy),
         motionZones: (0, generated_cap_routers_js_1.createCapRouter_motionZones)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'motion-zones'), remoteCapProxy),
         mqttBroker: (0, generated_cap_routers_js_1.createCapRouter_mqttBroker)((_ctx, addonId) => {
@@ -412,7 +411,7 @@ function mountAllCaps(services) {
         osd: (0, generated_cap_routers_js_1.createCapRouter_osd)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'osd'), remoteCapProxy),
         osdManager: (0, generated_cap_routers_js_1.createCapRouter_osdManager)((_ctx) => reg?.getSingleton('osd-manager') ?? null, remoteCapProxy),
         petFeeder: (0, generated_cap_routers_js_1.createCapRouter_petFeeder)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'pet-feeder'), remoteCapProxy),
-        pipelineAnalytics: (0, generated_cap_routers_js_1.createCapRouter_pipelineAnalytics)((_ctx) => reg?.getSingleton('pipeline-analytics') ?? null, remoteCapProxy),
+        pipelineAnalytics: (0, generated_cap_routers_js_1.createCapRouter_pipelineAnalytics)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'pipeline-analytics'), remoteCapProxy),
         pipelineExecutor: (0, generated_cap_routers_js_1.createCapRouter_pipelineExecutor)((_ctx) => reg?.getSingleton('pipeline-executor') ??
             null, remoteCapProxy),
         pipelineOrchestrator: (0, generated_cap_routers_js_1.createCapRouter_pipelineOrchestrator)((_ctx) => reg?.getSingleton('pipeline-orchestrator') ?? null, remoteCapProxy),
@@ -431,7 +430,7 @@ function mountAllCaps(services) {
         recordingExport: (0, generated_cap_routers_js_1.createCapRouter_recordingExport)((_ctx) => reg?.getSingleton('recording-export') ??
             null, remoteCapProxy),
         recordingSignal: (0, generated_cap_routers_js_1.createCapRouter_recordingSignal)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'recording-signal'), remoteCapProxy),
-        sceneMonitor: (0, generated_cap_routers_js_1.createCapRouter_sceneMonitor)((_ctx) => reg?.getSingleton('scene-monitor') ?? null, remoteCapProxy),
+        sceneMonitor: (0, generated_cap_routers_js_1.createCapRouter_sceneMonitor)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'scene-monitor'), remoteCapProxy),
         scriptRunner: (0, generated_cap_routers_js_1.createCapRouter_scriptRunner)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'script-runner'), remoteCapProxy),
         serverManagement: (0, generated_cap_routers_js_1.createCapRouter_serverManagement)((_ctx) => reg?.getSingleton('server-management') ??
             null, remoteCapProxy),
@@ -542,7 +541,7 @@ function mountAllCaps(services) {
         valve: (0, generated_cap_routers_js_1.createCapRouter_valve)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'valve'), remoteCapProxy),
         vectorStore: (0, generated_cap_routers_js_1.createCapRouter_vectorStore)((_ctx) => reg?.getSingleton('vector-store') ?? null, remoteCapProxy),
         vibration: (0, generated_cap_routers_js_1.createCapRouter_vibration)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'vibration'), remoteCapProxy),
-        videoclips: (0, generated_cap_routers_js_1.createCapRouter_videoclips)((_ctx) => reg?.getSingleton('videoclips') ?? null, remoteCapProxy),
+        videoclips: (0, generated_cap_routers_js_1.createCapRouter_videoclips)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'videoclips'), remoteCapProxy),
         viewerUi: (0, generated_cap_routers_js_1.createCapRouter_viewerUi)((_ctx) => reg?.getSingleton('viewer-ui') ?? null, remoteCapProxy),
         waterHeater: (0, generated_cap_routers_js_1.createCapRouter_waterHeater)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'water-heater'), remoteCapProxy),
         weather: (0, generated_cap_routers_js_1.createCapRouter_weather)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'weather'), remoteCapProxy),

package/dist/api/trpc/generated-cap-routers.js

@@ -10733,7 +10733,7 @@ function createCapRouter_vibration(getProvider, createRemoteProxy) {
 }
 function createCapRouter_videoclips(getProvider, createRemoteProxy) {
     return (0, trpc_middleware_js_1.trpcRouter)({
-        listClips: trpc_middleware_js_1.adminProcedure
+        listClips: trpc_middleware_js_1.protectedProcedure
             .input(types_126.videoclipsCapability.methods.listClips.input.loose())
             .output(types_126.videoclipsCapability.methods.listClips.output)
             .query(async ({ input, ctx }) => {
@@ -10742,7 +10742,16 @@ function createCapRouter_videoclips(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.listClips(methodInput);
         }),
-        getClipPlayback: trpc_middleware_js_1.adminProcedure
+        listSources: trpc_middleware_js_1.protectedProcedure
+            .input(types_126.videoclipsCapability.methods.listSources.input.loose())
+            .output(types_126.videoclipsCapability.methods.listSources.output)
+            .query(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('videoclips', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.listSources(methodInput);
+        }),
+        getClipPlayback: trpc_middleware_js_1.protectedProcedure
             .input(types_126.videoclipsCapability.methods.getClipPlayback.input.loose())
             .output(types_126.videoclipsCapability.methods.getClipPlayback.output)
             .query(async ({ input, ctx }) => {

package/dist/server-root/index.js

@@ -83,9 +83,13 @@ var require_dist = __commonJS({
       PENDING_ROOT_SWAP_FILE: /* @__PURE__ */ __name(() => PENDING_ROOT_SWAP_FILE, "PENDING_ROOT_SWAP_FILE"),
       REQUIRED_NATIVE_PACKAGES: /* @__PURE__ */ __name(() => REQUIRED_NATIVE_PACKAGES, "REQUIRED_NATIVE_PACKAGES"),
       RESTART_INTENT_FILE: /* @__PURE__ */ __name(() => RESTART_INTENT_FILE, "RESTART_INTENT_FILE"),
+      ROLLBACK_UNSUPPORTED_REASON: /* @__PURE__ */ __name(() => ROLLBACK_UNSUPPORTED_REASON, "ROLLBACK_UNSUPPORTED_REASON"),
       RootUpdateService: /* @__PURE__ */ __name(() => RootUpdateService, "RootUpdateService"),
       SERVER_ROOT_DIRNAME: /* @__PURE__ */ __name(() => SERVER_ROOT_DIRNAME, "SERVER_ROOT_DIRNAME"),
       SERVER_ROOT_STATE_FILE: /* @__PURE__ */ __name(() => SERVER_ROOT_STATE_FILE, "SERVER_ROOT_STATE_FILE"),
+      STAGING_ATTEMPTS: /* @__PURE__ */ __name(() => STAGING_ATTEMPTS, "STAGING_ATTEMPTS"),
+      STAGING_FAILED_REASON: /* @__PURE__ */ __name(() => STAGING_FAILED_REASON, "STAGING_FAILED_REASON"),
+      STAGING_RETRY_DELAYS_MS: /* @__PURE__ */ __name(() => STAGING_RETRY_DELAYS_MS, "STAGING_RETRY_DELAYS_MS"),
       applyPendingRootSwap: /* @__PURE__ */ __name(() => applyPendingRootSwap, "applyPendingRootSwap"),
       assessImageContract: /* @__PURE__ */ __name(() => assessImageContract, "assessImageContract"),
       clearPendingRootSwap: /* @__PURE__ */ __name(() => clearPendingRootSwap, "clearPendingRootSwap"),
@@ -105,6 +109,7 @@ var require_dist = __commonJS({
       isDevChannelVersion: /* @__PURE__ */ __name(() => isDevChannelVersion, "isDevChannelVersion"),
       isHostExternal: /* @__PURE__ */ __name(() => isHostExternal, "isHostExternal"),
       isServerRootState: /* @__PURE__ */ __name(() => isServerRootState, "isServerRootState"),
+      isTransientNpmNetworkError: /* @__PURE__ */ __name(() => isTransientNpmNetworkError, "isTransientNpmNetworkError"),
       migrateToSingleCopy: /* @__PURE__ */ __name(() => migrateToSingleCopy, "migrateToSingleCopy"),
       minNodeMajorOf: /* @__PURE__ */ __name(() => minNodeMajorOf, "minNodeMajorOf"),
       pendingRootSwapPath: /* @__PURE__ */ __name(() => pendingRootSwapPath, "pendingRootSwapPath"),
@@ -1071,6 +1076,18 @@ var require_dist = __commonJS({
     __name(buildNpmRegistryArgs, "buildNpmRegistryArgs");
     var NPM_VIEW_TIMEOUT_MS = 2e4;
     var NPM_INSTALL_TIMEOUT_MS = 15 * 6e4;
+    var STAGING_ATTEMPTS = 3;
+    var STAGING_RETRY_DELAYS_MS = [
+      5e3,
+      15e3
+    ];
+    var TRANSIENT_NPM_ERROR_RE = /npm error code (?:ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|ECONNREFUSED|EPIPE|E50[234]|E429)\b|npm error network/i;
+    function isTransientNpmNetworkError(message) {
+      return TRANSIENT_NPM_ERROR_RE.test(message);
+    }
+    __name(isTransientNpmNetworkError, "isTransientNpmNetworkError");
+    var STAGING_FAILED_REASON = "staging-failed";
+    var ROLLBACK_UNSUPPORTED_REASON = "rollback-unsupported";
     var CLOSURE_ALLOW_SCRIPTS = {
       "@camstack/server": true,
       "better-sqlite3": true,
@@ -1131,8 +1148,20 @@ var require_dist = __commonJS({
       env;
       readWrapperProbesFn;
       now;
+      sleep;
       runningPackageJsonPath;
       workspaceProbeDir;
+      /**
+      * The version THIS PROCESS loaded — read once, here, from the package.json
+      * of the copy the code came from, and never again. The file is the only
+      * place the fact exists in a form the process can read, and the moment of
+      * construction is the only moment it is guaranteed to describe what is in
+      * memory: the starter swaps `current/` BEFORE loading the entry, and nothing
+      * else may move it, so a later read that disagrees is a disk that changed
+      * under a live process — reported through `installedVersion`, never folded
+      * into this number.
+      */
+      loadedVersion;
       checkCache = null;
       inFlight = "idle";
       constructor(options) {
@@ -1160,8 +1189,22 @@ var require_dist = __commonJS({
         this.env = options.env ?? process.env;
         this.readWrapperProbesFn = options.readWrapperProbes ?? readWrapperProbes;
         this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve3) => {
+          setTimeout(resolve3, ms);
+        }));
         this.runningPackageJsonPath = options.runningPackageJsonPath;
         this.workspaceProbeDir = options.workspaceProbeDir;
+        this.loadedVersion = readPackageVersion(this.runningPackageJsonPath);
+        const bootedVersion = this.env[this.envNames.activeVersion];
+        if (bootedVersion !== void 0 && this.loadedVersion !== null && bootedVersion !== this.loadedVersion) {
+          this.logger.warn("running root package disagrees with the version the starter booted", {
+            tags: this.logTags,
+            meta: {
+              loadedVersion: this.loadedVersion,
+              bootedVersion
+            }
+          });
+        }
       }
       // ── Status ────────────────────────────────────────────────────────────
       resolveBootMode() {
@@ -1169,8 +1212,36 @@ var require_dist = __commonJS({
         if (raw === "workspace" || raw === "baked" || raw === "data-root") return raw;
         return detectWorkspaceRoot(this.workspaceProbeDir) !== null ? "workspace" : "baked";
       }
+      /** What THIS process loaded — see {@link loadedVersion}. Never a disk read. */
       runningVersion() {
-        return readPackageVersion(this.runningPackageJsonPath);
+        return this.loadedVersion;
+      }
+      /**
+      * What is in the data-root `current/` copy RIGHT NOW — the version the next
+      * boot would load if nothing is staged. Only answered on a `data-root` boot:
+      * on a workspace boot there is no such copy, and on a `baked` boot the
+      * starter already judged `current/` unloadable (or absent), so a version
+      * read from it would claim "runs after restart" about code that will not.
+      */
+      installedVersion() {
+        if (this.resolveBootMode() !== "data-root") return null;
+        return readPackageVersion(path6.join(rootPackageDir2(currentDir(this.rootDir()), this.spec), "package.json"));
+      }
+      /**
+      * The three facts a restart question needs, read together so no surface can
+      * quote one without the others: what is staged, what is on disk, and whether
+      * the code that would run after a restart differs from the code running now.
+      */
+      restartFacts() {
+        const pendingVersion = readPendingRootSwap(this.rootDir())?.version ?? null;
+        const installedVersion = this.installedVersion();
+        const running = this.runningVersion();
+        const restartRequired = pendingVersion !== null || installedVersion !== null && running !== null && installedVersion !== running;
+        return {
+          pendingVersion,
+          installedVersion,
+          restartRequired
+        };
       }
       /** The running root package's identity — feeds registerNode / topology rows. */
       getRunningRootPackage() {
@@ -1207,16 +1278,26 @@ var require_dist = __commonJS({
         if (readPendingRootSwap(this.rootDir()) !== null) return "pending-restart";
         return "idle";
       }
+      /**
+      * `latest` is an update this node can still TAKE: newer than what runs, and
+      * not the version already staged here — that one is a restart away, and
+      * re-applying it is refused (`already-staged`).
+      */
+      isUpdateAvailable(latestVersion, runningVersion, pendingVersion) {
+        return latestVersion !== null && runningVersion !== null && latestVersion !== pendingVersion && compareSemver(latestVersion, runningVersion) > 0;
+      }
       async getServerPackageStatus() {
         const runningVersion = this.runningVersion();
         const latestVersion = this.checkCache?.latestVersion ?? null;
-        const pending = readPendingRootSwap(this.rootDir());
-        const updateAvailable = latestVersion !== null && runningVersion !== null && compareSemver(latestVersion, runningVersion) > 0;
+        const { pendingVersion, installedVersion, restartRequired } = this.restartFacts();
+        const updateAvailable = this.isUpdateAvailable(latestVersion, runningVersion, pendingVersion);
         return {
           packageName: this.spec.packageName,
           runningVersion,
           nodeRuntimeVersion: process.versions.node,
           activeVersion: this.env[this.envNames.activeVersion] ?? runningVersion,
+          installedVersion,
+          restartRequired,
           // Single-copy model: no N-1 retention, no rollback record.
           previousVersion: null,
           seedVersion: this.seedVersion(),
@@ -1224,7 +1305,7 @@ var require_dist = __commonJS({
           updateAvailable,
           bootMode: this.resolveBootMode(),
           updateState: this.updateState(),
-          pendingVersion: pending?.version ?? null,
+          pendingVersion,
           rolledBack: null,
           stateFileCorrupt: false,
           lastCheckedAtMs: this.checkCache?.checkedAtMs ?? null,
@@ -1246,6 +1327,7 @@ var require_dist = __commonJS({
       // ── Check ─────────────────────────────────────────────────────────────
       async checkServerUpdate() {
         const runningVersion = this.runningVersion();
+        const { pendingVersion, restartRequired } = this.restartFacts();
         if (this.inFlight !== "idle") {
           return {
             packageName: this.spec.packageName,
@@ -1253,7 +1335,9 @@ var require_dist = __commonJS({
             latestVersion: this.checkCache?.latestVersion ?? null,
             updateAvailable: false,
             checkedAtMs: this.checkCache?.checkedAtMs ?? this.now(),
-            error: `busy: ${this.inFlight}`
+            error: `busy: ${this.inFlight}`,
+            pendingVersion,
+            restartRequired
           };
         }
         this.inFlight = "checking";
@@ -1288,14 +1372,16 @@ var require_dist = __commonJS({
               }
             });
           }
-          const updateAvailable = latestVersion !== null && runningVersion !== null && compareSemver(latestVersion, runningVersion) > 0;
+          const updateAvailable = this.isUpdateAvailable(latestVersion, runningVersion, pendingVersion);
           return {
             packageName: this.spec.packageName,
             runningVersion,
             latestVersion,
             updateAvailable,
             checkedAtMs: this.checkCache.checkedAtMs,
-            error: null
+            error: null,
+            pendingVersion,
+            restartRequired
           };
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
@@ -1315,7 +1401,9 @@ var require_dist = __commonJS({
             latestVersion: this.checkCache.latestVersion,
             updateAvailable: false,
             checkedAtMs: this.checkCache.checkedAtMs,
-            error: message
+            error: message,
+            pendingVersion,
+            restartRequired
           };
         } finally {
           this.inFlight = "idle";
@@ -1345,7 +1433,12 @@ var require_dist = __commonJS({
           accepted: false,
           targetVersion,
           restarting: false,
-          message
+          message,
+          // "Already running" is not a gate saying no — it is the work already
+          // done. Every other reason is a refusal the caller may need to clear.
+          outcome: reason === "already-running" ? "already-current" : "refused",
+          reason,
+          error: null
         };
       }
       async applyServerUpdate(input) {
@@ -1388,21 +1481,17 @@ var require_dist = __commonJS({
         this.inFlight = "staging";
         let stagingPath;
         try {
-          stagingPath = await this.stageClosure(target);
+          stagingPath = await this.stageClosureWithRetry(target);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          this.logger.error("root package update staging failed", {
-            tags: this.logTags,
-            meta: {
-              targetVersion: target,
-              error: message
-            }
-          });
           return {
             accepted: false,
             targetVersion: target,
             restarting: false,
-            message: `Staging failed: ${message}`
+            message: `Staging failed: ${message}`,
+            outcome: "failed",
+            reason: STAGING_FAILED_REASON,
+            error: message
           };
         } finally {
           this.inFlight = "idle";
@@ -1431,10 +1520,59 @@ var require_dist = __commonJS({
           accepted: true,
           targetVersion: target,
           restarting: true,
-          message: `Staged ${this.spec.packageName}@${target} \u2014 restarting to apply (single automatic reboot).`
+          message: `Staged ${this.spec.packageName}@${target} \u2014 restarting to apply (single automatic reboot). Until that restart completes the node still runs ${runningVersion ?? "the previous version"}.`,
+          outcome: "staged",
+          reason: null,
+          error: null
         };
       }
       /**
+      * {@link stageClosure}, attempted up to {@link STAGING_ATTEMPTS} times when
+      * the failure is a transient registry network error and ONLY then. Every
+      * attempt is logged with its ordinal; the final failure is logged at ERROR
+      * with the attempt count, so a log that shows one line shows the whole
+      * story. Throws the last error when every attempt failed.
+      */
+      async stageClosureWithRetry(target) {
+        let lastError = new Error("staging never ran");
+        for (let attempt = 1; attempt <= STAGING_ATTEMPTS; attempt += 1) {
+          try {
+            return await this.stageClosure(target);
+          } catch (err) {
+            lastError = err;
+            const message = err instanceof Error ? err.message : String(err);
+            const transient = isTransientNpmNetworkError(message);
+            const delayMs = STAGING_RETRY_DELAYS_MS[attempt - 1];
+            const willRetry = transient && attempt < STAGING_ATTEMPTS && delayMs !== void 0;
+            if (!willRetry) {
+              this.logger.error("root package update staging failed", {
+                tags: this.logTags,
+                meta: {
+                  targetVersion: target,
+                  attempt,
+                  attempts: STAGING_ATTEMPTS,
+                  transient,
+                  error: message
+                }
+              });
+              break;
+            }
+            this.logger.warn("root package update staging failed \u2014 transient network error, retrying", {
+              tags: this.logTags,
+              meta: {
+                targetVersion: target,
+                attempt,
+                attempts: STAGING_ATTEMPTS,
+                delayMs,
+                error: message
+              }
+            });
+            await this.sleep(delayMs);
+          }
+        }
+        throw lastError;
+      }
+      /**
       * npm-install the target closure into a SAME-FS `.staging-*` dir, then
       * validate it (entry + version + native prebuilds). Returns the staging dir
       * path for the pending-root-swap marker; the STARTER swaps it into `current`
@@ -1583,7 +1721,10 @@ var require_dist = __commonJS({
           accepted: false,
           targetVersion: null,
           restarting: false,
-          message: "Rollback is not supported in the single-copy model (no retained previous version). Recover by re-applying a known-good version via applyServerUpdate, or reinstall the image seed."
+          message: "Rollback is not supported in the single-copy model (no retained previous version). Recover by re-applying a known-good version via applyServerUpdate, or reinstall the image seed.",
+          outcome: "refused",
+          reason: ROLLBACK_UNSUPPORTED_REASON,
+          error: null
         };
       }
       // ── Plain restart ─────────────────────────────────────────────────────
@@ -1608,7 +1749,10 @@ var require_dist = __commonJS({
           accepted: false,
           targetVersion,
           restarting: false,
-          message
+          message,
+          outcome: "refused",
+          reason,
+          error: null
         };
       }
       restartNode() {
@@ -1630,7 +1774,10 @@ var require_dist = __commonJS({
           accepted: true,
           targetVersion: runningVersion,
           restarting: true,
-          message: "Restarting the node \u2014 the supervisor relaunches it on the same version."
+          message: "Restarting the node \u2014 the supervisor relaunches it on the same version.",
+          outcome: "restart-scheduled",
+          reason: null,
+          error: null
         };
       }
       // ── Boot health confirmation ──────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.353",
+  "version": "1.2.355",
   "private": false,
   "files": [
     "dist",
@@ -35,18 +35,18 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.242",
-    "@camstack/addon-agent-ui": "1.2.131",
+    "@camstack/addon-admin-ui": "1.2.244",
+    "@camstack/addon-agent-ui": "1.2.132",
     "@camstack/addon-auth": "1.2.123",
     "@camstack/addon-decoder-nodeav": "1.2.115",
     "@camstack/addon-notifiers": "1.2.119",
-    "@camstack/addon-pipeline": "1.2.271",
-    "@camstack/addon-pipeline-orchestrator": "1.2.230",
-    "@camstack/addon-post-analysis": "1.2.270",
+    "@camstack/addon-pipeline": "1.2.273",
+    "@camstack/addon-pipeline-orchestrator": "1.2.231",
+    "@camstack/addon-post-analysis": "1.2.272",
     "@camstack/sdk": "1.2.118",
-    "@camstack/system": "1.2.274",
-    "@camstack/types": "1.2.232",
-    "@camstack/ui-library": "1.2.189",
+    "@camstack/system": "1.2.276",
+    "@camstack/types": "1.2.234",
+    "@camstack/ui-library": "1.2.190",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.2.0",