@camstack/system 1.2.25 → 1.2.27

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

@@ -37,6 +37,21 @@ export type StorageProviderLookup = () => readonly IStorageProviderImpl[];
  *     remote), the safe default for the early-boot / in-memory path.
  */
 export type NodeLocalResolver = (providerId: string) => boolean | undefined;
+/**
+ * Where a single dispatch must execute: which `storage-provider`, on which
+ * node. `providerId` alone is NOT a routing key — every node's filesystem
+ * provider registers under the same id, so a target without its `nodeId`
+ * silently resolves to whichever node asked (the hub).
+ *
+ * `nodeId` absent = node-agnostic (S3/SFTP/WebDAV): reachable from anywhere,
+ * so the local provider runs it.
+ */
+export interface StorageDispatchTarget {
+    readonly providerId: string;
+    readonly nodeId?: string;
+}
+/** The two chunked-I/O session families the orchestrator tracks. */
+export type StorageSessionKind = 'upload' | 'download';
 export declare class StorageOrchestratorService {
     private readonly logger;
     private readonly getProviders;
@@ -54,8 +69,6 @@ export declare class StorageOrchestratorService {
      * the provider appears. See {@link attachStore}.
      */
     private locationStore;
-    /** This node's id — locations pinned to OTHER nodes dispatch remotely. */
-    private readonly localNodeId;
     /** Cross-node provider resolver (hub wiring: a node-routed capability
      *  proxy over `storage-provider`). Absent → remote locations error. */
     private readonly getRemoteProvider?;
@@ -76,6 +89,15 @@ export declare class StorageOrchestratorService {
      * early-boot path that predates the resolver wiring.
      */
     private nodeLocalResolver;
+    /** `localNodeId` with any forked-child `/addon` suffix stripped. */
+    private readonly localNode;
+    /**
+     * `<kind>:<sessionId>` → the dispatch target that OPENED the session.
+     * Chunked I/O carries no `StorageLocation` after the first hop, so without
+     * this the follow-up chunks fall back to a `providerId`-only lookup — which
+     * on a multi-node cluster means the hub's filesystem, not the agent's.
+     */
+    private readonly sessionTargets;
     constructor(logger: IScopedLogger, getProviders: StorageProviderLookup, 
     /**
      * Optional persistence backend. When supplied, `initialize()`
@@ -96,6 +118,12 @@ export declare class StorageOrchestratorService {
     /** Cross-node provider resolver (hub wiring: a node-routed capability
      *  proxy over `storage-provider`). Absent → remote locations error. */
     getRemoteProvider?: ((nodeId: string) => IStorageProviderImpl | null) | undefined);
+    /**
+     * The node this orchestrator runs on, with any forked-child `/addon`
+     * suffix stripped. A location whose `nodeId` differs is NOT this node's
+     * to touch — its bytes, and its free space, live elsewhere.
+     */
+    getLocalNodeId(): string;
     /** True once a persistence store is wired (constructor or {@link attachStore}). */
     hasStore(): boolean;
     /**
@@ -210,13 +238,45 @@ export declare class StorageOrchestratorService {
      */
     resolveRef(ref: StorageLocationRef): StorageLocation;
     /**
-     * Find the storage-provider that backs a given location. Lookup is by
-     * `location.providerId` against `getProviderInfo().providerId` from
-     * each registered collection provider. Throws with both the missing
-     * providerId and the offending location id so the operator can pick
-     * the right place to fix the config.
+     * Find the storage-provider that backs a given location — the entry point
+     * every consumer-facing `storage` cap method funnels through.
+     *
+     * Routing key is `(providerId, nodeId)`, never `providerId` alone: every
+     * node's FilesystemStorageProvider registers under the SAME providerId, so
+     * a providerId-only match resolves to whichever node asked. That is how a
+     * location created on an agent ended up writing to the HUB's filesystem
+     * (root-caused 2026-07-29).
      */
     getProviderFor(location: StorageLocation): Promise<IStorageProviderImpl>;
+    /**
+     * Resolve one dispatch target to the provider that must execute it.
+     *
+     * `descriptor` is the operator-facing subject of the error message
+     * (`location "recordings:disk"`, `uploadId "u-42"`); `locationId` is the
+     * structured tag for the log line when there is a location behind the
+     * dispatch (chunked sessions carry only the session id).
+     *
+     * Both failure branches LOG before throwing, and NEITHER falls back to the
+     * local provider — a silent fallback is the bug this method exists to fix.
+     */
+    private getProviderForTarget;
+    /**
+     * Remember which provider — and on which NODE — opened a chunked session.
+     * `beginUpload` / `beginDownload` carry a `StorageLocation`; every later
+     * chunk carries only the session id, and a session id issued by an agent
+     * means nothing to the hub's provider.
+     */
+    rememberSession(kind: StorageSessionKind, sessionId: string, location: StorageLocation): void;
+    /** Drop a session's routing entry (finalize / abort / end). */
+    forgetSession(kind: StorageSessionKind, sessionId: string): void;
+    /** Drop every session entry (addon shutdown). */
+    clearSessions(): void;
+    /**
+     * Resolve the provider that owns an in-flight chunked session, on the node
+     * that opened it. Throws when the orchestrator has no record of the open
+     * call (provider gone, or a chunk for a session it never issued).
+     */
+    getProviderForSession(kind: StorageSessionKind, sessionId: string): Promise<IStorageProviderImpl>;
     /** Convenience: lookup by id (returns `undefined` if not found). */
     getLocationById(id: string): StorageLocation | undefined;
     /**

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CS0pdC8l.js");
+const require_dist = require("../../dist-BxtIzexq.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { St as hydrateSchema, at as BaseAddon, it as errMsg } from "../../dist-CIek6F9X.mjs";
+import { St as hydrateSchema, at as BaseAddon, it as errMsg } from "../../dist-BXmFvn3h.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CS0pdC8l.js");
+const require_dist = require("../../dist-BxtIzexq.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { at as BaseAddon, z as logDestinationCapability } from "../../dist-CIek6F9X.mjs";
+import { at as BaseAddon, z as logDestinationCapability } from "../../dist-BXmFvn3h.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";

package/dist/{dist-CIek6F9X.mjs → dist-BXmFvn3h.mjs}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-//#region ../types/dist/event-category-BLcNejAE.mjs
+//#region ../types/dist/event-category-Bz24uP1U.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -270,6 +270,19 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["DeviceStateChanged"] = "device.state-changed";
 	/**
+	* Frame occupancy for a camera CHANGED — a tracked object was gained or
+	* lost. Carries `{ deviceId, totalObjects, byClass, zones }`.
+	*
+	* Emitted only on a change, so a steady scene is silent. It exists so a
+	* client can stop polling `zoneAnalytics.getCurrentSnapshot`: that was the
+	* one live badge with no push signal at all, and it cost a request every
+	* four seconds per visible camera.
+	*
+	* Like every event it is telemetry and may be dropped ([D8]) — a consumer
+	* keeps a slow reconcile rather than trusting it alone.
+	*/
+	EventCategory["ZoneAnalyticsOccupancyChanged"] = "zone-analytics.occupancy-changed";
+	/**
 	* Cap event fired by every device that registers the `battery`
 	* capability. Mirrors the cap definition's `onStatusChanged`. Carries
 	* `{ deviceId, status: BatteryStatus }`. Subscribers (alert center,
@@ -1849,6 +1862,7 @@ var ReadinessRegistry = class {
 	logger;
 	now;
 	generation;
+	verboseDeviceScopeLogs;
 	snapshot = /* @__PURE__ */ new Map();
 	subscriptions = /* @__PURE__ */ new Set();
 	unsubscribeBus;
@@ -1859,6 +1873,7 @@ var ReadinessRegistry = class {
 		this.logger = options.logger;
 		this.now = options.now ?? (() => Date.now());
 		this.generation = options.generation ?? randomGeneration();
+		this.verboseDeviceScopeLogs = options.verboseDeviceScopeLogs ?? false;
 		this.unsubscribeBus = this.bus.subscribe({ category: "system.ready-state" }, (event) => this.ingest(event.data));
 		this.unsubscribeAgentOffline = this.bus.subscribe({ category: "agent.offline" }, (event) => this.synthesizeDownForNode(event.data.agentId));
 		if (typeof this.bus.getRecent === "function") try {
@@ -1912,9 +1927,16 @@ var ReadinessRegistry = class {
 	* Every applied entry dispatches a one-shot transition to matching
 	* subscriptions so pending `awaitReady` callers unblock without having
 	* to wait for a fresh event.
+	*
+	* Returns the number of records APPLIED (added or advanced). Callers
+	* doing periodic reconciles use this to stay silent when the snapshot
+	* changed nothing — the every-60s "hydrated 1446 record(s)" heartbeat
+	* from every child process was pure noise (≈2 800 lines/hour observed
+	* live on 2026-08-01).
 	*/
 	hydrate(records) {
 		const now = this.now();
+		let applied = 0;
 		for (const record of records) {
 			const key = readinessKey(record.capName, record.scope);
 			const prev = this.snapshot.get(key) ?? null;
@@ -1940,7 +1962,8 @@ var ReadinessRegistry = class {
 				sourceNodeId: record.sourceNodeId
 			};
 			this.snapshot.set(key, hydrated);
-			if (this.logger) this.logger.debug(`readiness: ${record.capName} (${scopeKey(record.scope)}) → ${record.state} (hydrated${prev !== null ? " update" : ""}, gen=${record.generation.slice(0, 6)})`);
+			applied++;
+			this.logPerRecord(record.scope, `readiness: ${record.capName} (${scopeKey(record.scope)}) → ${record.state} (hydrated${prev !== null ? " update" : ""}, gen=${record.generation.slice(0, 6)})`);
 			const transition = {
 				capName: record.capName,
 				scope: record.scope,
@@ -1961,6 +1984,23 @@ var ReadinessRegistry = class {
 				}
 			}
 		}
+		return applied;
+	}
+	/**
+	* Per-record debug line, volume-gated: device-scoped records are logged
+	* only when `verboseDeviceScopeLogs` is set (see the option's doc for
+	* the 21 577-lines-per-boot-minute incident that forced the gate);
+	* node/global records always log. Device lines carry `tags.deviceId`
+	* so they group per-camera (CLAUDE.md logging rule).
+	*/
+	logPerRecord(scope, message) {
+		if (!this.logger) return;
+		if (scope.type === "device") {
+			if (!this.verboseDeviceScopeLogs) return;
+			this.logger.debug(message, { tags: { deviceId: scope.deviceId } });
+			return;
+		}
+		this.logger.debug(message);
 	}
 	/**
 	* True when THIS process is the origin authority for `record` — a
@@ -2135,7 +2175,7 @@ var ReadinessRegistry = class {
 			ts: payload.ts,
 			durationInPrevState
 		};
-		if (this.logger) this.logger.debug(`readiness: ${payload.capName} (${scopeKey(payload.scope)}) → ${payload.state} epoch=${epoch} gen=${payload.generation.slice(0, 6)} (prev ${durationInPrevState}ms)`);
+		this.logPerRecord(payload.scope, `readiness: ${payload.capName} (${scopeKey(payload.scope)}) → ${payload.state} epoch=${epoch} gen=${payload.generation.slice(0, 6)} (prev ${durationInPrevState}ms)`);
 		for (const sub of this.subscriptions) {
 			if (sub.capName !== payload.capName) continue;
 			if (!scopesEqual(sub.scope, payload.scope)) continue;
@@ -2180,7 +2220,7 @@ var ReadinessRegistry = class {
 				ts: now,
 				durationInPrevState
 			};
-			if (this.logger) this.logger.debug(`readiness: ${record.capName} (${scopeKey(record.scope)}) → down (synthesized from agent.offline ${offlineNodeId})`);
+			this.logPerRecord(record.scope, `readiness: ${record.capName} (${scopeKey(record.scope)}) → down (synthesized from agent.offline ${offlineNodeId})`);
 			for (const sub of this.subscriptions) {
 				if (sub.capName !== record.capName) continue;
 				if (!scopesEqual(sub.scope, record.scope)) continue;
@@ -5326,6 +5366,29 @@ var NcOccupancyConditionSchema = z.object({
 	count: z.number().int().min(0).default(1),
 	sustainSeconds: z.number().int().min(0).max(3600).default(15)
 });
+/**
+* Which zone-crossing DIRECTION a rule accepts (`ObjectEvent.zoneCrossing`).
+*
+* The values are not symmetric, and deliberately so — the absent value has to
+* mean exactly what every rule authored before this condition existed already
+* does:
+*  - `enter` — entries and every NON-crossing record (movement state,
+*    package, sensor). Exits are rejected. **This is the absent behaviour**:
+*    an operator who never asked for exits must not start receiving them.
+*  - `exit`  — ONLY an exit crossing. A record that is not a crossing at all
+*    fails closed, because "the car left the drive" is a question about a
+*    boundary, not about a detection.
+*  - `any`   — no direction filter; entries, exits and non-crossings alike.
+*
+* A rule asking for a direction should normally also scope `zones`, which the
+* engine evaluates against the crossed zone as well as the current membership
+* (an exit's membership no longer contains the zone it just left).
+*/
+var NcCrossingSchema = z.enum([
+	"enter",
+	"exit",
+	"any"
+]);
 /** Admin-zone membership condition (zone IDs as stamped by the ZoneEngine). */
 var NcZoneConditionSchema = z.object({
 	ids: z.array(z.string().min(1)).min(1),
@@ -5350,6 +5413,13 @@ var NcConditionsSchema = z.object({
 	/** Veto zones — any hit fails the rule. */
 	zonesExclude: z.array(z.string().min(1)).optional(),
 	/**
+	* Zone-crossing direction. IMMEDIATE only — a crossing is a per-event fact
+	* and a closed track carries none, so a `track-end` rule asking for one
+	* fails closed (use `zones`, which tests `zonesVisited`). ABSENT = `enter`,
+	* which is exactly today's behaviour. See {@link NcCrossingSchema}.
+	*/
+	crossing: NcCrossingSchema.optional(),
+	/**
 	* Exact (case-insensitive) match on the record's collapsed `label`
 	* (identity name / plate text / subclass).
 	*/
@@ -5538,11 +5608,31 @@ var NcMediaPolicySchema = z.object({
 	*/
 	profile: CamProfileSchema.optional()
 });
+/**
+* Cooldown GRANULARITY over the subject's class — how much a fired
+* notification suppresses.
+*  - `shared` (default, and the absent value) — one window for the whole
+*    rule/scope: a cat silences the next dog for `cooldownSec`.
+*  - `per-class` — an independent window per detected class, so cat→dog fires
+*    at once and cat→cat still waits.
+*
+* AUDIO subjects are ALWAYS per-class regardless of this setting: a scream
+* must not be swallowed by a bark's window (the precedent this generalizes —
+* see `cooldownKey` in the rule engine).
+*/
+var NcThrottleGranularitySchema = z.enum(["shared", "per-class"]);
 /** Throttle — cooldown survives restarts (rebuilt from the outbox on boot). */
 var NcThrottleSchema = z.object({
 	cooldownSec: z.number().int().min(0).max(86400).default(60),
 	/** `rule` = one shared cooldown; `rule-device` = per-camera cooldown. */
-	scope: z.enum(["rule", "rule-device"]).default("rule-device")
+	scope: z.enum(["rule", "rule-device"]).default("rule-device"),
+	/**
+	* Class granularity of the cooldown key. Optional rather than defaulted:
+	* a Zod default does NOT run on the addon→addon cap path, so a persisted
+	* rule authored before this field simply carries none — and the engine
+	* reads absent as `shared`, the pre-existing behaviour.
+	*/
+	granularity: NcThrottleGranularitySchema.optional()
 });
 /** Client-supplied rule fields (server stamps id/createdBy/createdAt/updatedAt). */
 var NcRuleInputSchema = z.object({
@@ -5650,6 +5740,7 @@ var NcConditionDescriptorSchema = z.object({
 		"schedule",
 		"plateMatcher",
 		"packagePhase",
+		"crossingSelect",
 		"polygonDraw",
 		"occupancy"
 	]),
@@ -10422,6 +10513,18 @@ var motionCapability = {
 	name: "motion",
 	scope: "device",
 	mode: "singleton",
+	/**
+	* Providers register per-device natives via `ctx.registerNativeCap`
+	* (Hikvision/Reolink/Amcrest/Wyze/HA/Homematic/Alexa/Matter) — there is
+	* NO system singleton provider. Without this flag `resolveCapMount`
+	* derived `{ kind: 'singleton' }`, so `motion.getStatus`/`isDetected`
+	* resolved via `registry.getSingleton('motion')` (always null) and every
+	* call 412'd "provider not available" while bindings listed a live
+	* `motion` native (2026-08-02). The flag routes the router through
+	* `requireDeviceScoped` → `getProviderForDevice`, like `motion-trigger`,
+	* `snapshot` and every other per-device native cap.
+	*/
+	deviceNative: true,
 	deviceTypes: [DeviceType.Camera, DeviceType.Sensor],
 	methods: { 
 	/**
@@ -15673,7 +15776,29 @@ var deviceManagerCapability = {
 		getDeviceStatusAggregate: method(z.object({
 			deviceId: z.number(),
 			caps: z.array(z.string()).readonly().optional()
-		}), z.record(z.string(), z.unknown().nullable()))
+		}), z.record(z.string(), z.unknown().nullable())),
+		/**
+		* The same aggregate, for a LIST of devices in one round-trip.
+		*
+		* The viewer's camera list is the caller this exists for. Each card asked
+		* for its own badges — battery here, recording mode there — so a ten-camera
+		* install issued N separate procedures per reconcile, each its own message
+		* on the one WebSocket that also carries the WebRTC signalling (the client
+		* has no `httpBatchLink`, so there is no transport-level batching to lean
+		* on: collapsing has to happen at the procedure level, which is here).
+		*
+		* Keyed by device id as a STRING — a JSON object cannot key by number, and
+		* pretending otherwise is how a record survives the wire only in tests.
+		* The per-device value is exactly what `getDeviceStatusAggregate` returns,
+		* so a caller can move between the two without reshaping anything.
+		*
+		* `caps` matters more here than in the single call: a client that needs two
+		* caps should not pay for every status-carrying cap × every device.
+		*/
+		getDeviceStatusAggregateBatch: method(z.object({
+			deviceIds: z.array(z.number()).readonly(),
+			caps: z.array(z.string()).readonly().optional()
+		}), z.record(z.string(), z.record(z.string(), z.unknown().nullable())))
 	}
 };
 /**
@@ -17399,6 +17524,37 @@ var MotionEventSchema = z.object({
 * Absent on legacy rows ⇒ treat as `pipeline`.
 */
 var DetectionSourceSchema = z.enum(["pipeline", "onboard"]);
+/**
+* Which WAY a subject crossed a zone boundary. An entry and an exit are two
+* different notifications ("the parcel arrived" / "the car left the drive"),
+* and until this existed they were indistinguishable on the persisted record —
+* which is why exits were computed and dropped at the emit boundary rather
+* than doubling every zone-scoped rule.
+*/
+var ZoneCrossingDirectionSchema = z.enum(["enter", "exit"]);
+/**
+* The confirmed zone crossing that produced an object event. Present ONLY on
+* an event emitted BY a crossing (`zone.enter` / `zone.exit`); a movement-state
+* event (`object.entering` / `leaving` / `stationary` / `loitering`) and an
+* appearance event carry none, so a rule asking for a direction fails closed
+* on them.
+*
+* Exactly ONE crossing per event: the emitter turns each confirmed crossing
+* into its own event, so a frame in which a track enters A while leaving B
+* produces two events with two directions — never one ambiguous row.
+*
+* `zoneId` is load-bearing for an EXIT: the event's `zones` list is the
+* membership the box has NOW, and by definition it no longer contains the zone
+* that was just left. Without the id here, a zone-scoped rule could never match
+* the exit it asked for.
+*/
+var ZoneCrossingSchema = z.object({
+	direction: ZoneCrossingDirectionSchema,
+	/** Admin zone id crossed. */
+	zoneId: z.string(),
+	/** Zone display name at crossing time (falls back to the id). */
+	zoneName: z.string().optional()
+});
 var ObjectEventSchema = z.object({
 	...BaseEventFields,
 	kind: z.literal("object"),
@@ -17425,6 +17581,12 @@ var ObjectEventSchema = z.object({
 	zones: z.array(z.string()).readonly().optional(),
 	/** Omitted in slim projection. */
 	state: TrackStateSchema.optional(),
+	/**
+	* The zone crossing this event IS, when it is one. Absent on every other
+	* event kind (movement state, appearance, package) — see
+	* {@link ZoneCrossingSchema}. Omitted in slim projection.
+	*/
+	zoneCrossing: ZoneCrossingSchema.optional(),
 	/** Detection-frame dimensions in pixels — let consumers normalize the
 	*  pixel-space `bbox` onto a displayed image. Omitted in slim projection. */
 	frameWidth: z.number().optional(),
@@ -24958,6 +25120,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceManager.getDeviceStatusAggregateBatch": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"deviceManager.getLinkedDevices": {
 		capName: "device-manager",
 		capScope: "system",