@camstack/types 1.2.253 → 1.2.255

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

@@ -61,17 +61,34 @@
  * (`packages/addon-benchmark/vite.config.ts`) and therefore read whatever the
  * host loaded; nothing in this file is consumed that way. See
  * `docs/design/2026-08-19-viewer-notification-rule-parity.md` §3 and Phase 3.
+ *
+ * THREE SYSTEM KINDS, AND ONE THAT IS ONLY READ (D637)
+ * ────────────────────────────────────────────────────
+ * A `system-event` rule used to be ONE kind for every infrastructure event. It
+ * is now one kind per family (`device-events`, `system`, `alarm`), DERIVED from
+ * the event kinds the rule names (`system-event-families.ts`), exactly as sound
+ * and occupancy are derived from their condition. A stored rule whose kinds span
+ * families — or name a legacy kind, or none — derives `mixed`: it keeps firing,
+ * it is listed and deletable, and it is never edited.
  */
 import { type NcAudioCondition, type NcConditions, type NcDelivery, type NcOccupancyCondition } from '../capabilities/notification-rules.cap.js';
+import { type NcSystemEventFamily } from './system-event-families.js';
 /**
  * The kind of rule an operator is authoring.
  *
  * Coarser than `delivery` in one direction and finer in another, deliberately:
  * `immediate` / `track-end` / `package-event` are ONE kind here (their
  * differences are already the catalog's `appliesTo` job), while `device-event`
- * and `immediate` each split in two on their discriminating condition.
+ * and `immediate` each split in two on their discriminating condition, and
+ * `system-event` splits by the FAMILY of the event kinds it names (D637).
  */
