@camstack/types 1.1.49 → 1.1.51

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-BfvNtyu8.js");
+const require_sleep = require("./sleep-CF-UWPp0.js");
 const require_event_category = require("./event-category-CGj9fI4L.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 exports.BaseAddon = require_sleep.BaseAddon;

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { A as parseJsonUnknown, D as asString, I as scopeKey, M as ReadinessRegistry, N as ReadinessTimeoutError, S as DeviceType, T as asJsonObject, a as viewerUiCapability, bt as DisposerChain, ct as BaseAddon, ft as emitReadiness, i as deviceOpsCapability, j as DATAPLANE_SECRET_HEADER, lt as normalizeAddonInitResult, m as expandCapMethods, o as adminUiCapability, s as createDeviceProxy, t as sleep } from "./sleep-DOq2moJx.mjs";
+import { A as parseJsonUnknown, D as asString, I as scopeKey, M as ReadinessRegistry, N as ReadinessTimeoutError, S as DeviceType, T as asJsonObject, a as viewerUiCapability, bt as DisposerChain, ct as BaseAddon, ft as emitReadiness, i as deviceOpsCapability, j as DATAPLANE_SECRET_HEADER, lt as normalizeAddonInitResult, m as expandCapMethods, o as adminUiCapability, s as createDeviceProxy, t as sleep } from "./sleep-D8ZkNoYz.mjs";
 import { t as EventCategory } from "./event-category-D4HJq7Mw.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 export { BaseAddon, DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, ReadinessTimeoutError, adminUiCapability, asJsonObject, asString, createDeviceProxy, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, normalizeAddonInitResult, parseJsonUnknown, scopeKey, sleep, viewerUiCapability };

package/dist/capabilities/index.d.ts

@@ -77,8 +77,8 @@ export { type ILlmProvider, type LlmDefault, type LlmDefaultSelector, LlmDefault
 export { type ILlmRuntimeProvider, llmRuntimeCapability, type LlmNodeModel, LlmNodeModelSchema, type LlmRuntimeCompleteInput, LlmRuntimeCompleteInputSchema, type LlmRuntimeDiskUsage, LlmRuntimeDiskUsageSchema, type LlmRuntimeStatus, LlmRuntimeStatusSchema, type ManagedModelRef, ManagedModelRefSchema, type ManagedRuntimeConfig, ManagedRuntimeConfigSchema, } from './llm-runtime.cap.js';
 export { type LlmErrorCode, LlmErrorCodeSchema, type LlmGenerateBaseInput, LlmGenerateBaseInputSchema, type LlmGenerateErr, LlmGenerateErrSchema, type LlmGenerateOk, LlmGenerateOkSchema, type LlmGenerateResult, LlmGenerateResultSchema, type LlmImage, LlmImageSchema, type LlmUsage, LlmUsageSchema, } from './llm-shared.js';
 export { type IOauthIntegrationProvider, type OauthIntegrationDescriptor, OauthIntegrationDescriptorSchema, oauthIntegrationCapability, } from './oauth-integration.cap.js';
-export { type AudioEvent, AudioEventSchema, type DetectionSource, DetectionSourceSchema, type EventKind, type EventKindCategory, EventKindCategorySchema, type EventKindDescriptor, EventKindDescriptorSchema, type EventKindIcon, EventKindIconSchema, EventKindSchema, type IPipelineAnalyticsProvider, type KeyEvent, KeyEventSchema, type MediaFile, type MediaFileKind, MediaFileSchema, type MotionEvent, MotionEventSchema, type ObjectEvent, ObjectEventSchema, pipelineAnalyticsCapability, type RecentTracksPage, RecentTracksPageSchema, type RecentTracksQuery, RecentTracksQueryInput, type ScoredObjectEvent, ScoredObjectEventSchema, type SensorEvent, SensorEventSchema, type Track, type TrackCascadeCounts, TrackCascadeCountsSchema, TrackedDetectionSchema, type TrackEnvelope, TrackEnvelopeSchema, type TrackProjection, TrackProjectionSchema, TrackSchema, type TrackState, TrackStateSchema, type TrackZoneFilter, TrackZoneFilterSchema, } from './pipeline-analytics.cap.js';
-export { EVENT_KIND_BY_CAP, type SensorEventKindDescriptor } from './sensor-event-kinds.js';
+export { type AudioEvent, AudioEventSchema, type DetectionSource, DetectionSourceSchema, type EventKind, type EventKindCategory, EventKindCategorySchema, type EventKindDescriptor, EventKindDescriptorSchema, type EventKindIcon, EventKindIconSchema, EventKindSchema, type EventPruneCounts, type EventStoreDeviceFootprint, type EventStoreFootprint, type IPipelineAnalyticsProvider, type KeyEvent, KeyEventSchema, type MediaFile, type MediaFileKind, MediaFileSchema, type MotionEvent, MotionEventSchema, type ObjectEvent, ObjectEventSchema, pipelineAnalyticsCapability, type RecentTracksPage, RecentTracksPageSchema, type RecentTracksQuery, RecentTracksQueryInput, type ScoredObjectEvent, ScoredObjectEventSchema, type SensorEvent, SensorEventSchema, type Track, type TrackCascadeCounts, TrackCascadeCountsSchema, TrackedDetectionSchema, type TrackEnvelope, TrackEnvelopeSchema, type TrackProjection, TrackProjectionSchema, TrackSchema, type TrackState, TrackStateSchema, type TrackZoneFilter, TrackZoneFilterSchema, } from './pipeline-analytics.cap.js';
+export { EVENT_KIND_BY_CAP, EVENTFUL_CAP_NAMES, buildEventKindDescriptor, type SensorEventKindDescriptor, } from './sensor-event-kinds.js';
 export type { PipelineStepInputOutput, PipelineValidationIssue, PipelineValidationResult, } from './pipeline-executor.cap.js';
 export { ModelSubstitutionSchema, PipelineDefaultStepSchema, PipelineEngineChoiceSchema, PipelineRunResultBridge, PipelineStepInputSchema, PipelineValidationIssueSchema, PipelineValidationResultSchema, pipelineExecutorCapability, } from './pipeline-executor.cap.js';
 export type { CameraAssignmentStatus, CameraAudioStatus, CameraBrokerProfile, CameraBrokerStatus, CameraDecoderShm, CameraDecoderStatus, CameraDetectionPhase, CameraDetectionProvisioning, CameraDetectionProvisioningState, CameraDetectionStatus, CameraMotionStatus, CameraRecordingMode, CameraRecordingStatus, CameraSourceStatus, CameraSourceStream, CameraStatus, IngestOwner, } from './pipeline-orchestrator.cap.js';

package/dist/capabilities/pipeline-analytics.cap.d.ts

@@ -76,6 +76,7 @@ export declare const EventKindIconSchema: z.ZodEnum<{
 export type EventKindIcon = z.infer<typeof EventKindIconSchema>;
 export declare const EventKindCategorySchema: z.ZodEnum<{
     sensor: "sensor";
+    control: "control";
     audio: "audio";
     custom: "custom";
     motion: "motion";
@@ -83,10 +84,18 @@ export declare const EventKindCategorySchema: z.ZodEnum<{
     detection: "detection";
 }>;
 export type EventKindCategory = z.infer<typeof EventKindCategorySchema>;
+/** Taxonomy level — macro (timeline lane) vs sub (events-page leaf). */
+export declare const EventKindLevelSchema: z.ZodEnum<{
+    sub: "sub";
+    macro: "macro";
+}>;
+export type EventKindLevel = z.infer<typeof EventKindLevelSchema>;
 declare const EventKindDescriptorSchema: z.ZodObject<{
     kind: z.ZodString;
+    labelKey: z.ZodString;
     label: z.ZodString;
     color: z.ZodString;
+    iconId: z.ZodString;
     icon: z.ZodEnum<{
         button: "button";
         generic: "generic";
@@ -103,12 +112,18 @@ declare const EventKindDescriptorSchema: z.ZodObject<{
     }>;
     category: z.ZodEnum<{
         sensor: "sensor";
+        control: "control";
         audio: "audio";
         custom: "custom";
         motion: "motion";
         package: "package";
         detection: "detection";
     }>;
+    parentKind: z.ZodNullable<z.ZodString>;
+    level: z.ZodEnum<{
+        sub: "sub";
+        macro: "macro";
+    }>;
     source: z.ZodObject<{
         capName: z.ZodString;
         deviceId: z.ZodNumber;
@@ -168,11 +183,27 @@ declare const TrackAudioLabelSchema: z.ZodObject<{
     lastAt: z.ZodNumber;
 }, z.core.$strip>;
 export type TrackAudioLabel = z.infer<typeof TrackAudioLabelSchema>;
+/**
+ * How a track was produced. `pipeline` (default / absent) = the spatial
+ * detection+tracking pipeline. `sensor` = a SYNTHETIC track projected from a
+ * linked sensor/control state change (no positions; carries a snapshot). The
+ * spatial subsystems (tracker association, occupancy count, re-id/embedding,
+ * resurrection) MUST skip `sensor` tracks — they have no bbox trajectory.
+ */
+export declare const TrackSourceSchema: z.ZodEnum<{
+    sensor: "sensor";
+    pipeline: "pipeline";
+}>;
+export type TrackSource = z.infer<typeof TrackSourceSchema>;
 declare const TrackSchema: z.ZodObject<{
     trackId: z.ZodString;
     deviceId: z.ZodNumber;
     className: z.ZodString;
     label: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodEnum<{
+        sensor: "sensor";
+        pipeline: "pipeline";
+    }>>;
     firstSeen: z.ZodNumber;
     lastSeen: z.ZodNumber;
     positions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -365,6 +396,10 @@ declare const RecentTracksPageSchema: z.ZodObject<{
         deviceId: z.ZodNumber;
         className: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodEnum<{
+            sensor: "sensor";
+            pipeline: "pipeline";
+        }>>;
         firstSeen: z.ZodNumber;
         lastSeen: z.ZodNumber;
         positions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -500,6 +535,31 @@ declare const TrackCascadeCountsSchema: z.ZodObject<{
     embeddings: z.ZodNumber;
 }, z.core.$strip>;
 export type TrackCascadeCounts = z.infer<typeof TrackCascadeCountsSchema>;
+/** Event-store footprint for one camera. */
+declare const EventStoreDeviceFootprintSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    rows: z.ZodNumber;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+export type EventStoreDeviceFootprint = z.infer<typeof EventStoreDeviceFootprintSchema>;
+/** Aggregate event-store footprint: global totals + per-camera breakdown. */
+declare const EventStoreFootprintSchema: z.ZodObject<{
+    totalRows: z.ZodNumber;
+    totalBytes: z.ZodNumber;
+    devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        rows: z.ZodNumber;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type EventStoreFootprint = z.infer<typeof EventStoreFootprintSchema>;
+/** Per-kind counts returned by the event-prune / device-delete mutations. */
+declare const EventPruneCountsSchema: z.ZodObject<{
+    motion: z.ZodNumber;
+    object: z.ZodNumber;
+    audio: z.ZodNumber;
+}, z.core.$strip>;
+export type EventPruneCounts = z.infer<typeof EventPruneCountsSchema>;
 export declare const pipelineAnalyticsCapability: {
     readonly name: "pipeline-analytics";
     readonly scope: "device";
@@ -516,6 +576,10 @@ export declare const pipelineAnalyticsCapability: {
             deviceId: z.ZodNumber;
             className: z.ZodString;
             label: z.ZodOptional<z.ZodString>;
+            source: z.ZodOptional<z.ZodEnum<{
+                sensor: "sensor";
+                pipeline: "pipeline";
+            }>>;
             firstSeen: z.ZodNumber;
             lastSeen: z.ZodNumber;
             positions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -580,6 +644,10 @@ export declare const pipelineAnalyticsCapability: {
             deviceId: z.ZodNumber;
             className: z.ZodString;
             label: z.ZodOptional<z.ZodString>;
+            source: z.ZodOptional<z.ZodEnum<{
+                sensor: "sensor";
+                pipeline: "pipeline";
+            }>>;
             firstSeen: z.ZodNumber;
             lastSeen: z.ZodNumber;
             positions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -666,6 +734,10 @@ export declare const pipelineAnalyticsCapability: {
             deviceId: z.ZodNumber;
             className: z.ZodString;
             label: z.ZodOptional<z.ZodString>;
+            source: z.ZodOptional<z.ZodEnum<{
+                sensor: "sensor";
+                pipeline: "pipeline";
+            }>>;
             firstSeen: z.ZodNumber;
             lastSeen: z.ZodNumber;
             positions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -748,6 +820,10 @@ export declare const pipelineAnalyticsCapability: {
                 deviceId: z.ZodNumber;
                 className: z.ZodString;
                 label: z.ZodOptional<z.ZodString>;
+                source: z.ZodOptional<z.ZodEnum<{
+                    sensor: "sensor";
+                    pipeline: "pipeline";
+                }>>;
                 firstSeen: z.ZodNumber;
                 lastSeen: z.ZodNumber;
                 positions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -916,8 +992,10 @@ export declare const pipelineAnalyticsCapability: {
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
+            labelKey: z.ZodString;
             label: z.ZodString;
             color: z.ZodString;
+            iconId: z.ZodString;
             icon: z.ZodEnum<{
                 button: "button";
                 generic: "generic";
@@ -934,12 +1012,18 @@ export declare const pipelineAnalyticsCapability: {
             }>;
             category: z.ZodEnum<{
                 sensor: "sensor";
+                control: "control";
                 audio: "audio";
                 custom: "custom";
                 motion: "motion";
                 package: "package";
                 detection: "detection";
             }>;
+            parentKind: z.ZodNullable<z.ZodString>;
+            level: z.ZodEnum<{
+                sub: "sub";
+                macro: "macro";
+            }>;
             source: z.ZodObject<{
                 capName: z.ZodString;
                 deviceId: z.ZodNumber;
@@ -1077,6 +1161,84 @@ export declare const pipelineAnalyticsCapability: {
             deleted: z.ZodNumber;
             failed: z.ZodReadonly<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>, "mutation">;
+        /**
+         * Durable event-store footprint for the management UI: event rows
+         * (motion + object + audio) counted per camera + total, plus the
+         * event-owned media bytes on disk per camera + total. Stat/count-based,
+         * computed on demand.
+         */
+        readonly getEventStoreFootprint: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+            totalRows: z.ZodNumber;
+            totalBytes: z.ZodNumber;
+            devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                rows: z.ZodNumber;
+                bytes: z.ZodNumber;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>, "query">;
+        /**
+         * Cluster-wide prune of events older than `olderThanMs` (exclusive) across
+         * every camera, deleting each event's media in lockstep. Logged to the
+         * events ops-log with `reason` (default `'retention'`). Returns the summed
+         * per-kind deleted counts.
+         */
+        readonly pruneEvents: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            olderThanMs: z.ZodNumber;
+            reason: z.ZodOptional<z.ZodEnum<{
+                manual: "manual";
+                retention: "retention";
+                quota: "quota";
+                operator: "operator";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            motion: z.ZodNumber;
+            object: z.ZodNumber;
+            audio: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
+        /**
+         * Manually delete EVERY event (motion + object + audio) for one camera and
+         * its event-owned media in lockstep. Logged to the events ops-log as
+         * `op:'manual-delete', reason:'manual'`. Destructive — the admin UI guards
+         * it behind a confirm.
+         */
+        readonly deleteDeviceEvents: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            motion: z.ZodNumber;
+            object: z.ZodNumber;
+            audio: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
+        /** The events ops-log rows (newest-first), optionally scoped to one camera.
+         *  Backed by a declared pipeline-analytics SQLite collection. */
+        readonly listOpsLog: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            at: z.ZodNumber;
+            domain: z.ZodEnum<{
+                events: "events";
+                recording: "recording";
+            }>;
+            op: z.ZodEnum<{
+                prune: "prune";
+                "manual-delete": "manual-delete";
+                rescan: "rescan";
+                "retention-run": "retention-run";
+            }>;
+            reason: z.ZodEnum<{
+                manual: "manual";
+                retention: "retention";
+                quota: "quota";
+                operator: "operator";
+            }>;
+            deviceId: z.ZodNullable<z.ZodNumber>;
+            nodeId: z.ZodString;
+            itemsAffected: z.ZodNumber;
+            bytesReclaimed: z.ZodNumber;
+            detail: z.ZodNullable<z.ZodString>;
+            actor: z.ZodString;
+        }, z.core.$strip>>>, "query">;
         readonly getEventMedia: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             eventId: z.ZodString;
             kind: z.ZodOptional<z.ZodEnum<{

package/dist/capabilities/recording.cap.d.ts

@@ -464,14 +464,68 @@ export declare const recordingCapability: {
             storageBytes: z.ZodNumber;
         }, z.core.$strip>, "mutation">;
         /** Apply this device's retention policy to footage now; returns the oldest
-         *  surviving footage start (the retention floor) or null if no footage. */
+         *  surviving footage start (the retention floor) or null if no footage. The
+         *  prune is logged to the recordings ops-log with `reason` (default
+         *  `'retention'` — the policy-driven prune; `'quota'` when disk-pressure
+         *  triggered). */
         readonly pruneFootage: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
+            reason: z.ZodOptional<z.ZodEnum<{
+                manual: "manual";
+                retention: "retention";
+                quota: "quota";
+                operator: "operator";
+            }>>;
         }, z.core.$strip>, z.ZodObject<{
             floorMs: z.ZodNullable<z.ZodNumber>;
             deletedBuckets: z.ZodNumber;
             reclaimedBytes: z.ZodNumber;
         }, z.core.$strip>, "mutation">;
+        /**
+         * Manually delete a camera's footage — the whole footprint, or a
+         * `[fromMs, toMs)` window when either bound is given. Logged to the
+         * recordings ops-log as `op:'manual-delete', reason:'manual'`. Destructive:
+         * the admin UI guards it behind a confirm.
+         */
+        readonly deleteFootprint: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            fromMs: z.ZodOptional<z.ZodNumber>;
+            toMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            deletedBuckets: z.ZodNumber;
+            reclaimedBytes: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
+        /** The recordings ops-log rows (newest-first), optionally scoped to one
+         *  camera. Backed by the recorder's bounded DurableState ring. */
+        readonly listOpsLog: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            at: z.ZodNumber;
+            domain: z.ZodEnum<{
+                events: "events";
+                recording: "recording";
+            }>;
+            op: z.ZodEnum<{
+                prune: "prune";
+                "manual-delete": "manual-delete";
+                rescan: "rescan";
+                "retention-run": "retention-run";
+            }>;
+            reason: z.ZodEnum<{
+                manual: "manual";
+                retention: "retention";
+                quota: "quota";
+                operator: "operator";
+            }>;
+            deviceId: z.ZodNullable<z.ZodNumber>;
+            nodeId: z.ZodString;
+            itemsAffected: z.ZodNumber;
+            bytesReclaimed: z.ZodNumber;
+            detail: z.ZodNullable<z.ZodString>;
+            actor: z.ZodString;
+        }, z.core.$strip>>>, "query">;
     };
 };
 export type IRecordingProvider = InferProvider<typeof recordingCapability>;

package/dist/capabilities/sensor-event-kinds.d.ts

@@ -1,25 +1,42 @@
 /**
- * Static event-kind descriptors for the SENSOR cap family — the mapping
+ * Cap → event-kind mapping for the SENSOR / CONTROL cap families — the table
  * `pipeline-analytics.listEventKinds` uses to turn a linked device's bound
- * sensor caps (contact / flood / gas / carbon-monoxide / enum-sensor /
- * event-emitter) into per-camera event-kind entries.
+ * caps into per-camera event-kind descriptors.
  *
- * Lives beside the sensor cap definitions so adding a new sensor cap and its
- * event-kind descriptor happens in one place. The `source` field of the full
- * `EventKindDescriptor` is stamped at compose time (per linked device) — this
- * map carries only the static half.
+ * The descriptor DATA (color / iconId / labelKey / parentKind / category)
+ * is NOT duplicated here — every entry is derived from the single
+ * `EVENT_TAXONOMY` dictionary (`catalogs/event-taxonomy.ts`). This file owns
+ * ONLY the cap-name → taxonomy-kind mapping. Adding a new eventful sensor /
+ * control cap means adding one line here (and a taxonomy entry); the anti-
+ * drift guard `scripts/check-event-kind-coverage.ts` fails the build if an
+ * eventful cap is missing.
  */
-import type { EventKindCategory, EventKindIcon } from './pipeline-analytics.cap.js';
-/** The static half of an `EventKindDescriptor` (no per-device `source`). */
-export interface SensorEventKindDescriptor {
-    readonly kind: string;
-    readonly label: string;
-    readonly color: string;
+import { type EventTaxonomyEntry } from '../catalogs/event-taxonomy.js';
+import type { EventKindDescriptor, EventKindIcon } from './pipeline-analytics.cap.js';
+/**
+ * The static half of an `EventKindDescriptor` (no per-device `source`).
+ * Extends the taxonomy entry with the legacy closed-enum `icon` glyph kept
+ * as a fallback for clients that predate `iconId`.
+ */
+export interface SensorEventKindDescriptor extends EventTaxonomyEntry {
+    /** Legacy closed-vocab glyph — fallback for `iconId`. */
     readonly icon: EventKindIcon;
-    readonly category: EventKindCategory;
 }
 /**
- * Sensor cap name → static event-kind descriptor. A linked device
+ * Sensor / control cap name → static event-kind descriptor. A linked device
  * contributes one entry per bound cap present in this map.
  */
 export declare const EVENT_KIND_BY_CAP: Readonly<Record<string, SensorEventKindDescriptor>>;
+/** The cap names covered by the taxonomy (for the anti-drift guard). */
+export declare const EVENTFUL_CAP_NAMES: readonly string[];
+/**
+ * Build a full `EventKindDescriptor` for a taxonomy `kind`, stamping the
+ * per-device `source`. Returns null when `kind` is not in the taxonomy.
+ * This is THE bridge from the serializable taxonomy dictionary to the cap
+ * wire shape — every event-kind descriptor the server emits goes through it,
+ * so color/iconId/labelKey are never re-declared at a call site.
+ */
+export declare function buildEventKindDescriptor(kind: string, source: {
+    readonly capName: string;
+    readonly deviceId: number;
+}): EventKindDescriptor | null;

package/dist/capabilities/zone-rules.cap.d.ts

@@ -100,9 +100,10 @@ export declare const zoneRulesCapability: {
      * `package` backs the package-drop detector — a package zone is a
      * `ZoneRule` on the `'package'` stage referencing drawn polygons
      * (see docs/superpowers/specs/2026-07-17-package-zones-design.md §3.1).
-     * The orchestrator provider that writes this stage lands in a later
-     * slice; until then the mirror carries only `{motion, detection}` and
-     * consumers read `package` as absent (treat as `[]`).
+     * The orchestrator provider writes this stage as a first-class slice
+     * (Phase 4): every mutation mirrors the full `{motion, detection,
+     * package}` shape, so consumers read the current package rules directly
+     * off `device.state.zoneRules.value.package`.
      */
     readonly runtimeState: z.ZodObject<{
         motion: z.ZodReadonly<z.ZodArray<z.ZodObject<{

package/dist/catalogs/event-taxonomy.d.ts

@@ -0,0 +1,44 @@
+export type EventTaxonomyCategory = 'motion' | 'audio' | 'detection' | 'sensor' | 'control' | 'package' | 'custom';
+export type EventTaxonomyLevel = 'macro' | 'sub';
+/**
+ * The static, serializable half of an event kind. Descriptors surfaced by
+ * `listEventKinds` extend this with a per-device `source`.
+ */
+export interface EventTaxonomyEntry {
+    /** Unique kind id ('vehicle', 'car', 'lock', 'audio-dog', …). */
+    readonly kind: string;
+    /** Macro parent ('car' → 'vehicle'); null for a macro. */
+    readonly parentKind: string | null;
+    /** Derived from `parentKind` — explicit for the UI. */
+    readonly level: EventTaxonomyLevel;
+    readonly category: EventTaxonomyCategory;
+    /** Hex color for timeline/legend rendering. */
+    readonly color: string;
+    /** Dictionary id → lucide component on the UI side. */
+    readonly iconId: string;
+    /** i18n key; `label` is the English fallback. */
+    readonly labelKey: string;
+    /** English fallback label (UI translates `labelKey` when it can). */
+    readonly label: string;
+}
+export declare const TAXONOMY_COLORS: {
+    readonly motion: "#f59e0b";
+    readonly audio: "#06b6d4";
+    readonly person: "#22c55e";
+    readonly vehicle: "#3b82f6";
+    readonly animal: "#f97316";
+    readonly package: "#a855f7";
+    readonly sensor: "#8b5cf6";
+    readonly control: "#10b981";
+    readonly genericDetection: "#64748b";
+};
+/** Global default color when a kind is unknown (matches legacy box-drawer). */
+export declare const DEFAULT_EVENT_COLOR = "#22ff55";
+/** The complete taxonomy dictionary, keyed by kind. */
+export declare const EVENT_TAXONOMY: Readonly<Record<string, EventTaxonomyEntry>>;
+/** Taxonomy entry for a kind, or undefined when unknown. */
+export declare function getTaxonomyEntry(kind: string): EventTaxonomyEntry | undefined;
+/** Color for a kind — dictionary value, else the global default. */
+export declare function colorForKind(kind: string): string;
+/** The sub kinds whose `parentKind` is `macro` (empty for a leaf macro). */
+export declare function subKindsOf(macro: string): readonly EventTaxonomyEntry[];

package/dist/catalogs/index.d.ts

@@ -1 +1,3 @@
 export * from './coco-classmap.js';
+export * from './audio-classmap.js';
+export * from './event-taxonomy.js';