@camstack/types 1.2.279 → 1.2.281

package/dist/notification/rule-kinds.d.ts

@@ -201,6 +201,59 @@ export interface NcRuleSectionSubject {
     readonly delivery: string;
     readonly conditions: NcRuleConditionsSubject;
 }
+/**
+ * Which capability a device must carry to be OFFERED on a rule of this kind's
+ * device-scope picker (operator ruling, 2026-10-01). `null` means "no
+ * capability filter for this kind" — either every device applies (the system
+ * families, each already a separate concern; see
+ * `docs/architecture/notifications.md`'s D637 `deviceIds` table) or `mixed`,
+ * which authors nothing.
+ *
+ * DERIVED, never a hand-picked list:
+ *  - `sensor` reads `EVENTFUL_CAP_NAMES` — the SAME cap table the engine
+ *    itself turns a linked device's bound caps into sensor event kinds with
+ *    (`EVENT_KIND_BY_CAP`). A device this picker offers for a sensor rule is
+ *    exactly a device the rule's `sensorKinds` condition could ever name.
+ *  - `detection` (which a package-event rule is — there is no separate
+ *    `package` kind, D637) / `occupancy` read the one pipeline cap a camera
+ *    needs to produce the detections / counts / parcels those kinds match on.
+ *  - `sound` reads the one cap a device needs to produce the audio metrics a
+ *    sound rule's sampling window is built from.
+ *  - `device-events` / `system` / `alarm` / `mixed` are `null`: a device
+ *    event rule's `deviceIds` legitimately spans every device type (liveness,
+ *    battery, consumable, `detection-blind`), a system rule has no device
+ *    scope at all (dropped from the editor's tabs), and `alarm`'s `deviceIds`
+ *    is a reference to whichever camera's rule set it off — not a scope this
+ *    picker authors.
+ *
+ * Callers resolve the ids via `deviceManager.listDeviceIdsByCaps` (max 16
+ * names — `EVENTFUL_CAP_NAMES` is exactly 16) and must treat an unanswered
+ * read as "unknown", never as "no devices" (D315): this function only names
+ * WHICH caps to ask for, not what to show while the answer is pending.
+ */
+export declare function ruleDeviceCompatCapNames(kind: NcRuleKind): readonly string[] | null;
+/**
+ * The capability every CAMERA carries: `camera-streams` is a `defaultActive`
+ * wrapper bound to every `Camera`-type device (`camera-streams.cap.ts`).
+ * Named once, because a sensor rule's compatible set needs it (below).
+ */
+export declare const NC_CAMERA_SCOPE_CAP_NAME = "camera-streams";
+/**
+ * Every capability QUERY whose union is the set of devices a rule of this kind
+ * may be SCOPED to (`conditions.devices`) — what the save-time guard and the
+ * admin's Devices tab ask `deviceManager.listDeviceIdsByCaps`, one call per
+ * entry. `null` exactly where {@link ruleDeviceCompatCapNames} is `null`.
+ *
+ * Several queries rather than one list because `listDeviceIdsByCaps` takes at
+ * most 16 names and `EVENTFUL_CAP_NAMES` is already exactly 16.
+ *
+ * A `sensor` rule's set is the eventful devices PLUS every camera (fix round
+ * 1, 2026-10-01): the engine matches a sensor rule scoped to a CAMERA — a
+ * per-camera row carries the camera's id, and a linked set matches on
+ * `rowCameraIds` (D630 §6) — so a camera-scoped sensor rule is legitimate and
+ * a guard that refused it would make every such stored rule un-editable.
+ */
+export declare function ruleDeviceCompatCapQueries(kind: NcRuleKind): readonly (readonly string[])[] | null;
 /**
  * Which kind of rule is this?
  *
@@ -279,7 +332,7 @@ export declare function droppedConditionsForKind(conditions: NcAuthoredCondition
  * the stored system rules that span families. `mixed` is a real, owning section
  * (a rule must be listed somewhere) that nothing can CREATE into.
  */
