@camstack/types 0.1.14 → 0.1.16

package/dist/interfaces/readiness.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Consumer-facing interface for the kernel-owned readiness registry.
+ *
+ * Implemented by `ReadinessRegistry` under
+ * `@camstack/types/readiness/readiness-registry.ts`. Exposed here as a
+ * narrow interface so `AddonContext.kernel.readinessRegistry` can be
+ * typed without pulling the full registry module into the addon
+ * interface file (avoids import cycles).
+ *
+ * Addons emit via the standalone `emitReadiness(bus, ...)` helper —
+ * they don't need a registry handle for that. The registry is
+ * purely a consumer primitive: `awaitReady` for one-shot waits and
+ * `onReadyState` for long-lived observers.
+ */
+import type { ReadinessScope, ReadinessState } from './event-bus.js';
+export interface IReadinessTransition {
+    readonly capName: string;
+    readonly scope: ReadinessScope;
+    readonly state: ReadinessState;
+    readonly epoch: number;
+    readonly generation: string;
+    readonly sourceNodeId: string;
+    readonly ts: number;
+    readonly durationInPrevState: number;
+}
+export interface IReadinessRegistryRecord {
+    readonly capName: string;
+    readonly scope: ReadinessScope;
+    readonly state: ReadinessState;
+    readonly generation: string;
+    readonly epoch: number;
+    readonly lastChange: number;
+    /**
+     * Node that emitted the latest transition. Needed for `agent.offline`
+     * demux of `device`-scoped caps. For `node`-scoped caps this matches
+     * `scope.nodeId`.
+     */
+    readonly sourceNodeId: string;
+}
+export interface IAwaitReadyOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type IReadinessHandler = (transition: IReadinessTransition) => void;
+export interface IReadinessRegistry<TCapName extends string = string> {
+    /** Current snapshot for a `(capName, scope)` pair, or `null` if never seen. */
+    get(capName: TCapName, scope: ReadinessScope): IReadinessRegistryRecord | null;
+    /**
+     * One-shot: resolves when the cap is `ready`. Reads the snapshot
+     * first — if already ready, resolves on next tick. Rejects with
+     * `ReadinessTimeoutError` after `timeoutMs` (default 30_000) or
+     * with the AbortSignal's reason on cancel.
+     */
+    awaitReady(capName: TCapName, scope: ReadinessScope, opts?: IAwaitReadyOptions): Promise<void>;
+    /**
+     * Observable: every transition (starting/ready/down) dispatches to
+     * `handler`. On subscribe the current state (if known) replays
+     * asynchronously as the initial transition. Returns unsubscribe.
+     */
+    onReadyState(capName: TCapName, scope: ReadinessScope, handler: IReadinessHandler): () => void;
+    /**
+     * Hydrate the snapshot from an authoritative source (typically the
+     * hub's `$readiness.getSnapshot` action). Entries already present
+     * locally are skipped — live deltas always take precedence over the
+     * snapshot. For each newly added entry a one-shot transition is
+     * dispatched to matching subscriptions so pending `awaitReady`
+     * callers unblock without waiting for a fresh delta.
+     */
+    hydrate(records: readonly IReadinessRegistryRecord[]): void;
+    /**
+     * Serializable snapshot for cross-process transport. Returned as an
+     * array (MsgPack-friendly) rather than the internal Map.
+     */
+    getSnapshotForTransport(): readonly IReadinessRegistryRecord[];
+}
+/**
+ * A stable, cached reference to a capability that tracks readiness state.
+ * Obtained via `ctx.useCapability()` or `ctx.acquireCapability()`.
+ *
+ * The generic `T` is a phantom type documenting the expected provider interface.
+ */
+export interface ICapabilityHandle<T = unknown> {
+    readonly capName: string;
+    readonly scope: ReadinessScope;
+    readonly isReady: boolean;
+    /**
+     * Block until the capability is ready, or throw `CapabilityUnavailableError`
+     * on timeout.
+     */
+    awaitReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Execute `fn` with readiness gating. Blocks until ready, then calls `fn`.
+     * Preferred over `awaitReady() + fn()` because it re-gates after a
+     * down→ready cycle that may occur between the await and the call.
+     */
+    call<R>(fn: () => Promise<R>, timeoutMs?: number): Promise<R>;
+    /** Unsubscribe from ReadinessRegistry. Called by AddonContextImpl on shutdown. */
+    dispose(): void;
+    readonly _provider: T;
+}
+//# sourceMappingURL=readiness.d.ts.map

