@camstack/system 1.2.389 → 1.2.391

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.d.ts

@@ -1,295 +1,295 @@
-import { ProviderRegistration, BaseAddon } from '@camstack/types';
-interface StorageOrchestratorConfig extends Record<string, unknown> {
-}
+import type { ProviderRegistration } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
+interface StorageOrchestratorConfig extends Record<string, unknown> {}
 export declare class StorageOrchestratorAddon extends BaseAddon<StorageOrchestratorConfig> {
-    private service;
-    private pressureManager;
-    /**
-     * How much of each location CamStack itself holds (D388).
-     *
-     * Built on first use rather than in a field initializer: `this.ctx` does not
-     * exist until `initialize()` runs, and a field initializer touching it throws
-     * in the constructor.
-     */
-    private occupancySlice;
-    private get occupancy();
-    private pressureTimer;
-    private pressureSweepInFlight;
-    private migration;
-    /**
-     * Cached `providerId → nodeLocal` snapshot (SP1). Backs the orchestrator's
-     * synchronous `NodeLocalResolver` — `getProviderInfo()` is async, so we
-     * keep a sync cache and refresh it whenever the provider collection
-     * changes (alongside the seed pass). Absent providerId → resolver returns
-     * `undefined` (treated as node-agnostic).
-     */
-    private readonly nodeLocalByProvider;
-    /**
-     * Cached `providerId → secret config keys`, derived from each provider's own
-     * `configSchema` in the SAME refresh as `nodeLocalByProvider` — one
-     * `getProviderInfo()` round trip answers both questions.
-     *
-     * An absent providerId yields an EMPTY set, which redacts nothing. That is
-     * the one direction this cache can be wrong in, so it is worth saying why it
-     * is acceptable: the entry is populated at the same moment the provider
-     * becomes resolvable at all, so a location whose provider is unknown here
-     * cannot be dispatched to either — there is no window in which a credential
-     * is readable through a provider the orchestrator can otherwise use.
-     */
-    private readonly secretKeysByProvider;
-    /**
-     * Disposers run on `onShutdown` — currently the eventBus subscription
-     * for `capability:provider-registered` events used by the lazy seed
-     * fallback. Stored separately from the `BaseAddon` disposer chain so
-     * it can be inspected in tests.
-     */
-    private readonly seedSubscriptionDisposers;
-    constructor();
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    /**
-     * The remote behind the data door on a node that owns no engine.
-     *
-     * `null` on a hub — the hub IS the store, and a hub that forwarded would
-     * route its own door back into itself through `$hub-cap-fwd`. `null` too
-     * when this process has no cluster broker (a forked worker, or a test
-     * harness); the door then behaves exactly as it always did and refuses.
-     *
-     * Built once and memoised. It is only consulted when `getEngines()` is
-     * empty, so on a hub — and on an agent rolled back to a local engine via
-     * `CAMSTACK_AGENT_LOCAL_DATA_STORE` — the resolve never runs a second time.
-     */
-    private hubForward;
-    private hubSettingsForward;
-    protected onShutdown(): Promise<void>;
-    onHubReachable(): Promise<void>;
-    /**
-     * Resolve the live engine from the capability registry and wrap it in a
-     * `SqliteLocationStore`. Returns `null` when no engine has registered
-     * yet — the service falls back to in-memory only. On a HUB that is a
-     * boot-order window: `data-store-provider` precedes `storage` in
-     * `INFRA_CAPABILITIES`, so it is the rare path.
-     *
-     * On an AGENT it is permanent and intended, and the line says so. An agent
-     * boots no engine (`resolveAgentInfraCapabilities`), and this store must NOT
-     * be pointed at the hub-forwarding data door: `storage_locations` is keyed by
-     * a bare location id (`recordings:default`, `eventMedia:default`, …) which
-     * every node in the cluster shares, so an agent writing through the door
-     * would land on the HUB's rows. The locations an agent needs are re-seeded
-     * from its addon declarations at every boot; the operator's real, node-pinned
-     * locations live in the hub's own table (`__nodeId` in the config blob) and
-     * are dispatched to the agent's `storage-provider` from there.
-     *
-     * Reads the ENGINE, not the `settings-store` singleton: since D44 this
-     * addon *is* that singleton, so asking the registry for it would hand
-     * the orchestrator its own dispatcher and route its location table back
-     * through itself.
-     */
-    private resolveLocationStore;
-    /**
-     * Late-wire the persistence store once a `data-store-provider` engine
-     * registers. Production boot order means the store is usually absent at
-     * `onInitialize`; this runs on every `capability:provider-registered`
-     * event until it succeeds. Single-flighted + idempotent (the service
-     * ignores a second attach). Without this, operator edits (e.g. a
-     * location's `minFreePercent`) live only in memory and are wiped on every
-     * restart — the service never hydrates from / persists to SQLite.
-     */
-    private storeWireInFlight;
-    private ensureStoreWired;
-    private storageProviders;
-    /** Single-flighted pressure sweep — never overlaps a slow eviction round. */
-    private runPressureSweep;
-    /**
-     * locationId → resolved `minFreePercent`. The policy is intrinsic to the
-     * location's provider (`shouldSaveDiskSpace` gates the guard, `minFreePercent`
-     * is the default), overridable per-location via `config.minFreePercent`.
-     * Locations with the guard off (or threshold 0) are omitted. Moved here from
-     * the recorder so disk-pressure is a single core concern.
-     */
-    private resolveLocationThresholds;
-    /** Location ids that have already logged the `minFreeGb` / `minFreePercent`
-     *  redundancy. The pressure sweep runs on a timer; the notice is worth
-     *  exactly one line per location per process, not one per minute. */
-    private readonly minFreeRedundancyLogged;
-    private logMinFreeRedundancyOnce;
-    /**
-     * The draining locations and the ACTIVE peers of their class whose growth
-     * paces them (D386). Rebuilt every sweep from the live mode of every
-     * location, so this is also what STOPS a drain: a location the operator
-     * switched back simply stops appearing.
-     */
-    private drainStore;
-    /** The drain ratchet's durable home, once a data-store engine exists. Same
-     *  late-wiring window as the location table — on an agent it is never. */
-    private resolveDrainStore;
-    private drainPlanRefusalLogged;
-    private resolveDrainPlan;
-    /** Drain progress for every draining location, as of the last sweep. */
-    private drainProgress;
-    /**
-     * What the provider's own schema declared secret, or `undefined` when this
-     * node has never heard from that provider. The distinction is the whole
-     * point — see `secretKeysForConfig`, which fails CLOSED on `undefined`.
-     */
-    private declaredSecretKeys;
-    /** Which keys of a given stored config must never leave this process. */
-    /**
-     * Move a singleton location's bytes when its root changes.
-     *
-     * Runs BEFORE the row is saved: a copy that fails throws out of the mutation,
-     * so the location keeps pointing at the intact original and the operator is
-     * told why rather than discovering it in a blank panel weeks later.
-     * `moveLocationTree` deletes nothing until every file has been read back from
-     * the destination.
-     *
-     * A no-op for everything else — a rename, a mode change, a `multi` kind, or a
-     * location being created for the first time.
-     */
-    private carryDataOnRepoint;
-    private secretKeysFor;
-    /**
-     * Ring the doorbell: the SET of storage locations changed (D387).
-     *
-     * A consumer that resolves locations at boot had no way to learn that the
-     * operator added, edited or removed one — the recorder kept writing to the
-     * disk set it resolved hours ago, and an operator who added a second
-     * recordings disk in the admin UI got nothing until something unrelated
-     * happened to re-resolve.
-     *
-     * Telemetry, and deliberately so (D8/D11): it carries no row, it is allowed
-     * to be dropped, and every consumer re-reads `listLocations` for itself and
-     * converges on its own periodic path anyway. A bulk edit rings it once per
-     * row — coalescing is the consumer's job, not this one's.
-     *
-     * Never throws into the mutation that produced it: the location IS saved,
-     * and a bus that will not take a telemetry event must not turn that into a
-     * failed upsert.
-     */
-    private announceLocationsChanged;
-    /** A location with its provider's declared secrets replaced by the sentinel. */
-    /**
-     * The location as a PROVIDER must see it: every keychain marker in its
-     * config resolved (D787). The same object when it holds none — a filesystem
-     * location costs nothing. An unresolvable secret is left out and logged by
-     * ref; the provider then fails its own connection, by name.
-     */
-    private withResolvedSecrets;
-    /**
-     * Strip the provider's DECLARED secrets (its form schema, by type) out of a
-     * location config into the keychain, under `row/storage_locations/<id>`.
-     * A provider that has not registered declares nothing: only keys that
-     * already hold a marker are handled then — a new plaintext is never guessed
-     * at, it stays as sent until the provider is back and the location is saved.
-     */
-    private keepSecretsInKeychain;
-    private redacted;
-    /**
-     * Is this location backed by a provider that serves a genuine local
-     * filesystem? `true` / `false` / `undefined` — see
-     * `StorageOrchestratorService.refuseIncompatibleProvider` for why the
-     * unknown case is kept distinct rather than folded into either answer.
-     */
-    private providerIsNodeLocal;
-    /** See the call site in the `resolve` dispatch, and `access-guards.ts`. */
-    private refuseRemoteResolve;
-    /**
-     * The volume figures for one location, or `null` when this node cannot take
-     * a measurement that is genuinely about it.
-     *
-     * The decision lives in `location-volume-capacity.ts` — including why a
-     * remote-provider location (the SMB share that was reporting the hub's own
-     * disk) gets nothing rather than a number. Here we only supply the node id,
-     * the provider's declared locality and the real filesystem, and log the
-     * reason once per distinct fault: `listLocations` is on the admin UI's poll,
-     * so a line per call would be a line per second.
-     */
-    private localCapacityOf;
-    /** locationId → the last unmeasurable reason logged for it. */
-    private readonly capacityUnknownLogged;
-    private logCapacityUnknownOnce;
-    private clearCapacityUnknown;
-    /** Per-location cap on EVICTABLE bytes (`config.maxUsedGb`): the operator's
-     *  "recordings may use at most N GB in total" — enforced by the pressure
-     *  manager alongside the free-percent guard. */
-    private resolveLocationMaxUsedBytes;
-    private locationBasePath;
-    /**
-     * A stable key for the PHYSICAL storage device behind a location — the
-     * `realpath` of its `basePath`, so symlinked / bind-mounted aliases and
-     * same-root managed locations (`recordings:default` + `recordingsLow:default`,
-     * both at `/recordings`) collapse to one key. Feeds the pressure manager's
-     * in-sweep dedup so a shared disk is relieved at most once per tick (closing
-     * the bounded over-eviction window; see `getLocationDeviceKey`). Falls back to
-     * the lexically-resolved path when realpath throws (root missing at boot),
-     * `null` when the location has no basePath — either way dedup degrades to
-     * per-location, never merging two distinct disks.
-     */
-    private locationDeviceKey;
-    /**
-     * Does this location still hold anything of ITS class?
-     *
-     * Shared roots (`/recordings` hosting high + low + events) are scored by
-     * class subtree (`<camera>/high|mid`, `/low`, `/events`), not by a raw
-     * `readdir` of the root — camera dirs and `.camstack-location` would
-     * otherwise make every class look occupied. The walk stays shallow: one
-     * dirent per camera, then first-entry of the named subtree. A `find` of
-     * segments is precisely what must not happen here.
-     *
-     * **What it cannot see, stated rather than papered over:**
-     *
-     *  - A location on ANOTHER node, or behind a remote provider (S3 / SFTP /
-     *    WebDAV): its bytes are not on this filesystem and this probe answers
-     *    `unknown`, never `empty`.
-     *  - A location with no `basePath` — same answer.
-     *  - The difference between "holds live footage" and "holds one stray
-     *    lock-file". It measures ON-DISK entries of this class, not durable
-     *    rows, so it refuses a location holding orphan files that no index
-     *    names. That direction is the safe one, and `force` is the escape
-     *    hatch for it.
-     *
-     * A missing root (`ENOENT`) is `empty`, not `unknown`: an unmounted disk and
-     * a deleted directory are indistinguishable here, and if the record's own
-     * path does not exist there is nothing this delete can strand. Every OTHER
-     * errno — `EACCES`, `EIO`, a stale NFS handle — is `unknown` and refuses.
-     */
-    private locationOccupancy;
-    /**
-     * The pressure guard's two readings come from the SAME probe the UI's
-     * capacity does — one capacity truth per location, not two.
-     *
-     * They used to `statfs` the raw `basePath` themselves, which on this node
-     * answers for whatever local path happens to carry that name: a location
-     * owned by another node, or served by a remote provider, could decide
-     * eviction from the hub's own disk. Both now degrade exactly as they did
-     * when the path was unstattable — `100` (guard inert) and `0` (no byte
-     * target) — but they do so for every reading that is not ABOUT the location,
-     * not only for the ones that threw.
-     */
-    private volumeCapacityOf;
-    /** Free capacity (%) on a location's volume; 100 (guard inert) when unmeasurable. */
-    private locationFreePercent;
-    /** Total bytes on a location's volume; 0 when unmeasurable. */
-    private locationVolumeTotalBytes;
-    /**
-     * Seed default storage locations from the addon-declared
-     * `storageLocations`, aggregated by the kernel into a
-     * `StorageLocationRegistry`. Idempotent — re-running on a populated
-     * map is a no-op (each declared id's `<id>:default` is already in the
-     * service's map).
-     *
-     * `basePath` is this node's data root (`ctx.nodeDataDir` = `CAMSTACK_DATA`
-     * ?? the kernel boot dir). Every declared default is attributed to the
-     * `filesystem-storage`
-     * provider; operators repoint individual locations (or add remote
-     * SFTP/S3/WebDAV instances) through the admin UI afterwards.
-     */
-    private seedFromDeclarations;
-    /**
-     * Rebuild the `providerId → nodeLocal` cache from every registered
-     * `storage-provider`'s `getProviderInfo()`. Cheap registry scan; runs on
-     * boot and on every provider-registered reconcile. Failed probes are
-     * skipped (the provider stays absent → treated as node-agnostic).
-     */
-    private refreshNodeLocalCache;
+	private service;
+	private pressureManager;
+	/**
+	* How much of each location CamStack itself holds (D388).
+	*
+	* Built on first use rather than in a field initializer: `this.ctx` does not
+	* exist until `initialize()` runs, and a field initializer touching it throws
+	* in the constructor.
+	*/
+	private occupancySlice;
+	private get occupancy();
+	private pressureTimer;
+	private pressureSweepInFlight;
+	private migration;
+	/**
+	* Cached `providerId → nodeLocal` snapshot (SP1). Backs the orchestrator's
+	* synchronous `NodeLocalResolver` — `getProviderInfo()` is async, so we
+	* keep a sync cache and refresh it whenever the provider collection
+	* changes (alongside the seed pass). Absent providerId → resolver returns
+	* `undefined` (treated as node-agnostic).
+	*/
+	private readonly nodeLocalByProvider;
+	/**
+	* Cached `providerId → secret config keys`, derived from each provider's own
+	* `configSchema` in the SAME refresh as `nodeLocalByProvider` — one
+	* `getProviderInfo()` round trip answers both questions.
+	*
+	* An absent providerId yields an EMPTY set, which redacts nothing. That is
+	* the one direction this cache can be wrong in, so it is worth saying why it
+	* is acceptable: the entry is populated at the same moment the provider
+	* becomes resolvable at all, so a location whose provider is unknown here
+	* cannot be dispatched to either — there is no window in which a credential
+	* is readable through a provider the orchestrator can otherwise use.
+	*/
+	private readonly secretKeysByProvider;
+	/**
+	* Disposers run on `onShutdown` — currently the eventBus subscription
+	* for `capability:provider-registered` events used by the lazy seed
+	* fallback. Stored separately from the `BaseAddon` disposer chain so
+	* it can be inspected in tests.
+	*/
+	private readonly seedSubscriptionDisposers;
+	constructor();
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	/**
+	* The remote behind the data door on a node that owns no engine.
+	*
+	* `null` on a hub — the hub IS the store, and a hub that forwarded would
+	* route its own door back into itself through `$hub-cap-fwd`. `null` too
+	* when this process has no cluster broker (a forked worker, or a test
+	* harness); the door then behaves exactly as it always did and refuses.
+	*
+	* Built once and memoised. It is only consulted when `getEngines()` is
+	* empty, so on a hub — and on an agent rolled back to a local engine via
+	* `CAMSTACK_AGENT_LOCAL_DATA_STORE` — the resolve never runs a second time.
+	*/
+	private hubForward;
+	private hubSettingsForward;
+	protected onShutdown(): Promise<void>;
+	override onHubReachable(): Promise<void>;
+	/**
+	* Resolve the live engine from the capability registry and wrap it in a
+	* `SqliteLocationStore`. Returns `null` when no engine has registered
+	* yet — the service falls back to in-memory only. On a HUB that is a
+	* boot-order window: `data-store-provider` precedes `storage` in
+	* `INFRA_CAPABILITIES`, so it is the rare path.
+	*
+	* On an AGENT it is permanent and intended, and the line says so. An agent
+	* boots no engine (`resolveAgentInfraCapabilities`), and this store must NOT
+	* be pointed at the hub-forwarding data door: `storage_locations` is keyed by
+	* a bare location id (`recordings:default`, `eventMedia:default`, …) which
+	* every node in the cluster shares, so an agent writing through the door
+	* would land on the HUB's rows. The locations an agent needs are re-seeded
+	* from its addon declarations at every boot; the operator's real, node-pinned
+	* locations live in the hub's own table (`__nodeId` in the config blob) and
+	* are dispatched to the agent's `storage-provider` from there.
+	*
+	* Reads the ENGINE, not the `settings-store` singleton: since D44 this
+	* addon *is* that singleton, so asking the registry for it would hand
+	* the orchestrator its own dispatcher and route its location table back
+	* through itself.
+	*/
+	private resolveLocationStore;
+	/**
+	* Late-wire the persistence store once a `data-store-provider` engine
+	* registers. Production boot order means the store is usually absent at
+	* `onInitialize`; this runs on every `capability:provider-registered`
+	* event until it succeeds. Single-flighted + idempotent (the service
+	* ignores a second attach). Without this, operator edits (e.g. a
+	* location's `minFreePercent`) live only in memory and are wiped on every
+	* restart — the service never hydrates from / persists to SQLite.
+	*/
+	private storeWireInFlight;
+	private ensureStoreWired;
+	private storageProviders;
+	/** Single-flighted pressure sweep — never overlaps a slow eviction round. */
+	private runPressureSweep;
+	/**
+	* locationId → resolved `minFreePercent`. The policy is intrinsic to the
+	* location's provider (`shouldSaveDiskSpace` gates the guard, `minFreePercent`
+	* is the default), overridable per-location via `config.minFreePercent`.
+	* Locations with the guard off (or threshold 0) are omitted. Moved here from
+	* the recorder so disk-pressure is a single core concern.
+	*/
+	private resolveLocationThresholds;
+	/** Location ids that have already logged the `minFreeGb` / `minFreePercent`
+	*  redundancy. The pressure sweep runs on a timer; the notice is worth
+	*  exactly one line per location per process, not one per minute. */
+	private readonly minFreeRedundancyLogged;
+	private logMinFreeRedundancyOnce;
+	/**
+	* The draining locations and the ACTIVE peers of their class whose growth
+	* paces them (D386). Rebuilt every sweep from the live mode of every
+	* location, so this is also what STOPS a drain: a location the operator
+	* switched back simply stops appearing.
+	*/
+	private drainStore;
+	/** The drain ratchet's durable home, once a data-store engine exists. Same
+	*  late-wiring window as the location table — on an agent it is never. */
+	private resolveDrainStore;
+	private drainPlanRefusalLogged;
+	private resolveDrainPlan;
+	/** Drain progress for every draining location, as of the last sweep. */
+	private drainProgress;
+	/**
+	* What the provider's own schema declared secret, or `undefined` when this
+	* node has never heard from that provider. The distinction is the whole
+	* point — see `secretKeysForConfig`, which fails CLOSED on `undefined`.
+	*/
+	private declaredSecretKeys;
+	/** Which keys of a given stored config must never leave this process. */
+	/**
+	* Move a singleton location's bytes when its root changes.
+	*
+	* Runs BEFORE the row is saved: a copy that fails throws out of the mutation,
+	* so the location keeps pointing at the intact original and the operator is
+	* told why rather than discovering it in a blank panel weeks later.
+	* `moveLocationTree` deletes nothing until every file has been read back from
+	* the destination.
+	*
+	* A no-op for everything else — a rename, a mode change, a `multi` kind, or a
+	* location being created for the first time.
+	*/
+	private carryDataOnRepoint;
+	private secretKeysFor;
+	/**
+	* Ring the doorbell: the SET of storage locations changed (D387).
+	*
+	* A consumer that resolves locations at boot had no way to learn that the
+	* operator added, edited or removed one — the recorder kept writing to the
+	* disk set it resolved hours ago, and an operator who added a second
+	* recordings disk in the admin UI got nothing until something unrelated
+	* happened to re-resolve.
+	*
+	* Telemetry, and deliberately so (D8/D11): it carries no row, it is allowed
+	* to be dropped, and every consumer re-reads `listLocations` for itself and
+	* converges on its own periodic path anyway. A bulk edit rings it once per
+	* row — coalescing is the consumer's job, not this one's.
+	*
+	* Never throws into the mutation that produced it: the location IS saved,
+	* and a bus that will not take a telemetry event must not turn that into a
+	* failed upsert.
+	*/
+	private announceLocationsChanged;
+	/** A location with its provider's declared secrets replaced by the sentinel. */
+	/**
+	* The location as a PROVIDER must see it: every keychain marker in its
+	* config resolved (D787). The same object when it holds none — a filesystem
+	* location costs nothing. An unresolvable secret is left out and logged by
+	* ref; the provider then fails its own connection, by name.
+	*/
+	private withResolvedSecrets;
+	/**
+	* Strip the provider's DECLARED secrets (its form schema, by type) out of a
+	* location config into the keychain, under `row/storage_locations/<id>`.
+	* A provider that has not registered declares nothing: only keys that
+	* already hold a marker are handled then — a new plaintext is never guessed
+	* at, it stays as sent until the provider is back and the location is saved.
+	*/
+	private keepSecretsInKeychain;
+	private redacted;
+	/**
+	* Is this location backed by a provider that serves a genuine local
+	* filesystem? `true` / `false` / `undefined` — see
+	* `StorageOrchestratorService.refuseIncompatibleProvider` for why the
+	* unknown case is kept distinct rather than folded into either answer.
+	*/
+	private providerIsNodeLocal;
+	/** See the call site in the `resolve` dispatch, and `access-guards.ts`. */
+	private refuseRemoteResolve;
+	/**
+	* The volume figures for one location, or `null` when this node cannot take
+	* a measurement that is genuinely about it.
+	*
+	* The decision lives in `location-volume-capacity.ts` — including why a
+	* remote-provider location (the SMB share that was reporting the hub's own
+	* disk) gets nothing rather than a number. Here we only supply the node id,
+	* the provider's declared locality and the real filesystem, and log the
+	* reason once per distinct fault: `listLocations` is on the admin UI's poll,
+	* so a line per call would be a line per second.
+	*/
+	private localCapacityOf;
+	/** locationId → the last unmeasurable reason logged for it. */
+	private readonly capacityUnknownLogged;
+	private logCapacityUnknownOnce;
+	private clearCapacityUnknown;
+	/** Per-location cap on EVICTABLE bytes (`config.maxUsedGb`): the operator's
+	*  "recordings may use at most N GB in total" — enforced by the pressure
+	*  manager alongside the free-percent guard. */
+	private resolveLocationMaxUsedBytes;
+	private locationBasePath;
+	/**
+	* A stable key for the PHYSICAL storage device behind a location — the
+	* `realpath` of its `basePath`, so symlinked / bind-mounted aliases and
+	* same-root managed locations (`recordings:default` + `recordingsLow:default`,
+	* both at `/recordings`) collapse to one key. Feeds the pressure manager's
+	* in-sweep dedup so a shared disk is relieved at most once per tick (closing
+	* the bounded over-eviction window; see `getLocationDeviceKey`). Falls back to
+	* the lexically-resolved path when realpath throws (root missing at boot),
+	* `null` when the location has no basePath — either way dedup degrades to
+	* per-location, never merging two distinct disks.
+	*/
+	private locationDeviceKey;
+	/**
+	* Does this location still hold anything of ITS class?
+	*
+	* Shared roots (`/recordings` hosting high + low + events) are scored by
+	* class subtree (`<camera>/high|mid`, `/low`, `/events`), not by a raw
+	* `readdir` of the root — camera dirs and `.camstack-location` would
+	* otherwise make every class look occupied. The walk stays shallow: one
+	* dirent per camera, then first-entry of the named subtree. A `find` of
+	* segments is precisely what must not happen here.
+	*
+	* **What it cannot see, stated rather than papered over:**
+	*
+	*  - A location on ANOTHER node, or behind a remote provider (S3 / SFTP /
+	*    WebDAV): its bytes are not on this filesystem and this probe answers
+	*    `unknown`, never `empty`.
+	*  - A location with no `basePath` — same answer.
+	*  - The difference between "holds live footage" and "holds one stray
+	*    lock-file". It measures ON-DISK entries of this class, not durable
+	*    rows, so it refuses a location holding orphan files that no index
+	*    names. That direction is the safe one, and `force` is the escape
+	*    hatch for it.
+	*
+	* A missing root (`ENOENT`) is `empty`, not `unknown`: an unmounted disk and
+	* a deleted directory are indistinguishable here, and if the record's own
+	* path does not exist there is nothing this delete can strand. Every OTHER
+	* errno — `EACCES`, `EIO`, a stale NFS handle — is `unknown` and refuses.
+	*/
+	private locationOccupancy;
+	/**
+	* The pressure guard's two readings come from the SAME probe the UI's
+	* capacity does — one capacity truth per location, not two.
+	*
+	* They used to `statfs` the raw `basePath` themselves, which on this node
+	* answers for whatever local path happens to carry that name: a location
+	* owned by another node, or served by a remote provider, could decide
+	* eviction from the hub's own disk. Both now degrade exactly as they did
+	* when the path was unstattable — `100` (guard inert) and `0` (no byte
+	* target) — but they do so for every reading that is not ABOUT the location,
+	* not only for the ones that threw.
+	*/
+	private volumeCapacityOf;
+	/** Free capacity (%) on a location's volume; 100 (guard inert) when unmeasurable. */
+	private locationFreePercent;
+	/** Total bytes on a location's volume; 0 when unmeasurable. */
+	private locationVolumeTotalBytes;
+	/**
+	* Seed default storage locations from the addon-declared
+	* `storageLocations`, aggregated by the kernel into a
+	* `StorageLocationRegistry`. Idempotent — re-running on a populated
+	* map is a no-op (each declared id's `<id>:default` is already in the
+	* service's map).
+	*
+	* `basePath` is this node's data root (`ctx.nodeDataDir` = `CAMSTACK_DATA`
+	* ?? the kernel boot dir). Every declared default is attributed to the
+	* `filesystem-storage`
+	* provider; operators repoint individual locations (or add remote
+	* SFTP/S3/WebDAV instances) through the admin UI afterwards.
+	*/
+	private seedFromDeclarations;
+	/**
+	* Rebuild the `providerId → nodeLocal` cache from every registered
+	* `storage-provider`'s `getProviderInfo()`. Cheap registry scan; runs on
+	* boot and on every provider-registered reconcile. Failed probes are
+	* skipped (the provider stays absent → treated as node-agnostic).
+	*/
+	private refreshNodeLocalCache;
 }
 export default StorageOrchestratorAddon;