-export type NcRuleKind = 'detection' | 'sensor' | 'occupancy' | 'sound' | 'system';
+export type NcRuleKind = 'detection' | 'sensor' | 'occupancy' | 'sound' | NcSystemEventFamily | 'mixed';
+/** Every kind a `system-event` rule can derive — the three families and `mixed`. */
+export declare const NC_SYSTEM_RULE_KINDS: readonly ["device-events", "system", "alarm", "mixed"];
+/** Is this a kind a `system-event` rule derives (any family, or `mixed`)? */
+export declare function isSystemRuleKind(kind: NcRuleKind | undefined): boolean;
+/** The family a kind authors, or undefined (a camera kind, or `mixed`). */
+export declare function systemFamilyOfKind(kind: NcRuleKind): NcSystemEventFamily | undefined;
 export interface NcRuleKindSpec {
     readonly kind: NcRuleKind;
     /** What the conditions section is CALLED for this kind (English fallback). */
@@ -81,6 +98,13 @@ export interface NcRuleKindSpec {
      * excluded — burying it would hide the whole feature (which is how an
      * operator with a working audio engine reported there was no way to create an
      * audio rule).
+     *
+     * NOT UNIQUE PER KIND. A GROUP of kinds may share one discriminator: the three
+     * system families and `mixed` all ride `systemEvent` (D637), and which of them
+     * a rule is comes from the event kinds, not from the condition's presence. A
+     * consumer that maps a discriminator back to ONE kind (a `Map` keyed on it)
+     * keeps the last spec and silently misroutes the others — ask
+     * {@link kindsForDiscriminator} for the whole group.
      */
     readonly discriminator?: keyof NcConditions;
     /**
@@ -89,6 +113,12 @@ export interface NcRuleKindSpec {
      * save is about to drop one.
      */
     readonly excluded: Readonly<Record<string, string>>;
+    /**
+     * false = readable and deletable, never edited. Only `mixed`: a rule that
+     * predates D637 and spans families. It keeps firing; the operator recreates
+     * it one rule per family.
+     */
+    readonly editable: boolean;
     /**
      * Can a notification of this kind carry a picture AT ALL?
      *
@@ -96,9 +126,9 @@ export interface NcRuleKindSpec {
      * ladder resolves media by OWNER, and only a subject that freezes one has any
      * (`triggerCanCarryStill` in the addon's `test-event.ts` is the same list).
      *
-     * Only `system` is left. An infrastructure event is about no camera at all —
-     * there is nothing to photograph, so every media control on it is a knob that
-     * does nothing. A SOUND rule was here until 2026-08-15 and was right to be:
+     * Only the system-event kinds are left. An infrastructure event is about no
+     * camera at all — there is nothing to photograph, so every media control on it
+     * is a knob that does nothing. A SOUND rule was here until 2026-08-15 and was right to be:
      * its subject is a sampling window that owns no frame. It now photographs the
      * camera at the match instead (`still-shelf.ts`), which is a picture nothing
      * else could give it.
@@ -124,6 +154,12 @@ export interface NcRuleKindSpec {
 export declare const NC_RULE_KIND_SPECS: readonly NcRuleKindSpec[];
 /** The spec for a kind. Total by construction — every member has an entry. */
 export declare function ruleKindSpec(kind: NcRuleKind): NcRuleKindSpec;
+/**
+ * Every kind a discriminator makes — one kind for `audio` and `occupancy`, the
+ * whole system group for `systemEvent`. Empty for a condition that makes no
+ * kind. See {@link NcRuleKindSpec.discriminator}.
+ */
+export declare function kindsForDiscriminator(discriminator: keyof NcConditions): readonly NcRuleKind[];
 /** The delivery a system rule rides — named once, compared everywhere. */
 export declare const NC_SYSTEM_DELIVERY = "system-event";
 /**
@@ -171,9 +207,18 @@ export interface NcRuleSectionSubject {
  * the order below is the engine's own: `evaluateRule` checks the system branch
  * first, then the occupancy and audio gates. Takes a plain `delivery` string so
  * a trigger this build does not know still classifies (as `detection`, which is
- * the read-only path's own fallback).
+ * the read-only path's own fallback). A system rule classifies by the FAMILY of
+ * its event kinds (D637) — see {@link systemRuleKindOf}.
  */
 export declare function ruleKindOf(rule: NcRuleSectionSubject): NcRuleKind;
+/**
+ * A system rule's kind: its one family, or `mixed` (D637).
+ *
+ * Takes the UNTYPED condition for the same reason {@link NcRuleConditionsSubject}
+ * is structural. `mixed` covers kinds across families, a legacy or unknown kind,
+ * and no kinds at all — it fails toward read-only, never toward editable.
+ */
+export declare function systemRuleKindOf(condition: unknown): NcSystemEventFamily | 'mixed';
 /**
  * The shape {@link conditionVisibleForKind} reads off a catalog descriptor.
  *
@@ -226,10 +271,14 @@ export declare function droppedConditionsForKind(conditions: NcAuthoredCondition
  *
  * `all` is kept and is the DEFAULT: a section that hides rules is how an
  * operator concludes a rule was deleted. Which sections a given SURFACE offers
- * for authoring is that surface's decision — the viewer omits `system` from its
- * create flow and still renders system rules under `all`.
+ * for authoring is that surface's decision — the viewer omits the system-event
+ * sections from its create flow and still renders system rules under `all`.
+ *
+ * D637 split the one `system` section into the three families, plus `mixed`:
+ * 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' | 'system';
+export type NcRuleSectionKey = 'all' | 'detection' | 'audio' | 'occupancy' | 'device-events' | 'system' | 'alarm' | 'mixed';
 export interface NcRuleSection {
     readonly key: NcRuleSectionKey;
     /** English fallback; the viewer maps `key` onto an i18n key. */
@@ -240,6 +289,8 @@ export interface NcRuleSection {
     readonly newRuleLabel: string;
     /** What the section says when it holds nothing yet. */
     readonly emptyHint: string;
+    /** Can a rule be CREATED from this section? false only for `mixed` (D637). */
+    readonly creatable: boolean;
 }
 export declare const NC_RULE_SECTIONS: readonly NcRuleSection[];
 /** The section for a key, or `undefined` — the lookup behind every label. */
@@ -254,8 +305,9 @@ export declare function isOccupancyRule(subject: NcRuleSectionSubject): boolean;
  * Does a rule belong in this section?
  *
  * `all` always matches — a section that hides a rule is how an operator
- * concludes it was deleted. The other four PARTITION the list: sound and
- * occupancy are claimed by their condition, system by its trigger, and
+ * 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.
  *
@@ -271,8 +323,9 @@ export type NcRuleOwningSectionKey = Exclude<NcRuleSectionKey, 'all'>;
 /**
  * Which section OWNS this rule — the counter behind a section strip.
  *
- * Derived from {@link ruleMatchesSection} rather than restated, so the strip's
- * counts and the strip's contents can never disagree.
+ * The same order as {@link ruleMatchesSection} — trigger first, then the
+ * discriminating condition — and the section spec asserts the two agree on
+ * every subject, so the strip's counts and its contents cannot disagree.
  */
 export declare function ruleSectionOf(subject: NcRuleSectionSubject): NcRuleOwningSectionKey;
 /**
@@ -310,6 +363,10 @@ export declare const NC_AUDIO_SEED: NcAudioCondition;
  * on a trigger they must pick first. That is exactly the gap reported on
  * 2026-08-13 ("non vedo un modo per creare le nuove rules audio e occupancy")
  * for two features whose engines had already shipped.
+ *
+ * A system seed carries its event kinds for the same reason: the kind is derived
+ * from them (D637), so an empty seed would open a `mixed` rule. `mixed` itself
+ * falls to the default and is never offered — its section is not `creatable`.
  */
 export interface NcRuleSeed extends NcRuleSectionSubject {
     readonly delivery: NcDelivery;
@@ -349,7 +406,7 @@ export interface NcRuleEditorSection {
  *
  * Two rules, both of them about a control that would decide nothing:
  *
- *  - a `system-event` rule has no device scope — `conditions.devices` is not
+ *  - a system-event rule (any family) has no device scope — `conditions.devices` is not
  *    evaluated for it and the input builder refuses to write it — so the
  *    Cameras section is DROPPED rather than shown and ignored;
  *  - a sound or occupancy rule is NAMED on its conditions section. Neither has

package/dist/notification/scope-picker-items.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Nodes and packages as a PICKER lists them (D637). One projection shared by the
+ * admin UI and the viewer, so the system family's two pickers group and label
+ * the same way. The shape is structurally the pickers' `PickerItem<string>`.
+ */
+import type { NodeDirectoryEntry } from '../capabilities/nodes.cap.js';
+export interface NcScopePickerItem {
+    readonly id: string;
+    readonly name: string;
+    readonly type?: string;
+    readonly location?: string | null;
+    readonly detail?: string;
+}
+export declare function nodePickerItems(nodes: readonly NodeDirectoryEntry[]): readonly NcScopePickerItem[];
+/**
+ * The server's own package name: `server-update-available` / `server-updated`
+ * carry it, and `addons.listPackages` does not list it.
+ */
+export declare const NC_SERVER_PACKAGE_NAME = "@camstack/server";
+/**
+ * Every package name an update EVENT carries as `packageName`, one per
+ * producer. The package picker offers each of them whether or not
+ * `addons.listPackages` lists it, because a rule scoped to a name no event
+ * carries can never fire (and one an event carries must be pickable).
+ *
+ * - `@camstack/server` — `server-update-available` / `server-updated`: the hub
+ *   root package (`HUB_ROOT_SPEC.packageName`, `@camstack/node-root`).
+ * - `@camstack/system` — `server-update-available` from the framework check,
+ *   which checks `[SYSTEM_PACKAGE]` only (`AddonPackageService.listFrameworkPackages`).
+ *   `@camstack/types` / `@camstack/sdk` are framework packages for upload
+ *   routing but are never announced, so they are NOT here.
+ * - `camstack-wrapper` — `wrapper-update-available` (`WRAPPER_PACKAGE_NAME`,
+ *   `wrapper-update-checker.ts`).
+ *
+ * Types cannot import those producers; the backend spec
+ * `core/updates/__tests__/update-event-package-names.spec.ts` pins each literal
+ * to its producer constant. This is a picker list, never a routing list.
+ */
+export declare const NC_UPDATE_EVENT_PACKAGE_NAMES: readonly ["@camstack/server", "@camstack/system", "camstack-wrapper"];
+export interface NcInstalledPackageLike {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Every update-event package first (always offered: an event carries it), in
+ * `NC_UPDATE_EVENT_PACKAGE_NAMES` order, then the installed addons sorted by
+ * name. An installed version is the second line.
+ */
+export declare function packagePickerItems(packages: readonly NcInstalledPackageLike[]): readonly NcScopePickerItem[];

package/dist/notification/system-event-families.d.ts

@@ -0,0 +1,76 @@
+/**
+ * WHICH FAMILY every system-event kind belongs to, and which narrowing filters
+ * each family may carry: one table, read by the hub validator, by `ruleKindOf`
+ * and by both rule editors (D637).
+ *
+ * A system rule used to be one editor for thirty-one kinds and five filters.
+ * "Eventi di sistema" carried battery kinds under a liveness `deviceTypes` filter
+ * and went silent for two weeks (D636). The three families are three questions:
+ * about devices, about the installation, and about the alarm panel. A rule
+ * answers one of them. The engine never needed to know, and it still does not:
+ * a mixed stored rule keeps firing. Only AUTHORING is strict.
+ *
+ * The legacy `camera-*` tail has no family (`null`). It is parsed, never produced,
+ * never offered.
+ */
+import { type NcSystemEventCondition, type NcSystemEventKind } from '../capabilities/notification-rules.cap.js';
+import { type NcSystemEventFilterKey } from './system-event-filters.js';
+export declare const NC_SYSTEM_EVENT_FAMILIES: readonly ["device-events", "system", "alarm"];
+export type NcSystemEventFamily = (typeof NC_SYSTEM_EVENT_FAMILIES)[number];
+export declare function isSystemEventFamily(value: string): value is NcSystemEventFamily;
+/** Total over the enum: a kind added to the cap without a family fails tsc here. */
+export declare const NC_SYSTEM_EVENT_FAMILY: Readonly<Record<NcSystemEventKind, NcSystemEventFamily | null>>;
+/** A condition field that can narrow or exclude a system subject. */
+export type NcSystemEventConditionFilterKey = NcSystemEventFilterKey | 'excludeDeviceIds';
+export declare const NC_SYSTEM_EVENT_CONDITION_FILTER_KEYS: readonly NcSystemEventConditionFilterKey[];
+/**
+ * The filters a family may carry. The four base filters are the union of
+ * `systemEventFilterApplies` over the family's kinds (the spec pins that
+ * equality). `excludeDeviceIds` is a device-events filter only: an alarm is
+ * narrowed to the camera that triggered it and excludes nothing.
+ */
+export declare const NC_SYSTEM_EVENT_FAMILY_FILTERS: Readonly<Record<NcSystemEventFamily, readonly NcSystemEventConditionFilterKey[]>>;
+/** A themed set of kinds as both editors list them. `label` is an English fallback. */
+export interface NcSystemEventKindGroupSpec {
+    readonly id: string;
+    readonly family: NcSystemEventFamily;
+    readonly label: string;
+    readonly kinds: readonly NcSystemEventKind[];
+}
+export declare const NC_SYSTEM_EVENT_KIND_GROUP_SPECS: readonly NcSystemEventKindGroupSpec[];
+export declare function systemEventKindsOfFamily(family: NcSystemEventFamily): readonly NcSystemEventKind[];
+/** The kind names on an UNTYPED condition, or `undefined` when it has none. */
+export declare function systemEventKindNamesOf(condition: unknown): readonly string[] | undefined;
+export type NcSystemEventFamilyVerdict = {
+    readonly kind: 'family';
+    readonly family: NcSystemEventFamily;
+} | {
+    readonly kind: 'mixed';
+};
+/**
+ * One family, or `mixed`. Mixed covers kinds that span families, a legacy kind,
+ * a kind this build does not know (it fails toward read-only and never toward
+ * editable), and an empty selection (nothing to decide on).
+ */
+export declare function systemEventFamilyOf(kindNames: readonly string[]): NcSystemEventFamilyVerdict;
+export type NcSystemEventFamilyProblem = {
+    readonly code: 'no-kinds';
+} | {
+    readonly code: 'legacy-kind';
+    readonly kind: NcSystemEventKind;
+} | {
+    readonly code: 'mixed-families';
+    readonly families: readonly NcSystemEventFamily[];
+} | {
+    readonly code: 'filter-outside-family';
+    readonly filter: NcSystemEventConditionFilterKey;
+    readonly family: NcSystemEventFamily;
+};
+/**
+ * Why the hub refuses this condition on a new or updated rule. Empty = accepted.
+ * Families are reported in `NC_SYSTEM_EVENT_FAMILIES` order, and filters in
+ * `NC_SYSTEM_EVENT_CONDITION_FILTER_KEYS` order, so a refusal reads the same
+ * every time.
+ */
+export declare function systemEventFamilyProblems(condition: NcSystemEventCondition | undefined): readonly NcSystemEventFamilyProblem[];
+export declare function describeSystemEventFamilyProblem(problem: NcSystemEventFamilyProblem): string;

package/dist/notification/template-vars.d.ts

@@ -8,10 +8,31 @@
  * `addon-post-analysis` run each producer and compare its keys with this list,
  * so the two cannot drift silently again.
  */
-import { NcRuleKindSchema, NcTemplateFamilySchema, NcTemplateFieldSchema, NcTemplateVarContextSchema, NcTemplateVarDescriptorSchema, NcTemplateVarGroupSchema, type NcTemplateVarContext, type NcTemplateVarDescriptor } from '../capabilities/notification-rules.cap.js';
+import { NcRuleKindSchema, NcTemplateFamilySchema, NcTemplateFieldSchema, NcTemplateVarContextSchema, NcTemplateVarDescriptorSchema, NcTemplateVarGroupSchema, type NcTemplateVarContext, type NcTemplateVarDescriptor, type NcTemplateVarKind } from '../capabilities/notification-rules.cap.js';
+import { type NcRuleKind } from './rule-kinds.js';
 export { NcRuleKindSchema, NcTemplateFamilySchema, NcTemplateFieldSchema, NcTemplateVarContextSchema, NcTemplateVarDescriptorSchema, NcTemplateVarGroupSchema, };
 export type { NcTemplateFamily, NcTemplateField, NcTemplateVarContext, NcTemplateVarDescriptor, NcTemplateVarGroup, } from '../capabilities/notification-rules.cap.js';
 export declare const NC_TEMPLATE_VARS: readonly NcTemplateVarDescriptor[];
+/**
+ * Does a descriptor declared for `declared` kinds have a value for a rule of
+ * `kind`?
+ *
+ * `system` on the WIRE stands for every system rule kind (D637): the served
+ * catalog keeps the five pre-D637 tokens so installed viewers still parse it
+ * (`NcTemplateVarKindSchema`), and the family split lives here, in the match.
+ * Exported so the admin's local interpreter of the served catalog asks the
+ * same question instead of restating it.
+ */
+export declare function templateVarKindApplies(declared: readonly NcTemplateVarKind[] | undefined, kind: NcRuleKind | undefined): boolean;
+/**
+ * Is a descriptor that names `systemEventKinds` on the event-kind axis of a
+ * system rule? Read only for a system rule kind; any other kind ignores it.
+ *
+ * Event kinds chosen: the descriptor must speak about one of them. None chosen
+ * yet: a FAMILY kind watches its own family's event kinds (a device-events rule
+ * is never offered the alarm's `{{mode}}`), and `mixed` watches all of them.
+ */
+export declare function templateVarSystemEventApplies(d: NcTemplateVarDescriptor, ctx: NcTemplateVarContext): boolean;
 /**
  * The variables that have a value in `ctx`, in catalog order. Pure.
  *

package/package.json

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