package/dist/interfaces/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/interfaces/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;CACrC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,oBAAoB,KAAK,IAAI,CAAA;AAE1E,MAAM,WAAW,kBAAkB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IAClE,+EAA+E;IAC/E,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,wBAAwB,GAAG,IAAI,CAAA;IAE9E;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9F;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAA;IAE9F;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,SAAS,wBAAwB,EAAE,GAAG,IAAI,CAAA;IAE3D;;;OAGG;IACH,uBAAuB,IAAI,SAAS,wBAAwB,EAAE,CAAA;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB;;;OAGG;IACH,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7C;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAE7D,kFAAkF;IAClF,OAAO,IAAI,IAAI,CAAA;IAGf,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAA;CACtB"}

package/dist/interfaces/repl.d.ts

@@ -9,7 +9,7 @@ export type ReplScope = {
     providerId: string;
 } | {
     type: 'device';
-    deviceId: string;
+    deviceId: number;
 } | {
     type: 'addon';
     addonId: string;

package/dist/interfaces/restreamer.d.ts

@@ -15,10 +15,10 @@ export interface RestreamerExposedResource {
 export interface IRestreamer {
     readonly id: string;
     readonly name: string;
-    registerDevice(deviceId: string, streams: readonly RegisteredStream[]): Promise<void>;
+    registerDevice(deviceId: number, streams: readonly RegisteredStream[]): Promise<void>;
     pushPacket(streamId: string, packet: EncodedPacket): void;
-    unregisterDevice(deviceId: string): Promise<void>;
-    getExposedResources(deviceId: string): readonly RestreamerExposedResource[];
+    unregisterDevice(deviceId: number): Promise<void>;
+    getExposedResources(deviceId: number): readonly RestreamerExposedResource[];
     proxyWhepOffer?(streamId: string, sdpOffer: string): Promise<string>;
 }
 //# sourceMappingURL=restreamer.d.ts.map

package/dist/interfaces/scoped-token.d.ts

@@ -1,22 +1,2 @@
-/**
- * Scope restriction for a scoped token.
- */
-export interface TokenScope {
-    readonly type: 'addon' | 'route-prefix' | 'capability';
-    readonly target: string;
-}
-/**
- * A per-user API token with restricted scopes.
- */
-export interface ScopedToken {
-    readonly id: string;
-    readonly userId: string;
-    readonly name: string;
-    readonly tokenHash: string;
-    readonly tokenPrefix: string;
-    readonly scopes: TokenScope[];
-    readonly expiresAt?: number;
-    readonly lastUsedAt?: number;
-    readonly createdAt: number;
-}
+export { type TokenScope, type ScopedToken } from '../schemas/auth-records.js';
 //# sourceMappingURL=scoped-token.d.ts.map

package/dist/interfaces/scoped-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-token.d.ts","sourceRoot":"","sources":["../../src/interfaces/scoped-token.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,GAAG,YAAY,CAAA;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAA;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B"}
+{"version":3,"file":"scoped-token.d.ts","sourceRoot":"","sources":["../../src/interfaces/scoped-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/interfaces/server-analysis.d.ts

@@ -1,11 +1,34 @@
 /**
- * Detection Analysis Pipeline -- processes raw detections through
- * configurable stages to produce tracked, enriched, actionable events.
+ * Detection Analysis Pipeline -- types for tracked detections, sub-detections,
+ * recognition results, and audio classification.
  */
-import type { Detection } from './device-capabilities/object-detector.js';
 import type { VideoFrame } from './camera-pipeline.js';
-export declare const DETECTION_TYPES: readonly ["person", "vehicle", "animal", "package"];
-export type DetectionType = typeof DETECTION_TYPES[number];
+/**
+ * A single detection entry consumed by the analysis pipeline (tracking,
+ * zones, session aggregation).
+ *
+ * Intentionally DIFFERENT from `SpatialDetection` (the engine-level
+ * detector output in `types/detection.ts`):
+ *   - `SpatialDetection` is raw model output: `{class, bbox:{x,y,w,h},
+ *     landmarks?, mask?}`.
+ *   - `AnalysisDetection` is the pipeline's view: tuple-bbox
+ *     `[x1,y1,x2,y2]`, optional enrichment (`id`, `label`, `zones`,
+ *     `previousZones`) added by upstream stages.
+ *
+ * Renamed from the ambiguous `Detection` on 2026-04-14 to disambiguate
+ * from the other Detection types in the codebase (`ObjectDetection`
+ * for UI payloads, `SpatialDetection` for engine output).
+ */
+export interface AnalysisDetection {
+    className: string;
+    score: number;
+    boundingBox?: [number, number, number, number];
+    id?: string;
+    label?: string;
+    labelScore?: number;
+    zones?: string[];
+    previousZones?: string[];
+}
 export declare const SUB_DETECTION_TYPES: readonly ["face", "plate"];
 export type SubDetectionType = typeof SUB_DETECTION_TYPES[number];
 export declare const RECOGNITION_TYPES: readonly ["face", "plate", "clip", "custom"];
@@ -14,14 +37,14 @@ export interface AnalysisContext {
     readonly deviceId: string;
     readonly frame: VideoFrame;
     readonly timestamp: number;
-    readonly rawDetections: readonly Detection[];
+    readonly rawDetections: readonly AnalysisDetection[];
     readonly trackedDetections: readonly ServerTrackedDetection[];
     readonly events: readonly AnalysisEvent[];
     readonly metadata: Readonly<Record<string, unknown>>;
 }
 export interface ServerTrackedDetection {
     readonly trackId: string;
-    readonly detection: Detection;
+    readonly detection: AnalysisDetection;
     readonly crop?: Buffer;
     readonly tracking: TrackingInfo;
     readonly subDetections: readonly SubDetection[];
@@ -63,84 +86,4 @@ export interface AnalysisEvent {
     readonly description: string;
     readonly data: Readonly<Record<string, unknown>>;
 }
-export interface IAnalysisStage {
-    readonly id: string;
-    readonly name: string;
-    readonly priority: number;
-    enabled: boolean;
-    process(ctx: AnalysisContext): Promise<AnalysisContext>;
-}
-export interface ISubDetector {
-    readonly detectionType: SubDetectionType;
-    readonly targetClasses: readonly string[];
-    detect(crop: Buffer, cropWidth: number, cropHeight: number): Promise<SubDetection[]>;
-}
-export interface IFaceDetector extends ISubDetector {
-    readonly detectionType: 'face';
-}
-export interface IPlateDetector extends ISubDetector {
-    readonly detectionType: 'plate';
-}
-export interface IRecognizer {
-    readonly recognitionType: RecognitionType;
-    recognize(crop: Buffer, width: number, height: number): Promise<RecognitionResult | null>;
-}
-export interface IFaceRecognizer extends IRecognizer {
-    getEmbedding(crop: Buffer): Promise<Float32Array>;
-    registerKnown(label: string, embedding: Float32Array): void;
-}
-export interface IPlateRecognizer extends IRecognizer {
-    readonly recognitionType: 'plate';
-}
-export interface IAudioClassifier {
-    readonly ready: boolean;
-    initialize(): Promise<void>;
-    classify(audioSamples: Float32Array, sampleRate: number, topN?: number): Promise<readonly AudioClassification[]>;
-    release(): Promise<void>;
-}
-export interface AudioClassification {
-    readonly classIndex: number;
-    readonly className: string;
-    readonly score: number;
-    readonly isSurveillanceRelevant: boolean;
-}
-export interface IClassFilterStage extends IAnalysisStage {
-    readonly id: 'class-filter';
-    setConfig(deviceId: string, config: Record<string, unknown>): void;
-    getConfig(deviceId: string): Record<string, unknown>;
-}
-export interface ITrackerStage extends IAnalysisStage {
-    readonly id: 'tracker';
-    setConfig(deviceId: string, config: Record<string, unknown>): void;
-    getConfig(deviceId: string): Record<string, unknown>;
-    resetDevice(deviceId: string): void;
-}
-export interface ISubDetectionStage extends IAnalysisStage {
-    readonly id: 'sub-detection';
-    registerDetector(detector: ISubDetector): void;
-}
-export interface IRecognitionStage extends IAnalysisStage {
-    readonly id: 'recognition';
-    registerRecognizer(recognizer: IRecognizer): void;
-}
-export interface IZoneAnalysisStage extends IAnalysisStage {
-    readonly id: 'zone-analysis';
-    setConfig(deviceId: string, config: Record<string, unknown>): void;
-}
-export interface IEventGenerationStage extends IAnalysisStage {
-    readonly id: 'event-generation';
-    setConfig(deviceId: string, config: Record<string, unknown>): void;
-}
-export interface IObjectSnapshotStage extends IAnalysisStage {
-    readonly id: 'object-snapshot';
-    setConfig(deviceId: string, config: Record<string, unknown>): void;
-}
-export interface IAnalysisPipeline {
-    addStage(stage: IAnalysisStage): void;
-    removeStage(stageId: string): void;
-    getStages(): readonly IAnalysisStage[];
-    analyze(deviceId: string, frame: VideoFrame, rawDetections: Detection[]): Promise<AnalysisContext>;
-}
-export declare function createAnalysisContext(deviceId: string, frame: VideoFrame, rawDetections: Detection[]): AnalysisContext;
-export declare function enrichContext(ctx: AnalysisContext, updates: Partial<Pick<AnalysisContext, 'trackedDetections' | 'events' | 'metadata'>>): AnalysisContext;
 //# sourceMappingURL=server-analysis.d.ts.map

package/dist/interfaces/server-analysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-analysis.d.ts","sourceRoot":"","sources":["../../src/interfaces/server-analysis.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0CAA0C,CAAA;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAItD,eAAO,MAAM,eAAe,qDAAsD,CAAA;AAClF,MAAM,MAAM,aAAa,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC,CAAA;AAE1D,eAAO,MAAM,mBAAmB,4BAA6B,CAAA;AAC7D,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAA;AAEjE,eAAO,MAAM,iBAAiB,8CAA+C,CAAA;AAC7E,MAAM,MAAM,eAAe,GAAG,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAA;AAI9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;IACzC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACrD;AAID,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/C,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,YAAY,GAAG,KAAK,GAAG,MAAM,CAAA;IACxD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACxG;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAA;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACtD;AAID,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;IAC/C,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAA;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACjD;AAID,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CACxD;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAA;IACxC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;IACzC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;CACrF;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;CAChC;AAID,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IACzC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;CAC1F;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACjD,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAG,IAAI,CAAA;CAC5D;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAClC;AAID,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,QAAQ,CACN,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAA;IAC1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAA;CACzC;AAID,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAClE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;IACtB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAClE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;CAC/C;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,kBAAkB,CAAC,UAAU,EAAE,WAAW,GAAG,IAAI,CAAA;CAClD;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACnE;AAED,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAA;IAC/B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACnE;AAED,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAA;IAC9B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACnE;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;IACrC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,SAAS,IAAI,SAAS,cAAc,EAAE,CAAA;IACtC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CACnG;AAID,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,SAAS,EAAE,GACzB,eAAe,CAUjB;AAED,wBAAgB,aAAa,CAC3B,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,mBAAmB,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC,GACnF,eAAe,CAOjB"}
+{"version":3,"file":"server-analysis.d.ts","sourceRoot":"","sources":["../../src/interfaces/server-analysis.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/storage-location.d.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+/**
+ * `StorageLocationType` — the closed enum of *kinds* of storage a location
+ * can serve. Defined here (not in `capabilities/storage.cap.ts`) so the
+ * persisted record schema and the consumer-facing cap can both consume it
+ * without forming a circular import. The `storage` cap re-exports it
+ * verbatim for back-compat.
+ *
+ * This Zod schema is the **authoritative source** for `StorageLocationType`.
+ * The TS alias in `./storage.ts` re-exports `z.infer<typeof
+ * StorageLocationTypeSchema>` so the wire surface (cap) and the legacy
+ * `IStorageProvider` interface stay in lockstep.
+ */
+export declare const StorageLocationTypeSchema: z.ZodEnum<{
+    data: "data";
+    media: "media";
+    recordings: "recordings";
+    cache: "cache";
+    logs: "logs";
+    models: "models";
+    "recordings-high": "recordings-high";
+    "recordings-low": "recordings-low";
+    "recordings-clips": "recordings-clips";
+    "event-images": "event-images";
+    "addons-data": "addons-data";
+    backups: "backups";
+}>;
+/**
+ * `StorageLocationType` — TS alias for the Zod enum above. Re-exported
+ * by `./storage.ts` so the legacy `IStorageProvider` interface keeps the
+ * same name without duplicating the literal union.
+ */
+export type StorageLocationType = z.infer<typeof StorageLocationTypeSchema>;
+/**
+ * Cardinality of a storage location type:
+ *
+ *  - `singleton` — exactly one location instance allowed system-wide.
+ *    Multiple instances would split state in a way that breaks
+ *    consumers (e.g. two `addons-data` roots → addon's persistent
+ *    state lands in either or both; two `cache` roots → cache misses
+ *    on every read; two `data` roots → sqlite path bifurcation).
+ *    Operators can EDIT the singleton's config (path / providerId)
+ *    but never add a second instance. The seed always creates the
+ *    initial default.
+ *
+ *  - `multi` — multiple instances are first-class. Operators add
+ *    secondary locations (e.g. NAS + local SSD for `recordings`,
+ *    offsite + on-disk for `backups`). One is `isDefault: true`
+ *    at any moment; others are addressable via fully-qualified id.
+ *
+ * Used by `StorageOrchestratorService.upsertLocation` to reject
+ * "Add" attempts on singleton types, and by the admin UI to hide
+ * the "+ Add location" button on those groups.
+ */
+export declare const STORAGE_LOCATION_CARDINALITY: Readonly<Record<StorageLocationType, 'singleton' | 'multi'>>;
+/**
+ * Persisted record for a storage location instance. Multi-instance
+ * (per `STORAGE_LOCATION_CARDINALITY[type]`) — operators can register
+ * e.g. two `backups` locations (one filesystem, one SFTP) with
+ * different `providerId`s, but only one `cache`/`data`/etc.
+ *
+ * `id` is a stable namespaced string of the form `<type>:<slug>`.
+ * The default location for a type uses `id === <type>:default` by
+ * convention (the bare type ref like `'backups'` resolves to it).
+ *
+ * `isSystem: true` marks a location as orchestrator-seeded and
+ * undeletable. The bootstrap-installed defaults (one per type) carry
+ * this flag; operator-added locations don't. Editing the config of
+ * a system location is allowed (path migration, provider swap) but
+ * deleting it is rejected at the cap level.
+ */
+export declare const StorageLocationSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        data: "data";
+        media: "media";
+        recordings: "recordings";
+        cache: "cache";
+        logs: "logs";
+        models: "models";
+        "recordings-high": "recordings-high";
+        "recordings-low": "recordings-low";
+        "recordings-clips": "recordings-clips";
+        "event-images": "event-images";
+        "addons-data": "addons-data";
+        backups: "backups";
+    }>;
+    displayName: z.ZodString;
+    providerId: z.ZodString;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    isDefault: z.ZodDefault<z.ZodBoolean>;
+    isSystem: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type StorageLocation = z.infer<typeof StorageLocationSchema>;
+/**
+ * Reference accepted by consumer-facing `api.storage.*` calls.
+ * Either:
+ *  - a `StorageLocationType` (e.g. `'backups'`) → orchestrator resolves to the default of that type
+ *  - a fully-qualified id (e.g. `'backups:nas-01'`) → addresses a specific instance
+ *
+ * The orchestrator's `resolveRef(ref)` handles both cases.
+ */
+export declare const StorageLocationRefSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    data: "data";
+    media: "media";
+    recordings: "recordings";
+    cache: "cache";
+    logs: "logs";
+    models: "models";
+    "recordings-high": "recordings-high";
+    "recordings-low": "recordings-low";
+    "recordings-clips": "recordings-clips";
+    "event-images": "event-images";
+    "addons-data": "addons-data";
+    backups: "backups";
+}>, z.ZodString]>;
+export type StorageLocationRef = z.infer<typeof StorageLocationRefSchema>;
+//# sourceMappingURL=storage-location.d.ts.map

package/dist/interfaces/storage-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-location.d.ts","sourceRoot":"","sources":["../../src/interfaces/storage-location.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;EAsBpC,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,WAAW,GAAG,OAAO,CAAC,CAerG,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;iBAUhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;iBAGnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}