-export type NcRuleSectionKey = 'all' | 'detection' | 'audio' | 'occupancy' | 'device-events' | 'system' | 'alarm' | 'mixed';
+export type NcRuleSectionKey = 'all' | 'detection' | 'sensor' | 'audio' | 'occupancy' | 'device-events' | 'system' | 'alarm' | 'mixed';
 export interface NcRuleSection {
     readonly key: NcRuleSectionKey;
     /** English fallback; the viewer maps `key` onto an i18n key. */
@@ -308,15 +361,20 @@ export declare function isOccupancyRule(subject: NcRuleSectionSubject): boolean;
  * `all` always matches — a section that hides a rule is how an operator
  * concludes it was deleted. The others PARTITION the list: sound and
  * occupancy are claimed by their condition, a system-event rule by its trigger
- * and then by the family of its event kinds (or `mixed`, D637), and
- * everything left over — including a trigger this build has never heard of —
- * counts as a detection rule so it stays visible somewhere.
- *
- * Keyed on the CONDITION for two of them, because the trigger alone cannot
- * answer: a sound rule is `immediate` and an occupancy rule is `device-event`,
- * and in each case the condition is the discriminator the engine itself uses.
- * A section keyed on delivery would put both back in the pile they are
- * invisible in.
+ * and then by the family of its event kinds (or `mixed`, D637), `sensor`
+ * claims the `device-event` trigger that occupancy did not (operator ruling,
+ * 2026-10-01 — a doorbell press used to fall into `detection` for want of its
+ * own section, which is the "everything mixed together" the viewer's
+ * `ruleKindOf`-based list had already fixed and the admin's section strip had
+ * not), and everything left over — including a trigger this build has never
+ * heard of — counts as a detection rule so it stays visible somewhere.
+ *
+ * Keyed on the CONDITION for sound and occupancy, because the trigger alone
+ * cannot answer: a sound rule is `immediate` and an occupancy rule is
+ * `device-event`, and in each case the condition is the discriminator the
+ * engine itself uses. `sensor` IS keyed on the trigger, same as `ruleKindOf`'s
+ * `'sensor'` kind — a device-event subject with no occupancy condition is a
+ * sensor rule, full stop.
  */
 export declare function ruleMatchesSection(subject: NcRuleSectionSubject, section: NcRuleSectionKey): boolean;
 /** The ONE real section a rule lives in — `all` holds everything and is not it. */

package/dist/types/appearance.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A model-free appearance descriptor of one detection box (D683 §8).
+ *
+ * Computed on the runner from the analysis raster the frame already leased
+ * (`pipeline-runner/appearance-descriptor.ts`), carried on `ObjectDetection`
+ * and mirrored onto the tracker's `SpatialDetection`. A vector about a box,
+ * never pixels (D9/D18). No learned weights, so no licence question (O6).
+ *
+ * Layout: the box shrunk 10 % per side, split into an upper and a lower half;
+ * per half a hue–saturation histogram (8 hue × 4 saturation), a value histogram
+ * (8) and a magnitude-weighted gradient-orientation histogram (8). Each block
+ * is L1-normalised and quantised to integers 0–255. About 300 bytes of JSON.
+ */
+export declare const APPEARANCE_DESCRIPTOR_VERSION = 1;
+export declare const APPEARANCE_BIN_COUNT = 96;
+export declare const APPEARANCE_BLOCKS: {
+    readonly upperHs: readonly [0, 32];
+    readonly upperV: readonly [32, 40];
+    readonly upperGrad: readonly [40, 48];
+    readonly lowerHs: readonly [48, 80];
+    readonly lowerV: readonly [80, 88];
+    readonly lowerGrad: readonly [88, 96];
+};
+export type AppearanceBlockName = keyof typeof APPEARANCE_BLOCKS;
+export interface AppearanceDescriptor {
+    readonly version: 1;
+    /** {@link APPEARANCE_BIN_COUNT} integers, laid out by {@link APPEARANCE_BLOCKS}. */
+    readonly bins: readonly number[];
+    /** The view carries no colour (IR / greyscale / near-black): hue–saturation says nothing. */
+    readonly gray: boolean;
+}
+/**
+ * Whether appearance may influence anything at all (D683 §3.2, fix round 1
+ * ruling 2026-09-30 on the Task 10 cost-bench STOP): OFF until the
+ * descriptor is calibrated on tapes that carry it (Task 23, review M9).
+ *
+ * This is the ONE authority both addons read — never two settings that
+ * could disagree (CLAUDE.md D62). The tracker's `TrackerV2Config.appearanceResolvesAmbiguity`
+ * default reads it (`addon-post-analysis/pipeline/tracker-v2/types.ts`); the
+ * runner's cost gate reads it too (`addon-pipeline/pipeline-runner/appearance-attach.ts`),
+ * short-circuiting BEFORE any crop, resample or descriptor is computed, so a
+ * disabled camera costs nothing extra per frame.
+ */
+export declare const APPEARANCE_RESOLVES_AMBIGUITY_DEFAULT = false;

package/dist/types/detection.d.ts

@@ -1,6 +1,7 @@
 import type { FirstLevelMacroClass } from './labels.js';
 import type { AudioClassifyOutcome } from '../capabilities/schemas/detection-shared.js';
 import type { TrackState } from '../capabilities/pipeline-analytics.cap.js';
+import type { AppearanceDescriptor } from './appearance.js';
 import type { BoundingBox as EngineBoundingBox, FrameInput, Landmark } from './io.js';
 export interface SpatialDetection {
     readonly class: string;
@@ -24,6 +25,12 @@ export interface SpatialDetection {
      * produced it all the way to the confirmation gate (D379).
      */
     readonly birthEvidence?: BirthEvidence;
+    /**
+     * Mirrored from {@link ObjectDetection.appearance} when this detection enters
+     * the tracker (D683). Absent = no descriptor was computed (too small, no
+     * raster, a runner that predates it): never read as "different".
+     */
+    readonly appearance?: AppearanceDescriptor;
 }
 export interface CropInput {
     readonly frame: FrameInput;
@@ -422,6 +429,11 @@ export interface ObjectDetection extends DetectionBase {
         readonly x: number;
         readonly y: number;
     }[];
+    /**
+     * The box's model-free appearance descriptor, computed by the runner on the
+     * frame this detection was measured on (D683). First-level boxes only.
+     */
+    readonly appearance?: AppearanceDescriptor;
 }
 /** Audio detection — flat, time-localised within the window. */
 export interface AudioDetection extends DetectionBase {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.279",
+  "version": "1.2.281",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",